flashbox 0.1.0__tar.gz

flashbox-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Your Name
+
+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.

flashbox-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: flashbox
+Version: 0.1.0
+Summary: A dynamic, repository-aware persistent Docker sandbox CLI for AI Agents.
+Author-email: Mark Eyser <markeyser@github.com>
+Project-URL: Homepage, https://github.com/markeyser/flashbox
+Keywords: ai,agents,docker,sandbox,mcp,cli,telemetry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Terminals
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10; extra == "dev"
+Requires-Dist: ruff>=0.3.0; extra == "dev"
+Dynamic: license-file
+
+# Flashbox ⚡️
+
+A lightning-fast, repository-aware persistent Docker sandbox CLI designed specifically for AI Coding Agents.
+
+Flashbox allows your AI coding agents (like Antigravity or Cursor) to safely execute terminal commands, run scripts, and compile code in an isolated Linux environment without polluting your local macOS host. It completely replaces the heavy, latency-prone Boxlite MCP server with a streamlined local Python CLI mapping directly to your Docker daemon.
+
+## Why Flashbox?
+- **Zero Token Overhead:** Unlike MCP servers, Flashbox doesn't inject massive JSON schemas into your prompt context.
+- **Dynamic Repository Mounting:** If you run `sandbox start` in `/Projects/MyCoolApp`, Flashbox dynamically mounts that specific directory to `/vault` inside a dedicated `flashbox-mycoolapp` container.
+- **Native Execution Speed:** Bypasses JSON-RPC handshakes. `sandbox exec` streams natively through `subprocess` directly to Docker.
+- **Built-in Telemetry:** Ships with a real-time TUI to monitor the active exact CPU and RAM your AI is drawing.
+
+## System Requirements
+- **Operating System:** Fully cross-platform. Tested heavily on **macOS (Apple Silicon)**, but works flawlessly on **Linux** and **Windows (via WSL2)**.
+- **Docker Daemon:** You **MUST** have the Docker engine running in the background. On macOS/Windows, this means having **Docker Desktop** or **OrbStack** open and active. On Linux, the native `docker` service must be running.
+- **Python:** Python 3.10+ installed on the host machine.
+
+## Installation
+
+Because Flashbox is packaged cleanly, you can install it globally via `pipx` or your preferred Python package manager:
+
+```zsh
+# Run this inside the cloned repo
+pipx install .
+```
+
+## Usage
+
+Once installed, the globally accessible `sandbox` command is available from any directory.
+
+### Quick Start
+Navigate to any project directory and initialize the sandbox:
+```zsh
+cd /Users/markeyser/Projects/MyCoolApp
+sandbox start
+```
+*This instantly spins up a `python:3.11-slim` container uniquely named `flashbox-mycoolapp` and installs base tools (`git`, `rg`, `jq`, `curl`).*
+
+### AI Execution
+Instruct your AI agent to execute commands using the `exec` flag. The agent's native system terminal will push the command securely into the container:
+```bash
+sandbox exec "python3 main.py"
+sandbox exec "grep -r 'TODO' ."
+```
+
+### Telemetry Dashboard
+Launch the TUI to monitor the AI's impact on your system resources and disk space in real-time:
+```zsh
+sandbox monitor
+```
+
+### Clean Slate
+If the AI corrupts the environment or installs too many dependencies, instantly wipe the infrastructure (your code on the native host remains untouched):
+```zsh
+sandbox remove
+sandbox start
+```

flashbox-0.1.0/README.md

