docketeer-subprocess 0.0.16__tar.gz

docketeer_subprocess-0.0.16/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+.envrc.private
+.claude/settings.local.json
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+workspace/
+.coverage
+.loq_cache
+.python-version

docketeer_subprocess-0.0.16/CLAUDE.md

@@ -0,0 +1,17 @@
+# docketeer-subprocess
+
+Unsandboxed subprocess command execution. Implements the `docketeer.executor`
+entry point for environments where bubblewrap is unavailable or redundant.
+
+## Structure
+
+- **`executor.py`** — the `SubprocessExecutor`. Runs commands as plain
+  subprocesses. Uses the first mount's `source` as `cwd`. Ignores sandbox
+  parameters (network_access, username, mounts for remapping).
+- **`mcp_bridge.py`** — copied from bubblewrap, bridges Claude's stdio-based
+  MCP transport to the docketeer unix socket. Stdlib-only.
+
+## Testing
+
+Tests mock `asyncio.create_subprocess_exec`. No real subprocesses are spawned
+in tests. Verify cwd selection, env merging, and claude arg construction.

docketeer_subprocess-0.0.16/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: docketeer-subprocess
+Version: 0.0.16
+Summary: Unsandboxed subprocess executor plugin for Docketeer
+Project-URL: Homepage, https://github.com/chrisguidry/docketeer
+Project-URL: Repository, https://github.com/chrisguidry/docketeer
+Project-URL: Issues, https://github.com/chrisguidry/docketeer/issues
+Author-email: Chris Guidry <guid@omg.lol>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Requires-Dist: docketeer
+Description-Content-Type: text/markdown
+
+# docketeer-subprocess
+
+Unsandboxed command execution for [Docketeer](https://github.com/chrisguidry/docketeer)
+using plain subprocesses.
+
+This plugin provides a `CommandExecutor` implementation that runs external
+programs directly as subprocesses of the current process, with no sandboxing.
+
+## When to use this
+
+Use `docketeer-subprocess` instead of `docketeer-bubblewrap` when:
+
+- Running inside a **container** (Docker, Podman, etc.) that already provides
+  isolation
+- Running on a **non-Linux host** where bubblewrap isn't available (macOS,
+  Windows/WSL)
+- Running on a **dedicated machine** where the overhead of namespace isolation
+  isn't needed
+- You don't have unprivileged user namespaces enabled
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DOCKETEER_EXECUTOR` | _(auto)_ | Set to `subprocess` when both executor plugins are installed |
+
+If `docketeer-subprocess` is the only executor plugin installed, it's selected
+automatically. If both `docketeer-bubblewrap` and `docketeer-subprocess` are
+installed, set `DOCKETEER_EXECUTOR=subprocess` to choose this one.
+
+## How it works
+
+The executor runs commands via `asyncio.create_subprocess_exec` with the
+current user's environment. The `CommandExecutor` ABC parameters are handled
+as follows:
+
+- **`mounts`** — accepted but not used for filesystem remapping. The first
+  mount's `source` is used as the working directory.
+- **`network_access`** — ignored (always available)
+- **`username`** — ignored (runs as current user)
+- **`env`** — merged with `os.environ`, caller values override
+
+The `start_claude` method launches `claude -p` with an MCP bridge that
+connects Claude's stdio transport to docketeer's unix socket, the same way
+the bubblewrap executor does.

docketeer_subprocess-0.0.16/README.md

@@ -0,0 +1,45 @@
+# docketeer-subprocess
+
+Unsandboxed command execution for [Docketeer](https://github.com/chrisguidry/docketeer)
+using plain subprocesses.
+
+This plugin provides a `CommandExecutor` implementation that runs external
+programs directly as subprocesses of the current process, with no sandboxing.
+
+## When to use this
+
+Use `docketeer-subprocess` instead of `docketeer-bubblewrap` when:
+
+- Running inside a **container** (Docker, Podman, etc.) that already provides
+  isolation
+- Running on a **non-Linux host** where bubblewrap isn't available (macOS,
+  Windows/WSL)
+- Running on a **dedicated machine** where the overhead of namespace isolation
+  isn't needed
+- You don't have unprivileged user namespaces enabled
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DOCKETEER_EXECUTOR` | _(auto)_ | Set to `subprocess` when both executor plugins are installed |
+
+If `docketeer-subprocess` is the only executor plugin installed, it's selected
+automatically. If both `docketeer-bubblewrap` and `docketeer-subprocess` are
+installed, set `DOCKETEER_EXECUTOR=subprocess` to choose this one.
+
+## How it works
+
+The executor runs commands via `asyncio.create_subprocess_exec` with the
+current user's environment. The `CommandExecutor` ABC parameters are handled
+as follows:
+
+- **`mounts`** — accepted but not used for filesystem remapping. The first
+  mount's `source` is used as the working directory.
+- **`network_access`** — ignored (always available)
+- **`username`** — ignored (runs as current user)
+- **`env`** — merged with `os.environ`, caller values override
+
+The `start_claude` method launches `claude -p` with an MCP bridge that
+connects Claude's stdio transport to docketeer's unix socket, the same way
+the bubblewrap executor does.

