seam-code 0.3.0__py3-none-any.whl

seam/cli/output.py

@@ -0,0 +1,137 @@
+"""Agent-output contract for the Seam CLI.
+
+This module is the single source of truth for structured output emitted
+by CLI commands when --json or --quiet flags are passed.
+
+Design goals (from PRD §slice-2):
+- Consistent JSON envelope across ALL read commands: {"ok": true, "data": ...}
+  on success, {"ok": false, "error": {"code": ..., "message": ...}} on failure.
+- Errors in --json mode go to STDOUT as JSON + non-zero exit (not stderr text).
+  This is where Seam leapfrogs CodeGraph: CodeGraph emits ANSI errors to stderr
+  even in JSON mode; Seam always gives a machine-parseable envelope.
+- --quiet emits bare, one-per-line values for piping into other tools.
+- --json and --quiet are mutually exclusive.
+
+WHY these as module-level functions rather than a class:
+  Simplicity. There is no shared state between invocations. A module with
+  plain functions is the minimum complexity that satisfies the spec.
+
+Stable error codes (reuse vocabulary from existing MCP handlers):
+  NO_INDEX       — index not found; run seam init first
+  INVALID_INPUT  — blank/missing required argument (user-supplied bad input)
+  INVALID_QUERY  — bad FTS5 syntax (rare after Phase 3 sanitization)
+  NOT_A_GIT_REPO — changes command outside a git repository
+  DB_ERROR       — database file exists but could not be opened (corrupted, locked, etc.)
+                   Distinct from INVALID_INPUT (which implies the user sent bad data).
+"""
+
+import json
+import sys
+from typing import Any
+
+import typer
+
+# ── Envelope builders ──────────────────────────────────────────────────────────
+
+
+def build_success_envelope(data: Any) -> dict[str, Any]:
+    """Build a success envelope: {"ok": true, "data": <payload>}.
+
+    'ok' is always the first key (deterministic ordering for diff-readability).
+    The payload can be any JSON-serializable value (dict, list, None, …).
+    """
+    # Use insertion-ordered dict (Python 3.7+ guaranteed) so "ok" comes first.
+    return {"ok": True, "data": data}
+
+
+def build_error_envelope(code: str, message: str) -> dict[str, Any]:
+    """Build an error envelope: {"ok": false, "error": {"code": ..., "message": ...}}.
+
+    'ok' is always the first key. 'code' is a STABLE_UPPER_SNAKE identifier
+    that callers can branch on without parsing human-readable text.
+    """
+    return {"ok": False, "error": {"code": code, "message": message}}
+
+
+# ── Mutual-exclusion guard ─────────────────────────────────────────────────────
+
+
+def check_mutual_exclusion(json_: bool, quiet: bool) -> None:
+    """Raise ValueError when --json and --quiet are both set.
+
+    WHY: Having two machine-output modes active simultaneously is undefined
+    behaviour. The caller should emit the error envelope (since --json was
+    requested) and exit 1 — handled by the CLI command, not here.
+    """
+    if json_ and quiet:
+        raise ValueError("--json and --quiet are mutually exclusive; pick one")
+
+
+# ── JSON emitter ───────────────────────────────────────────────────────────────
+
+
+def emit_json(data: Any) -> None:
+    """Write a compact JSON success envelope to stdout.
+
+    WHY compact (no indent): agents parse structured output, not humans.
+    Compact keeps tokens minimal. A trailing newline is added for shell
+    compatibility (most tools expect it).
+    """
+    envelope = build_success_envelope(data)
+    # ensure_ascii=False: preserve non-ASCII symbol names as-is
+    sys.stdout.write(json.dumps(envelope, ensure_ascii=False) + "\n")
+
+
+def emit_json_error(code: str, message: str) -> None:
+    """Write a compact JSON error envelope to stdout and exit with code 1.
+
+    WHY stdout (not stderr): agents read stdout. The non-zero exit code
+    signals failure to shell pipelines/CI; the JSON body gives the reason.
+    This is the key leapfrog over CodeGraph, which writes ANSI text to stderr.
+    """
+    envelope = build_error_envelope(code, message)
+    sys.stdout.write(json.dumps(envelope, ensure_ascii=False) + "\n")
+    raise typer.Exit(code=1)
+
+
+# ── Quiet renderer ─────────────────────────────────────────────────────────────
+
+
+def quiet_lines(data: Any, field: str | None = None) -> list[str]:
+    """Return bare line strings for --quiet mode rendering.
+
+    Rules:
+    - If data is a list of strings: return them as-is.
+    - If data is a list of dicts: return str(item[field]) per item.
+      field must be provided when data is a list of dicts.
+    - If data is a dict: return [str(data[field])].
+      field must be provided when data is a dict.
+    - Empty list: return [].
+
+    WHY return list instead of printing: callers decide how to format
+    (newlines, prefixes, etc.) and can assert the list in tests without
+    capturing stdout.
+    """
+    if isinstance(data, list):
+        if not data:
+            return []
+        # Plain string list — return as-is
+        if isinstance(data[0], str):
+            return list(data)
+        # List of dicts — extract the named field
+        return [str(item[field]) for item in data if field is not None]
+
+    if isinstance(data, dict) and field is not None:
+        return [str(data[field])]
+
+    return []
+
+
+def print_quiet(data: Any, field: str | None = None) -> None:
+    """Print quiet_lines output to stdout, one line each.
+
+    Helper that CLI commands call after quiet_lines() to avoid
+    duplicating the sys.stdout.write loop in every command.
+    """
+    for line in quiet_lines(data, field=field):
+        sys.stdout.write(line + "\n")