@@ -0,0 +1,57 @@
+# Flashbox ⚡️
+
+A lightning-fast, repository-aware persistent Docker sandbox CLI designed specifically for AI Coding Agents.
+
+Flashbox allows your AI coding agents (like Antigravity or Cursor) to safely execute terminal commands, run scripts, and compile code in an isolated Linux environment without polluting your local macOS host. It completely replaces the heavy, latency-prone Boxlite MCP server with a streamlined local Python CLI mapping directly to your Docker daemon.
+
+## Why Flashbox?
+- **Zero Token Overhead:** Unlike MCP servers, Flashbox doesn't inject massive JSON schemas into your prompt context.
+- **Dynamic Repository Mounting:** If you run `sandbox start` in `/Projects/MyCoolApp`, Flashbox dynamically mounts that specific directory to `/vault` inside a dedicated `flashbox-mycoolapp` container.
+- **Native Execution Speed:** Bypasses JSON-RPC handshakes. `sandbox exec` streams natively through `subprocess` directly to Docker.
+- **Built-in Telemetry:** Ships with a real-time TUI to monitor the active exact CPU and RAM your AI is drawing.
+
+## System Requirements
+- **Operating System:** Fully cross-platform. Tested heavily on **macOS (Apple Silicon)**, but works flawlessly on **Linux** and **Windows (via WSL2)**.
+- **Docker Daemon:** You **MUST** have the Docker engine running in the background. On macOS/Windows, this means having **Docker Desktop** or **OrbStack** open and active. On Linux, the native `docker` service must be running.
+- **Python:** Python 3.10+ installed on the host machine.
+
+## Installation
+
+Because Flashbox is packaged cleanly, you can install it globally via `pipx` or your preferred Python package manager:
+
+```zsh
+# Run this inside the cloned repo
+pipx install .
+```
+
+## Usage
+
+Once installed, the globally accessible `sandbox` command is available from any directory.
+
+### Quick Start
+Navigate to any project directory and initialize the sandbox:
+```zsh
+cd /Users/markeyser/Projects/MyCoolApp
+sandbox start
+```
+*This instantly spins up a `python:3.11-slim` container uniquely named `flashbox-mycoolapp` and installs base tools (`git`, `rg`, `jq`, `curl`).*
+
+### AI Execution
+Instruct your AI agent to execute commands using the `exec` flag. The agent's native system terminal will push the command securely into the container:
+```bash
+sandbox exec "python3 main.py"
+sandbox exec "grep -r 'TODO' ."
+```
+
+### Telemetry Dashboard
+Launch the TUI to monitor the AI's impact on your system resources and disk space in real-time:
+```zsh
+sandbox monitor
+```
+
+### Clean Slate
+If the AI corrupts the environment or installs too many dependencies, instantly wipe the infrastructure (your code on the native host remains untouched):
+```zsh
+sandbox remove
+sandbox start
+```

