spaceload 0.1.0__tar.gz

spaceload-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spaceload-0.1.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: spaceload
+Version: 0.1.0
+Summary: Workspace Context Switcher — record and replay developer workspace setups
+Author: tomjosetj31
+License: MIT License
+        
+        Copyright (c) 2026 Tom
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/tomjosetj31/spaceload
+Project-URL: Repository, https://github.com/tomjosetj31/spaceload
+Project-URL: Bug Tracker, https://github.com/tomjosetj31/spaceload/issues
+Project-URL: Changelog, https://github.com/tomjosetj31/spaceload/blob/master/CHANGELOG.md
+Keywords: workspace,developer-tools,macos,productivity,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-timeout>=2.1; extra == "dev"
+Provides-Extra: firefox
+Requires-Dist: lz4>=4.0; extra == "firefox"
+Provides-Extra: all
+Requires-Dist: lz4>=4.0; extra == "all"
+Dynamic: license-file
+
+# Spaceload — Workspace Context Switcher
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+
+A macOS CLI tool that records and replays developer workspace setups: browser tabs, VPN connections, IDE projects, and terminal sessions.
+
+## Overview
+
+`spaceload` lets you snapshot your entire development environment and restore it later with a single command. Stop context-switching overhead and get back into flow faster.
+
+## Features
+
+- **Record** workspace sessions (browser tabs, VPN, IDE, terminals)
+- **Replay** saved workspaces in one command
+- **Export/Import** workspace definitions as YAML
+- **List** and manage saved workspaces
+
+## Installation
+
+```bash
+git clone https://github.com/tomjosetj31/spaceload
+cd spaceload
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Usage
+
+```bash
+# Start recording a workspace session
+spaceload record my-project
+
+# ... open your browser tabs, connect VPN, open IDE, etc. ...
+
+# Stop recording and save the session
+spaceload stop
+
+# Replay a saved workspace
+spaceload run my-project
+
+# List all saved workspaces
+spaceload list
+
+# Inspect a workspace as YAML
+spaceload show my-project
+
+# Delete a workspace
+spaceload delete my-project
+
+# Import a workspace from a YAML file
+spaceload import my-project.yaml
+```
+
+### Recording Options
+
+```bash
+# Record only new things opened during recording (default)
+spaceload record my-project
+
+# Also capture everything already open when recording starts
+spaceload record my-project --include-open
+# or
+spaceload record my-project -i
+```
+
+## Supported Integrations
+
+### Specialized Adapters (Rich Tracking)
+
+These apps have dedicated adapters that track specific details:
+
+| Category | Supported | What's Tracked |
+|----------|-----------|----------------|
+| **Browser** | Chrome, Safari, Arc, Firefox | Individual tab URLs |
+| **VPN** | Tailscale, WireGuard, Cisco AnyConnect, Mullvad, OpenVPN, Tunnelblick | Connection state & profile |
+| **IDE** | VS Code, Cursor, Zed | Open project/folder paths |
+| **Terminal** | iTerm2, Terminal.app, Warp, Kitty | Working directories per session, commands (with shell hook) |
+
+### Generic App Tracking
+
+Any **other application** you open during recording is automatically tracked as an `app_open` action with the app name. This includes apps like Notes, Calendar, Slack, Spotify, etc.
+
+### Firefox Support
+
+Firefox tab reading requires the `lz4` library to parse session files:
+
+```bash
+# Install with Firefox support
+pip install -e ".[firefox]"
+
+# Or install lz4 separately
+pip install lz4
+```
+
+Without `lz4`, Firefox tabs won't be read during recording, but URLs can still be opened during replay.
+
+### Terminal Command Tracking
+
+To track terminal commands during recording, add the shell hook to your shell config:
+
+```bash
+# For zsh (~/.zshrc):
+eval "$(spaceload shell-hook zsh)"
+
+# For bash (~/.bashrc):
+eval "$(spaceload shell-hook bash)"
+```
+
+Then restart your shell or run `source ~/.zshrc`.
+
+**How it works:**
+- Commands are only tracked when a recording session is active
+- The hook checks for the daemon socket before sending (no overhead when not recording)
+- Commands run in the background so they don't slow down your shell
+- During replay, commands are **displayed but not auto-executed** (for safety)
+
+### Smart Browser Filtering
+
+The recorder automatically filters out:
+- **New tab pages** (`chrome://newtab/`, `about:newtab`, etc.)
+- **Internal browser pages** (`chrome://`, `about:`, `safari-resource:`, etc.)
+- **Intermediate URLs** (pages open less than 3 seconds)
+- **Redirect chains** (multiple URLs from same domain in quick succession)
+
+## Logs & Debugging
+
+Logs are written to `~/.spaceload/` for debugging:
+
+```bash
+# Daemon log (recording)
+cat ~/.spaceload/daemon.log
+
+# Replay log
+cat ~/.spaceload/replay.log
+```
+
+## Architecture
+
+- **CLI** (`spaceload/cli/`) — Click-based command interface
+- **Daemon** (`spaceload/daemon/`) — Unix socket server that records actions in the background
+- **Store** (`spaceload/store/`) — SQLite-backed persistence layer with YAML export/import
+- **Replayer** (`spaceload/replayer/`) — Replays recorded action sequences
+- **Adapters** (`spaceload/adapters/`) — Per-integration plugins (browser, VPN, IDE, terminal)
+
+## Tech Stack
+
+- Python 3.11+
+- [Click](https://click.palletsprojects.com/) for the CLI
+- SQLite (stdlib) for persistence
+- PyYAML for export/import
+- Unix domain sockets for CLI↔daemon IPC
+
+## Contributing
+
+Contributions are welcome! Whether it's a bug fix, a new adapter for an app you use, or a documentation improvement — all PRs are appreciated.
+
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to set up the project locally, run tests, and submit a pull request.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

spaceload-0.1.0/README.md

@@ -0,0 +1,164 @@
+# Spaceload — Workspace Context Switcher
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+
+A macOS CLI tool that records and replays developer workspace setups: browser tabs, VPN connections, IDE projects, and terminal sessions.
+
+## Overview
+
+`spaceload` lets you snapshot your entire development environment and restore it later with a single command. Stop context-switching overhead and get back into flow faster.
+
+## Features
+
+- **Record** workspace sessions (browser tabs, VPN, IDE, terminals)
+- **Replay** saved workspaces in one command
+- **Export/Import** workspace definitions as YAML
+- **List** and manage saved workspaces
+
+## Installation
+
+```bash
+git clone https://github.com/tomjosetj31/spaceload
+cd spaceload
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Usage
+
+```bash
+# Start recording a workspace session
+spaceload record my-project
+
+# ... open your browser tabs, connect VPN, open IDE, etc. ...
+
+# Stop recording and save the session
+spaceload stop
+
+# Replay a saved workspace
+spaceload run my-project
+
+# List all saved workspaces
+spaceload list
+
+# Inspect a workspace as YAML
+spaceload show my-project
+
+# Delete a workspace
+spaceload delete my-project
+
+# Import a workspace from a YAML file
+spaceload import my-project.yaml
+```
+
+### Recording Options
+
+```bash
+# Record only new things opened during recording (default)
+spaceload record my-project
+
+# Also capture everything already open when recording starts
+spaceload record my-project --include-open
+# or
+spaceload record my-project -i
+```
+
+## Supported Integrations
+
+### Specialized Adapters (Rich Tracking)
+
+These apps have dedicated adapters that track specific details:
+
+| Category | Supported | What's Tracked |
+|----------|-----------|----------------|
+| **Browser** | Chrome, Safari, Arc, Firefox | Individual tab URLs |
+| **VPN** | Tailscale, WireGuard, Cisco AnyConnect, Mullvad, OpenVPN, Tunnelblick | Connection state & profile |
+| **IDE** | VS Code, Cursor, Zed | Open project/folder paths |
+| **Terminal** | iTerm2, Terminal.app, Warp, Kitty | Working directories per session, commands (with shell hook) |
+
+### Generic App Tracking
+
+Any **other application** you open during recording is automatically tracked as an `app_open` action with the app name. This includes apps like Notes, Calendar, Slack, Spotify, etc.
+
+### Firefox Support
+
+Firefox tab reading requires the `lz4` library to parse session files:
+
+```bash
+# Install with Firefox support
+pip install -e ".[firefox]"
+
+# Or install lz4 separately
+pip install lz4
+```
+
+Without `lz4`, Firefox tabs won't be read during recording, but URLs can still be opened during replay.
+
+### Terminal Command Tracking
+
+To track terminal commands during recording, add the shell hook to your shell config:
+
+```bash
+# For zsh (~/.zshrc):
+eval "$(spaceload shell-hook zsh)"
+
+# For bash (~/.bashrc):
+eval "$(spaceload shell-hook bash)"
+```
+
+Then restart your shell or run `source ~/.zshrc`.
+
+**How it works:**
+- Commands are only tracked when a recording session is active
+- The hook checks for the daemon socket before sending (no overhead when not recording)
+- Commands run in the background so they don't slow down your shell
+- During replay, commands are **displayed but not auto-executed** (for safety)
+
+### Smart Browser Filtering
+
+The recorder automatically filters out:
+- **New tab pages** (`chrome://newtab/`, `about:newtab`, etc.)
+- **Internal browser pages** (`chrome://`, `about:`, `safari-resource:`, etc.)
+- **Intermediate URLs** (pages open less than 3 seconds)
+- **Redirect chains** (multiple URLs from same domain in quick succession)
+
+## Logs & Debugging
+
+Logs are written to `~/.spaceload/` for debugging:
+
+```bash
+# Daemon log (recording)
+cat ~/.spaceload/daemon.log
+
+# Replay log
+cat ~/.spaceload/replay.log
+```
+
+## Architecture
+
+- **CLI** (`spaceload/cli/`) — Click-based command interface
+- **Daemon** (`spaceload/daemon/`) — Unix socket server that records actions in the background
+- **Store** (`spaceload/store/`) — SQLite-backed persistence layer with YAML export/import
+- **Replayer** (`spaceload/replayer/`) — Replays recorded action sequences
+- **Adapters** (`spaceload/adapters/`) — Per-integration plugins (browser, VPN, IDE, terminal)
+
+## Tech Stack
+
+- Python 3.11+
+- [Click](https://click.palletsprojects.com/) for the CLI
+- SQLite (stdlib) for persistence
+- PyYAML for export/import
+- Unix domain sockets for CLI↔daemon IPC
+
+## Contributing
+
+Contributions are welcome! Whether it's a bug fix, a new adapter for an app you use, or a documentation improvement — all PRs are appreciated.
+
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to set up the project locally, run tests, and submit a pull request.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

spaceload-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spaceload"
+version = "0.1.0"
+description = "Workspace Context Switcher — record and replay developer workspace setups"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+authors = [
+    { name = "tomjosetj31" },
+]
+keywords = ["workspace", "developer-tools", "macos", "productivity", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "click>=8.1",
+    "PyYAML>=6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/tomjosetj31/spaceload"
+Repository = "https://github.com/tomjosetj31/spaceload"
+"Bug Tracker" = "https://github.com/tomjosetj31/spaceload/issues"
+Changelog = "https://github.com/tomjosetj31/spaceload/blob/master/CHANGELOG.md"
+
+[project.scripts]
+spaceload = "spaceload.cli.main:cli"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4",
+    "pytest-timeout>=2.1",
+]
+firefox = [
+    "lz4>=4.0",  # Required for reading Firefox session files
+]
+all = [
+    "lz4>=4.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["spaceload*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+timeout = 30

spaceload-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spaceload-0.1.0/spaceload/__init__.py

@@ -0,0 +1,3 @@
+"""spaceload — Workspace Context Switcher."""
+
+__version__ = "0.1.0"

spaceload-0.1.0/spaceload/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapters package for ctx."""

spaceload-0.1.0/spaceload/adapters/aerospace/__init__.py

@@ -0,0 +1,17 @@
+"""AeroSpace adapter package for ctx."""
+
+from spaceload.adapters.aerospace.adapter import (
+    AeroSpaceAdapter,
+    AeroWindow,
+    BROWSER_APP_NAMES,
+    IDE_APP_NAMES,
+    TERMINAL_APP_NAMES,
+)
+
+__all__ = [
+    "AeroSpaceAdapter",
+    "AeroWindow",
+    "BROWSER_APP_NAMES",
+    "IDE_APP_NAMES",
+    "TERMINAL_APP_NAMES",
+]

spaceload-0.1.0/spaceload/adapters/aerospace/adapter.py

@@ -0,0 +1,38 @@
+"""AeroSpace adapter — re-exported from spaceload.adapters.wm for backward compatibility.
+
+New code should import from spaceload.adapters.wm directly.
+"""
+
+from __future__ import annotations
+
+from spaceload.adapters.wm.aerospace import AeroSpaceAdapter
+from spaceload.adapters.wm.base import WMWindow as AeroWindow  # legacy alias
+
+# App name maps kept here for backward compat; canonical home is ctx.adapters.wm.app_names
+BROWSER_APP_NAMES: dict[str, str] = {
+    "chrome": "Google Chrome",
+    "safari": "Safari",
+    "arc": "Arc",
+    "firefox": "Firefox",
+}
+
+IDE_APP_NAMES: dict[str, str] = {
+    "vscode": "Code",
+    "cursor": "Cursor",
+    "zed": "Zed",
+}
+
+TERMINAL_APP_NAMES: dict[str, str] = {
+    "iterm2": "iTerm2",
+    "terminal": "Terminal",
+    "warp": "Warp",
+    "kitty": "kitty",
+}
+
+__all__ = [
+    "AeroSpaceAdapter",
+    "AeroWindow",
+    "BROWSER_APP_NAMES",
+    "IDE_APP_NAMES",
+    "TERMINAL_APP_NAMES",
+]

spaceload-0.1.0/spaceload/adapters/browser/__init__.py

@@ -0,0 +1,6 @@
+"""Browser adapter package for ctx."""
+
+from spaceload.adapters.browser.base import BrowserAdapter, TabSet
+from spaceload.adapters.browser.registry import BrowserAdapterRegistry
+
+__all__ = ["BrowserAdapter", "TabSet", "BrowserAdapterRegistry"]

spaceload-0.1.0/spaceload/adapters/browser/arc.py

@@ -0,0 +1,53 @@
+"""Arc browser adapter using AppleScript."""
+
+from __future__ import annotations
+
+import subprocess
+
+from spaceload.adapters.browser.base import BrowserAdapter
+
+_GET_TABS_SCRIPT = """\
+tell application "Arc"
+    set tabURLs to {}
+    repeat with w in windows
+        repeat with t in tabs of w
+            set end of tabURLs to URL of t
+        end repeat
+    end repeat
+    set AppleScript's text item delimiters to "\\n"
+    return tabURLs as text
+end tell
+"""
+
+
+class ArcAdapter(BrowserAdapter):
+    """Adapter for the Arc browser on macOS using AppleScript."""
+
+    @property
+    def name(self) -> str:
+        return "arc"
+
+    def is_available(self) -> bool:
+        result = subprocess.run(
+            ["pgrep", "-x", "Arc"],
+            capture_output=True,
+        )
+        return result.returncode == 0
+
+    def get_open_tabs(self) -> list[str]:
+        result = subprocess.run(
+            ["osascript", "-e", _GET_TABS_SCRIPT],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode != 0 or not result.stdout.strip():
+            return []
+        return [u for u in result.stdout.strip().splitlines() if u.strip()]
+
+    def open_url(self, url: str) -> bool:
+        result = subprocess.run(
+            ["open", "-a", "Arc", url],
+            capture_output=True,
+        )
+        return result.returncode == 0

spaceload-0.1.0/spaceload/adapters/browser/base.py

@@ -0,0 +1,35 @@
+"""Browser adapter base class for ctx."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+
+@dataclass
+class TabSet:
+    """Represents the current open tabs in a browser."""
+
+    browser: str
+    urls: list[str] = field(default_factory=list)
+
+
+class BrowserAdapter(ABC):
+    """Abstract base class for browser adapters."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Unique identifier for this browser (e.g. 'chrome', 'safari')."""
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Return True if this browser is currently running."""
+
+    @abstractmethod
+    def get_open_tabs(self) -> list[str]:
+        """Return the URLs of all currently open tabs."""
+
+    @abstractmethod
+    def open_url(self, url: str) -> bool:
+        """Open *url* in this browser. Return True on success."""

spaceload-0.1.0/spaceload/adapters/browser/chrome.py

@@ -0,0 +1,53 @@
+"""Google Chrome browser adapter using AppleScript."""
+
+from __future__ import annotations
+
+import subprocess
+
+from spaceload.adapters.browser.base import BrowserAdapter
+
+_GET_TABS_SCRIPT = """\
+tell application "Google Chrome"
+    set tabURLs to {}
+    repeat with w in windows
+        repeat with t in tabs of w
+            set end of tabURLs to URL of t
+        end repeat
+    end repeat
+    set AppleScript's text item delimiters to "\\n"
+    return tabURLs as text
+end tell
+"""
+
+
+class ChromeAdapter(BrowserAdapter):
+    """Adapter for Google Chrome on macOS using AppleScript."""
+
+    @property
+    def name(self) -> str:
+        return "chrome"
+
+    def is_available(self) -> bool:
+        result = subprocess.run(
+            ["pgrep", "-x", "Google Chrome"],
+            capture_output=True,
+        )
+        return result.returncode == 0
+
+    def get_open_tabs(self) -> list[str]:
+        result = subprocess.run(
+            ["osascript", "-e", _GET_TABS_SCRIPT],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode != 0 or not result.stdout.strip():
+            return []
+        return [u for u in result.stdout.strip().splitlines() if u.strip()]
+
+    def open_url(self, url: str) -> bool:
+        result = subprocess.run(
+            ["open", "-a", "Google Chrome", url],
+            capture_output=True,
+        )
+        return result.returncode == 0