SourceIndex 0.1.0__py3-none-any.whl

sourceindex/cli/commands.py

@@ -0,0 +1,678 @@
+"""CLI subcommands. Heavy imports (build/search/server/claudecode) are
+deferred into each ``cmd_*`` body so ``sourceindex statusline`` — re-run
+on every Claude Code render tick — doesn't pay for ``litellm``."""
+
+import argparse
+import contextlib
+import sys
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+
+from ..lib.log import get_logger
+from .api_key import _persist_api_key, _prompt_api_key, _require_api_key
+
+_log = get_logger(__name__)
+from .install import (
+    CLAUDE_MD_MARKER_AGENT,
+    CLAUDE_MD_MARKER_MCP,
+    CLAUDE_MD_SECTION_AGENT,
+    CLAUDE_MD_SECTION_MCP,
+    _append_claude_md,
+    _ensure_gitignored,
+    _install_hooks,
+    _register_pretooluse_hook,
+    _write_mcp_config,
+    _write_restrict_hook,
+    _write_subagent_config,
+)
+
+
+def _parse_languages(value: str | None):
+    if not value:
+        return None
+    from ..lib.languages import get_languages
+    keys = [k.strip() for k in value.split(",") if k.strip()]
+    return get_languages(keys) if keys else None
+
+
+def _stream_progress(progress_path: Path, stop: threading.Event) -> None:
+    """Tail a single-line progress file the daemon updates on each tick.
+    Re-renders the bar to our own stderr — the daemon's stderr is /dev/null."""
+    last = ""
+    is_tty = sys.stderr.isatty()
+    landed_on_fresh_line = False
+    while not stop.wait(0.25):
+        try:
+            line = progress_path.read_text().rstrip("\n")
+        except (FileNotFoundError, OSError):
+            continue
+        if not line or line == last:
+            continue
+        if is_tty and not landed_on_fresh_line:
+            # Move below any log lines already printed before the build started.
+            sys.stderr.write("\n")
+            landed_on_fresh_line = True
+        last = line
+        if is_tty:
+            sys.stderr.write("\r\033[K" + line)
+            sys.stderr.flush()
+        else:
+            print(line, file=sys.stderr)
+    if is_tty and landed_on_fresh_line:
+        sys.stderr.write("\n")
+        sys.stderr.flush()
+
+
+@contextlib.contextmanager
+def _mirror_daemon_progress(repo_hash: str):
+    """Mirror the daemon's progress side-channel onto our stderr for the
+    duration of the wrapped RPC. No-ops if the daemon writes nothing."""
+    from ..daemon import lifecycle
+    progress_path = lifecycle.progress_file(repo_hash)
+    stop = threading.Event()
+    thread = threading.Thread(
+        target=_stream_progress, args=(progress_path, stop), daemon=True,
+    )
+    thread.start()
+    try:
+        yield
+    finally:
+        stop.set()
+        thread.join(timeout=1)
+
+
+def cmd_init(args: argparse.Namespace) -> None:
+    from ..daemon import Client, IndexDir
+    from ..lib.backend import apply_remote_config
+    from ..lib.llm import auth_error_to_systemexit
+
+    repo_root = Path(args.repo_root).resolve()
+    idx = IndexDir.for_repo(repo_root)
+    index_dir = idx.path
+    languages = _parse_languages(getattr(args, "languages", None))
+    mode = getattr(args, "mode", "agent")
+    allow_dump = bool(getattr(args, "allow_dump", False))
+
+    api_key = _prompt_api_key(args.api_key)
+    # First-run write of plaintext .env; the daemon migrates it on its
+    # next start. Writing into an encrypted store would corrupt the blob.
+    if not idx.is_encrypted_layout():
+        _persist_api_key(index_dir, api_key)
+    _ensure_gitignored(repo_root)
+
+    model = apply_remote_config(index_dir=index_dir, default_model=args.model)
+
+    _log.info("Installing git hooks")
+    _install_hooks(repo_root)
+    _ensure_autostart_installed()
+    # Register before any early-return paths so re-running init on an
+    # already-indexed repo still backfills its registry entry.
+    from ..lib import registry
+    registry.add(idx.repo_hash, str(repo_root))
+
+    if mode == "mcp":
+        _log.info("Writing MCP config")
+        _write_mcp_config(repo_root)
+        _log.info("Updating CLAUDE.md with workflow instructions...")
+        _append_claude_md(repo_root, CLAUDE_MD_SECTION_MCP, CLAUDE_MD_MARKER_MCP)
+    elif mode == "agent":
+        _log.info("Writing Claude subagent config")
+        _write_subagent_config(repo_root)
+        _log.info("Installing subagent single-shot gate (PreToolUse hook)")
+        _write_restrict_hook(repo_root)
+        _register_pretooluse_hook(repo_root)
+        _log.info("Updating CLAUDE.md with workflow instructions...")
+        _append_claude_md(repo_root, CLAUDE_MD_SECTION_AGENT, CLAUDE_MD_MARKER_AGENT)
+    else:
+        raise ValueError(f"Unknown init mode: {mode!r} (expected 'mcp' or 'agent')")
+
+    if idx.is_encrypted_layout() or idx.has_plaintext_index():
+        _log.info(
+            f"Index already exists at {index_dir}, skipping build. Use 'sourceindex update' to refresh.",
+            extra={"event": "init.index_exists", "index_dir": str(index_dir)},
+        )
+        return
+
+    _log.info(
+        f"Initializing index for {repo_root}...",
+        extra={"event": "init.start", "repo_root": str(repo_root), "mode": mode},
+    )
+    _preflight_indexing(repo_root, index_dir, languages, model)
+    client = Client(repo_root, allow_dump_on_spawn=allow_dump)
+    lang_strings = [l.key for l in languages] if languages else None
+    with auth_error_to_systemexit(index_dir=index_dir, api_key=api_key), \
+         _mirror_daemon_progress(idx.repo_hash):
+        result = client.init(
+            api_key=api_key, model=model,
+            languages=lang_strings, workers=args.workers,
+        )
+    _log.info(
+        f"Index written to {index_dir}",
+        extra={"event": "init.done", "index_dir": str(index_dir), **result},
+    )
+
+
+def cmd_install_hooks(args: argparse.Namespace) -> None:
+    repo_root = Path(args.repo_root).resolve()
+    _install_hooks(repo_root)
+
+
+def cmd_update(args: argparse.Namespace) -> None:
+    from ..daemon import Client, IndexDir
+    from ..lib.backend import apply_remote_config
+    from ..lib.llm import auth_error_to_systemexit
+
+    repo_root = Path(args.repo_root).resolve()
+    idx = IndexDir.for_repo(repo_root)
+    index_dir = idx.path
+    languages = _parse_languages(getattr(args, "languages", None))
+    allow_dump = bool(getattr(args, "allow_dump", False))
+
+    api_key = _require_api_key(getattr(args, "api_key", None), daemon_managed=idx.is_encrypted_layout())
+    model = apply_remote_config(index_dir=index_dir, default_model=args.model)
+    client = Client(repo_root, allow_dump_on_spawn=allow_dump)
+    lang_strings = [l.key for l in languages] if languages else None
+    with auth_error_to_systemexit(index_dir=index_dir, api_key=api_key), \
+         _mirror_daemon_progress(idx.repo_hash):
+        if not (idx.is_encrypted_layout() or idx.has_plaintext_index()):
+            _log.info(
+                f"No index found. Building full index for {repo_root}...",
+                extra={"event": "update.cold_build", "repo_root": str(repo_root)},
+            )
+            result = client.init(
+                api_key=api_key, model=model,
+                languages=lang_strings, workers=args.workers,
+            )
+            _log.info(
+                f"Index written to {index_dir}",
+                extra={"event": "init.done", "index_dir": str(index_dir), **result},
+            )
+        else:
+            client.update(
+                api_key=api_key, model=model,
+                languages=lang_strings, workers=args.workers,
+            )
+
+
+def cmd_serve(args: argparse.Namespace) -> None:
+    from ..build import DEFAULT_MODEL
+    from ..daemon import IndexDir
+    from ..lib.backend import apply_remote_config
+    from ..server import run_server
+
+    repo_root = Path(args.repo_root).resolve()
+    index_dir = IndexDir.for_repo(repo_root, args.index_dir).path
+
+    model = apply_remote_config(index_dir=index_dir, default_model=DEFAULT_MODEL)
+    run_server(repo_root, index_dir, index_search_model=model)
+
+
+ROADMAP_FILENAME = "sourceindex-output.txt"
+
+
+def cmd_search(args: argparse.Namespace) -> None:
+    """Run the search pipeline, write the roadmap into the index dir, and
+    print a one-line completion signal naming that path.
+
+    Routing the roadmap through a file (instead of stdout) keeps the calling
+    subagent a pure tool invoker — it never sees the roadmap text, so it
+    cannot summarize, paraphrase, or conjecture about it. The main agent
+    reads the file directly.
+
+    By default the file lives in the index dir (``<repo>/.sourceindex/``,
+    already gitignored) so it doesn't leave a stray artifact in the repo
+    root. ``--output`` overrides the destination — a caller that points one
+    shared index dir at concurrent searches (e.g. the sourceindex-bare eval
+    variant) uses it to write a per-run path and avoid clobbering.
+    """
+    from ..daemon import Client, IndexDir
+    from ..lib.backend import apply_remote_config
+    from ..lib.llm import auth_error_to_systemexit
+    from ..search import search_index
+
+    repo_root = Path(args.repo_root).resolve()
+    idx = IndexDir.for_repo(repo_root, args.index_dir)
+    index_dir = idx.path
+
+    api_key = _require_api_key(getattr(args, "api_key", None), daemon_managed=idx.is_encrypted_layout())
+    model = apply_remote_config(index_dir=index_dir, default_model=args.index_search_model)
+    _preflight_search(index_dir, args.query, model)
+    with auth_error_to_systemexit(index_dir=index_dir, api_key=api_key):
+        if idx.is_encrypted_layout():
+            client = Client(repo_root)
+            result = client.search(args.query, model=model, api_key=api_key)["roadmap"]
+        else:
+            result = search_index(
+                query=args.query,
+                repo_root=repo_root,
+                index_dir=index_dir,
+                index_search_model=model,
+                mode=getattr(args, "mode", "implement"),
+            )
+
+    if result.startswith("ERROR:"):
+        print(result)
+        # Non-zero so callers (e.g. swe_bench_eval's prefix.py with check=True) see the
+        # failure — a 0 exit here used to surface later as a FileNotFoundError on --output.
+        raise SystemExit(2)
+
+    output_arg = getattr(args, "output", None)
+    output_path = Path(output_arg) if output_arg else index_dir / ROADMAP_FILENAME
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(result)
+    print(f"Roadmap written to {output_path}")
+
+
+def _run_preflight(estimator) -> None:
+    # SystemExit propagates (budget overrun); other failures are swallowed
+    # so a backend hiccup never blocks the action.
+    try:
+        from ..lib.cost import abort_if_over_budget, fetch_budget
+        abort_if_over_budget(estimator(), fetch_budget())
+    except SystemExit:
+        raise
+    except Exception as e:  # noqa: BLE001
+        _log.debug(
+            "pre-flight estimate failed",
+            extra={"event": "preflight.failed", "error": str(e)},
+        )
+
+
+def _preflight_indexing(repo_root: Path, index_dir: Path, languages, model: str) -> None:
+    # Estimate only files that will actually hit the LLM — skip empties
+    # and files already covered by _summary_cache.json (cache hits don't
+    # incur an LLM call).
+    def estimate() -> float:
+        import json
+        from ..build.walker import collect_source_files, hash_file_content
+        from ..lib.cost import estimate_indexing_cost
+        from ..lib.languages import detect_languages, get_languages
+
+        cache_hashes: set[str] = set()
+        cache_path = index_dir / "_summary_cache.json"
+        if cache_path.exists():
+            try:
+                cache_hashes = set(json.loads(cache_path.read_text()).keys())
+            except (OSError, ValueError):
+                pass  # unreadable cache → estimate as if nothing is cached
+
+        resolved = languages or detect_languages(repo_root) or get_languages()
+        sizes: list[int] = []
+        for rel in collect_source_files(repo_root, resolved):
+            try:
+                content = (repo_root / rel).read_text(errors="replace")
+            except OSError:
+                continue
+            if not content.strip():
+                continue  # indexer skips empty files
+            if hash_file_content(content) in cache_hashes:
+                continue  # cache hit — no LLM call
+            sizes.append(len(content.encode()))
+        return estimate_indexing_cost(sizes, model)[2]
+    _run_preflight(estimate)
+
+
+def _preflight_search(index_dir: Path, query: str, model: str) -> None:
+    def estimate() -> float:
+        from ..lib.cost import estimate_search_cost
+        index_md = index_dir / "index.md"
+        details = index_dir / "details"
+        index_md_size = index_md.stat().st_size if index_md.exists() else 0
+        tier2_total = 0
+        if details.exists():
+            for p in details.rglob("*.md"):
+                try:
+                    tier2_total += p.stat().st_size
+                except OSError:
+                    continue
+        return estimate_search_cost(index_md_size, tier2_total, len(query), model)[2]
+    _run_preflight(estimate)
+
+
+def cmd_dump(args: argparse.Namespace) -> None:
+    from ..daemon import AdminSocketUnavailable, Client, IndexDir
+
+    repo_root = Path(args.repo_root).resolve()
+    idx = IndexDir.for_repo(repo_root)
+    out_dir = Path(args.out).resolve()
+
+    if not idx.is_encrypted_layout() and idx.has_plaintext_index():
+        # Plaintext layout: just copy. Gives eval a single dump entry
+        # point regardless of whether init was encrypted.
+        from ..daemon import PlaintextStore
+        store = PlaintextStore(idx.path)
+        files, total = store.plaintext_dump(out_dir)
+        _log.info(
+            f"Copied plaintext store to {out_dir} ({files} files, {total} bytes)",
+            extra={"event": "dump.plaintext_copy", "out_dir": str(out_dir),
+                   "files": files, "bytes": total},
+        )
+        return
+
+    client = Client(repo_root, admin=True)
+    try:
+        result = client.dump_all(out_dir)
+    except AdminSocketUnavailable as e:
+        raise SystemExit(
+            f"[sourceindex] {e}\n"
+            "Hint: pass --allow-dump to `sourceindex init` or "
+            "`sourceindex daemon` to enable the admin socket."
+        )
+    _log.info(
+        f"Dumped encrypted store to {out_dir} "
+        f"({result.get('files_written', '?')} files, {result.get('bytes', '?')} bytes)",
+        extra={"event": "dump.done", "out_dir": str(out_dir), **result},
+    )
+
+
+def _deinit_one(repo_root: Path, repo_hash: str) -> dict:
+    """Drop the encryption key + runtime files for a single repo. Caller is
+    responsible for the safety check (deletion of a live <repo>/.sourceindex/
+    must be opt-in). Returns telemetry suitable for a log `extra` payload."""
+    import shutil
+    from ..daemon import IndexDir, lifecycle
+    from ..daemon.keyring_store import delete_key
+    from ..lib import registry
+
+    daemon_stopped = lifecycle.stop_daemon(repo_root)
+    delete_key(repo_hash)
+    lifecycle.cleanup_stale_files(repo_hash)
+    index_removed = False
+    idx_path = IndexDir.for_repo(repo_root).path
+    if idx_path.exists():
+        shutil.rmtree(idx_path)
+        index_removed = True
+    registry.remove(repo_hash)
+    return {
+        "daemon_stopped": daemon_stopped,
+        "index_removed": index_removed,
+    }
+
+
+def cmd_deinit(args: argparse.Namespace) -> None:
+    from ..daemon import IndexDir
+    from ..lib import registry
+
+    if getattr(args, "all", False):
+        # Login-time sweep: forget every registered repo whose path has gone
+        # missing. Live repos are skipped — they're not orphans.
+        swept = []
+        kept = 0
+        for repo_hash, repo_path in registry.read():
+            if Path(repo_path).exists():
+                kept += 1
+                continue
+            telemetry = _deinit_one(Path(repo_path), repo_hash)
+            swept.append((repo_hash, repo_path, telemetry))
+        _log.info(
+            "Sweep complete: %d orphan repo(s) cleaned, %d live repo(s) left alone",
+            len(swept), kept,
+            extra={
+                "event": "cli.deinit_all",
+                "swept": [{"repo_hash": h, "repo_path": p, **t} for h, p, t in swept],
+                "kept": kept,
+            },
+        )
+        return
+
+    repo_root = Path(args.repo_root).resolve()
+    idx = IndexDir.for_repo(repo_root)
+
+    # Safety: a live store is real data. Require --force so the user
+    # opts into deleting it rather than getting it wiped by surprise.
+    if not args.force and idx.path.exists():
+        _log.error(
+            "Refusing to deinit: %s still exists. Pass --force to remove "
+            "the encrypted index, drop the key, and stop the daemon.",
+            idx.path,
+        )
+        sys.exit(2)
+
+    telemetry = _deinit_one(repo_root, idx.repo_hash)
+    _log.info(
+        "Deinit complete for %s (repo_hash=%s, daemon_stopped=%s, "
+        "index_removed=%s)",
+        repo_root, idx.repo_hash, telemetry["daemon_stopped"],
+        telemetry["index_removed"],
+        extra={"event": "cli.deinit", "repo_hash": idx.repo_hash, **telemetry},
+    )
+
+
+_SYSTEMD_UNIT_NAME = "sourceindex-sweep.service"
+_SYSTEMD_UNIT_TEMPLATE = """\
+[Unit]
+Description=SourceIndex login-time sweep — remove orphan state for deleted repos
+
+[Service]
+Type=oneshot
+ExecStart={binary} deinit --all
+
+[Install]
+WantedBy=default.target
+"""
+
+
+def _ensure_autostart_installed() -> None:
+    """Install and enable the systemd --user unit that runs deinit --all at
+    each login. Idempotent — re-runs of `sourceindex init` are no-ops once
+    the unit is present and current. Non-fatal: a missing systemctl just
+    logs a warning so the rest of init still completes."""
+    import shutil as _shutil
+    import subprocess
+
+    if sys.platform != "linux":
+        return
+
+    binary = _shutil.which("sourceindex") or sys.argv[0]
+    desired = _SYSTEMD_UNIT_TEMPLATE.format(binary=binary)
+    unit_dir = Path.home() / ".config" / "systemd" / "user"
+    unit_path = unit_dir / _SYSTEMD_UNIT_NAME
+    if unit_path.is_file() and unit_path.read_text() == desired:
+        return
+
+    unit_dir.mkdir(parents=True, exist_ok=True)
+    unit_path.write_text(desired)
+    try:
+        subprocess.run(["systemctl", "--user", "daemon-reload"], check=True, capture_output=True)
+        subprocess.run(["systemctl", "--user", "enable", _SYSTEMD_UNIT_NAME], check=True, capture_output=True)
+    except FileNotFoundError:
+        _log.warning(
+            "systemctl not found; wrote %s but couldn't enable it. "
+            "Reboot-then-delete orphans won't be cleaned automatically.",
+            unit_path,
+        )
+        return
+    except subprocess.CalledProcessError as e:
+        _log.warning(
+            "systemctl returned %s while enabling the login-time sweep: %s. "
+            "Unit file is at %s — enable it manually if you want auto-cleanup.",
+            e.returncode, e.stderr.decode(errors="replace").strip(), unit_path,
+        )
+        return
+    _log.info(
+        "Installed login-time orphan sweep at %s",
+        unit_path,
+        extra={"event": "init.autostart_installed", "unit_path": str(unit_path)},
+    )
+
+
+def cmd_daemon(args: argparse.Namespace) -> None:
+    from ..daemon import lifecycle, run_daemon
+
+    repo_root = Path(args.repo_root).resolve()
+    if args.stop:
+        stopped = lifecycle.stop_daemon(repo_root)
+        if stopped:
+            _log.info("Daemon stopped", extra={"event": "daemon.stopped"})
+        else:
+            _log.info("No daemon was running", extra={"event": "daemon.not_running"})
+        return
+    run_daemon(repo_root, allow_dump=bool(args.allow_dump))
+
+
+def cmd_usage(args: argparse.Namespace) -> None:
+    from ..lib.cost import fetch_budget
+
+    budget = fetch_budget()
+    if budget is None:
+        print(
+            "[sourceindex] Could not reach the hosted backend. "
+            "Check SOURCEINDEX_BACKEND_URL / SOURCEINDEX_API_KEY, "
+            "or set SOURCEINDEX_BACKEND_URL=\"\" to opt out of the backend."
+        )
+        return
+    if not budget.get("minted"):
+        print(
+            "[sourceindex] No usage this month yet — your virtual key "
+            "will be minted on your first indexing call."
+        )
+        return
+
+    month = budget.get("month", "?")
+    used = float(budget.get("used_usd") or 0)
+    limit = budget.get("limit_usd")
+    remaining = budget.get("remaining_usd")
+    lines = [f"[sourceindex] Month {month}", f"[sourceindex]   Used:      ${used:.4f}"]
+    if limit is not None:
+        lines.append(f"[sourceindex]   Cap:       ${limit:.2f}")
+    if remaining is not None:
+        lines.append(f"[sourceindex]   Remaining: ${remaining:.4f}")
+    lines.append("[sourceindex]   Resets:    first of next month (UTC)")
+    print("\n".join(lines))
+
+
+def cmd_report_savings(args: argparse.Namespace) -> None:
+    """Stop-hook entry point — read payload JSON from stdin, persist savings ledger."""
+    from ..claudecode import savings
+
+    savings.main()
+
+
+def cmd_statusline(args: argparse.Namespace) -> None:
+    """statusLine entry point — read payload JSON from stdin, render savings line."""
+    from ..claudecode import statusline
+
+    statusline.main()
+
+
+def cmd_savings_summary(args: argparse.Namespace) -> None:
+    """Stop-hook entry point — print a per-turn multi-line savings breakdown
+    (session/week/month). Pairs with ``report-savings`` as a second Stop
+    hook: that one updates the ledger silently, this one renders detail."""
+    from ..claudecode import savings_summary
+
+    savings_summary.main()
+
+
+def _local_timepart(ts: str) -> str:
+    """Convert a UTC ``ts`` string (``...Z``) to a local ``HH:MM:SS`` time."""
+    if not ts:
+        return ts
+    try:
+        dt = datetime.strptime(ts, "%Y-%m-%dT%H:%M:%S.%fZ").replace(tzinfo=timezone.utc)
+        return dt.astimezone().strftime("%H:%M:%S")
+    except (ValueError, TypeError):
+        return ts[11:19] if len(ts) >= 19 else ts
+
+
+def _format_log_record(rec: dict) -> str | None:
+    """Render one JSONL log record as a compact summary line. Return ``None``
+    to suppress the record (covered by a sibling event, or pure debug noise)."""
+    ts = rec.get("ts") or ""
+    timepart = _local_timepart(ts)
+    event = rec.get("event") or ""
+    msg = rec.get("message") or ""
+    level = rec.get("level") or ""
+
+    if event == "cli.invocation":
+        return f"{timepart}  cli      sourceindex {rec.get('command', '?')}"
+    if event == "update.start":
+        return f"{timepart}  update   start: {rec.get('changed_count', '?')} files"
+    if event == "update.cache_hit":
+        return f"{timepart}  update   cached: {rec.get('path', '?')}"
+    if event == "update.done":
+        return (
+            f"{timepart}  update   done: {rec.get('files_indexed', 0)} files "
+            f"· ${rec.get('cost_usd', 0):.4f} · {rec.get('elapsed_s', 0):.1f}s"
+        )
+    if event == "search.start":
+        q = (rec.get("query") or "").strip().replace("\n", " ")
+        if len(q) > 60:
+            q = q[:57] + "..."
+        return f'{timepart}  search   start: "{q}"'
+    if event == "search.pass_1a":
+        return f"{timepart}  search   pass 1a: {rec.get('files_selected', '?')} files"
+    if event == "search.pass_1b":
+        return f"{timepart}  search   pass 1b: {rec.get('functions_selected', '?')} functions"
+    if event == "search.done":
+        return (
+            f"{timepart}  search   done: {rec.get('roadmap_bytes', 0)} bytes "
+            f"· {rec.get('latency_ms', 0) / 1000:.1f}s"
+        )
+    if event == "llm.call":
+        model = rec.get("model") or "?"
+        short = model.rsplit("/", 1)[-1]
+        cost = rec.get("cost_usd") or 0.0
+        latency = (rec.get("latency_ms") or 0) / 1000.0
+        return (
+            f"{timepart}  llm      {short} · "
+            f"in={rec.get('input_tokens', 0)} out={rec.get('output_tokens', 0)} · "
+            f"${cost:.4f} · {latency:.1f}s"
+        )
+    if event == "llm.cost_unknown":
+        tried = rec.get("tried")
+        tail = f" (tried: {', '.join(tried)})" if tried else ""
+        return f"{timepart}  warn     cost lookup failed for {rec.get('model', '?')}{tail}"
+    if event == "lazy_refresh.skipped":
+        return (
+            f"{timepart}  warn     refresh skipped: {rec.get('reason', '?')} "
+            f"({rec.get('changed_count', 0)} files changed)"
+        )
+    if event in (
+        "update.concurrent_indexing", "batch.dispatch", "batch.results",
+        "search.pass_1a.start", "search.pass_1b.start",
+    ):
+        return None
+    if level in ("INFO", "WARNING", "ERROR"):
+        return f"{timepart}  {level.lower():8s} {msg or event}"
+    return None
+
+
+def cmd_log(args: argparse.Namespace) -> None:
+    """Pretty-print the sourceindex JSONL log."""
+    import json
+    from ..daemon import IndexDir
+
+    repo_root = Path(args.repo_root).resolve()
+    log_path = (
+        Path(args.log_path).resolve()
+        if args.log_path
+        else IndexDir.for_repo(repo_root).path / "sourceindex.log"
+    )
+    if not log_path.is_file():
+        raise SystemExit(f"[sourceindex] No log file at {log_path}")
+    log_lines = log_path.read_text().splitlines()
+
+    filt = (args.filter or "").lower()
+    rendered: list[str] = []
+    for line in log_lines:
+        if not line.strip():
+            continue
+        try:
+            rec = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if filt and filt not in (rec.get("event") or "").lower():
+            continue
+        out = _format_log_record(rec)
+        if out:
+            rendered.append(out)
+
+    # Slice after formatting so --tail N counts visible lines, not raw
+    # JSONL records (which can collapse 10 → 2 once suppressed events,
+    # batch chatter, and unrecognized DEBUG entries are dropped).
+    if args.tail and args.tail > 0:
+        rendered = rendered[-args.tail :]
+    for line in rendered:
+        print(line)