command-gate 0.2.4__py3-none-any.whl

cgate/helper/waiter.py

@@ -0,0 +1,123 @@
+"""Pure, mockable primitives used by ``cgate.helper.__main__``.
+
+Kept separate from the argparse entry point so tests can exercise the
+actual wait/retry/safety logic without going through subprocess spawning.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import sys
+import time
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+# WaitForSingleObject return codes (winbase.h).
+_WAIT_OBJECT_0 = 0x00000000
+_WAIT_TIMEOUT = 0x00000102
+# Rights needed only to wait on the handle, not to inspect/control the process.
+_SYNCHRONIZE = 0x00100000
+
+
+def _pid_alive(pid: int) -> bool:
+    """Return whether a process with this PID is still running.
+
+    Windows-only: uses ``OpenProcess`` + ``WaitForSingleObject`` (a zero
+    timeout, so this never blocks) instead of shelling out to
+    ``tasklist``/WMI, since this runs in a tight poll loop. A process
+    handle becomes signaled the instant the process terminates, so a
+    ``WAIT_TIMEOUT`` result means "still running"; ``OpenProcess`` failing
+    outright means the PID has already exited (or never existed).
+    """
+    if sys.platform != "win32":
+        return False
+    kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined]
+    handle = kernel32.OpenProcess(_SYNCHRONIZE, False, pid)  # noqa: FBT003 -- Win32 ABI positional arg
+    if not handle:
+        return False
+    try:
+        return kernel32.WaitForSingleObject(handle, 0) == _WAIT_TIMEOUT
+    finally:
+        kernel32.CloseHandle(handle)
+
+
+def wait_for_pids(pids: list[int], *, timeout: float = 30.0, poll_interval: float = 0.25) -> bool:
+    """Block until every PID in ``pids`` has exited, or ``timeout`` elapses.
+
+    Returns True if all exited within the timeout, False otherwise. This
+    is a best-effort wait, not a hard precondition -- the caller proceeds
+    with the file operation (and its own retry loop) either way, so a
+    timeout here just means "start the retries a bit early."
+    """
+    deadline = time.monotonic() + timeout
+    remaining = set(pids)
+    while remaining and time.monotonic() < deadline:
+        remaining = {pid for pid in remaining if _pid_alive(pid)}
+        if remaining:
+            time.sleep(poll_interval)
+    return not remaining
+
+
+def retry_replace(
+    source: Path, target: Path, *, total_seconds: float = 10.0, interval: float = 1.0
+) -> str | None:
+    """Retry moving ``source`` onto ``target`` for up to ``total_seconds``.
+
+    Mirrors ``cgate.update.replace_binary``'s return contract: None on
+    success, an error description string on failure. Retries absorb a
+    lingering AV scan or a slow-to-release OS handle after the process
+    being replaced has already exited.
+    """
+    deadline = time.monotonic() + total_seconds
+    last_error = "no attempts made"
+    while True:
+        try:
+            source.replace(target)
+        except OSError as exc:
+            last_error = f"{type(exc).__name__}: {exc}"
+            if time.monotonic() >= deadline:
+                return last_error
+            time.sleep(interval)
+        else:
+            return None
+
+
+def retry_delete(target: Path, *, total_seconds: float = 10.0, interval: float = 1.0) -> str | None:
+    """Retry deleting ``target`` for up to ``total_seconds``. Same contract as ``retry_replace``."""
+    deadline = time.monotonic() + total_seconds
+    last_error = "no attempts made"
+    while True:
+        try:
+            target.unlink()
+        except OSError as exc:
+            last_error = f"{type(exc).__name__}: {exc}"
+            if time.monotonic() >= deadline:
+                return last_error
+            time.sleep(interval)
+        else:
+            return None
+
+
+TARGET_NAMES: frozenset[str] = frozenset({"cgate.exe", "cgate-helper.exe"})
+SOURCE_NAMES: frozenset[str] = frozenset({"cgate.exe.new", "cgate-helper.exe.new"})
+
+
+def is_safe_target(
+    path: Path, *, helper_dir: Path, allowed_names: frozenset[str] = TARGET_NAMES
+) -> bool:
+    """Refuse to touch anything outside the helper's own install directory.
+
+    Not a security boundary -- a caller that controls the helper's
+    location also controls this argument. It's a sanity rail against
+    bugs: a wrong path slipping through should fail loudly instead of
+    silently deleting or overwriting something unexpected. ``allowed_names``
+    differs for a ``replace``'s source (the staged ``*.new`` download) vs.
+    either operation's target (the live ``cgate.exe``/``cgate-helper.exe``).
+    """
+    try:
+        same_dir = path.resolve().parent == helper_dir.resolve()
+    except OSError:
+        return False
+    return same_dir and path.name.lower() in allowed_names

cgate/mcp_installer.py

@@ -0,0 +1,161 @@
+"""Detect IA clients and register cgate's MCP server."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final, TypeAlias
+
+JsonScalar: TypeAlias = str | int | float | bool | None
+JsonValue: TypeAlias = JsonScalar | list["JsonValue"] | dict[str, "JsonValue"]
+JsonObject: TypeAlias = dict[str, JsonValue]
+
+
+@dataclass(frozen=True, slots=True)
+class ClientSpec:
+    """Everything cgate needs to know about one supported IA client.
+
+    Kept as a single record per client (issue #18) so adding a client is
+    one atomic edit to ``CLIENTS`` instead of three parallel dicts that
+    can silently drift out of sync and surface as a ``KeyError`` far from
+    the point where a client was actually added.
+    """
+
+    label: str
+    # Multiple paths because some clients (notably Claude Code) store MCP
+    # config in more than one location, ordered by precedence: when a
+    # client is detected, the FIRST existing path is used as the primary
+    # config_path for register/unregister/is_registered. Paths are home-
+    # relative and joined with Path.home() at detection time.
+    config_paths: tuple[str, ...]
+    config_key: str
+
+
+CLIENTS: Final[dict[str, ClientSpec]] = {
+    "claude": ClientSpec(
+        label="Claude Code",
+        # Claude Code does NOT use ``~/.claude/mcp.json`` -- it stores MCP
+        # servers in ``~/.claude.json`` (legacy global) or
+        # ``~/.claude/settings.json`` (project-level global). The first
+        # existing one wins. See issue #2.
+        config_paths=(".claude.json", ".claude/settings.json"),
+        config_key="mcpServers",
+    ),
+    "opencode": ClientSpec(
+        label="opencode",
+        config_paths=(".config/opencode/opencode.jsonc",),
+        config_key="mcp",
+    ),
+    "cursor": ClientSpec(
+        label="Cursor",
+        config_paths=(".cursor/mcp.json",),
+        config_key="mcpServers",
+    ),
+}
+CONFIG_SERVER_ENTRY_KEY: Final = "cgate"
+
+
+@dataclass(frozen=True, slots=True)
+class ClientInstall:
+    """One installed IA client and its config file path."""
+
+    name: str
+    label: str
+    config_path: Path
+
+
+def detect_clients() -> list[ClientInstall]:
+    """Return IA clients whose config file exists under the user's home.
+
+    A client is considered "installed" if ANY of the paths listed for it
+    in ``CLIENTS`` exists. When several paths exist (Claude Code can have
+    both ``~/.claude.json`` and ``~/.claude/settings.json``), the FIRST
+    existing path is returned so register/unregister write back to the
+    same file that was detected.
+    """
+    home = Path.home()
+    found: list[ClientInstall] = []
+    for name, spec in CLIENTS.items():
+        for relative in spec.config_paths:
+            candidate = home / relative
+            if candidate.exists():
+                found.append(ClientInstall(name=name, label=spec.label, config_path=candidate))
+                break
+    return found
+
+
+def read_json(path: Path) -> JsonObject:
+    """Read a JSON config, returning an empty config when missing or invalid."""
+    try:
+        with path.open(encoding="utf-8") as stream:
+            data: JsonObject = json.load(stream)
+    except (FileNotFoundError, json.JSONDecodeError, UnicodeDecodeError):
+        return {}
+    return data
+
+
+def write_json_atomic(path: Path, data: JsonObject) -> None:
+    """Back up a config, then durably write and atomically replace it."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(path.suffix + ".tmp")
+    try:
+        if path.exists():
+            _ = shutil.copyfile(path, path.with_suffix(path.suffix + ".bak"))
+        with temporary.open("w", encoding="utf-8") as stream:
+            json.dump(data, stream, indent=2)
+            _ = stream.write("\n")
+            stream.flush()
+            _ = os.fsync(stream.fileno())
+        _ = temporary.replace(path)
+    except OSError:
+        temporary.unlink(missing_ok=True)
+        raise
+
+
+def current_binary_command() -> tuple[str, list[str]]:
+    """Return the command and arguments clients use to launch cgate's MCP server."""
+    executable = Path(sys.executable).resolve()
+    if executable.name.startswith("cgate"):
+        return str(executable), ["mcp", "serve"]
+    return sys.executable, ["-m", "cgate.mcp_server"]
+
+
+def register(client: ClientInstall, command: str, args: list[str]) -> None:
+    """Add or update the client's cgate entry idempotently."""
+    config = read_json(client.config_path)
+    config_key = CLIENTS[client.name].config_key
+    bucket_value = config.get(config_key)
+    bucket: JsonObject = bucket_value if isinstance(bucket_value, dict) else {}
+    entry_args: list[JsonValue] = [*args]
+    if client.name == "opencode":
+        entry: JsonObject = {
+            "type": "local",
+            "command": [command, *entry_args],
+        }
+    else:
+        entry = {"command": command, "args": entry_args}
+    bucket[CONFIG_SERVER_ENTRY_KEY] = entry
+    config[config_key] = bucket
+    write_json_atomic(client.config_path, config)
+
+
+def unregister(client: ClientInstall) -> bool:
+    """Remove cgate from a client's config and report whether it was present."""
+    config = read_json(client.config_path)
+    config_key = CLIENTS[client.name].config_key
+    bucket_value = config.get(config_key)
+    if not isinstance(bucket_value, dict) or CONFIG_SERVER_ENTRY_KEY not in bucket_value:
+        return False
+    del bucket_value[CONFIG_SERVER_ENTRY_KEY]
+    write_json_atomic(client.config_path, config)
+    return True
+
+
+def is_registered(client: ClientInstall) -> bool:
+    """Return whether the client's config contains a cgate MCP entry."""
+    bucket = read_json(client.config_path).get(CLIENTS[client.name].config_key)
+    return isinstance(bucket, dict) and CONFIG_SERVER_ENTRY_KEY in bucket

