ama-cli 0.1.0__py3-none-any.whl

ama_cli/__init__.py

@@ -0,0 +1,7 @@
+"""Ama CLI — connect your coding agent to Ama.
+
+The public, thin CLI. It speaks HTTP to a hosted or self-hosted Ama and never
+imports server code (see the `public-cli-isolation` contract in .importlinter).
+"""
+
+__version__ = "0.1.0"

ama_cli/agents/__init__.py

@@ -0,0 +1,25 @@
+"""Coding-agent detection and MCP registration."""
+
+from ama_cli.agents.base import (
+    AgentSpec,
+    Confidence,
+    Detection,
+    Env,
+    Platform,
+    Signal,
+    SignalKind,
+)
+from ama_cli.agents.registry import REGISTRY, detect_all, get_spec
+
+__all__ = [
+    "REGISTRY",
+    "AgentSpec",
+    "Confidence",
+    "Detection",
+    "Env",
+    "Platform",
+    "Signal",
+    "SignalKind",
+    "detect_all",
+    "get_spec",
+]

ama_cli/agents/adapters/__init__.py

@@ -0,0 +1,48 @@
+"""The adapter registry.
+
+v1 covers Claude Code, Cursor, Codex, Gemini CLI and VS Code. Windsurf, Zed,
+Cline and Roo are detected but not yet registerable — adapters are cheap once
+the seam exists, but each needs testing against a real install, and that is the
+actual cost. `ama mcp add` says so rather than failing obscurely.
+
+Zed is the only remaining target needing a comment-preserving (JSONC) writer;
+every v1 agent is either CLI-backed or plain JSON.
+"""
+
+from __future__ import annotations
+
+from ama_cli.agents.adapters.cli_backed import (
+    ClaudeCodeAdapter,
+    CodexAdapter,
+    GeminiAdapter,
+    VSCodeAdapter,
+)
+from ama_cli.agents.adapters.cursor import CursorAdapter
+from ama_cli.agents.mcp import AgentAdapter
+
+ADAPTERS: tuple[AgentAdapter, ...] = (
+    ClaudeCodeAdapter(),
+    CursorAdapter(),
+    CodexAdapter(),
+    GeminiAdapter(),
+    VSCodeAdapter(),
+)
+
+ADAPTERS_BY_ID: dict[str, AgentAdapter] = {a.spec.id: a for a in ADAPTERS}
+
+
+def get_adapter(agent_id: str) -> AgentAdapter | None:
+    """Look up an adapter by agent id, or None when the agent has no adapter yet."""
+    return ADAPTERS_BY_ID.get(agent_id)
+
+
+__all__ = [
+    "ADAPTERS",
+    "ADAPTERS_BY_ID",
+    "ClaudeCodeAdapter",
+    "CodexAdapter",
+    "CursorAdapter",
+    "GeminiAdapter",
+    "VSCodeAdapter",
+    "get_adapter",
+]

ama_cli/agents/adapters/cli_backed.py

