ama-cli 0.1.0__tar.gz

ama_cli-0.1.0/.gitignore

@@ -0,0 +1,99 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+!packages/design-system/src/lib/
+!apps/web/src/lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Node.js
+node_modules/
+.turbo/
+.next/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+.ama_state
+
+# Data
+data/
+!data/podcast_demo/
+!apps/web/src/routes/**/data/
+/prompts/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+ag_news_200.jsonl
+
+# Node.js
+node_modules/
+# pnpm-lock.yaml is intentionally COMMITTED. It is the single source of truth for
+# JS dependency resolution and apps/web/Dockerfile installs with --frozen-lockfile.
+# Ignoring it is what previously left bun.lock as the only committed lockfile,
+# so reproducible installs used bun's resolution while the docs mandated pnpm.
+
+# mkcert certificates are safe to commit - they only work when the local CA is trusted
+# infra/caddy/certs/ - intentionally NOT ignored for zero-config local dev
+
+# Terraform
+*.tfstate
+*.tfstate.*
+*.tfvars
+!terraform.tfvars.example
+.terraform/
+
+# Atlantis secrets (Helm values with GitHub tokens)
+infra/k8s/atlantis/secrets.yaml
+
+# Agent harness state.
+# Worktrees are multi-GB full repo clones (workmux scratch); leaving them
+# unignored puts them in every agent's glob/grep scope and times out searches.
+.claude/worktrees/
+.claude/settings.local.json
+
+# Local MCP client config for Claude Code in this repo (personal endpoint/keys).
+# Root-anchored so the tracked plugins/ama-agent/.mcp.json is unaffected.
+/.mcp.json
+
+# Compiled email templates are committed (read at runtime by ama.modules.email.templates;
+# the prod image copies packages/ without running a pnpm build)
+!packages/email-templates/dist/
+!packages/email-templates/dist/**
+
+# TypeScript incremental build artifacts
+*.tsbuildinfo
+.design-sync/sb-reference/
+.design-sync/learnings/
+.design-sync/.cache/
+.design-sync/node_modules
+.ds-sync/
+ds-bundle/

ama_cli-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: ama-cli
+Version: 0.1.0
+Summary: Connect your coding agent to Ama.
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9
+Description-Content-Type: text/markdown
+
+# ama
+
+Connect your coding agent to [Ama](https://ama.dev).
+
+```bash
+curl -fsSL https://ama.dev/install | sh
+```
+
+That installs the CLI and runs `ama onboard`. Three questions and you are done:
+
+1. **Sign in** — in your browser.
+2. **Confirm** — which agents, and where.
+3. **Start now?** — opens your agent on a live notebook.
+
+Already have the CLI?
+
+```bash
+ama onboard
+```
+
+Re-running either line upgrades.
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `ama onboard` | Sign in, detect agents, register MCP. Start here. |
+| `ama detect` | Show which coding agents were found, and why. |
+| `ama login` / `logout` / `whoami` | Manage credentials. |
+| `ama mcp add` / `list` / `remove` | Manage MCP registration directly. |
+
+## Supported agents
+
+Registered automatically:
+
+| Agent | |
+|---|---|
+| Claude Code | `claude mcp add -s user` |
+| Cursor | `~/.cursor/mcp.json` |
+| Codex CLI | `codex mcp add` — also export `AMA_API_KEY`; Codex stores the variable name, not the token |
+| Gemini CLI | `gemini mcp add` |
+| VS Code (Copilot) | `code --add-mcp` |
+
+**Detected but not yet registered automatically:** Windsurf, Zed, Cline, Roo
+Code. `ama onboard` tells you rather than pretending, and prints what to paste.
+
+`ama detect` explains what it found and where, so you can check before anything
+is written. `ama onboard --dry-run` prints the exact diff for every file it
+would touch — and signs in to nothing, so no key is created.
+
+## Self-hosted
+
+Point at your own deployment; the CLI reads `/.well-known/mcp.json` for the
+endpoint and auth method rather than assuming anything.
+
+```bash
+ama onboard --host https://ama.internal.example.com
+```
+
+## Install without the script
+
+```bash
+uv tool install ama-cli    # binary is `ama`
+```
+
+## Notes
+
+This is the public client. It speaks HTTP to a hosted or self-hosted Ama and
+carries no server dependencies — `typer` and `rich`, nothing else.
+
+Your API key is stored in `~/.ama/credentials.json`, mode `0600`. The CLI never
+writes a literal token into a project-scoped config file, since those get
+committed; project scope uses environment-variable indirection instead.
+
+Licensed under Apache-2.0.

ama_cli-0.1.0/README.md

@@ -0,0 +1,75 @@
+# ama
+
+Connect your coding agent to [Ama](https://ama.dev).
+
+```bash
+curl -fsSL https://ama.dev/install | sh
+```
+
+That installs the CLI and runs `ama onboard`. Three questions and you are done:
+
+1. **Sign in** — in your browser.
+2. **Confirm** — which agents, and where.
+3. **Start now?** — opens your agent on a live notebook.
+
+Already have the CLI?
+
+```bash
+ama onboard
+```
+
+Re-running either line upgrades.
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `ama onboard` | Sign in, detect agents, register MCP. Start here. |
+| `ama detect` | Show which coding agents were found, and why. |
+| `ama login` / `logout` / `whoami` | Manage credentials. |
+| `ama mcp add` / `list` / `remove` | Manage MCP registration directly. |
+
+## Supported agents
+
+Registered automatically:
+
+| Agent | |
+|---|---|
+| Claude Code | `claude mcp add -s user` |
+| Cursor | `~/.cursor/mcp.json` |
+| Codex CLI | `codex mcp add` — also export `AMA_API_KEY`; Codex stores the variable name, not the token |
+| Gemini CLI | `gemini mcp add` |
+| VS Code (Copilot) | `code --add-mcp` |
+
+**Detected but not yet registered automatically:** Windsurf, Zed, Cline, Roo
+Code. `ama onboard` tells you rather than pretending, and prints what to paste.
+
+`ama detect` explains what it found and where, so you can check before anything
+is written. `ama onboard --dry-run` prints the exact diff for every file it
+would touch — and signs in to nothing, so no key is created.
+
+## Self-hosted
+
+Point at your own deployment; the CLI reads `/.well-known/mcp.json` for the
+endpoint and auth method rather than assuming anything.
+
+```bash
+ama onboard --host https://ama.internal.example.com
+```
+
+## Install without the script
+
+```bash
+uv tool install ama-cli    # binary is `ama`
+```
+
+## Notes
+
+This is the public client. It speaks HTTP to a hosted or self-hosted Ama and
+carries no server dependencies — `typer` and `rich`, nothing else.
+
+Your API key is stored in `~/.ama/credentials.json`, mode `0600`. The CLI never
+writes a literal token into a project-scoped config file, since those get
+committed; project scope uses environment-variable indirection instead.
+
+Licensed under Apache-2.0.

ama_cli-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "ama-cli"
+version = "0.1.0"
+description = "Connect your coding agent to Ama."
+readme = "README.md"
+requires-python = ">=3.11"
+# Deliberately thin. This package is on the install path of a one-line
+# onboarding command, so every dependency is weight a new user waits for.
+# It must never depend on ama-core (enforced by .importlinter) -- that is the
+# server, and it is unpublishable anyway (path + git sources).
+dependencies = [
+  "typer>=0.9",
+  "rich>=13.0",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+
+[project.scripts]
+ama = "ama_cli.cli:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ama_cli"]
+
+[dependency-groups]
+dev = [
+  "pytest>=8.0",
+  "ruff>=0.8",
+  "ty>=0.0.1a8",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ama_cli-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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