context-router-cli 0.2.0__py3-none-any.whl

cli/commands/memory.py

@@ -0,0 +1,145 @@
+"""context-router memory command — manages durable session observations."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+memory_app = typer.Typer(help="Manage durable session memory (observations).")
+
+
+def _open_store(project_root: str) -> tuple["ObservationStore", "Database"]:
+    """Open the database and return (ObservationStore, Database).
+
+    Caller must close the Database.
+    """
+    from core.orchestrator import _find_project_root
+    from memory.store import ObservationStore
+    from storage_sqlite.database import Database
+
+    root = Path(project_root) if project_root else _find_project_root(Path.cwd())
+    db_path = root / ".context-router" / "context-router.db"
+    if not db_path.exists():
+        typer.echo(
+            "No index found. Run 'context-router init' and 'context-router index' first.",
+            err=True,
+        )
+        raise typer.Exit(1)
+    db = Database(db_path)
+    db.initialize()
+    return ObservationStore(db), db
+
+
+@memory_app.command("add")
+def add(
+    from_session: Annotated[
+        str,
+        typer.Option("--from-session", help="Path to session JSON file."),
+    ],
+    project_root: Annotated[
+        str,
+        typer.Option("--project-root", help="Project root. Auto-detected when omitted."),
+    ] = "",
+    json_output: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Add observations from a session JSON file to durable memory.
+
+    The session file must be a JSON object or array matching the Observation
+    schema (summary field is required; all others are optional).
+
+    Exit codes:
+      0 — success
+      1 — file not found or database not initialised
+      2 — invalid JSON or schema
+    """
+    session_path = Path(from_session)
+    if not session_path.exists():
+        typer.echo(f"Session file not found: {from_session}", err=True)
+        raise typer.Exit(1)
+
+    store, db = _open_store(project_root)
+    try:
+        ids = store.add_from_session_json(session_path.read_text(encoding="utf-8"))
+    except ValueError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(2)
+    finally:
+        db.close()
+
+    if json_output:
+        import json
+        typer.echo(json.dumps({"added": len(ids), "ids": ids}))
+    else:
+        typer.echo(f"Added {len(ids)} observation(s) to memory.")
+
+
+@memory_app.command("search")
+def search(
+    query: Annotated[str, typer.Argument(help="Search query.")],
+    project_root: Annotated[
+        str,
+        typer.Option("--project-root", help="Project root. Auto-detected when omitted."),
+    ] = "",
+    json_output: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Search stored observations by keyword.
+
+    Exit codes:
+      0 — success (even if no results)
+      1 — database not initialised
+    """
+    store, db = _open_store(project_root)
+    try:
+        results = store.search(query)
+    finally:
+        db.close()
+
+    if json_output:
+        import json
+        typer.echo(json.dumps([r.model_dump(mode="json") for r in results], indent=2))
+        return
+
+    if not results:
+        typer.echo("No observations found.")
+        return
+
+    for obs in results:
+        typer.echo(f"  [{obs.task_type or 'general'}] {obs.summary}")
+        if obs.fix_summary:
+            typer.echo(f"    Fix: {obs.fix_summary}")
+
+
+@memory_app.command("stale")
+def stale(
+    project_root: Annotated[
+        str,
+        typer.Option("--project-root", help="Project root. Auto-detected when omitted."),
+    ] = "",
+    json_output: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """List observations that reference files no longer in the index.
+
+    Exit codes:
+      0 — success (even if no stale observations)
+      1 — database not initialised
+    """
+    store, db = _open_store(project_root)
+    try:
+        stale_obs = store.find_stale()
+    finally:
+        db.close()
+
+    if json_output:
+        import json
+        typer.echo(json.dumps([o.model_dump(mode="json") for o in stale_obs], indent=2))
+        return
+
+    if not stale_obs:
+        typer.echo("No stale observations found.")
+        return
+
+    typer.echo(f"{len(stale_obs)} stale observation(s) (files no longer indexed):")
+    for obs in stale_obs:
+        typer.echo(f"  {obs.summary[:80]}")

cli/commands/pack.py

@@ -0,0 +1,110 @@
+"""context-router pack command — generates a ranked context pack."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+pack_app = typer.Typer(help="Generate a ranked context pack for a task.")
+
+_VALID_MODES = ("review", "debug", "implement", "handover")
+
+
+@pack_app.callback(invoke_without_command=True)
+def pack(
+    mode: Annotated[
+        str,
+        typer.Option("--mode", "-m", help="Task mode: review|debug|implement|handover."),
+    ],
+    query: Annotated[
+        str,
+        typer.Option("--query", "-q", help="Free-text description of the task."),
+    ] = "",
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Output result as JSON."),
+    ] = False,
+    project_root: Annotated[
+        str,
+        typer.Option(
+            "--project-root",
+            help="Project root containing .context-router/. Auto-detected when omitted.",
+        ),
+    ] = "",
+    error_file: Annotated[
+        str,
+        typer.Option(
+            "--error-file",
+            "-e",
+            help="Path to error file (JUnit XML, stack trace, log). Used in debug mode.",
+        ),
+    ] = "",
+) -> None:
+    """Generate a context pack for the given task MODE.
+
+    Exit codes:
+      0 — success
+      1 — no index found (run 'context-router index' first)
+      2 — invalid mode argument
+    """
+    if mode not in _VALID_MODES:
+        typer.echo(
+            f"Error: invalid mode '{mode}'. Must be one of: {', '.join(_VALID_MODES)}",
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+    from pathlib import Path
+
+    from core.orchestrator import Orchestrator  # local import — keeps CLI startup fast
+
+    root = Path(project_root) if project_root else None
+    err_path = Path(error_file) if error_file else None
+    try:
+        result = Orchestrator(project_root=root).build_pack(mode, query, error_file=err_path)
+    except FileNotFoundError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1)
+
+    if json_output:
+        typer.echo(result.model_dump_json(indent=2))
+        return
+
+    _print_pack(result)
+
+
+def _print_pack(pack: object) -> None:  # type: ignore[type-arg]
+    """Print a human-readable summary of a ContextPack."""
+    from contracts.models import ContextPack  # local import
+
+    assert isinstance(pack, ContextPack)
+
+    typer.echo(
+        f"Mode: {pack.mode}  |  "
+        f"Items: {len(pack.selected_items)}  |  "
+        f"Tokens: {pack.total_est_tokens:,} / {pack.baseline_est_tokens:,}  |  "
+        f"Reduction: {pack.reduction_pct:.1f}%"
+    )
+    if pack.query:
+        typer.echo(f"Query: {pack.query}")
+    typer.echo("")
+
+    col_widths = (40, 16, 10, 8)
+    header = (
+        f"{'Title':<{col_widths[0]}}  "
+        f"{'Source':<{col_widths[1]}}  "
+        f"{'Confidence':>{col_widths[2]}}  "
+        f"{'Tokens':>{col_widths[3]}}"
+    )
+    typer.echo(header)
+    typer.echo("-" * (sum(col_widths) + 6))
+
+    for item in pack.selected_items:
+        title = item.title[: col_widths[0] - 1] if len(item.title) >= col_widths[0] else item.title
+        typer.echo(
+            f"{title:<{col_widths[0]}}  "
+            f"{item.source_type:<{col_widths[1]}}  "
+            f"{item.confidence:>{col_widths[2]}.2f}  "
+            f"{item.est_tokens:>{col_widths[3]},}"
+        )