cgate/mcp_server/__init__.py

@@ -0,0 +1,6 @@
+"""MCP server exposing three tools to AI agents (spec §The MCP server)."""
+from __future__ import annotations
+
+from cgate.mcp_server.server import build_server
+
+__all__ = ["build_server"]

cgate/mcp_server/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m cgate.mcp_server`` to run the stdio server."""
+
+from cgate.mcp_server.server import main
+
+if __name__ == "__main__":
+    main()

cgate/mcp_server/auto_resolution.py

@@ -0,0 +1,80 @@
+"""Resolve whether a proposed command queues for approval or executes immediately."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal, TypedDict
+
+from cgate.db.mode import AppModeNotSetError, Mode
+
+if TYPE_CHECKING:
+    from cgate.db.mode import AppModeRepo
+    from cgate.db.server_settings import ServerSettingsRepo
+
+
+class BehaviorDecision(TypedDict):
+    """The resolved behavior for one proposed command, with audit context."""
+
+    action: Literal["queue", "execute"]
+    mode: str
+    server_auto_allowed: bool
+    reason: Literal["global_propose", "server_not_opted_in", "both_allowed", "risky_command"]
+    risk_label: str | None
+
+
+def resolve_auto_behavior(
+    *,
+    mode_repo: AppModeRepo,
+    settings_repo: ServerSettingsRepo,
+    server_alias: str,
+    risk_label: str | None,
+) -> BehaviorDecision:
+    """Execute only when the global mode is AUTO and the server has opted in.
+
+    An unset global mode (AppModeNotSetError) behaves as PROPOSE, and an
+    alias without an explicit server_settings row behaves as not opted in:
+    auto-execution requires both sides to be explicit.
+
+    ``risk_label`` (from ``cgate.risk.find_risk``, computed by the caller)
+    overrides ``both_allowed`` -- a command matching a known high-blast-
+    radius pattern always queues for a human, even with AUTO mode on and
+    the server opted in. It's carried through regardless of the decision
+    reason so the caller (and the human reviewing the queue) always knows
+    whether this command was flagged, not just when it changed the outcome.
+    """
+    try:
+        mode = mode_repo.get().mode
+    except AppModeNotSetError:
+        mode = Mode.PROPOSE
+    auto_allowed = settings_repo.get_or_default(server_alias).auto_allowed
+    match mode:
+        case Mode.PROPOSE:
+            return {
+                "action": "queue",
+                "mode": mode.value,
+                "server_auto_allowed": auto_allowed,
+                "reason": "risky_command" if risk_label is not None else "global_propose",
+                "risk_label": risk_label,
+            }
+        case Mode.AUTO:
+            if not auto_allowed:
+                return {
+                    "action": "queue",
+                    "mode": mode.value,
+                    "server_auto_allowed": auto_allowed,
+                    "reason": "server_not_opted_in",
+                    "risk_label": risk_label,
+                }
+            if risk_label is not None:
+                return {
+                    "action": "queue",
+                    "mode": mode.value,
+                    "server_auto_allowed": auto_allowed,
+                    "reason": "risky_command",
+                    "risk_label": risk_label,
+                }
+            return {
+                "action": "execute",
+                "mode": mode.value,
+                "server_auto_allowed": auto_allowed,
+                "reason": "both_allowed",
+                "risk_label": None,
+            }