@@ -0,0 +1,271 @@
+"""Adapters for agents that ship their own non-interactive MCP CLI.
+
+Preferred over writing config files: the vendor's CLI owns the dialect, so it
+insulates us from schema and path churn. It matters most for VS Code, whose docs
+describe the user `mcp.json` as living "in your user profile" but never state OS
+paths — and those paths break under named profiles, Insiders and portable
+installs anyway.
+"""
+
+from __future__ import annotations
+
+from ama_cli.agents.base import Env
+from ama_cli.agents.mcp import (
+    Plan,
+    RemoteServer,
+    RunCommand,
+    Scope,
+    unsupported_plan,
+)
+from ama_cli.agents.registry import CLAUDE_CODE, CODEX, GEMINI_CLI, VSCODE
+
+
+def _replace_first(argv: tuple[str, ...]) -> RunCommand:
+    """A pre-emptive remove, so a re-run replaces rather than erroring.
+
+    None of these CLIs have a --force, and `mcp add` errors when the server
+    already exists -- so re-running onboard would fail without this. Replace
+    rather than skip: someone re-onboarding after rotating their key must end up
+    with the new token, not silently keep the old one.
+
+    Tolerates failure because on a clean machine there is nothing to remove.
+    """
+    return RunCommand(argv, tolerate_failure=True)
+
+
+class ClaudeCodeAdapter:
+    """Claude Code, via `claude mcp add`.
+
+    Scopes are Claude's own: `local` (default -- this project only), `project`
+    (.mcp.json, VCS-shared), `user` (all projects). We map GLOBAL -> user.
+    """
+
+    spec = CLAUDE_CODE
+
+    def plan_add(self, server: RemoteServer, scope: Scope, env: Env) -> Plan:
+        if not env.which("claude"):
+            return unsupported_plan(self.spec.id, "claude is not on PATH")
+
+        if scope is Scope.PROJECT:
+            # Claude expands ${VAR} and ${VAR:-default} in url and headers, so
+            # .mcp.json can be committed without leaking the token.
+            auth = server.authorization(scope, env_ref=f"${{{server.token_env_var}}}")
+        else:
+            auth = server.authorization(scope)
+
+        # `-s user` is required for global: `claude mcp add` defaults to
+        # `-s local`, which would scope the server to this directory only.
+        claude_scope = "project" if scope is Scope.PROJECT else "user"
+        argv = (
+            "claude",
+            "mcp",
+            "add",
+            "--transport",
+            "http",
+            "-s",
+            claude_scope,
+            server.name,
+            server.url,
+            "--header",
+            f"Authorization: {auth}",
+        )
+        return Plan(
+            self.spec.id,
+            steps=(
+                _replace_first(("claude", "mcp", "remove", "-s", claude_scope, server.name)),
+                RunCommand(argv, secret=server.token),
+            ),
+        )
+
+    def plan_remove(self, name: str, scope: Scope, env: Env) -> Plan:
+        if not env.which("claude"):
+            return unsupported_plan(self.spec.id, "claude is not on PATH")
+        claude_scope = "project" if scope is Scope.PROJECT else "user"
+        return Plan(
+            self.spec.id,
+            steps=(RunCommand(("claude", "mcp", "remove", "-s", claude_scope, name)),),
+        )
+
+    def list_servers(self, scope: Scope, env: Env) -> list[str]:
+        return _list_via_cli(("claude", "mcp", "list"), env, "claude")
+
+
+class GeminiAdapter:
+    """Gemini CLI, via `gemini mcp add`.
+
+    Gemini distinguishes transport by *key*: `httpUrl` is streamable HTTP while
+    `url` is SSE. Using `url` for an HTTP endpoint is the classic Gemini
+    misconfiguration -- `--transport http` is what keeps us on the right one.
+    """
+
+    spec = GEMINI_CLI
+
+    def plan_add(self, server: RemoteServer, scope: Scope, env: Env) -> Plan:
+        if not env.which("gemini"):
+            return unsupported_plan(self.spec.id, "gemini is not on PATH")
+
+        auth = (
+            server.authorization(scope, env_ref=f"${{{server.token_env_var}}}")
+            if scope is Scope.PROJECT
+            else server.authorization(scope)
+        )
+        argv = (
+            "gemini",
+            "mcp",
+            "add",
+            "--transport",
+            "http",
+            "-s",
+            "project" if scope is Scope.PROJECT else "user",
+            "--header",
+            f"Authorization: {auth}",
+            server.name,
+            server.url,
+        )
+        # Deliberately not passing --trust: it bypasses tool-call confirmation,
+        # which is not ours to switch off silently.
+        return Plan(
+            self.spec.id,
+            steps=(
+                _replace_first(("gemini", "mcp", "remove", server.name)),
+                RunCommand(argv, secret=server.token),
+            ),
+        )
+
+    def plan_remove(self, name: str, scope: Scope, env: Env) -> Plan:
+        if not env.which("gemini"):
+            return unsupported_plan(self.spec.id, "gemini is not on PATH")
+        return Plan(self.spec.id, steps=(RunCommand(("gemini", "mcp", "remove", name)),))
+
+    def list_servers(self, scope: Scope, env: Env) -> list[str]:
+        return _list_via_cli(("gemini", "mcp", "list"), env, "gemini")
+
+
+class CodexAdapter:
+    """Codex CLI, via `codex mcp add`.
+
+    Two things make Codex the odd one out:
+
+    1. It is global-only -- no project config exists.
+    2. Bearer tokens are env-var-indirected *by design*: it stores the variable
+       name, never the token. So registration alone is not enough -- AMA_API_KEY
+       must also be exported in the user's shell, or the server silently fails
+       to authenticate.
+    """
+
+    spec = CODEX
+
+    def plan_add(self, server: RemoteServer, scope: Scope, env: Env) -> Plan:
+        if not env.which("codex"):
+            return unsupported_plan(self.spec.id, "codex is not on PATH")
+        if scope is Scope.PROJECT:
+            return unsupported_plan(
+                self.spec.id, "Codex has no project-level config; it is global-only"
+            )
+        argv = (
+            "codex",
+            "mcp",
+            "add",
+            server.name,
+            "--url",
+            server.url,
+            "--bearer-token-env-var",
+            server.token_env_var,
+        )
+        # No secret= : the token never reaches this command by design.
+        return Plan(
+            self.spec.id,
+            steps=(
+                _replace_first(("codex", "mcp", "remove", server.name)),
+                RunCommand(argv),
+            ),
+        )
+
+    def plan_remove(self, name: str, scope: Scope, env: Env) -> Plan:
+        if not env.which("codex"):
+            return unsupported_plan(self.spec.id, "codex is not on PATH")
+        return Plan(self.spec.id, steps=(RunCommand(("codex", "mcp", "remove", name)),))
+
+    def list_servers(self, scope: Scope, env: Env) -> list[str]:
+        return _list_via_cli(("codex", "mcp", "list"), env, "codex")
+
+
+class VSCodeAdapter:
+    """VS Code / Copilot, via `code --add-mcp`.
+
+    VS Code's root key is `servers`, not `mcpServers` -- the single biggest
+    schema divergence in the ecosystem. We never write that file: `--add-mcp`
+    does, and it knows where the user's profile actually is.
+    """
+
+    spec = VSCODE
+
+    def _binary(self, env: Env) -> str | None:
+        for candidate in ("code", "code-insiders"):
+            if env.which(candidate):
+                return candidate
+        return None
+
+    def plan_add(self, server: RemoteServer, scope: Scope, env: Env) -> Plan:
+        binary = self._binary(env)
+        if not binary:
+            return unsupported_plan(self.spec.id, "code is not on PATH")
+        if scope is Scope.PROJECT:
+            return unsupported_plan(
+                self.spec.id,
+                "`code --add-mcp` writes user scope only; project scope needs .vscode/mcp.json",
+            )
+
+        import json as _json
+
+        payload = _json.dumps(
+            {
+                "name": server.name,
+                "type": "http",
+                "url": server.url,
+                "headers": {"Authorization": server.authorization(scope)},
+            }
+        )
+        return Plan(
+            self.spec.id,
+            steps=(RunCommand((binary, "--add-mcp", payload), secret=server.token),),
+        )
+
+    def plan_remove(self, name: str, scope: Scope, env: Env) -> Plan:
+        return unsupported_plan(
+            self.spec.id,
+            "VS Code has no MCP remove command; use the MCP: Open User Configuration command",
+        )
+
+    def list_servers(self, scope: Scope, env: Env) -> list[str]:
+        # No documented list command; the config lives at a path VS Code's docs
+        # never state. Reporting nothing beats guessing wrong.
+        return []
+
+
+def _list_via_cli(argv: tuple[str, ...], env: Env, binary: str) -> list[str]:
+    """Parse server names out of an agent's `mcp list` output.
+
+    Best-effort by construction: these are human-readable listings with no
+    documented machine format, so this reports what it can recognise and stays
+    quiet otherwise rather than inventing structure.
+    """
+    import re
+    import subprocess
+
+    if not env.which(binary):
+        return []
+    try:
+        proc = subprocess.run(argv, capture_output=True, text=True, timeout=20)
+    except (OSError, subprocess.SubprocessError):
+        return []
+    if proc.returncode != 0:
+        return []
+
+    names: list[str] = []
+    for line in proc.stdout.splitlines():
+        # Matches the common "name: url" / "name  url" listing shapes.
+        m = re.match(r"^\s*([A-Za-z0-9_-]+)\s*[::]\s*\S", line)
+        if m:
+            names.append(m.group(1))
+    return names