cli/commands/watch.py

@@ -0,0 +1,126 @@
+"""context-router watch command — watches for file changes and re-indexes."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from contracts.config import load_config
+from core.plugin_loader import PluginLoader
+from graph_index.indexer import Indexer
+from graph_index.watcher import IndexWatcher
+from storage_sqlite.database import Database
+
+watch_app = typer.Typer(help="Watch for file changes and incrementally re-index.")
+
+
+@watch_app.callback(invoke_without_command=True)
+def watch(
+    project_root: Annotated[
+        Path,
+        typer.Option(
+            "--project-root",
+            "-p",
+            help="Root of the project to watch. Defaults to current directory.",
+        ),
+    ] = Path("."),
+    repo_name: Annotated[
+        str,
+        typer.Option("--repo", help="Logical repository name stored with symbols."),
+    ] = "default",
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Output initial index result as JSON."),
+    ] = False,
+) -> None:
+    """Watch PROJECT_ROOT for file changes and trigger incremental re-indexing.
+
+    Performs a full index on startup, then monitors the directory tree for
+    changes. Modified or created files are re-indexed; deleted files are
+    removed from the database.
+
+    Press Ctrl-C to stop watching.
+
+    Exit codes:
+      0 — stopped cleanly (Ctrl-C)
+      1 — configuration / setup error
+      2 — unexpected internal error
+    """
+    try:
+        project_root = project_root.resolve()
+        config_dir = project_root / ".context-router"
+
+        try:
+            config = load_config(project_root)
+        except Exception as exc:  # noqa: BLE001
+            _err(f"Failed to load config: {exc}", json_output, exit_code=1)
+            return
+
+        db_path = config_dir / "context-router.db"
+        if not db_path.exists():
+            _err(
+                f"Database not found at {db_path}. Run 'context-router init' first.",
+                json_output,
+                exit_code=1,
+            )
+            return
+
+        db = Database(db_path)
+        db.initialize()
+
+        try:
+            plugin_loader = PluginLoader()
+            plugin_loader.discover()
+
+            indexer = Indexer(db, plugin_loader, config, repo_name)
+
+            # Full index on startup
+            typer.echo(f"Indexing {project_root} ...", err=True)
+            result = indexer.run(project_root)
+
+            if json_output:
+                typer.echo(
+                    json.dumps(
+                        {
+                            "files_scanned": result.files_scanned,
+                            "symbols_written": result.symbols_written,
+                            "edges_written": result.edges_written,
+                            "duration_seconds": round(result.duration_seconds, 3),
+                            "errors": result.errors,
+                        }
+                    )
+                )
+            else:
+                typer.echo(
+                    f"Initial index: {result.files_scanned} files, "
+                    f"{result.symbols_written} symbols ({result.duration_seconds:.2f}s)",
+                    err=True,
+                )
+
+            typer.echo(f"Watching {project_root} for changes ... (Ctrl-C to stop)", err=True)
+
+            watcher = IndexWatcher(indexer, project_root, config)
+            watcher.start()  # Blocks until KeyboardInterrupt
+
+        finally:
+            db.close()
+
+    except typer.Exit:
+        raise
+    except KeyboardInterrupt:
+        raise typer.Exit(code=0)
+    except Exception as exc:  # noqa: BLE001
+        _err(f"Unexpected error: {exc}", json_output, exit_code=2)
+
+
+def _err(message: str, json_output: bool, exit_code: int) -> None:
+    """Print an error to stderr and exit with the given code."""
+    if json_output:
+        typer.echo(json.dumps({"status": "error", "message": message}), err=True)
+    else:
+        typer.echo(f"Error: {message}", err=True)
+    raise typer.Exit(code=exit_code)

cli/commands/workspace.py

@@ -0,0 +1,294 @@
+"""context-router workspace command — manages multi-repo workspaces."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+workspace_app = typer.Typer(help="Manage multi-repo workspaces.")
+repo_app = typer.Typer(help="Manage repos in the workspace.")
+link_app = typer.Typer(help="Manage cross-repo links.")
+workspace_app.add_typer(repo_app, name="repo")
+workspace_app.add_typer(link_app, name="link")
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _load_or_die(root: Path):
+    """Load workspace or exit with code 1 if missing."""
+    from workspace import WorkspaceLoader
+    ws = WorkspaceLoader.load(root)
+    if ws is None:
+        typer.echo(
+            "No workspace.yaml found. Run 'context-router workspace init' first.",
+            err=True,
+        )
+        raise typer.Exit(1)
+    return ws
+
+
+def _save(root: Path, ws) -> None:
+    from workspace import WorkspaceLoader
+    WorkspaceLoader.save(root, ws)
+
+
+def _root_path(root: str) -> Path:
+    return Path(root).resolve() if root else Path.cwd()
+
+
+# ---------------------------------------------------------------------------
+# workspace init
+# ---------------------------------------------------------------------------
+
+@workspace_app.command("init")
+def workspace_init(
+    root: Annotated[
+        str,
+        typer.Option("--root", help="Directory to create workspace.yaml in."),
+    ] = "",
+    name: Annotated[
+        str,
+        typer.Option("--name", help="Workspace name."),
+    ] = "default",
+    json_output: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Create a new empty workspace.yaml.
+
+    Exit codes:
+      0 — success
+      1 — workspace.yaml already exists
+    """
+    from workspace import WorkspaceLoader
+
+    r = _root_path(root)
+    ws_file = r / "workspace.yaml"
+    if ws_file.exists():
+        typer.echo(
+            f"workspace.yaml already exists at {ws_file}. "
+            "Use 'workspace repo add' to add repositories.",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    ws = WorkspaceLoader.init(r, name=name)
+
+    if json_output:
+        typer.echo(json.dumps({"name": ws.name, "path": str(ws_file)}))
+    else:
+        typer.echo(f"Workspace '{ws.name}' initialised at {ws_file}")
+
+
+# ---------------------------------------------------------------------------
+# workspace repo add
+# ---------------------------------------------------------------------------
+
+@repo_app.command("add")
+def repo_add(
+    name: Annotated[str, typer.Argument(help="Logical name for the repository.")],
+    path: Annotated[str, typer.Argument(help="Filesystem path to the repository.")],
+    language: Annotated[
+        str,
+        typer.Option("--language", "-l", help="Primary language (optional)."),
+    ] = "",
+    root: Annotated[
+        str,
+        typer.Option("--root", help="Workspace root directory."),
+    ] = "",
+    auto_detect_links: Annotated[
+        bool,
+        typer.Option("--detect-links/--no-detect-links", help="Auto-detect cross-repo links."),
+    ] = True,
+    json_output: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Add a repository to the workspace.
+
+    Exit codes:
+      0 — success
+      1 — workspace.yaml not found
+    """
+    from workspace import RepoRegistry, detect_links
+
+    r = _root_path(root)
+    ws = _load_or_die(r)
+    reg = RepoRegistry(ws)
+    repo = reg.add(name, Path(path).resolve(), language=language)
+
+    if auto_detect_links:
+        all_repos = reg.get_all()
+        detected = detect_links(all_repos)
+        for from_repo, targets in detected.items():
+            for to_repo in targets:
+                reg.add_link(from_repo, to_repo)
+
+    updated_ws = reg.to_descriptor()
+    _save(r, updated_ws)
+
+    if json_output:
+        typer.echo(json.dumps({
+            "name": repo.name,
+            "path": str(repo.path),
+            "branch": repo.branch,
+            "sha": repo.sha,
+            "dirty": repo.dirty,
+        }))
+    else:
+        status = f"{repo.branch}@{repo.sha}" if repo.branch else "(no git)"
+        dirty = " (dirty)" if repo.dirty else ""
+        typer.echo(f"Repo added: {repo.name}  {status}{dirty}")
+
+
+# ---------------------------------------------------------------------------
+# workspace repo list
+# ---------------------------------------------------------------------------
+
+@repo_app.command("list")
+def repo_list(
+    root: Annotated[
+        str,
+        typer.Option("--root", help="Workspace root directory."),
+    ] = "",
+    json_output: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """List all repos in the workspace.
+
+    Exit codes:
+      0 — success
+      1 — workspace.yaml not found
+    """
+    from workspace import RepoRegistry
+
+    r = _root_path(root)
+    ws = _load_or_die(r)
+    reg = RepoRegistry(ws)
+    repos = reg.get_all()
+
+    if json_output:
+        typer.echo(json.dumps([
+            {
+                "name": repo.name,
+                "path": str(repo.path),
+                "branch": repo.branch,
+                "sha": repo.sha,
+                "dirty": repo.dirty,
+                "language": repo.language,
+            }
+            for repo in repos
+        ], indent=2))
+        return
+
+    if not repos:
+        typer.echo("No repos in workspace. Use 'context-router workspace repo add' to add one.")
+        return
+
+    typer.echo(f"{'NAME':<20} {'BRANCH':<20} {'SHA':<10} {'DIRTY':<6} PATH")
+    typer.echo("-" * 80)
+    for repo in repos:
+        branch = repo.branch or "—"
+        sha = repo.sha[:8] if repo.sha else "—"
+        dirty = "yes" if repo.dirty else "no"
+        typer.echo(f"{repo.name:<20} {branch:<20} {sha:<10} {dirty:<6} {repo.path}")
+
+
+# ---------------------------------------------------------------------------
+# workspace link add
+# ---------------------------------------------------------------------------
+
+@link_app.command("add")
+def link_add(
+    from_repo: Annotated[str, typer.Argument(help="Source repository name.")],
+    to_repo: Annotated[str, typer.Argument(help="Target repository name (dependency).")],
+    root: Annotated[
+        str,
+        typer.Option("--root", help="Workspace root directory."),
+    ] = "",
+    json_output: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Add a manual cross-repo dependency link.
+
+    Records that FROM_REPO depends on TO_REPO, boosting TO_REPO items
+    in cross-repo context packs.
+
+    Exit codes:
+      0 — success
+      1 — workspace.yaml not found
+    """
+    from workspace import RepoRegistry
+
+    r = _root_path(root)
+    ws = _load_or_die(r)
+    reg = RepoRegistry(ws)
+    reg.add_link(from_repo, to_repo)
+    _save(r, reg.to_descriptor())
+
+    if json_output:
+        typer.echo(json.dumps({"from": from_repo, "to": to_repo}))
+    else:
+        typer.echo(f"Link added: {from_repo} → {to_repo}")
+
+
+# ---------------------------------------------------------------------------
+# workspace pack
+# ---------------------------------------------------------------------------
+
+@workspace_app.command("pack")
+def workspace_pack(
+    mode: Annotated[
+        str,
+        typer.Option("--mode", "-m", help="review|implement|debug|handover"),
+    ],
+    query: Annotated[
+        str,
+        typer.Option("--query", "-q", help="Free-text task description."),
+    ] = "",
+    root: Annotated[
+        str,
+        typer.Option("--root", help="Workspace root directory."),
+    ] = "",
+    json_output: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Generate a cross-repo context pack for all workspace repos.
+
+    Exit codes:
+      0 — success
+      1 — workspace.yaml not found or no index
+      2 — invalid mode
+    """
+    from core.workspace_orchestrator import WorkspaceOrchestrator
+
+    r = _root_path(root)
+
+    if mode not in ("review", "implement", "debug", "handover"):
+        typer.echo(f"Error: --mode must be one of: review, implement, debug, handover", err=True)
+        raise typer.Exit(2)
+
+    try:
+        orch = WorkspaceOrchestrator(workspace_root=r)
+        pack = orch.build_pack(mode, query)
+    except FileNotFoundError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1)
+
+    if json_output:
+        typer.echo(pack.model_dump_json(indent=2))
+        return
+
+    if not pack.selected_items:
+        typer.echo("No context items found. Run 'context-router index' in each repo first.")
+        return
+
+    typer.echo(f"\n[{pack.mode}] {pack.query or '(no query)'}")
+    typer.echo(
+        f"~{pack.total_est_tokens:,} tokens  "
+        f"({pack.reduction_pct:.0f}% reduction)\n"
+    )
+    typer.echo(f"{'TITLE':<45} {'SOURCE':<18} {'CONF':>5} {'TOK':>6}")
+    typer.echo("-" * 78)
+    for item in pack.selected_items:
+        title = item.title[:44]
+        source = item.source_type[:17]
+        typer.echo(f"{title:<45} {source:<18} {item.confidence:>5.2f} {item.est_tokens:>6}")