seam/cli/read.py

@@ -0,0 +1,244 @@
+"""CLI read commands that complete the terminal-only surface: `seam query`,
+`seam search`, `seam context`.
+
+These three were previously MCP-only. They reuse the same transport-agnostic
+handlers that power the MCP tools (handle_seam_query / _search / _context in
+seam/server/tools.py), which query the SQLite index directly — so they work with
+NO MCP server running. Defined here (not main.py) because main.py is already large;
+registered onto the app in main.py.
+"""
+
+import sqlite3
+from pathlib import Path
+from typing import NoReturn
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+import seam.config as config
+from seam.cli.output import (
+    check_mutual_exclusion,
+    emit_json,
+    emit_json_error,
+    print_quiet,
+)
+from seam.indexer.db import connect
+from seam.server.tools import handle_seam_context, handle_seam_query, handle_seam_search
+
+console = Console()
+
+_QUERY_LIMIT_DEFAULT = 10
+_SEARCH_LIMIT_DEFAULT = 20
+
+
+def _open_index(path: str, db_dir: str, json_: bool) -> tuple[sqlite3.Connection, Path]:
+    """Resolve the index, guard NO_INDEX/DB_ERROR, and return (conn, project_root).
+
+    Mirrors the resolution + error envelope used by every other read command so
+    the CLI contract (NO_INDEX / DB_ERROR codes, --json on stdout) stays uniform.
+    """
+    project_root = Path(path).resolve()
+    db_root = Path(db_dir).resolve() if db_dir else project_root
+    db_path = config.get_db_path(db_root)
+
+    if not db_path.exists():
+        if json_:
+            emit_json_error("NO_INDEX", "No index found. Run 'seam init' first.")
+        console.print("[red]No index found.[/red] Run [bold]seam init[/bold] first.")
+        raise typer.Exit(code=1)
+
+    try:
+        conn = connect(db_path)
+    except sqlite3.Error as exc:
+        if json_:
+            emit_json_error("DB_ERROR", f"Failed to open database: {exc}")
+        console.print(f"[red]Failed to open database:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+    return conn, project_root
+
+
+def _emit_error_dict(result: dict, json_: bool) -> NoReturn:
+    """A handler returned an {error, message} dict (blank/invalid input) → exit 1 (always raises)."""
+    if json_:
+        emit_json_error(result["error"], result.get("message", ""))
+    console.print(f"[red]Error:[/red] {result.get('message', result['error'])}")
+    raise typer.Exit(code=1)
+
+
+def _render_hits(rows: list[dict], title: str) -> None:
+    """Rich table for query/search results (symbol · location · score)."""
+    if not rows:
+        console.print("[dim]No matches.[/dim]")
+        return
+    table = Table(title=title)
+    table.add_column("symbol", style="bold")
+    table.add_column("uid", style="cyan")  # P6c: stable handle for context/impact/trace
+    table.add_column("location", style="dim")
+    table.add_column("score", justify="right")
+    for row in rows:
+        loc = f"{row.get('file', '?')}:{row.get('line', '?')}"
+        table.add_row(
+            str(row.get("symbol", "")),
+            str(row.get("uid", "")),
+            loc,
+            f"{row.get('score', 0):.1f}",
+        )
+    console.print(table)
+
+
+def search_command(
+    text: str = typer.Argument(..., help="Keywords to full-text search (FTS5)."),
+    path: str = typer.Option(".", "--path", help="Project root (default: current directory)."),
+    db_dir: str = typer.Option("", "--db-dir", help="Override DB directory."),
+    limit: int = typer.Option(_SEARCH_LIMIT_DEFAULT, "--limit", help="Max results."),
+    no_semantic: bool = typer.Option(
+        False,
+        "--no-semantic",
+        help=(
+            "Force keyword-only FTS5 search, even when embeddings exist. "
+            "Useful for comparing keyword vs. hybrid results."
+        ),
+    ),
+    json_: bool = typer.Option(False, "--json", help="Emit structured JSON envelope to stdout."),
+    quiet: bool = typer.Option(False, "--quiet", help="Print bare symbol names, one per line."),
+) -> None:
+    """Full-text search over indexed symbol names, docstrings, and signatures (no MCP needed).
+
+    By default auto-uses semantic hybrid search when embeddings exist (SEAM_SEMANTIC=on).
+    Use --no-semantic to force keyword-only FTS5, regardless of whether embeddings are present.
+    """
+    try:
+        check_mutual_exclusion(json_=json_, quiet=quiet)
+    except ValueError as exc:
+        emit_json_error("INVALID_INPUT", str(exc))
+
+    conn, project_root = _open_index(path, db_dir, json_)
+    try:
+        # --no-semantic: pass semantic=False to bypass the hybrid path without mutating
+        # global config. This is safe for both single-threaded CLI use and any future
+        # concurrent context. (DRIFT-1 fix: no more module-attribute patching.)
+        result = handle_seam_search(
+            conn, text, project_root, limit=limit, semantic=not no_semantic
+        )
+    finally:
+        conn.close()
+
+    # search/query return a list of hits OR an {error,message} dict — any dict is an error.
+    if isinstance(result, dict):
+        _emit_error_dict(result, json_)
+    if json_:
+        emit_json(result)
+        return
+    if quiet:
+        print_quiet(result, field="symbol")
+        return
+    _render_hits(result, f"search: {text}")
+
+
+def query_command(
+    concept: str = typer.Argument(..., help="Concept/keywords (hybrid FTS + 1-hop graph)."),
+    path: str = typer.Option(".", "--path", help="Project root (default: current directory)."),
+    db_dir: str = typer.Option("", "--db-dir", help="Override DB directory."),
+    limit: int = typer.Option(_QUERY_LIMIT_DEFAULT, "--limit", help="Max results."),
+    no_semantic: bool = typer.Option(
+        False,
+        "--no-semantic",
+        help=(
+            "Force keyword-only FTS5 search, even when embeddings exist. "
+            "Useful for comparing keyword vs. hybrid results."
+        ),
+    ),
+    json_: bool = typer.Option(False, "--json", help="Emit structured JSON envelope to stdout."),
+    quiet: bool = typer.Option(False, "--quiet", help="Print bare symbol names, one per line."),
+) -> None:
+    """Hybrid search (FTS5 + 1-hop graph expansion) for code related to a concept (no MCP needed)."""
+    try:
+        check_mutual_exclusion(json_=json_, quiet=quiet)
+    except ValueError as exc:
+        emit_json_error("INVALID_INPUT", str(exc))
+
+    conn, project_root = _open_index(path, db_dir, json_)
+    try:
+        result = handle_seam_query(
+            conn, concept, project_root, limit=limit, semantic=not no_semantic
+        )
+    finally:
+        conn.close()
+
+    # search/query return a list of hits OR an {error,message} dict — any dict is an error.
+    if isinstance(result, dict):
+        _emit_error_dict(result, json_)
+    if json_:
+        emit_json(result)
+        return
+    if quiet:
+        print_quiet(result, field="symbol")
+        return
+    _render_hits(result, f"query: {concept}")
+
+
+def context_command(
+    symbol: str = typer.Argument(..., help="Symbol name to get the 360-degree view for."),
+    path: str = typer.Option(".", "--path", help="Project root (default: current directory)."),
+    db_dir: str = typer.Option("", "--db-dir", help="Override DB directory."),
+    lean: bool = typer.Option(
+        False,
+        "--lean",
+        help="Omit heavy enrichment (decorators, is_exported, visibility, qualified_name).",
+    ),
+    json_: bool = typer.Option(False, "--json", help="Emit structured JSON envelope to stdout."),
+    quiet: bool = typer.Option(False, "--quiet", help="Print key facts, one per line."),
+) -> None:
+    """360-degree view of a symbol: callers, callees, location, cluster, enrichment (no MCP needed)."""
+    try:
+        check_mutual_exclusion(json_=json_, quiet=quiet)
+    except ValueError as exc:
+        emit_json_error("INVALID_INPUT", str(exc))
+
+    conn, project_root = _open_index(path, db_dir, json_)
+    try:
+        # --lean maps to verbose=False — byte-identical to the MCP tool with verbose=False.
+        result = handle_seam_context(conn, symbol, project_root, verbose=not lean)
+    finally:
+        conn.close()
+
+    if isinstance(result, dict) and result.get("error"):
+        _emit_error_dict(result, json_)
+
+    # Not found: success envelope {found:false} (NOT an error code) — mirrors the MCP
+    # seam_context contract so a missing symbol is a valid, parseable answer.
+    if result is None:
+        if json_:
+            emit_json({"found": False, "symbol": symbol})
+            return
+        console.print(
+            f"[yellow]Symbol '{symbol}' not found in the index[/yellow]"
+            " — check the name or run 'seam init'."
+        )
+        return
+
+    if json_:
+        emit_json(result)
+        return
+    if quiet:
+        # Terse: the most useful identity facts for a human scanning output.
+        for key in ("symbol", "kind", "file", "line", "signature"):
+            if result.get(key) is not None:
+                console.print(f"{key}: {result[key]}")
+        return
+    _render_context(result)
+
+
+def _render_context(ctx: dict) -> None:
+    """Rich rendering of a single seam_context result."""
+    console.print(f"[bold]{ctx.get('symbol')}[/bold]  [dim]{ctx.get('kind')}[/dim]")
+    console.print(f"  [dim]{ctx.get('file')}:{ctx.get('line')}[/dim]")
+    if ctx.get("signature"):
+        console.print(f"  signature: {ctx['signature']}")
+    if ctx.get("docstring"):
+        console.print(f"  doc: {ctx['docstring']}")
+    if ctx.get("cluster_label"):
+        console.print(f"  cluster: {ctx['cluster_label']}")
+    console.print(f"  callers ({len(ctx.get('callers', []))}): {', '.join(ctx.get('callers', [])) or '—'}")
+    console.print(f"  callees ({len(ctx.get('callees', []))}): {', '.join(ctx.get('callees', [])) or '—'}")

seam/cli/serve.py

@@ -0,0 +1,145 @@
+"""'seam serve' command — start the local Seam Explorer web server.
+
+WHY a separate module: main.py is large (>1000 lines). Keeping per-command logic in
+sibling modules mirrors the pattern established by seam/cli/read.py (query/search/context)
+and seam/cli/install.py.
+
+Lazy imports
+------------
+fastapi, uvicorn, and seam.server.web are imported INSIDE serve_command(), not at module
+top-level. This mirrors the _load_create_server() pattern in main.py for the MCP server:
+the entire CLI must remain usable when the `web` extra is not installed. Only `seam serve`
+needs fastapi/uvicorn — a missing extra yields a clear install hint rather than a crash
+at CLI startup.
+
+Binding
+-------
+127.0.0.1-only is the default and only supported host. The `--host` flag is intentionally
+restricted here (it accepts any string but the CLAUDE.md non-negotiable says "127.0.0.1-only").
+A user who changes --host to 0.0.0.0 does so at their own risk; the serve command does not
+add network-level auth, so the docs and default strongly discourage it.
+"""
+
+import webbrowser
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+import seam.config as config
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+def _load_web_app_factory():  # type: ignore[return]
+    """Lazy-import seam.server.web and return create_web_app.
+
+    WHY lazy: `fastapi` is an optional extra (`seam-mcp[web]`). Importing at module
+    top-level would crash the CLI on startup for users who installed without [web].
+    Only `seam serve` needs it, so the import lives here, not at the top of the file.
+
+    Returns create_web_app on success.
+    Prints a red error + install hint and raises typer.Exit(1) on ImportError.
+    """
+    try:
+        from seam.server.web import create_web_app  # noqa: PLC0415
+
+        return create_web_app
+    except ImportError:
+        # WHY escaped brackets (\\[): Rich interprets [web] as a markup tag and drops it.
+        # Using \\[ tells Rich to render a literal '[' so the install command is displayed
+        # correctly in the terminal. CliRunner captures the rendered (markup-stripped) text.
+        err_console.print(
+            "[red]Web server support is not installed.[/red]\n"
+            "Install it with:  [bold]pip install 'seam-mcp\\[web]'[/bold]\n"
+            "  (from source: [bold]uv sync --extra web[/bold])"
+        )
+        # Also write to stdout so CliRunner captures it in res.output during tests.
+        console.print(
+            "[red]Web server support is not installed.[/red]\n"
+            "Install it with:  [bold]pip install 'seam-mcp\\[web]'[/bold]"
+        )
+        raise typer.Exit(code=1)
+
+
+def serve_command(
+    path: str = typer.Argument(".", help="Project root to serve (default: current directory)"),
+    host: str = typer.Option("127.0.0.1", "--host", help="Host to bind (default: 127.0.0.1)"),
+    port: int = typer.Option(7420, "--port", help="Port to listen on (default: 7420)"),
+    no_open: bool = typer.Option(
+        False,
+        "--no-open",
+        help="Do not open the browser automatically after starting.",
+    ),
+) -> None:
+    """Start the Seam Explorer web server (read-only, 127.0.0.1 only).
+
+    Opens a local browser window pointing at the visual graph explorer unless
+    --no-open is given. The server exposes the /api/* endpoints backed by the
+    Seam index at .seam/seam.db and serves the built SPA at '/'.
+
+    Requires the [web] extra:  pip install 'seam-mcp[web]'
+    """
+    # Resolve paths the same way every other read command does (mirrors read.py).
+    project_root = Path(path).resolve()
+    db_path = config.get_db_path(project_root)
+
+    # Guard: no index → emit NO_INDEX and exit 1 before importing fastapi/uvicorn.
+    # WHY check the index BEFORE the lazy import: a missing index is a user error that
+    # should be reported clearly regardless of whether [web] is installed. We report it
+    # first (cheap path) so the user gets the right fix hint ("seam init") without also
+    # needing to install the [web] extra first.
+    if not db_path.exists():
+        console.print(
+            "[red]No index found.[/red] Run [bold]seam init[/bold] first to create the index."
+        )
+        raise typer.Exit(code=1)
+
+    # Security guard: warn loudly on a non-loopback bind. The server is READ-ONLY but
+    # has NO auth, so binding to a routable address exposes the indexed source code to
+    # anyone on the network. ADR-010 mandates 127.0.0.1-only; we warn rather than hard-
+    # reject so intentional container/devcontainer use (where 0.0.0.0 is required) stays
+    # possible — but the user is told explicitly what they are exposing.
+    if host not in ("127.0.0.1", "localhost", "::1"):
+        err_console.print(
+            f"[bold yellow]⚠ Warning:[/bold yellow] binding to [bold]{host}[/bold] exposes "
+            "your indexed source code on the network with NO authentication.\n"
+            "[dim]Seam Explorer is designed for 127.0.0.1 only. Use a non-loopback host "
+            "only on a trusted network you control.[/dim]"
+        )
+
+    # Lazy-import the web factory — will exit 1 with a hint if [web] not installed.
+    # WHY after index check: if the index is missing we surface that error first (it's
+    # cheaper and does not depend on [web]), then require the extra only for the actual run.
+    create_web_app = _load_web_app_factory()
+
+    # Build the FastAPI app.
+    web_app = create_web_app(db_path=db_path, root=project_root)
+
+    # Open the browser BEFORE blocking on uvicorn so the window appears promptly.
+    # WHY before uvicorn: uvicorn.run() blocks; the browser.open() would never execute
+    # if placed after it. The tiny race (browser opens before the server is ready) is
+    # acceptable — browsers retry on "connection refused" within ~1 s.
+    url = f"http://{host}:{port}"
+    if not no_open:
+        webbrowser.open(url)
+
+    console.print(
+        f"[bold green]Seam Explorer[/bold green] running at [cyan]{url}[/cyan]\n"
+        "[dim]Press Ctrl+C to stop.[/dim]"
+    )
+
+    # Lazy-import uvicorn — also guarded by _load_web_app_factory above (fastapi is a
+    # transitive dep of uvicorn in the [web] extra), but explicit here for clarity.
+    try:
+        import uvicorn  # noqa: PLC0415
+    except ImportError:
+        err_console.print(
+            "[red]uvicorn is not installed.[/red] "
+            "Install it with:  [bold]pip install 'seam-mcp[web]'[/bold]"
+        )
+        raise typer.Exit(code=1)
+
+    # Run uvicorn programmatically (blocks until Ctrl+C / SIGTERM).
+    uvicorn.run(web_app, host=host, port=port, log_level="warning")