ama-cli 0.1.0__py3-none-any.whl

ama_cli/cli.py

@@ -0,0 +1,433 @@
+"""Typer app for the public Ama CLI.
+
+Thin by design: this module wires commands to the terminal and nothing else.
+Detection lives in `ama_cli.agents`, registration in `ama_cli.agents.adapters`.
+"""
+
+from __future__ import annotations
+
+import difflib
+import os
+import webbrowser
+from datetime import datetime
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from ama_cli import auth, credentials
+from ama_cli import onboard as onboard_flow
+from ama_cli.agents import Confidence, Detection, Env, detect_all
+from ama_cli.credentials import DEFAULT_HOST, HOST_ENV_VAR
+from ama_cli.agents.adapters import ADAPTERS_BY_ID, get_adapter
+from ama_cli.agents.mcp import (
+    DEFAULT_SERVER_NAME,
+    Plan,
+    RemoteServer,
+    RunCommand,
+    Scope,
+    apply_plan,
+)
+
+app = typer.Typer(
+    name="ama",
+    help="Connect your coding agent to Ama.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+mcp_app = typer.Typer(help="Manage MCP registration with your coding agents.", no_args_is_help=True)
+app.add_typer(mcp_app, name="mcp")
+console = Console()
+
+_CONFIDENCE_LABEL = {
+    Confidence.MACHINE: "machine",
+    Confidence.BINARY: "binary",
+    Confidence.REPO: "repo",
+}
+
+
+def _version() -> str:
+    """This package's installed version.
+
+    Read from installed metadata rather than duplicated as a constant, so it
+    cannot drift from what pyproject.toml declares and PyPI publishes.
+    """
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        return version("ama-cli")
+    except PackageNotFoundError:  # running from a source tree, not installed
+        return "unknown"
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"ama {_version()}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        None,
+        "--version",
+        "-V",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the version and exit.",
+    ),
+) -> None:
+    """Ama — connect your coding agent to Ama.
+
+    Present so Typer keeps subcommand dispatch. With a single registered command
+    and no callback, Typer collapses the app into that command.
+    """
+
+
+def _detected(env: Env) -> list[Detection]:
+    return [d for d in detect_all(env) if d.detected]
+
+
+def _resolve_agents(env: Env, agent: str | None) -> list[Detection]:
+    """Pick the agents to act on: an explicit --agent list, or whatever was detected."""
+    if agent:
+        wanted = [a.strip() for a in agent.split(",") if a.strip()]
+        unknown = [a for a in wanted if a not in ADAPTERS_BY_ID]
+        if unknown:
+            console.print(f"[red]Unknown agent(s):[/red] {', '.join(unknown)}")
+            console.print(f"Known: {', '.join(sorted(ADAPTERS_BY_ID))}")
+            raise typer.Exit(2)
+        by_id = {d.agent_id: d for d in detect_all(env)}
+        return [by_id[a] for a in wanted]
+    return [d for d in _detected(env) if get_adapter(d.agent_id)]
+
+
+def _render_plan(plan: Plan) -> None:
+    """Print what a plan would do, secrets masked."""
+    for step in plan.steps:
+        if isinstance(step, RunCommand):
+            console.print(f"  [cyan]$[/cyan] {step.display}")
+            continue
+        if step.is_noop:
+            console.print(f"  [dim]{step.path} — already configured[/dim]")
+            continue
+        verb = "create" if step.creates else "update"
+        console.print(f"  [cyan]{verb}[/cyan] {step.path}")
+        diff = difflib.unified_diff(
+            (step.display_before or "").splitlines(),
+            step.display_after.splitlines(),
+            fromfile="before",
+            tofile="after",
+            lineterm="",
+        )
+        for line in diff:
+            if line.startswith("+") and not line.startswith("+++"):
+                console.print(f"    [green]{line}[/green]")
+            elif line.startswith("-") and not line.startswith("---"):
+                console.print(f"    [red]{line}[/red]")
+            elif line.startswith("@@"):
+                console.print(f"    [dim]{line}[/dim]")
+
+
+@app.command()
+def onboard(
+    host: str = typer.Option(
+        None, "--host", help=f"Ama host. Default: ${HOST_ENV_VAR} or {DEFAULT_HOST}."
+    ),
+    scope: Scope = typer.Option(Scope.GLOBAL, "--scope", help="Where to register."),
+    agent: str = typer.Option(
+        None, "--agent", help="Comma-separated agent ids. Default: detected."
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation. For CI."),
+    no_browser: bool = typer.Option(
+        False, "--no-browser", help="Print the sign-in URL instead of opening it."
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Show what would change, change nothing."
+    ),
+    no_start: bool = typer.Option(False, "--no-start", help="Skip the offer to launch your agent."),
+    name: str = typer.Option(DEFAULT_SERVER_NAME, "--name", help="Server name to register as."),
+) -> None:
+    """Sign in, connect your coding agent, and start.
+
+    The one command this package exists for: `curl -fsSL https://ama.dev/install | sh`
+    ends here.
+    """
+    code = onboard_flow.run(
+        env=Env.current(),
+        console=console,
+        host_flag=host,
+        scope=scope,
+        agent=agent,
+        yes=yes,
+        no_browser=no_browser,
+        dry_run=dry_run,
+        no_start=no_start,
+        server_name=name,
+        render=_render_plan,
+        deps=onboard_flow.Deps(
+            confirm=typer.confirm,
+            # Notebook mode's token is a password, not a key we minted: it must
+            # not land in scrollback or in the user's shell history.
+            ask_token=lambda: typer.prompt("Local token", hide_input=True),
+        ),
+    )
+    raise typer.Exit(code)
+
+
+@app.command()
+def login(
+    host: str = typer.Option(
+        None, "--host", help=f"Ama host. Default: ${HOST_ENV_VAR} or {DEFAULT_HOST}."
+    ),
+    no_browser: bool = typer.Option(
+        False, "--no-browser", help="Print the URL instead of opening it."
+    ),
+) -> None:
+    """Sign in and store an API key for this machine."""
+    env = Env.current()
+    target = host or os.environ.get(HOST_ENV_VAR) or DEFAULT_HOST
+
+    def show_url(url: str) -> None:
+        if no_browser:
+            console.print("Open this URL to sign in:\n")
+            console.print(f"  [cyan]{url}[/cyan]\n")
+        else:
+            console.print(f"Opening [cyan]{target}[/cyan] to sign in…")
+
+    try:
+        creds = auth.login(
+            target,
+            # --no-browser still runs the loopback listener: the user may be on
+            # a machine with a browser but no default handler. Only the auto-open
+            # is suppressed.
+            open_browser=(lambda _url: False) if no_browser else webbrowser.open,
+            on_url=show_url,
+        )
+    except auth.LoginError as exc:
+        console.print(f"[red]Login failed:[/red] {exc}")
+        raise typer.Exit(1) from exc
+
+    path = credentials.save(creds, env.home)
+    console.print(f"\n[green]✓[/green] Signed in as [bold]{creds.email or 'unknown'}[/bold]")
+    console.print(f"  Key {creds.masked_key} stored in {path}")
+    console.print("\nNext: [bold]ama mcp add[/bold] to connect your coding agent.")
+
+
+@app.command()
+def logout() -> None:
+    """Delete the stored API key from this machine."""
+    env = Env.current()
+    if credentials.delete(env.home):
+        console.print("[green]✓[/green] Signed out.")
+        console.print(
+            "[dim]The key still exists server-side — revoke it in settings if it was shared.[/dim]"
+        )
+    else:
+        console.print("[yellow]Not signed in.[/yellow]")
+
+
+@app.command()
+def whoami() -> None:
+    """Show who this machine is signed in as."""
+    env = Env.current()
+    creds = credentials.load(env.home)
+    if creds is None:
+        console.print("[yellow]Not signed in.[/yellow] Run [bold]ama login[/bold].")
+        raise typer.Exit(1)
+
+    table = Table(show_header=False, box=None)
+    table.add_row("Email", creds.email or "[dim]unknown[/dim]")
+    table.add_row("Host", creds.host)
+    table.add_row("Key", creds.masked_key)
+    table.add_row("MCP", creds.mcp_url)
+    console.print(table)
+
+
+@app.command()
+def detect(
+    all_agents: bool = typer.Option(False, "--all", help="Include agents that were not detected."),
+) -> None:
+    """Show which coding agents were detected on this machine."""
+    env = Env.current()
+    detections = detect_all(env)
+    shown = detections if all_agents else [d for d in detections if d.detected]
+
+    if not shown:
+        console.print("[yellow]No coding agents detected.[/yellow]")
+        console.print("Run with [bold]--all[/bold] to see everything that was checked.")
+        raise typer.Exit(0)
+
+    table = Table(title="Detected coding agents", title_justify="left")
+    table.add_column("", width=1)
+    table.add_column("Agent")
+    table.add_column("Confidence")
+    table.add_column("Evidence", overflow="fold")
+
+    for d in shown:
+        marker = "[green]●[/green]" if d.detected else "[dim]○[/dim]"
+        confidence = _CONFIDENCE_LABEL.get(d.confidence, "") if d.confidence else ""
+        reason = d.reason or "[dim]not detected[/dim]"
+        if d.detected and not get_adapter(d.agent_id):
+            confidence += " [dim](no adapter yet)[/dim]"
+        table.add_row(marker, d.display_name, confidence, reason)
+
+    console.print(table)
+
+
+@mcp_app.command("add")
+def mcp_add(
+    agent: str = typer.Option(
+        None, "--agent", help="Comma-separated agent ids. Default: detected."
+    ),
+    scope: Scope = typer.Option(Scope.GLOBAL, "--scope", help="Where to register."),
+    token: str = typer.Option(None, "--token", help="API key. Default: stored or $AMA_API_KEY."),
+    url: str = typer.Option(None, "--url", help="MCP URL. Default: stored or $AMA_MCP_URL."),
+    name: str = typer.Option(DEFAULT_SERVER_NAME, "--name", help="Server name to register as."),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Show what would change, change nothing."
+    ),
+) -> None:
+    """Register the Ama MCP server with your coding agents."""
+    env = Env.current()
+    creds = credentials.resolve(env.home, token=token, url=url)
+    if creds is None:
+        console.print(
+            "[red]No credentials.[/red] Pass --token, set $AMA_API_KEY, or run `ama login`."
+        )
+        raise typer.Exit(2)
+
+    targets = _resolve_agents(env, agent)
+    if not targets:
+        console.print("[yellow]No supported coding agents detected.[/yellow]")
+        console.print(f"Register manually: {creds.mcp_url}")
+        raise typer.Exit(0)
+
+    server = RemoteServer(url=creds.mcp_url, token=creds.api_key, name=name)
+    failures = 0
+
+    for detection in targets:
+        adapter = get_adapter(detection.agent_id)
+        if adapter is None:
+            console.print(f"[dim]{detection.display_name}: no adapter yet, skipping[/dim]")
+            continue
+
+        try:
+            plan = adapter.plan_add(server, scope, env)
+        except ValueError as exc:  # unreadable config -- refuse rather than clobber
+            console.print(f"[red]{detection.display_name}:[/red] {exc}")
+            failures += 1
+            continue
+
+        console.print(f"\n[bold]{detection.display_name}[/bold]")
+        if plan.unsupported:
+            console.print(f"  [yellow]skipped:[/yellow] {plan.unsupported}")
+            continue
+
+        _render_plan(plan)
+        if dry_run:
+            continue
+
+        result = apply_plan(plan, now=datetime.now())
+        if result.ok:
+            console.print("  [green]✓ registered[/green]")
+            for bak in result.backups:
+                console.print(f"  [dim]backup: {bak}[/dim]")
+        else:
+            console.print(f"  [red]✗ {result.detail}[/red]")
+            failures += 1
+
+    if dry_run:
+        console.print("\n[dim]--dry-run: nothing was changed.[/dim]")
+    elif not failures:
+        console.print("\n[dim]Undo anytime: ama mcp remove[/dim]")
+
+    if failures:
+        raise typer.Exit(1)
+
+
+@mcp_app.command("list")
+def mcp_list(
+    scope: Scope = typer.Option(Scope.GLOBAL, "--scope", help="Which scope to inspect."),
+) -> None:
+    """Show which agents have MCP servers registered, and which."""
+    env = Env.current()
+    rows: list[tuple[str, str]] = []
+
+    for detection in _detected(env):
+        adapter = get_adapter(detection.agent_id)
+        if adapter is None:
+            rows.append((detection.display_name, "[dim]no adapter yet[/dim]"))
+            continue
+        servers = adapter.list_servers(scope, env)
+        rows.append((detection.display_name, ", ".join(servers) if servers else "[dim]none[/dim]"))
+
+    if not rows:
+        console.print("[yellow]No coding agents detected.[/yellow]")
+        raise typer.Exit(0)
+
+    table = Table(title=f"MCP servers ({scope.value} scope)", title_justify="left")
+    table.add_column("Agent")
+    table.add_column("Servers", overflow="fold")
+    for agent_name, servers in rows:
+        table.add_row(agent_name, servers)
+    console.print(table)
+
+
+@mcp_app.command("remove")
+def mcp_remove(
+    agent: str = typer.Option(
+        None, "--agent", help="Comma-separated agent ids. Default: detected."
+    ),
+    scope: Scope = typer.Option(Scope.GLOBAL, "--scope", help="Where to remove from."),
+    name: str = typer.Option(DEFAULT_SERVER_NAME, "--name", help="Server name to remove."),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Show what would change, change nothing."
+    ),
+) -> None:
+    """Remove the Ama MCP server from your coding agents."""
+    env = Env.current()
+    targets = _resolve_agents(env, agent)
+    if not targets:
+        console.print("[yellow]No supported coding agents detected.[/yellow]")
+        raise typer.Exit(0)
+
+    failures = 0
+    for detection in targets:
+        adapter = get_adapter(detection.agent_id)
+        if adapter is None:
+            continue
+
+        try:
+            plan = adapter.plan_remove(name, scope, env)
+        except ValueError as exc:
+            console.print(f"[red]{detection.display_name}:[/red] {exc}")
+            failures += 1
+            continue
+
+        console.print(f"\n[bold]{detection.display_name}[/bold]")
+        if plan.unsupported:
+            console.print(f"  [yellow]skipped:[/yellow] {plan.unsupported}")
+            continue
+        if not plan.steps:
+            console.print("  [dim]not registered[/dim]")
+            continue
+
+        _render_plan(plan)
+        if dry_run:
+            continue
+
+        result = apply_plan(plan, now=datetime.now())
+        console.print(
+            "  [green]✓ removed[/green]" if result.ok else f"  [red]✗ {result.detail}[/red]"
+        )
+        failures += 0 if result.ok else 1
+
+    if dry_run:
+        console.print("\n[dim]--dry-run: nothing was changed.[/dim]")
+    if failures:
+        raise typer.Exit(1)
+
+
+if __name__ == "__main__":
+    app()