docketeer_subprocess-0.0.16/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "docketeer-subprocess"
+dynamic = ["version"]
+description = "Unsandboxed subprocess executor plugin for Docketeer"
+readme = "README.md"
+authors = [
+    { name = "Chris Guidry", email = "guid@omg.lol" }
+]
+license = "MIT"
+requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "docketeer",
+]
+
+[project.urls]
+Homepage = "https://github.com/chrisguidry/docketeer"
+Repository = "https://github.com/chrisguidry/docketeer"
+Issues = "https://github.com/chrisguidry/docketeer/issues"
+
+[project.entry-points."docketeer.executor"]
+subprocess = "docketeer_subprocess"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+raw-options.root = ".."
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/docketeer_subprocess"]
+
+[tool.uv.sources]
+docketeer = { workspace = true }
+
+[tool.pytest.ini_options]
+minversion = "9.0"
+timeout = 1
+addopts = [
+    "--import-mode=importlib",
+    "--cov=docketeer_subprocess",
+    "--cov=tests",
+    "--cov-branch",
+    "--cov-report=term-missing",
+    "--cov-fail-under=100",
+]
+asyncio_mode = "auto"
+filterwarnings = [
+    "error",
+]

docketeer_subprocess-0.0.16/src/docketeer_subprocess/__init__.py

@@ -0,0 +1,8 @@
+from docketeer_subprocess.executor import SubprocessExecutor
+
+
+def create_executor() -> SubprocessExecutor:
+    return SubprocessExecutor()
+
+
+__all__ = ["SubprocessExecutor", "create_executor"]

docketeer_subprocess-0.0.16/src/docketeer_subprocess/executor.py

@@ -0,0 +1,88 @@
+"""Unsandboxed subprocess command executor."""
+
+import asyncio
+import json
+import os
+import shutil
+from pathlib import Path
+
+from docketeer.executor import (
+    ClaudeInvocation,
+    CommandExecutor,
+    Mount,
+    RunningProcess,
+)
+
+_MCP_BRIDGE_PATH = Path(__file__).resolve().parent / "mcp_bridge.py"
+
+
+class SubprocessExecutor(CommandExecutor):
+    """Runs commands as plain subprocesses with no sandboxing."""
+
+    async def start(
+        self,
+        command: list[str],
+        *,
+        env: dict[str, str] | None = None,
+        mounts: list[Mount] | None = None,
+        network_access: bool = False,
+        username: str | None = None,
+    ) -> RunningProcess:
+        merged_env = dict(os.environ)
+        if env:
+            merged_env.update(env)
+
+        cwd: Path | None = None
+        if mounts:
+            cwd = mounts[0].source
+
+        process = await asyncio.create_subprocess_exec(
+            *command,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=merged_env,
+            cwd=cwd,
+        )
+        return RunningProcess(process)
+
+    async def start_claude(  # pragma: no cover — integration path
+        self,
+        invocation: ClaudeInvocation,
+        *,
+        env: dict[str, str] | None = None,
+    ) -> RunningProcess:
+        claude_path = shutil.which("claude")
+        if not claude_path:
+            raise RuntimeError("claude not found on PATH")
+
+        args: list[str] = [claude_path, "--tools", ""]
+
+        if invocation.mcp_socket_path:
+            mcp_config = json.dumps(
+                {
+                    "mcpServers": {
+                        "docketeer": {
+                            "command": "python3",
+                            "args": [
+                                str(_MCP_BRIDGE_PATH),
+                                str(invocation.mcp_socket_path),
+                            ],
+                        }
+                    }
+                }
+            )
+            args.extend(["--mcp-config", mcp_config])
+
+        args.extend(invocation.claude_args)
+
+        process = await asyncio.create_subprocess_exec(
+            *args,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=env,
+            cwd=invocation.workspace,
+            limit=10 * 1024 * 1024,
+        )
+        return RunningProcess(process)