cgate/mcp_server/server.py

@@ -0,0 +1,271 @@
+"""MCP server factory exposing command-gate tools over the stdio transport."""
+from __future__ import annotations
+
+import json
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, TypeAlias
+
+import anyio
+import mcp.server.stdio
+from mcp import types
+from mcp.server import Server, ServerRequestContext
+
+from cgate import __version__
+from cgate.connections.store import ConnectionsRepo
+from cgate.core.paths import data_dir
+from cgate.db.batches import BatchesRepo
+from cgate.db.commands import CommandsRepo
+from cgate.db.connection import Database, init_database
+from cgate.db.mode import AppModeRepo
+from cgate.db.server_settings import ServerSettingsRepo
+from cgate.mcp_server.tools import (
+    BatchStatusResult,
+    ConnectionResult,
+    ModeResult,
+    ProposeCommandResult,
+    ToolError,
+    check_status,
+    get_mode,
+    list_connections,
+    propose_command,
+)
+from cgate.update import maybe_heal_pending_update
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator
+
+ToolPayload: TypeAlias = (
+    ProposeCommandResult
+    | BatchStatusResult
+    | ModeResult
+    | list[ConnectionResult]
+    | dict[str, str]
+)
+
+
+@dataclass(frozen=True, slots=True)
+class _ToolDeps:
+    """Repositories opened independently for one MCP tool invocation."""
+
+    batches: BatchesRepo
+    commands: CommandsRepo
+    connections: ConnectionsRepo
+    mode: AppModeRepo
+    settings: ServerSettingsRepo
+
+    @classmethod
+    def from_db(cls, db: Database) -> _ToolDeps:
+        """Create the repository set backed by one database path."""
+        return cls(
+            batches=BatchesRepo(db),
+            commands=CommandsRepo(db),
+            connections=ConnectionsRepo(db),
+            mode=AppModeRepo(db),
+            settings=ServerSettingsRepo(db),
+        )
+
+
+def _content(payload: ToolPayload) -> list[types.ContentBlock]:
+    return [types.TextContent(type="text", text=json.dumps(payload, indent=2))]
+
+
+def _result(payload: ToolPayload, *, is_error: bool = False) -> types.CallToolResult:
+    return types.CallToolResult(content=_content(payload), is_error=is_error)
+
+
+def _tools() -> list[types.Tool]:
+    return [
+        types.Tool(
+            name="propose_command",
+            description=(
+                "Register a command for execution. Normally it queues for human "
+                "approval in cgate watch, but if cgate's global mode is AUTO AND "
+                "the target server has opted into auto-execution, it runs immediately "
+                "and the response includes the result. The response always carries "
+                "`mode`, `server_auto_allowed`, and `effective_reason` so you can tell "
+                "which path it took. A command matching a known high-blast-radius "
+                "pattern (e.g. a recursive force-delete, a raw disk write, deleting "
+                "shadow copies/backups) always queues for a human regardless of AUTO "
+                "mode -- `effective_reason` comes back as `risky_command` and "
+                "`risk_label` names what was matched; this is a heuristic, not a "
+                "guarantee, so don't rely on its absence to mean a command is safe. "
+                "batch_title is required; batch_description is optional. If batch_id "
+                "is omitted, a new batch is created."
+            ),
+            input_schema={
+                "type": "object",
+                "properties": {
+                    "server_alias": {
+                        "type": "string",
+                        "description": "Alias of a saved connection from list_connections.",
+                    },
+                    "command": {
+                        "type": "string",
+                        "description": "Exact shell or PowerShell command to register.",
+                    },
+                    "batch_id": {
+                        "type": "string",
+                        "description": "Optional existing batch ID to append to.",
+                    },
+                    "batch_title": {
+                        "type": "string",
+                        "description": "Required one-line purpose of the batch.",
+                    },
+                    "batch_description": {
+                        "type": "string",
+                        "description": "Optional one-line explanation of why the batch is needed.",
+                    },
+                    "reason": {
+                        "type": "string",
+                        "description": (
+                            "Optional justification for why this command is needed. "
+                            "Stored and shown to the human reviewer in cgate watch."
+                        ),
+                    },
+                },
+                "required": ["server_alias", "command", "batch_title"],
+            },
+        ),
+        types.Tool(
+            name="list_connections",
+            description=(
+                "List saved server connections and their server_type so an agent can "
+                "select a valid alias and command dialect. Each entry also carries "
+                "`auto_allowed`, the per-server auto-execution opt-in flag."
+            ),
+            input_schema={
+                "type": "object",
+                "properties": {},
+                "additionalProperties": False,
+            },
+        ),
+        types.Tool(
+            name="get_mode",
+            description=(
+                "Report the current global execution mode and which servers are "
+                "opted in for auto-execution. Read-only; safe to call any time to "
+                "learn what `propose_command` would do before invoking it."
+            ),
+            input_schema={
+                "type": "object",
+                "properties": {},
+                "additionalProperties": False,
+            },
+        ),
+        types.Tool(
+            name="check_status",
+            description=(
+                "Return every command in a batch with status, result, and audit fields. "
+                "States are pending, approved, rejected, executed, and failed."
+            ),
+            input_schema={
+                "type": "object",
+                "properties": {
+                    "batch_id": {
+                        "type": "string",
+                        "description": "ID of the batch to inspect.",
+                    }
+                },
+                "required": ["batch_id"],
+            },
+        ),
+    ]
+
+
+@asynccontextmanager
+async def _lifespan(_server: Server[None]) -> AsyncGenerator[None]:
+    yield None
+
+
+def build_server() -> Server[None]:
+    """Build a stateless MCP server configured with command-gate's four tools."""
+
+    async def on_list_tools(
+        _context: ServerRequestContext[None, types.PaginatedRequestParams],
+        _params: types.PaginatedRequestParams | None,
+    ) -> types.ListToolsResult:
+        return types.ListToolsResult(tools=_tools())
+
+    async def on_call_tool(
+        _context: ServerRequestContext[None, types.CallToolRequestParams],
+        params: types.CallToolRequestParams,
+    ) -> types.CallToolResult:
+        db = Database(path=data_dir() / "cgate.db")
+        init_database(db)
+        deps = _ToolDeps.from_db(db)
+        arguments = params.arguments or {}
+        try:
+            match params.name:
+                case "propose_command":
+                    payload = propose_command(
+                        batches_repo=deps.batches,
+                        commands_repo=deps.commands,
+                        connections_repo=deps.connections,
+                        mode_repo=deps.mode,
+                        settings_repo=deps.settings,
+                        server_alias=arguments["server_alias"],
+                        command=arguments["command"],
+                        batch_title=arguments.get("batch_title"),
+                        batch_description=arguments.get("batch_description"),
+                        batch_id=arguments.get("batch_id"),
+                        reason=arguments.get("reason"),
+                    )
+                case "list_connections":
+                    payload = list_connections(
+                        connections_repo=deps.connections,
+                        settings_repo=deps.settings,
+                    )
+                case "get_mode":
+                    payload = get_mode(mode_repo=deps.mode, settings_repo=deps.settings)
+                case "check_status":
+                    payload = check_status(
+                        batches_repo=deps.batches,
+                        commands_repo=deps.commands,
+                        batch_id=arguments["batch_id"],
+                    )
+                case _:
+                    return _result(
+                        {"error": "unknown_tool", "message": f"unknown tool '{params.name}'"},
+                        is_error=True,
+                    )
+        except ToolError as exc:
+            return _result({"error": exc.code, "message": exc.message}, is_error=True)
+        except KeyError as exc:
+            return _result(
+                {
+                    "error": "missing_argument",
+                    "message": f"missing required argument: {exc.args[0]}",
+                },
+                is_error=True,
+            )
+        return _result(payload)
+
+    return Server(
+        "command-gate",
+        version=__version__,
+        on_list_tools=on_list_tools,
+        on_call_tool=on_call_tool,
+        lifespan=_lifespan,
+    )
+
+
+async def _serve_stdio() -> None:
+    server = build_server()
+    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            server.create_initialization_options(),
+        )
+
+
+def main() -> None:
+    """Run the command-gate MCP server over standard input and output.
+
+    Spawns the helper to self-heal any staged update before we enter the
+    long-running stdio loop; the helper waits on our PID and does the
+    swap the instant the IA client that owns us closes the connection.
+    """
+    maybe_heal_pending_update()
+    anyio.run(_serve_stdio)