flashbox-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "flashbox"
+version = "0.1.0"
+description = "A dynamic, repository-aware persistent Docker sandbox CLI for AI Agents."
+readme = "README.md"
+authors = [
+    { name = "Mark Eyser", email = "markeyser@github.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "rich>=13.0.0",
+]
+keywords = ["ai", "agents", "docker", "sandbox", "mcp", "cli", "telemetry"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: Terminals",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-mock>=3.10",
+    "ruff>=0.3.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/markeyser/flashbox"
+
+[project.scripts]
+sandbox = "flashbox.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = []

flashbox-0.1.0/setup.cfg

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

flashbox-0.1.0/src/flashbox/__init__.py

@@ -0,0 +1,3 @@
+"""Flashbox package initialization."""
+
+__version__ = "0.1.0"

flashbox-0.1.0/src/flashbox/cli.py

@@ -0,0 +1,42 @@
+import argparse
+from flashbox.docker_manager import DockerManager
+from flashbox.monitor import FlashboxMonitor
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Flashbox: A dynamic, repository-aware persistent Docker sandbox CLI for AI Agents."
+    )
+    subparsers = parser.add_subparsers(dest="action", required=True)
+
+    subparsers.add_parser("start", help="Initialize and start the Flashbox for the current directory")
+    subparsers.add_parser("stop", help="Stop the active Flashbox")
+    subparsers.add_parser("remove", help="Destroy the Flashbox. Good for a clean slate rebuild.")
+    
+    # Monitor command parser
+    monitor_parser = subparsers.add_parser("monitor", help="Launch the real-time telemetry dashboard")
+    monitor_parser.add_argument("-r", "--refresh", type=float, default=1.0, help="Refresh rate in seconds")
+    
+    # Exec command parser
+    exec_parser = subparsers.add_parser("exec", help="Execute a raw bash command securely inside the sandbox")
+    exec_parser.add_argument("command", nargs="+", help="The command string to run")
+    
+    args = parser.parse_args()
+    
+    # Initialize the docker manager which dynamically detects the CWD
+    manager = DockerManager()
+
+    if args.action == "start":
+        manager.start()
+    elif args.action == "stop":
+        manager.stop()
+    elif args.action == "remove":
+        manager.remove()
+    elif args.action == "monitor":
+        monitor = FlashboxMonitor(manager)
+        monitor.run(args.refresh)
+    elif args.action == "exec":
+        # Join the command pieces back together preserving spaces
+        manager.exec_command(" ".join(args.command))
+
+if __name__ == "__main__":
+    main()

flashbox-0.1.0/src/flashbox/docker_manager.py

@@ -0,0 +1,83 @@
+import subprocess
+import sys
+import os
+import re
+
+IMAGE_NAME = "python:3.11-slim"
+
+class DockerManager:
+    def __init__(self, cwd=None):
+        self.cwd = cwd or os.getcwd()
+        self.container_name = self._generate_container_name(self.cwd)
+        self.vault_path = self.cwd
+
+    def _generate_container_name(self, path):
+        """Generates a safe, unique Docker container name based on the current directory."""
+        basename = os.path.basename(path).lower()
+        # Remove any invalid docker characters
+        safe_name = re.sub(r'[^a-zA-Z0-9_.-]', '', basename)
+        return f"flashbox-{safe_name}"
+
+    def _run_cmd(self, cmd, check=True):
+        """Executes a shell command and returns the stdout."""
+        result = subprocess.run(cmd, shell=True, text=True, capture_output=True)
+        if check and result.returncode != 0:
+            print(f"Error executing: {cmd}\n{result.stderr}", file=sys.stderr)
+            sys.exit(result.returncode)
+        return result.stdout.strip()
+
+    def is_running(self):
+        """Checks if this specific project container is currently running."""
+        out = self._run_cmd(f"docker ps -q -f name={self.container_name}", check=False)
+        return bool(out)
+
+    def start(self):
+        """Initializes the persistent container and mounts the local repo to /vault."""
+        from rich.console import Console
+        console = Console()
+
+        if self.is_running():
+            console.print(f"[yellow]Flashbox '{self.container_name}' is already running for this directory.[/yellow]")
+            return
+        
+        # Check if container exists but is stopped
+        out = self._run_cmd(f"docker ps -aq -f name={self.container_name}", check=False)
+        if out:
+            console.print(f"[cyan]Starting existing Flashbox '{self.container_name}'...[/cyan]")
+            self._run_cmd(f"docker start {self.container_name}")
+        else:
+            console.print(f"[green]Creating and starting new Flashbox '{self.container_name}'...[/green]")
+            # We mount the local directory to /vault inside the container
+            self._run_cmd(f"docker run -d --name {self.container_name} -v {self.vault_path}:/vault -w /vault {IMAGE_NAME} tail -f /dev/null")
+            
+            console.print("[cyan]Installing base AI tools (git, ripgrep, jq, curl)...[/cyan]")
+            self._run_cmd(f"docker exec {self.container_name} apt-get update")
+            self._run_cmd(f"docker exec {self.container_name} apt-get install -y git ripgrep jq curl")
+            console.print("[bold green]Flashbox initialized successfully and mounted to /vault.[/bold green]")
+
+    def stop(self):
+        """Stops the active container."""
+        from rich.console import Console
+        console = Console()
+        if not self.is_running():
+            console.print(f"[yellow]Flashbox '{self.container_name}' is not running.[/yellow]")
+            return
+        console.print(f"[cyan]Stopping Flashbox '{self.container_name}'...[/cyan]")
+        self._run_cmd(f"docker stop {self.container_name}")
+
+    def remove(self):
+        """Destroys the container. Useful for a clean slate."""
+        from rich.console import Console
+        console = Console()
+        console.print(f"[red]Destroying Flashbox '{self.container_name}'...[/red]")
+        self._run_cmd(f"docker rm -f {self.container_name}", check=False)
+        console.print("[bold green]Environment wiped successfully.[/bold green]")
+
+    def exec_command(self, command_string):
+        """Executes a raw bash command securely inside the sandbox."""
+        if not self.is_running():
+            self.start()
+        
+        # We pass the execution directly to Docker bypassing capture_output so interactive streams work
+        result = subprocess.run(["docker", "exec", "-w", "/vault", self.container_name, "bash", "-c", command_string])
+        sys.exit(result.returncode)

flashbox-0.1.0/src/flashbox/monitor.py

@@ -0,0 +1,110 @@
+import os
+import json
+import time
+from rich.console import Console
+from rich.live import Live
+from rich.table import Table
+from rich.panel import Panel
+from rich.layout import Layout
+from rich.align import Align
+import subprocess
+
+console = Console()
+
+class FlashboxMonitor:
+    def __init__(self, manager):
+        self.manager = manager
+        self.cooldown = 30 # seconds to determine "Idle" vs "Active"
+        self.last_active_time = 0
+        self.total_size = 0
+        self.total_files = 0
+        
+    def _get_docker_stats(self):
+        """Fetches real-time CPU and RAM limits from docker stats."""
+        if not self.manager.is_running():
+            return "N/A", "N/A"
+        try:
+            # We use no-stream to get a single snapshot of the active container
+            out = self.manager._run_cmd(
+                f"docker stats --no-stream --format '{{{{.CPUPerc}}}}|{{{{.MemUsage}}}}' {self.manager.container_name}", 
+                check=False
+            )
+            if out and "|" in out:
+                cpu, mem = out.split("|")
+                return cpu.strip(), mem.strip()
+            return "0.00%", "0B / 0B"
+        except Exception:
+            return "Error", "Error"
+
+    def _get_sandbox_size(self):
+        """Scans the volume mount directory specifically for its size."""
+        total_size = 0
+        total_files = 0
+        
+        for dirpath, _, filenames in os.walk(self.manager.cwd):
+            if '.git' in dirpath or '.venv' in dirpath:
+                continue
+            for f in filenames:
+                fp = os.path.join(dirpath, f)
+                if not os.path.islink(fp):
+                    try:
+                        total_size += os.path.getsize(fp)
+                        total_files += 1
+                        # Check modification time
+                        mtime = os.path.getmtime(fp)
+                        if time.time() - mtime < self.cooldown:
+                            self.last_active_time = time.time()
+                    except (OSError, FileNotFoundError):
+                        pass
+                        
+        self.total_size = total_size
+        self.total_files = total_files
+
+    def _format_size(self, size_bytes):
+        for unit in ['B', 'KB', 'MB', 'GB']:
+            if size_bytes < 1024.0:
+                return f"{size_bytes:.1f} {unit}"
+            size_bytes /= 1024.0
+        return f"{size_bytes:.1f} TB"
+
+    def generate_dashboard(self) -> Layout:
+        self._get_sandbox_size()
+        cpu, mem = self._get_docker_stats()
+        
+        is_active = (time.time() - self.last_active_time) < self.cooldown
+        status_color = "green" if is_active else "yellow"
+        status_text = "🟢 ACTIVE" if is_active else "🟡 IDLE"
+
+        # Build Metrics Table
+        metrics_table = Table(show_header=False, expand=True, box=None)
+        metrics_table.add_column("Metric", style="cyan")
+        metrics_table.add_column("Value", justify="right")
+        
+        metrics_table.add_row("Dynamic Container", self.manager.container_name)
+        metrics_table.add_row("Agent State", f"[{status_color}]{status_text}[/{status_color}]")
+        metrics_table.add_row("Mounted Vault Files", str(self.total_files))
+        metrics_table.add_row("Vault Source Vol.", self._format_size(self.total_size))
+        metrics_table.add_row("Container CPU", cpu)
+        metrics_table.add_row("Container RAM", mem)
+
+        panel = Panel(
+            Align.center(metrics_table, vertical="middle"),
+            title=f"[b blue]Flashbox Telemetry[/b blue]",
+            border_style="blue",
+        )
+        return panel
+
+    def run(self, refresh_rate=1.0):
+        if not self.manager.is_running():
+            console.print(f"[red]Flashbox '{self.manager.container_name}' is not currently running.[/red]")
+            console.print("Start it first with: [cyan]sandbox start[/cyan]")
+            return
+
+        console.clear()
+        try:
+            with Live(self.generate_dashboard(), console=console, screen=True, refresh_per_second=1/refresh_rate) as live:
+                while True:
+                    time.sleep(refresh_rate)
+                    live.update(self.generate_dashboard())
+        except KeyboardInterrupt:
+            console.print("\n[dim]Monitor stopped.[/dim]")

flashbox-0.1.0/src/flashbox.egg-info/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: flashbox
+Version: 0.1.0
+Summary: A dynamic, repository-aware persistent Docker sandbox CLI for AI Agents.
+Author-email: Mark Eyser <markeyser@github.com>
+Project-URL: Homepage, https://github.com/markeyser/flashbox
+Keywords: ai,agents,docker,sandbox,mcp,cli,telemetry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Terminals
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10; extra == "dev"
+Requires-Dist: ruff>=0.3.0; extra == "dev"
+Dynamic: license-file
+
+# Flashbox ⚡️
+
+A lightning-fast, repository-aware persistent Docker sandbox CLI designed specifically for AI Coding Agents.
+
+Flashbox allows your AI coding agents (like Antigravity or Cursor) to safely execute terminal commands, run scripts, and compile code in an isolated Linux environment without polluting your local macOS host. It completely replaces the heavy, latency-prone Boxlite MCP server with a streamlined local Python CLI mapping directly to your Docker daemon.
+
+## Why Flashbox?
+- **Zero Token Overhead:** Unlike MCP servers, Flashbox doesn't inject massive JSON schemas into your prompt context.
+- **Dynamic Repository Mounting:** If you run `sandbox start` in `/Projects/MyCoolApp`, Flashbox dynamically mounts that specific directory to `/vault` inside a dedicated `flashbox-mycoolapp` container.
+- **Native Execution Speed:** Bypasses JSON-RPC handshakes. `sandbox exec` streams natively through `subprocess` directly to Docker.
+- **Built-in Telemetry:** Ships with a real-time TUI to monitor the active exact CPU and RAM your AI is drawing.
+
+## System Requirements
+- **Operating System:** Fully cross-platform. Tested heavily on **macOS (Apple Silicon)**, but works flawlessly on **Linux** and **Windows (via WSL2)**.
+- **Docker Daemon:** You **MUST** have the Docker engine running in the background. On macOS/Windows, this means having **Docker Desktop** or **OrbStack** open and active. On Linux, the native `docker` service must be running.
+- **Python:** Python 3.10+ installed on the host machine.
+
+## Installation
+
+Because Flashbox is packaged cleanly, you can install it globally via `pipx` or your preferred Python package manager:
+
+```zsh
+# Run this inside the cloned repo
+pipx install .
+```
+
+## Usage
+
+Once installed, the globally accessible `sandbox` command is available from any directory.
+
+### Quick Start
+Navigate to any project directory and initialize the sandbox:
+```zsh
+cd /Users/markeyser/Projects/MyCoolApp
+sandbox start
+```
+*This instantly spins up a `python:3.11-slim` container uniquely named `flashbox-mycoolapp` and installs base tools (`git`, `rg`, `jq`, `curl`).*
+
+### AI Execution
+Instruct your AI agent to execute commands using the `exec` flag. The agent's native system terminal will push the command securely into the container:
+```bash
+sandbox exec "python3 main.py"
+sandbox exec "grep -r 'TODO' ."
+```
+
+### Telemetry Dashboard
+Launch the TUI to monitor the AI's impact on your system resources and disk space in real-time:
+```zsh
+sandbox monitor
+```
+
+### Clean Slate
+If the AI corrupts the environment or installs too many dependencies, instantly wipe the infrastructure (your code on the native host remains untouched):
+```zsh
+sandbox remove
+sandbox start
+```

flashbox-0.1.0/src/flashbox.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/flashbox/__init__.py
+src/flashbox/cli.py
+src/flashbox/docker_manager.py
+src/flashbox/monitor.py
+src/flashbox.egg-info/PKG-INFO
+src/flashbox.egg-info/SOURCES.txt
+src/flashbox.egg-info/dependency_links.txt
+src/flashbox.egg-info/entry_points.txt
+src/flashbox.egg-info/requires.txt
+src/flashbox.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_docker_manager.py
+tests/test_monitor.py

flashbox-0.1.0/src/flashbox.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

flashbox-0.1.0/src/flashbox.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sandbox = flashbox.cli:main

flashbox-0.1.0/src/flashbox.egg-info/requires.txt

@@ -0,0 +1,6 @@
+rich>=13.0.0
+
+[dev]
+pytest>=7.0
+pytest-mock>=3.10
+ruff>=0.3.0

flashbox-0.1.0/src/flashbox.egg-info/top_level.txt

@@ -0,0 +1 @@
+flashbox

flashbox-0.1.0/tests/test_cli.py

@@ -0,0 +1,73 @@
+import pytest
+from unittest.mock import MagicMock
+from flashbox.cli import main
+
+@pytest.fixture
+def mock_dependencies(mocker):
+    """Mocks out the DockerManager and FlashboxMonitor completely to isolate the CLI router."""
+    mock_manager_class = mocker.patch("flashbox.cli.DockerManager")
+    mock_manager_instance = mock_manager_class.return_value
+    
+    # We patch the monitor class too to avoid it initializing a Real rich UI
+    mock_monitor_class = mocker.patch("flashbox.cli.FlashboxMonitor")
+    mock_monitor_instance = mock_monitor_class.return_value
+    
+    return mock_manager_instance, mock_monitor_class, mock_monitor_instance
+
+def test_cli_start(mocker, mock_dependencies):
+    manager, _, _ = mock_dependencies
+    
+    # Simulate typing 'sandbox start' into the terminal
+    mocker.patch("sys.argv", ["sandbox", "start"])
+    main()
+    
+    manager.start.assert_called_once()
+
+def test_cli_stop(mocker, mock_dependencies):
+    manager, _, _ = mock_dependencies
+    
+    mocker.patch("sys.argv", ["sandbox", "stop"])
+    main()
+    
+    manager.stop.assert_called_once()
+
+def test_cli_remove(mocker, mock_dependencies):
+    manager, _, _ = mock_dependencies
+    
+    mocker.patch("sys.argv", ["sandbox", "remove"])
+    main()
+    
+    manager.remove.assert_called_once()
+
+def test_cli_exec(mocker, mock_dependencies):
+    """Verifies that the bash command string is rebuilt correctly from argparse nargs."""
+    manager, _, _ = mock_dependencies
+    
+    mocker.patch("sys.argv", ["sandbox", "exec", "pwd && ls -la"])
+    main()
+    
+    manager.exec_command.assert_called_once_with("pwd && ls -la")
+
+def test_cli_monitor_default(mocker, mock_dependencies):
+    manager, monitor_class, monitor_instance = mock_dependencies
+    
+    mocker.patch("sys.argv", ["sandbox", "monitor"])
+    main()
+    
+    # Verify the monitor takes ownership of the manager and launches the UI with a 1.0s refresh
+    monitor_class.assert_called_once_with(manager)
+    monitor_instance.run.assert_called_once_with(1.0)
+
+def test_cli_monitor_custom_refresh(mocker, mock_dependencies):
+    manager, monitor_class, monitor_instance = mock_dependencies
+    
+    mocker.patch("sys.argv", ["sandbox", "monitor", "-r", "0.5"])
+    main()
+    
+    monitor_instance.run.assert_called_once_with(0.5)
+
+def test_cli_missing_command(mocker):
+    """Verifies that the CLI correctly crashes and raises SystemExit if no command is given."""
+    mocker.patch("sys.argv", ["sandbox"])
+    with pytest.raises(SystemExit):
+        main()

flashbox-0.1.0/tests/test_docker_manager.py

@@ -0,0 +1,92 @@
+import os
+import sys
+import pytest
+from unittest.mock import MagicMock
+from flashbox.docker_manager import DockerManager
+
+@pytest.fixture
+def mock_run_cmd(mocker):
+    return mocker.patch("flashbox.docker_manager.DockerManager._run_cmd")
+
+@pytest.fixture
+def manager():
+    # Use a fixed path to ensure consistent naming across OS
+    return DockerManager(cwd="/Users/test/projects/My-Cool_App.1")
+
+def test_generate_container_name_strips_invalid_chars(manager):
+    """Verifies the container name strictly enforces docker character requirements."""
+    name = manager._generate_container_name("/path/with/wierd/!@#$/Repo Name!")
+    assert name == "flashbox-reponame", "Should strip spaces and special characters."
+
+    name = manager._generate_container_name("/path/normal-repo.app_1")
+    assert name == "flashbox-normal-repo.app_1", "Should retain dashes, dots, and underscores."
+
+def test_is_running_true(manager, mock_run_cmd):
+    """Tests the running check logic when container is active."""
+    mock_run_cmd.return_value = "container_id_123"
+    assert manager.is_running() is True
+    mock_run_cmd.assert_called_once_with(f"docker ps -q -f name={manager.container_name}", check=False)
+
+def test_is_running_false(manager, mock_run_cmd):
+    """Tests the running check logic when container is absent."""
+    mock_run_cmd.return_value = ""
+    assert manager.is_running() is False
+
+def test_start_already_running(manager, mock_run_cmd, mocker):
+    """If the container is already running, start should exit early."""
+    mocker.patch.object(manager, "is_running", return_value=True)
+    manager.start()
+    # It should not call any more docker commands
+    mock_run_cmd.assert_not_called()
+
+def test_start_existing_but_stopped(manager, mock_run_cmd, mocker):
+    """If the container exists but is stopped, it should use docker start instead of run."""
+    mocker.patch.object(manager, "is_running", return_value=False)
+    # Mock 'docker ps -aq' returning an ID (container exists)
+    mock_run_cmd.return_value = "container_id_123"
+    
+    manager.start()
+    
+    mock_run_cmd.assert_any_call(f"docker ps -aq -f name={manager.container_name}", check=False)
+    mock_run_cmd.assert_called_with(f"docker start {manager.container_name}")
+    # Ensure it doesn't trigger apt-get on existing containers
+    assert mock_run_cmd.call_count == 2
+
+def test_start_new_initialization(manager, mock_run_cmd, mocker):
+    """If the container is missing entirely, it must perform the full run and tool initialization sequence."""
+    mocker.patch.object(manager, "is_running", return_value=False)
+    # Mock 'docker ps -aq' returning empty string (no container)
+    mock_run_cmd.return_value = ""
+    
+    manager.start()
+    
+    # 1. ps -aq check
+    # 2. docker run
+    # 3. apt-get update
+    # 4. apt-get install
+    assert mock_run_cmd.call_count == 4
+    
+    # Check that volume mount points correctly to the init CWD
+    call_args_str = str(mock_run_cmd.mock_calls[1])
+    assert "docker run -d --name flashbox-my-cool_app.1" in call_args_str
+    assert f"-v /Users/test/projects/My-Cool_App.1:/vault" in call_args_str
+    
+def test_stop(manager, mock_run_cmd, mocker):
+    """Verify that stop properly checks state and executes the docker command."""
+    mocker.patch.object(manager, "is_running", return_value=True)
+    manager.stop()
+    mock_run_cmd.assert_called_once_with(f"docker stop {manager.container_name}")
+
+def test_exec_command_triggers_start(manager, mocker):
+    """Verify that running exec explicitly triggers a start if the sandbox is stopped."""
+    mock_start = mocker.patch.object(manager, "start")
+    mocker.patch.object(manager, "is_running", return_value=False)
+    
+    # Mock the actual system call to prevent running real 'docker exec'
+    mock_subprocess = mocker.patch("subprocess.run")
+    mock_exit = mocker.patch("sys.exit")
+    
+    manager.exec_command("echo hello")
+    
+    mock_start.assert_called_once()
+    mock_subprocess.assert_called_once()

flashbox-0.1.0/tests/test_monitor.py

@@ -0,0 +1,114 @@
+import os
+import time
+import pytest
+from unittest.mock import MagicMock
+from flashbox.monitor import FlashboxMonitor
+from flashbox.docker_manager import DockerManager
+
+@pytest.fixture
+def manager(mocker):
+    # Mock manager to isolate monitor logic
+    mgr = MagicMock(spec=DockerManager)
+    mgr.cwd = "/fake/repo/path"
+    mgr.container_name = "flashbox-fake-repo"
+    mgr.is_running.return_value = True
+    return mgr
+
+@pytest.fixture
+def monitor(manager):
+    return FlashboxMonitor(manager)
+
+def test_get_docker_stats_success(monitor, manager):
+    """Verifies that the raw output from docker stats is parsed correctly."""
+    manager._run_cmd.return_value = "5.50%|150MiB / 2GiB"
+    cpu, mem = monitor._get_docker_stats()
+    
+    # Needs to match the docker stats command signature in the monitor
+    manager._run_cmd.assert_called_once_with(
+        f"docker stats --no-stream --format '{{{{.CPUPerc}}}}|{{{{.MemUsage}}}}' {manager.container_name}",
+        check=False
+    )
+    assert cpu == "5.50%"
+    assert mem == "150MiB / 2GiB"
+
+def test_get_docker_stats_not_running(monitor, manager):
+    manager.is_running.return_value = False
+    cpu, mem = monitor._get_docker_stats()
+    assert cpu == "N/A"
+    assert mem == "N/A"
+
+def test_get_docker_stats_error_handling(monitor, manager):
+    """Verifies the monitor degrades gracefully if the docker daemon fails to return stats."""
+    manager._run_cmd.side_effect = Exception("Docker daemon dead")
+    cpu, mem = monitor._get_docker_stats()
+    assert cpu == "Error"
+    assert mem == "Error"
+
+def test_format_size(monitor):
+    """Verifies the iterative bytes to human readable formatting logic."""
+    assert monitor._format_size(500) == "500.0 B"
+    assert monitor._format_size(1024) == "1.0 KB"
+    assert monitor._format_size(1024 * 1024 * 5) == "5.0 MB"
+    assert monitor._format_size(1024 * 1024 * 1024 * 2.5) == "2.5 GB"
+
+def test_get_sandbox_size_filtering_and_calculation(monitor, mocker):
+    """
+    Very important test: The sandbox scans the host volume to detect changes.
+    It MUST skip .git and .venv folders, and properly evaluate file modification times.
+    """
+    # Mocking os.walk to return a fake file structure
+    # Structure: 
+    # /fake/repo/path/
+    #   - file1.py (size 100)
+    #   - .git/
+    #       - obj1.pack (size 5000) -> SHOULD BE SKIPPED
+    #   - .venv/
+    #       - bin/python (size 2000) -> SHOULD BE SKIPPED
+    #   - src/
+    #       - file2.py (size 300)
+    
+    mock_walk = mocker.patch("os.walk")
+    mock_walk.return_value = [
+        ("/fake/repo/path", ("src", ".git", ".venv"), ("file1.py",)),
+        ("/fake/repo/path/.git", (), ("obj1.pack",)),
+        ("/fake/repo/path/.venv", ("bin",), ()),
+        ("/fake/repo/path/.venv/bin", (), ("python",)),
+        ("/fake/repo/path/src", (), ("file2.py",)),
+    ]
+    
+    # Mock sizes
+    def mock_getsize(path):
+        sizes = {
+            "/fake/repo/path/file1.py": 100,
+            "/fake/repo/path/src/file2.py": 300,
+            # We add these just to ensure they don't break if mistakenly called
+            "/fake/repo/path/.git/obj1.pack": 5000,
+            "/fake/repo/path/.venv/bin/python": 2000,
+        }
+        return sizes.get(path, 0)
+    
+    mocker.patch("os.path.getsize", side_effect=mock_getsize)
+    mocker.patch("os.path.islink", return_value=False)
+    
+    # Mock the time so we can check activity tracking
+    current_time = 1000.0
+    mocker.patch("time.time", return_value=current_time)
+    
+    def mock_getmtime(path):
+        # file1.py is old (idle)
+        # file2.py is new (active, modified 5 seconds ago)
+        times = {
+            "/fake/repo/path/file1.py": current_time - 100,
+            "/fake/repo/path/src/file2.py": current_time - 5,
+        }
+        return times.get(path, current_time - 100)
+        
+    mocker.patch("os.path.getmtime", side_effect=mock_getmtime)
+    
+    # Execute
+    monitor._get_sandbox_size()
+    
+    # Asserts
+    assert monitor.total_files == 2, "Should only count file1.py and file2.py, skipping .git and .venv"
+    assert monitor.total_size == 400, "Should sum up size of file1.py and file2.py only"
+    assert monitor.last_active_time == current_time, "Since file2 was recently edited, active time should be updated to check time"