docketeer_subprocess-0.0.16/src/docketeer_subprocess/mcp_bridge.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""MCP bridge: relays stdin/stdout to a Unix domain socket.
+
+Stdlib-only so it can run inside a minimal sandbox without any
+pip-installed packages.
+
+Usage: python3 mcp_bridge.py <socket_path>
+"""
+
+import contextlib
+import socket
+import sys
+import threading
+from typing import BinaryIO
+
+
+def relay(
+    sock: socket.socket,
+    stdin: BinaryIO,
+    stdout: BinaryIO,
+) -> None:
+    """Relay newline-delimited messages between stdin/stdout and a socket.
+
+    Reads from stdin and forwards to the socket in a background thread.
+    Reads from the socket and writes to stdout in the calling thread.
+    Returns when the socket closes or stdin reaches EOF.
+    """
+
+    def stdin_to_socket() -> None:
+        try:
+            while True:
+                line = stdin.readline()
+                if not line:
+                    break
+                sock.sendall(line)
+        except (BrokenPipeError, OSError):
+            pass
+        finally:
+            with contextlib.suppress(OSError):
+                sock.shutdown(socket.SHUT_WR)
+
+    writer = threading.Thread(target=stdin_to_socket, daemon=True)
+    writer.start()
+
+    buf = b""
+    try:
+        while True:
+            data = sock.recv(4096)
+            if not data:
+                break
+            buf += data
+            while b"\n" in buf:
+                line, buf = buf.split(b"\n", 1)
+                stdout.write(line + b"\n")
+                stdout.flush()
+    except (BrokenPipeError, OSError):
+        pass
+    finally:
+        sock.close()
+
+
+def main() -> None:
+    if len(sys.argv) != 2:
+        print("Usage: mcp_bridge.py <socket_path>", file=sys.stderr)
+        sys.exit(1)
+
+    socket_path = sys.argv[1]
+    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    sock.connect(socket_path)
+    relay(sock, sys.stdin.buffer, sys.stdout.buffer)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

docketeer_subprocess-0.0.16/tests/test_executor.py

@@ -0,0 +1,115 @@
+"""Tests for the subprocess executor."""
+
+import asyncio
+import os
+from pathlib import Path
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from docketeer.executor import Mount
+from docketeer_subprocess import SubprocessExecutor, create_executor
+
+
+def test_create_executor():
+    executor = create_executor()
+    assert isinstance(executor, SubprocessExecutor)
+
+
+@pytest.fixture()
+def mock_process() -> AsyncMock:
+    proc = AsyncMock(spec=asyncio.subprocess.Process)
+    proc.pid = 42
+    proc.stdin = AsyncMock()
+    proc.stdout = AsyncMock()
+    proc.stderr = AsyncMock()
+    proc.returncode = 0
+    proc.communicate = AsyncMock(return_value=(b"out", b"err"))
+    return proc
+
+
+# --- start() ---
+
+
+async def test_start_runs_command(mock_process: AsyncMock):
+    executor = SubprocessExecutor()
+    with patch("docketeer_subprocess.executor.asyncio") as mock_asyncio:
+        mock_asyncio.subprocess = asyncio.subprocess
+        mock_asyncio.create_subprocess_exec = AsyncMock(return_value=mock_process)
+
+        rp = await executor.start(["echo", "hello"])
+
+    mock_asyncio.create_subprocess_exec.assert_called_once()
+    call_args = mock_asyncio.create_subprocess_exec.call_args
+    assert call_args[0] == ("echo", "hello")
+    assert rp.pid == 42
+
+
+async def test_start_merges_env(mock_process: AsyncMock):
+    executor = SubprocessExecutor()
+    with patch("docketeer_subprocess.executor.asyncio") as mock_asyncio:
+        mock_asyncio.subprocess = asyncio.subprocess
+        mock_asyncio.create_subprocess_exec = AsyncMock(return_value=mock_process)
+
+        await executor.start(["env"], env={"MY_VAR": "test_value"})
+
+    call_kwargs = mock_asyncio.create_subprocess_exec.call_args[1]
+    assert call_kwargs["env"]["MY_VAR"] == "test_value"
+    assert "PATH" in call_kwargs["env"]
+
+
+async def test_start_uses_first_mount_as_cwd(mock_process: AsyncMock, tmp_path: Path):
+    executor = SubprocessExecutor()
+    mounts = [
+        Mount(source=tmp_path, target=Path("/workspace"), writable=True),
+        Mount(source=Path("/other"), target=Path("/mnt/other")),
+    ]
+    with patch("docketeer_subprocess.executor.asyncio") as mock_asyncio:
+        mock_asyncio.subprocess = asyncio.subprocess
+        mock_asyncio.create_subprocess_exec = AsyncMock(return_value=mock_process)
+
+        await executor.start(["ls"], mounts=mounts)
+
+    call_kwargs = mock_asyncio.create_subprocess_exec.call_args[1]
+    assert call_kwargs["cwd"] == tmp_path
+
+
+async def test_start_no_cwd_without_mounts(mock_process: AsyncMock):
+    executor = SubprocessExecutor()
+    with patch("docketeer_subprocess.executor.asyncio") as mock_asyncio:
+        mock_asyncio.subprocess = asyncio.subprocess
+        mock_asyncio.create_subprocess_exec = AsyncMock(return_value=mock_process)
+
+        await executor.start(["ls"])
+
+    call_kwargs = mock_asyncio.create_subprocess_exec.call_args[1]
+    assert call_kwargs["cwd"] is None
+
+
+async def test_start_ignores_network_and_username(mock_process: AsyncMock):
+    executor = SubprocessExecutor()
+    with patch("docketeer_subprocess.executor.asyncio") as mock_asyncio:
+        mock_asyncio.subprocess = asyncio.subprocess
+        mock_asyncio.create_subprocess_exec = AsyncMock(return_value=mock_process)
+
+        rp = await executor.start(
+            ["echo", "hi"],
+            network_access=True,
+            username="someone",
+        )
+
+    result = await rp.wait()
+    assert result.returncode == 0
+
+
+async def test_start_env_overrides_inherited(mock_process: AsyncMock):
+    executor = SubprocessExecutor()
+    with patch.dict(os.environ, {"PATH": "/original"}):
+        with patch("docketeer_subprocess.executor.asyncio") as mock_asyncio:
+            mock_asyncio.subprocess = asyncio.subprocess
+            mock_asyncio.create_subprocess_exec = AsyncMock(return_value=mock_process)
+
+            await executor.start(["ls"], env={"PATH": "/custom"})
+
+    call_kwargs = mock_asyncio.create_subprocess_exec.call_args[1]
+    assert call_kwargs["env"]["PATH"] == "/custom"

docketeer_subprocess-0.0.16/tests/test_mcp_bridge.py

@@ -0,0 +1,184 @@
+"""Tests for the MCP bridge relay function."""
+
+import io
+import socket
+import threading
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from docketeer_subprocess.mcp_bridge import main, relay
+
+
+def test_relay_forwards_stdin_to_socket(tmp_path: Path):
+    """Data written to stdin arrives on the socket server."""
+    socket_path = tmp_path / "test.sock"
+
+    server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    server.bind(str(socket_path))
+    server.listen(1)
+
+    client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    client.connect(str(socket_path))
+
+    conn, _ = server.accept()
+
+    stdin = io.BytesIO(b'{"method":"ping"}\n')
+    stdout = io.BytesIO()
+
+    def accept_and_close() -> None:
+        data = conn.recv(4096)
+        received.append(data)
+        conn.close()
+
+    received: list[bytes] = []
+    t = threading.Thread(target=accept_and_close)
+    t.start()
+
+    relay(client, stdin, stdout)
+
+    t.join(timeout=5)
+    server.close()
+
+    assert received[0] == b'{"method":"ping"}\n'
+
+
+def test_relay_forwards_socket_to_stdout(tmp_path: Path):
+    """Data sent by the socket server arrives on stdout."""
+    socket_path = tmp_path / "test.sock"
+
+    server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    server.bind(str(socket_path))
+    server.listen(1)
+
+    client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    client.connect(str(socket_path))
+
+    conn, _ = server.accept()
+
+    stdin = io.BytesIO(b"")  # EOF immediately
+    stdout = io.BytesIO()
+
+    conn.sendall(b'{"result":"ok"}\n')
+    conn.close()
+
+    relay(client, stdin, stdout)
+    server.close()
+
+    assert stdout.getvalue() == b'{"result":"ok"}\n'
+
+
+def test_relay_exits_when_socket_closes(tmp_path: Path):
+    """relay() returns when the server closes the connection."""
+    socket_path = tmp_path / "test.sock"
+
+    server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    server.bind(str(socket_path))
+    server.listen(1)
+
+    client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    client.connect(str(socket_path))
+
+    conn, _ = server.accept()
+    conn.close()
+
+    stdin = io.BytesIO(b"")
+    stdout = io.BytesIO()
+
+    relay(client, stdin, stdout)
+    server.close()
+
+    assert stdout.getvalue() == b""
+
+
+def test_relay_handles_broken_pipe_on_send(tmp_path: Path):
+    """stdin_to_socket catches BrokenPipeError when the socket is closed."""
+    socket_path = tmp_path / "test.sock"
+
+    server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    server.bind(str(socket_path))
+    server.listen(1)
+
+    client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    client.connect(str(socket_path))
+
+    conn, _ = server.accept()
+
+    conn.close()
+
+    stdin = io.BytesIO(b'{"method":"ping"}\n')
+    stdout = io.BytesIO()
+
+    relay(client, stdin, stdout)
+    server.close()
+
+
+def test_relay_handles_recv_error():
+    """Main recv loop catches OSError when the socket errors mid-stream."""
+    mock_sock = MagicMock(spec=socket.socket)
+    mock_sock.recv.side_effect = OSError("connection reset")
+
+    stdin = io.BytesIO(b"")
+    stdout = io.BytesIO()
+
+    relay(mock_sock, stdin, stdout)
+    mock_sock.close.assert_called_once()
+
+
+def test_relay_handles_shutdown_error_after_stdin_eof():
+    """stdin_to_socket catches OSError if shutdown(SHUT_WR) fails."""
+    mock_sock = MagicMock(spec=socket.socket)
+    mock_sock.shutdown.side_effect = OSError("already closed")
+    mock_sock.recv.return_value = b""
+
+    stdin = io.BytesIO(b"")
+    stdout = io.BytesIO()
+
+    relay(mock_sock, stdin, stdout)
+
+
+def test_main_requires_socket_argument():
+    """main() exits with code 1 when no arguments are provided."""
+    with patch("sys.argv", ["mcp_bridge.py"]):
+        with pytest.raises(SystemExit) as exc_info:
+            main()
+    assert exc_info.value.code == 1
+
+
+def test_main_connects_and_relays(tmp_path: Path):
+    """main() connects to the socket and relays data."""
+    socket_path = tmp_path / "test.sock"
+
+    server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    server.bind(str(socket_path))
+    server.listen(1)
+
+    def server_handler() -> None:
+        conn, _ = server.accept()
+        conn.sendall(b'{"result":"ok"}\n')
+        conn.close()
+
+    t = threading.Thread(target=server_handler)
+    t.start()
+
+    stdin_mock = MagicMock()
+    stdin_mock.buffer = io.BytesIO(b"")
+    stdout_mock = MagicMock()
+    stdout_buf = io.BytesIO()
+    stdout_mock.buffer = stdout_buf
+
+    with (
+        patch("sys.argv", ["mcp_bridge.py", str(socket_path)]),
+        patch("docketeer_subprocess.mcp_bridge.sys") as mock_sys,
+    ):
+        mock_sys.argv = ["mcp_bridge.py", str(socket_path)]
+        mock_sys.stdin.buffer = io.BytesIO(b"")
+        mock_sys.stdout.buffer = stdout_buf
+        mock_sys.stderr = MagicMock()
+        main()
+
+    t.join(timeout=5)
+    server.close()
+
+    assert stdout_buf.getvalue() == b'{"result":"ok"}\n'