ama_cli/agents/adapters/cursor.py

@@ -0,0 +1,86 @@
+"""Cursor adapter — writes mcp.json directly.
+
+Cursor has no `mcp add` subcommand (`cursor-agent mcp` offers only list,
+list-tools, login, enable, disable), so this is the one v1 agent whose config we
+write ourselves. Both the editor and the CLI read the same file.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ama_cli.agents.base import Env
+from ama_cli.agents.mcp import (
+    FileWrite,
+    Plan,
+    RemoteServer,
+    Scope,
+    dump_json,
+    read_json,
+)
+from ama_cli.agents.registry import CURSOR
+
+ROOT_KEY = "mcpServers"
+
+
+class CursorAdapter:
+    """Cursor, via ~/.cursor/mcp.json (global) or .cursor/mcp.json (project).
+
+    Dialect note: Cursor identifies a remote server by the *presence of `url`*
+    and has no `type` field for it. Community snippets add
+    `"type": "streamable-http"`, but no official remote example includes one, so
+    we emit exactly what the docs show and nothing more. Guessing at an
+    undocumented discriminator is how you get a config that silently never
+    connects.
+    """
+
+    spec = CURSOR
+
+    def config_path(self, scope: Scope, env: Env) -> Path:
+        if scope is Scope.PROJECT:
+            return env.cwd / ".cursor" / "mcp.json"
+        return env.home / ".cursor" / "mcp.json"
+
+    def _entry(self, server: RemoteServer, scope: Scope) -> dict:
+        # ${env:VAR} is Cursor's interpolation syntax, resolved in url and
+        # headers. Project scope must use it -- that file gets committed.
+        env_ref = f"${{env:{server.token_env_var}}}"
+        return {
+            "url": server.url,
+            "headers": {"Authorization": server.authorization(scope, env_ref=env_ref)},
+        }
+
+    def plan_add(self, server: RemoteServer, scope: Scope, env: Env) -> Plan:
+        path = self.config_path(scope, env)
+        data, raw = read_json(path)
+
+        servers = dict(data.get(ROOT_KEY) or {})
+        servers[server.name] = self._entry(server, scope)
+        merged = {**data, ROOT_KEY: servers}
+
+        return Plan(
+            self.spec.id,
+            steps=(FileWrite(path=path, before=raw, after=dump_json(merged), secret=server.token),),
+        )
+
+    def plan_remove(self, name: str, scope: Scope, env: Env) -> Plan:
+        path = self.config_path(scope, env)
+        data, raw = read_json(path)
+
+        servers = dict(data.get(ROOT_KEY) or {})
+        if name not in servers:
+            return Plan(self.spec.id)  # already absent -- nothing to do
+        servers.pop(name)
+        merged = {**data, ROOT_KEY: servers}
+
+        return Plan(
+            self.spec.id,
+            steps=(FileWrite(path=path, before=raw, after=dump_json(merged)),),
+        )
+
+    def list_servers(self, scope: Scope, env: Env) -> list[str]:
+        try:
+            data, _ = read_json(self.config_path(scope, env))
+        except ValueError:
+            return []
+        return sorted((data.get(ROOT_KEY) or {}).keys())

ama_cli/agents/base.py

@@ -0,0 +1,206 @@
+"""Core types for coding-agent detection.
+
+Detection answers one question: *which coding agents does this developer
+actually use?* We then offer to register the Ama MCP server with each.
+
+Everything here is a pure function of an injected `Env`. Nothing calls
+`Path.home()`, `shutil.which`, or reads `sys.platform` at module scope, so
+tests build a temp home and a fake PATH and need no monkeypatching.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from enum import Enum, IntEnum
+from pathlib import Path
+
+
+class Platform(str, Enum):
+    """Host operating system, normalised."""
+
+    DARWIN = "darwin"
+    LINUX = "linux"
+    WINDOWS = "windows"
+
+    @classmethod
+    def current(cls) -> Platform:
+        """Map sys.platform onto the three cases we care about."""
+        if sys.platform == "darwin":
+            return cls.DARWIN
+        if sys.platform.startswith("win"):
+            return cls.WINDOWS
+        return cls.LINUX
+
+
+@dataclass(frozen=True)
+class Env:
+    """The host, injected rather than discovered.
+
+    `which` is a callable so tests can present a fake PATH without touching
+    the real one. `appdata` is only meaningful on Windows.
+    """
+
+    home: Path
+    cwd: Path
+    platform: Platform
+    which: Callable[[str], str | None] = shutil.which
+    appdata: Path | None = None
+    xdg_config_home: Path | None = None
+
+    @classmethod
+    def current(cls) -> Env:
+        """Build an Env from the real host.
+
+        The only place environment lookup happens. Everything downstream reads
+        the resolved Env, which is what keeps detectors testable.
+        """
+        appdata = os.environ.get("APPDATA")
+        xdg = os.environ.get("XDG_CONFIG_HOME")
+        return cls(
+            home=Path.home(),
+            cwd=Path.cwd(),
+            platform=Platform.current(),
+            which=shutil.which,
+            appdata=Path(appdata) if appdata else None,
+            xdg_config_home=Path(xdg) if xdg else None,
+        )
+
+    @property
+    def config_home(self) -> Path:
+        """$XDG_CONFIG_HOME, defaulting to ~/.config per the XDG spec."""
+        return self.xdg_config_home or self.home / ".config"
+
+    def display(self, path: Path) -> str:
+        """Render a path as ~/… when it sits under home, for UI output."""
+        try:
+            return f"~/{path.relative_to(self.home)}"
+        except ValueError:
+            return str(path)
+
+
+class Confidence(IntEnum):
+    """How strongly a signal implies *this developer uses this agent here*.
+
+    Ordered, so `max()` over a detection's signals gives its confidence.
+
+    MACHINE beats BINARY because a config directory in home means the agent has
+    actually run on this machine, whereas a binary may be an unused leftover.
+    REPO is last and deliberately weak: `CLAUDE.md` means *some contributor*
+    once used Claude Code, which says nothing about the person running onboard.
+    """
+
+    REPO = 1
+    BINARY = 2
+    MACHINE = 3
+
+
+class SignalKind(str, Enum):
+    """What kind of evidence a signal represents."""
+
+    MACHINE_DIR = "machine_dir"
+    BINARY = "binary"
+    REPO_PATH = "repo_path"
+
+
+_CONFIDENCE_BY_KIND = {
+    SignalKind.MACHINE_DIR: Confidence.MACHINE,
+    SignalKind.BINARY: Confidence.BINARY,
+    SignalKind.REPO_PATH: Confidence.REPO,
+}
+
+
+@dataclass(frozen=True)
+class Signal:
+    """One piece of evidence, with a human-readable reason for the UI.
+
+    `detail` is shown to the user verbatim — they should never have to wonder
+    why an agent appeared in the list.
+    """
+
+    kind: SignalKind
+    detail: str
+
+    @property
+    def confidence(self) -> Confidence:
+        """The confidence this kind of signal carries."""
+        return _CONFIDENCE_BY_KIND[self.kind]
+
+
+@dataclass(frozen=True)
+class Detection:
+    """The result of running one agent's detector against an Env."""
+
+    agent_id: str
+    display_name: str
+    signals: tuple[Signal, ...] = ()
+
+    @property
+    def detected(self) -> bool:
+        """True when any evidence was found."""
+        return bool(self.signals)
+
+    @property
+    def confidence(self) -> Confidence | None:
+        """The strongest signal's confidence, or None when undetected."""
+        return max((s.confidence for s in self.signals), default=None)
+
+    @property
+    def reason(self) -> str:
+        """All signal details, comma-joined, for display."""
+        return ", ".join(s.detail for s in self.signals)
+
+
+@dataclass(frozen=True)
+class AgentSpec:
+    """A declarative detector for one agent platform.
+
+    Detection is nearly always "look for a config dir, a binary, some repo
+    files", so specs are data. The two callables exist only for genuine
+    platform variance (VS Code and Roo bury config under OS-specific
+    application-support paths); everything else stays a plain tuple.
+
+    Adding an agent should mean adding one entry to `registry.py` and a test.
+    """
+
+    id: str
+    display_name: str
+    docs_url: str
+    binaries: tuple[str, ...] = ()
+    # Paths relative to home, e.g. ".claude" -> ~/.claude
+    machine_paths: tuple[str, ...] = ()
+    # Resolved against the Env for platform-specific locations.
+    machine_paths_fn: Callable[[Env], Sequence[Path]] | None = field(default=None, repr=False)
+    # Paths relative to cwd, e.g. "CLAUDE.md"
+    repo_paths: tuple[str, ...] = ()
+
+    def _machine_candidates(self, env: Env) -> list[Path]:
+        paths = [env.home / p for p in self.machine_paths]
+        if self.machine_paths_fn is not None:
+            paths.extend(self.machine_paths_fn(env))
+        return paths
+
+    def detect(self, env: Env) -> Detection:
+        """Gather every signal for this agent. Never raises."""
+        signals: list[Signal] = []
+
+        for path in self._machine_candidates(env):
+            if path.exists():
+                signals.append(Signal(SignalKind.MACHINE_DIR, env.display(path)))
+
+        for binary in self.binaries:
+            if env.which(binary):
+                signals.append(Signal(SignalKind.BINARY, f"{binary} on PATH"))
+
+        for rel in self.repo_paths:
+            if (env.cwd / rel).exists():
+                signals.append(Signal(SignalKind.REPO_PATH, f"{rel} in repo"))
+
+        return Detection(
+            agent_id=self.id,
+            display_name=self.display_name,
+            signals=tuple(signals),
+        )