ama_cli/credentials.py

@@ -0,0 +1,126 @@
+"""Local credential storage for the public CLI.
+
+`~/.ama/credentials.json`, mode 0600. Deliberately separate from the internal
+CLI's `~/.ama/session.json` (a WorkOS sealed session, with no API-key field):
+the two CLIs must not share state, which is the coupling the package split
+exists to prevent.
+
+Phase 2 (`ama login`) writes this. Until then `ama mcp add` takes --token/--url
+or reads AMA_API_KEY / AMA_MCP_URL from the environment.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from collections.abc import Mapping
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+CREDENTIALS_ENV_VAR = "AMA_API_KEY"
+MCP_URL_ENV_VAR = "AMA_MCP_URL"
+HOST_ENV_VAR = "AMA_HOST"
+DEFAULT_HOST = "https://ama.dev"
+
+
+def credentials_path(home: Path) -> Path:
+    """Where credentials live."""
+    return home / ".ama" / "credentials.json"
+
+
+@dataclass(frozen=True)
+class Credentials:
+    """A stored API key and the endpoint it belongs to."""
+
+    host: str
+    api_key: str
+    mcp_url: str
+    email: str | None = None
+    tenant_id: str | None = None
+    created_at: str | None = None
+
+    @property
+    def masked_key(self) -> str:
+        """The key, safe to display: prefix only.
+
+        Note the server's own key_prefix is the first 8 chars of the whole
+        string -- i.e. `ama_` plus four -- so there is little to show and
+        showing more would defeat the point.
+        """
+        return f"{self.api_key[:8]}…" if len(self.api_key) > 8 else "…"
+
+
+def load(home: Path) -> Credentials | None:
+    """Read stored credentials, or None when absent or unreadable."""
+    path = credentials_path(home)
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+    try:
+        return Credentials(
+            host=data["host"],
+            api_key=data["api_key"],
+            mcp_url=data["mcp_url"],
+            email=data.get("email"),
+            tenant_id=data.get("tenant_id"),
+            created_at=data.get("created_at"),
+        )
+    except KeyError:
+        return None
+
+
+def save(creds: Credentials, home: Path) -> Path:
+    """Write credentials with 0600 permissions.
+
+    The file is chmod'd before the secret is written, so it is never briefly
+    world-readable on a fresh create.
+    """
+    path = credentials_path(home)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.touch(mode=0o600, exist_ok=True)
+    path.chmod(stat.S_IRUSR | stat.S_IWUSR)
+    path.write_text(json.dumps(asdict(creds), indent=2) + "\n")
+    return path
+
+
+def delete(home: Path) -> bool:
+    """Remove stored credentials. True when something was deleted."""
+    path = credentials_path(home)
+    if path.exists():
+        path.unlink()
+        return True
+    return False
+
+
+def resolve(
+    home: Path,
+    *,
+    token: str | None = None,
+    url: str | None = None,
+    environ: Mapping[str, str] | None = None,
+) -> Credentials | None:
+    """Resolve credentials from flags, then env, then the stored file.
+
+    Explicit flags win so a user can always override; the environment comes next
+    for CI; the stored file is the everyday path.
+    """
+    env_map: Mapping[str, str] = os.environ if environ is None else environ
+    token = token or env_map.get(CREDENTIALS_ENV_VAR)
+    url = url or env_map.get(MCP_URL_ENV_VAR)
+
+    stored = load(home)
+    if token:
+        return Credentials(
+            host=stored.host if stored else DEFAULT_HOST,
+            api_key=token,
+            mcp_url=url or (stored.mcp_url if stored else f"{DEFAULT_HOST}/mcp/sse"),
+        )
+    if stored and url:
+        return Credentials(
+            host=stored.host, api_key=stored.api_key, mcp_url=url, email=stored.email
+        )
+    return stored

ama_cli/discovery.py

@@ -0,0 +1,114 @@
+"""Host discovery via `GET /.well-known/mcp.json`.
+
+Asking the host what it is beats hardcoding `ama.dev`: self-hosted deployments
+work for free, and the MCP path stays the server's business rather than a
+constant duplicated in the CLI.
+
+The manifest also tells us *which kind* of host this is, which changes the flow:
+
+    full mode      auth "oauth_or_bearer" + a signup key -> browser login works
+    notebook mode  auth "bearer", no signup              -> no tenant, no OAuth;
+                                                            the operator sets a
+                                                            preshared token
+
+So `ama onboard` against a local notebook cannot log in via the browser, and
+must ask for the token instead. See `src/ama/api/app.py`'s mcp_discovery_manifest
+for the two shapes.
+
+urllib rather than httpx: this package sits on the install path of a one-line
+onboarding command, so it stays at typer + rich.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+
+DISCOVERY_PATH = "/.well-known/mcp.json"
+_TIMEOUT_SECONDS = 15
+
+
+@dataclass(frozen=True)
+class Manifest:
+    """What the host says about itself."""
+
+    mcp_url: str
+    auth_type: str
+    token_prefix: str | None = None
+    signup_url: str | None = None
+
+    @property
+    def is_notebook_mode(self) -> bool:
+        """True when this is a single-user local deployment.
+
+        Notebook mode has no tenant to create and no OAuth flow -- it
+        string-compares a preshared token -- so the browser login the public CLI
+        is built around does not apply. The manifest is deliberately explicit
+        about this rather than making us probe for a 404.
+        """
+        return self.auth_type == "bearer"
+
+
+def default_mcp_url(host: str) -> str:
+    """The MCP endpoint to assume when the manifest cannot be read."""
+    return f"{host.rstrip('/')}/mcp/sse"
+
+
+def parse_manifest(data: dict, host: str) -> Manifest:
+    """Build a Manifest from the raw JSON, tolerating missing keys.
+
+    Every field is optional here on purpose: this parses a document served by a
+    host we may not control, possibly an older one. A missing field falls back to
+    convention rather than raising -- a manifest we half-understand is still
+    better than none.
+    """
+    endpoint = data.get("endpoint")
+    url = endpoint.get("url") if isinstance(endpoint, dict) else None
+
+    auth = data.get("authentication")
+    auth = auth if isinstance(auth, dict) else {}
+    bearer = auth.get("bearer")
+    bearer = bearer if isinstance(bearer, dict) else {}
+
+    signup = data.get("signup")
+    signup_url = signup.get("url") if isinstance(signup, dict) else None
+
+    return Manifest(
+        mcp_url=url or default_mcp_url(host),
+        auth_type=auth.get("type") or "oauth_or_bearer",
+        token_prefix=bearer.get("token_prefix"),
+        signup_url=signup_url,
+    )
+
+
+def discover(host: str, *, fetch=None) -> Manifest | None:
+    """Read the host's manifest, or None when it cannot be read.
+
+    Returns None rather than raising: discovery is an optimisation, not a
+    requirement. A host that is genuinely unreachable will fail again at login
+    with a clearer message than anything this could produce, and a self-hosted
+    box serving no manifest should still be onboardable by convention.
+
+    `fetch` is injected so tests need no network.
+    """
+    fetcher = _fetch if fetch is None else fetch
+    url = f"{host.rstrip('/')}{DISCOVERY_PATH}"
+    try:
+        data = fetcher(url)
+    except (OSError, urllib.error.URLError, json.JSONDecodeError, ValueError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    return parse_manifest(data, host)
+
+
+def _fetch(url: str) -> dict:
+    """GET a JSON document."""
+    req = urllib.request.Request(url, headers={"Accept": "application/json"})
+    with urllib.request.urlopen(req, timeout=_TIMEOUT_SECONDS) as resp:
+        return json.loads(resp.read())
+
+
+__all__ = ["DISCOVERY_PATH", "Manifest", "default_mcp_url", "discover", "parse_manifest"]