SourceIndex 0.1.0__py3-none-any.whl

sourceindex/claudecode/savings_summary.py

@@ -0,0 +1,88 @@
+"""Stop-hook entry point that prints a per-turn sourceindex savings summary.
+
+Wired as a second Stop hook alongside ``sourceindex report-savings``: the
+first hook walks the transcript and updates the on-disk ledger, this one
+reads the updated ledger and renders a multi-line breakdown to stdout —
+which Claude Code surfaces under the assistant's response area.
+
+Output (only when there's something to report):
+
+    SourceIndex savings
+      this session: $0.18
+      last 7 days:  $4.20 across 3 sessions
+      this month:   $19.50 across 12 sessions
+
+Stays silent if no ledger exists or the current session's saved is below
+the rendering threshold — same gate the statusLine companion applies.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import date, timedelta
+from typing import Any
+
+from .savings import load_state
+
+# Suppress sub-cent noise.
+RENDER_THRESHOLD = 0.005
+
+
+def run(payload: dict[str, Any], *, stdout=sys.stdout, today: date | None = None) -> int:
+    state = load_state()
+    if not state:
+        return 0
+
+    session_id = payload.get("session_id")
+    today = today or date.today()
+    week_start = today - timedelta(days=7)
+    month_start = today.replace(day=1)
+
+    session_saved = 0.0
+    week_saved = 0.0
+    week_count = 0
+    month_saved = 0.0
+    month_count = 0
+
+    for sid, entry in state.items():
+        if not isinstance(entry, dict):
+            continue
+        saved = float(entry.get("saved") or 0)
+        entry_date_str = entry.get("date") or ""
+        try:
+            entry_date = date.fromisoformat(entry_date_str)
+        except ValueError:
+            continue
+        if entry_date >= week_start:
+            week_saved += saved
+            week_count += 1
+        if entry_date >= month_start:
+            month_saved += saved
+            month_count += 1
+        if sid == session_id:
+            session_saved = saved
+
+    if session_saved < RENDER_THRESHOLD and week_saved < RENDER_THRESHOLD:
+        return 0
+
+    lines = [
+        "SourceIndex savings",
+        f"  this session: ${session_saved:0.2f}",
+        f"  last 7 days:  ${week_saved:0.2f} across {week_count} sessions",
+        f"  this month:   ${month_saved:0.2f} across {month_count} sessions",
+    ]
+    print("\n".join(lines), file=stdout)
+    return 0
+
+
+def main() -> int:
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+    except (ValueError, OSError):
+        payload = {}
+    return run(payload)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sourceindex/claudecode/statusline.py

@@ -0,0 +1,116 @@
+"""Render the sourceindex savings line into the Claude Code status line.
+
+Wired into Claude Code as a `statusLine` command. Reads the session ledger
+that the Stop hook (`sourceindex.report_savings`) writes after each turn
+and prints a one-liner like
+
+    SourceIndex saved $0.18 this session · $4.20 this week
+
+to stdout. Claude Code renders that flush-left on the bottom row above
+the mode indicator — per code.claude.com/docs/en/statusline, statusLine
+output is left-aligned and only `color` / `hyperlink` ANSI is honored,
+so cursor-positioning right-align tricks don't survive the renderer.
+
+Stays silent unless the current session itself has activity, AND the
+Stop hook fired within the last `FRESH_WINDOW_S` seconds — so the line
+appears briefly after each turn and fades out instead of staying lit
+between turns or while Claude Code is idle.
+
+The Stop hook does the heavy work — walking the transcript and computing
+cost — so this command can stay cheap enough for the per-tick refresh.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime
+from typing import Any
+
+from .savings import load_state
+
+# Show the savings line for this many seconds after the Stop hook fires.
+# Long enough to read on a fast turn, short enough that it doesn't linger
+# while Claude Code is idle waiting for the next prompt.
+FRESH_WINDOW_S = 60
+
+# Dim so the line doesn't compete with the bright auto-mode indicator
+# Claude Code renders directly below the status row. Right-alignment
+# isn't possible — Claude Code reserves the right side of the status
+# row for system notifications (xhigh, MCP errors, context-low) and
+# strips leading whitespace from statusLine output.
+DIM = "\x1b[2m"
+ITALIC = "\x1b[3m"
+NOT_ITALIC = "\x1b[23m"
+RESET = "\x1b[0m"
+
+
+def _stylize(msg: str) -> str:
+    branded = msg.replace("SourceIndex", f"{ITALIC}SourceIndex{NOT_ITALIC}", 1)
+    return f"{DIM}{branded}{RESET}"
+
+
+def format_compact(saved_session: float, weekly: float) -> str:
+    # Gate on session activity (not weekly) so the row stays blank on idle
+    # turns. Showing only the weekly total — the most common case — left
+    # the line permanently lit and competing with the auto-mode indicator.
+    if saved_session < 0.005:
+        return ""
+    parts = [f"${saved_session:0.2f} this session"]
+    if weekly >= 0.005:
+        parts.append(f"${weekly:0.2f} this week")
+    return "SourceIndex saved " + " · ".join(parts)
+
+
+def _is_fresh(entry: dict[str, Any], now: datetime) -> bool:
+    raw = entry.get("updated_at")
+    if not isinstance(raw, str):
+        return False
+    try:
+        ts = datetime.fromisoformat(raw)
+    except ValueError:
+        return False
+    return (now - ts).total_seconds() <= FRESH_WINDOW_S
+
+
+def run(payload: dict[str, Any], *, stdout=sys.stdout, now: datetime | None = None) -> int:
+    state = load_state()
+    if not state:
+        return 0
+
+    actual_now = now or datetime.now()
+    session_id = payload.get("session_id") or ""
+    entry = state.get(session_id) if isinstance(state.get(session_id), dict) else None
+    if not entry or not _is_fresh(entry, actual_now):
+        return 0
+
+    saved_session = float(entry.get("saved", 0.0))
+    weekly = sum(
+        float(e.get("saved", 0.0))
+        for e in state.values()
+        if isinstance(e, dict)
+    )
+
+    msg = format_compact(saved_session, weekly)
+    if not msg:
+        return 0
+
+    stdout.write(_stylize(msg))
+    return 0
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        payload = {}
+    if not isinstance(payload, dict):
+        payload = {}
+    try:
+        return run(payload)
+    except Exception:
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sourceindex/cli/__init__.py

@@ -0,0 +1,304 @@
+#!/usr/bin/env python3
+"""CLI entry point for sourceindex.
+
+Usage:
+    sourceindex init [--repo-root PATH] [--api-key KEY]
+    sourceindex update [--repo-root PATH]
+    sourceindex serve [--repo-root PATH]
+    sourceindex report-savings   # Stop-hook entry point; reads payload JSON from stdin
+    sourceindex statusline       # statusLine entry point; reads payload JSON from stdin
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from ..lib.log import configure, get_logger
+from .api_key import _load_persisted_env
+from .commands import (
+    cmd_daemon,
+    cmd_deinit,
+    cmd_dump,
+    cmd_init,
+    cmd_install_hooks,
+    cmd_log,
+    cmd_report_savings,
+    cmd_savings_summary,
+    cmd_search,
+    cmd_serve,
+    cmd_statusline,
+    cmd_update,
+    cmd_usage,
+)
+
+
+_LOG_LEVELS = ("DEBUG", "INFO", "WARNING", "ERROR")
+
+
+def _add_log_flags(parser: argparse.ArgumentParser) -> None:
+    """Attach the cross-cutting logging flags. Used as a parent parser so
+    every repo-touching subcommand carries them. ``statusline`` and
+    ``report-savings`` skip these (their stdout is reserved for product
+    output and they don't write to the on-disk log)."""
+    g = parser.add_argument_group("logging")
+    g.add_argument(
+        "--log-level",
+        choices=_LOG_LEVELS,
+        default=None,
+        help="Stderr log level. Default: INFO (or $SOURCEINDEX_LOG_LEVEL).",
+    )
+    g.add_argument("-v", "--verbose", action="store_true", help="Shortcut for --log-level DEBUG.")
+    g.add_argument("-q", "--quiet", action="store_true", help="Shortcut for --log-level WARNING.")
+    g.add_argument(
+        "--log-file",
+        default=None,
+        help="Path to JSONL log file. Default: <repo>/.sourceindex/sourceindex.log "
+        "(or $SOURCEINDEX_LOG_FILE).",
+    )
+    g.add_argument(
+        "--no-log-file",
+        action="store_true",
+        help="Disable the JSONL file log (equivalent to SOURCEINDEX_NO_LOG_FILE=1).",
+    )
+
+
+def _resolve_log_level(args: argparse.Namespace) -> str | None:
+    if getattr(args, "verbose", False):
+        return "DEBUG"
+    if getattr(args, "quiet", False):
+        return "WARNING"
+    return getattr(args, "log_level", None)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="sourceindex", description="Codebase index for agentic coding")
+    sub = parser.add_subparsers(dest="command")
+
+    lang_help = "Comma-separated languages to index (e.g. python,cpp,rust). Default: auto-detect."
+    model_help = (
+        "LiteLLM model string. Default: openrouter/openai/gpt-5.4-nano "
+        "(best price/latency/quality balance per Opus-judged description "
+        "quality + AST recall + line-range accuracy). Other examples: "
+        "claude-haiku-4-5, openrouter/deepseek/deepseek-v4-flash, "
+        "openrouter/google/gemini-2.5-flash. SOURCEINDEX_*_KEY must hold "
+        "a key matching the provider."
+    )
+
+    # Import from sourceindex/__init__.py rather than ..build — fetching from
+    # the build package would import litellm + the language registry just to
+    # render --help, ballooning `sourceindex statusline` startup.
+    from .. import REALTIME_MAX_WORKERS as _DEFAULT_WORKERS
+    workers_help = (
+        f"Max concurrent LLM requests (default: {_DEFAULT_WORKERS}). Pool is "
+        "auto-capped at min(workers, file_count). Lower if your provider "
+        "key has tight rate limits or your machine has limited file descriptors."
+    )
+
+    log_parent = argparse.ArgumentParser(add_help=False)
+    _add_log_flags(log_parent)
+
+    p_init = sub.add_parser("init", help="Build the full index", parents=[log_parent])
+    p_init.add_argument("--repo-root", default=".", help="Repository root (default: .)")
+    p_init.add_argument(
+        "--api-key",
+        default=None,
+        help="Sourceindex bearer key (or set SOURCEINDEX_API_KEY). Used for both indexing and search. "
+             "By default this routes through the hosted backend baked into lib/backend.py; override the "
+             "backend with SOURCEINDEX_BACKEND_URL=... to talk to a different deployment.",
+    )
+    p_init.add_argument("--languages", default=None, help=lang_help)
+    p_init.add_argument(
+        "--mode",
+        choices=["mcp", "agent"],
+        default="agent",
+        help="Claude integration mode: 'agent' writes a Claude subagent config + CLAUDE.md, 'mcp' writes .mcp.json + CLAUDE.md (default: agent)",
+    )
+    p_init.add_argument("--model", default="openrouter/openai/gpt-5.4-nano", help=model_help)
+    p_init.add_argument("--workers", type=int, default=_DEFAULT_WORKERS, help=workers_help)
+    p_init.add_argument(
+        "--allow-dump",
+        action="store_true",
+        help="Start the daemon with its admin socket bound, enabling "
+             "`sourceindex dump`. Production never sets this; eval scripts "
+             "pass it so they can materialize a plaintext copy of the index "
+             "per task.",
+    )
+
+    p_update = sub.add_parser("update", help="Update index for changed files", parents=[log_parent])
+    p_update.add_argument("--repo-root", default=".", help="Repository root (default: .)")
+    p_update.add_argument("--languages", default=None, help=lang_help)
+    p_update.add_argument("--model", default="openrouter/openai/gpt-5.4-nano", help=model_help)
+    p_update.add_argument("--workers", type=int, default=_DEFAULT_WORKERS, help=workers_help)
+    p_update.add_argument(
+        "--allow-dump",
+        action="store_true",
+        help="See `sourceindex init --allow-dump`.",
+    )
+
+    p_dump = sub.add_parser(
+        "dump",
+        help="Admin-only: decrypt the index into a plaintext mirror at --out.",
+        parents=[log_parent],
+    )
+    p_dump.add_argument("--repo-root", default=".", help="Repository root (default: .)")
+    p_dump.add_argument("--out", required=True, help="Output directory to write the plaintext mirror to.")
+
+    p_daemon = sub.add_parser(
+        "daemon",
+        help="Run or stop the per-repo daemon (auto-spawned by clients; rarely invoked directly).",
+        parents=[log_parent],
+    )
+    p_daemon.add_argument("--repo-root", default=".", help="Repository root (default: .)")
+    p_daemon.add_argument(
+        "--allow-dump", action="store_true",
+        help="Bind the admin socket so `sourceindex dump` and other admin RPCs work.",
+    )
+    p_daemon.add_argument(
+        "--stop", action="store_true",
+        help="Send SIGTERM to the running daemon and exit.",
+    )
+
+    p_deinit = sub.add_parser(
+        "deinit",
+        help="Tear down per-repo state: stop the daemon, delete the encryption key, "
+             "remove the runtime socket / pidfile. Use after `rm -rf <repo>` to clean "
+             "up orphan keyring entries.",
+        parents=[log_parent],
+    )
+    p_deinit.add_argument(
+        "--repo-root",
+        default=".",
+        help="Repository root (default: .). Works even if the path no longer exists — "
+             "the canonical form is hashed to look up the keyring entry.",
+    )
+    p_deinit.add_argument(
+        "--force",
+        action="store_true",
+        help="Proceed even if <repo>/.sourceindex/ still exists. The encrypted "
+             "store is removed along with the key. Without this flag, deinit "
+             "refuses on a live index so you don't lose data by surprise.",
+    )
+    p_deinit.add_argument(
+        "--all",
+        action="store_true",
+        help="Sweep mode: walk the registry at ~/.config/sourceindex/repos.tsv "
+             "and deinit every entry whose repo_root no longer exists. Live "
+             "repos are skipped. Triggered automatically at login by the "
+             "systemd unit that `sourceindex init` installs.",
+    )
+
+    p_install_hooks = sub.add_parser(
+        "install-hooks",
+        help="Refresh git hooks (post-commit/post-checkout/post-merge) in an existing repo. Use after a sourceindex upgrade adds a new hook.",
+        parents=[log_parent],
+    )
+    p_install_hooks.add_argument("--repo-root", default=".", help="Repository root (default: .)")
+
+    p_serve = sub.add_parser("serve", help="Start MCP server", parents=[log_parent])
+    p_serve.add_argument("--repo-root", default=".", help="Repository root (default: .)")
+    p_serve.add_argument("--index-dir", default=None, help="Index directory (default: REPO_ROOT/.sourceindex)")
+
+    p_usage = sub.add_parser(
+        "usage",
+        help="Show this month's spend and remaining budget from the hosted backend.",
+        parents=[log_parent],
+    )
+    p_usage.add_argument("--repo-root", default=".", help="Repository root (default: .)")
+
+    p_search = sub.add_parser("search", help="Run two-pass search and emit an enriched roadmap", parents=[log_parent])
+    p_search.add_argument("--repo-root", default=".", help="Repository root (default: .)")
+    p_search.add_argument("--index-dir", default=None, help="Index directory (default: REPO_ROOT/.sourceindex)")
+    p_search.add_argument("--query", required=True, help="Task description / search query")
+    p_search.add_argument("--index-search-model", default="openrouter/anthropic/claude-haiku-4-5", help=f"Model for search passes 1a/1b. {model_help}")
+    p_search.add_argument("--mode", choices=["implement", "qa"], default="implement",
+                          help="Prompt mode: 'implement' (feature work, default) or 'qa' (read-only question answering).")
+    p_search.add_argument("--output", default=None, help="Write the roadmap to this path instead of INDEX_DIR/sourceindex-output.txt. Lets a caller isolate per-run output — the sourceindex-bare eval variant points this at its own scratch dir so parallel same-task runs don't clobber one shared cache file.")
+
+    sub.add_parser(
+        "report-savings",
+        help="Claude Code Stop-hook entry point: reads payload JSON from stdin and persists the per-session savings ledger.",
+    )
+
+    sub.add_parser(
+        "statusline",
+        help="Claude Code statusLine entry point: reads payload JSON from stdin and prints the savings line for the bottom status row.",
+    )
+
+    sub.add_parser(
+        "savings-summary",
+        help="Stop-hook entry point: prints a multi-line per-turn savings breakdown (session/week/month). Pair with `report-savings` as a second Stop hook.",
+    )
+
+    # Developer-only: pretty-print the JSONL log. Hidden from --help (help=...
+    # is suppressed) so it doesn't appear in the user-facing surface; still
+    # invokable as `sourceindex log` for debugging.
+    p_log = sub.add_parser("log", parents=[log_parent])
+    p_log.add_argument("--repo-root", default=".")
+    p_log.add_argument("--log-path", default=None,
+                       help="Path to JSONL log (default: <repo>/.sourceindex/sourceindex.log)")
+    p_log.add_argument("--tail", type=int, default=0,
+                       help="Show only the last N records.")
+    p_log.add_argument("--filter", default=None,
+                       help="Substring to match against the event name (e.g. 'llm', 'search').")
+
+    args = parser.parse_args()
+
+    repo_root_arg = getattr(args, "repo_root", None)
+    if repo_root_arg is not None:
+        _load_persisted_env(Path(repo_root_arg).resolve())
+
+    # Configure logging after _load_persisted_env so SOURCEINDEX_LOG_* picked
+    # up from .sourceindex/.env take effect.
+    configure(
+        level=_resolve_log_level(args),
+        repo_root=Path(repo_root_arg).resolve() if repo_root_arg is not None else None,
+        log_file=getattr(args, "log_file", None),
+        enable_file=not getattr(args, "no_log_file", False),
+    )
+
+    # `log` is intentionally excluded — it's a read-only viewer over the
+    # log file, and recording each invocation pollutes the file it's
+    # about to print.
+    if args.command in ("init", "update", "serve", "search", "install-hooks", "dump", "daemon", "deinit"):
+        get_logger(__name__).debug(
+            "CLI invocation",
+            extra={
+                "event": "cli.invocation",
+                "command": args.command,
+                "repo_root": str(Path(repo_root_arg).resolve()) if repo_root_arg else None,
+            },
+        )
+
+    if args.command == "init":
+        cmd_init(args)
+    elif args.command == "update":
+        cmd_update(args)
+    elif args.command == "install-hooks":
+        cmd_install_hooks(args)
+    elif args.command == "serve":
+        cmd_serve(args)
+    elif args.command == "search":
+        cmd_search(args)
+    elif args.command == "report-savings":
+        cmd_report_savings(args)
+    elif args.command == "statusline":
+        cmd_statusline(args)
+    elif args.command == "savings-summary":
+        cmd_savings_summary(args)
+    elif args.command == "log":
+        cmd_log(args)
+    elif args.command == "usage":
+        cmd_usage(args)
+    elif args.command == "dump":
+        cmd_dump(args)
+    elif args.command == "daemon":
+        cmd_daemon(args)
+    elif args.command == "deinit":
+        cmd_deinit(args)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

sourceindex/cli/__main__.py

@@ -0,0 +1,10 @@
+"""Allow ``python -m sourceindex.cli``.
+
+The pyproject script entry point ``sourceindex = "sourceindex.cli:main"``
+covers the installed-binary path, but eval.sh and other tooling invoke the
+package directly via ``-m`` — that needs this module.
+"""
+
+from . import main
+
+main()

sourceindex/cli/api_key.py

@@ -0,0 +1,171 @@
+"""API key resolution + persistence for the CLI commands.
+
+Three concerns share this module:
+
+- Look up the API key (CLI arg → env var → persisted file).
+- Prompt the user for one on a TTY when ``init`` runs without any source.
+- Persist the key into ``<repo>/.sourceindex/.env`` so the post-commit hook,
+  search subagent, and MCP server pick it up without an env var.
+"""
+
+import getpass
+import os
+import re
+import sys
+from pathlib import Path
+
+from ..lib.log import get_logger
+
+_log = get_logger(__name__)
+
+
+PERSISTED_KEY_FILENAME = ".env"
+
+# Loose shape check: alphanumerics + `_` / `-`, at least 20 chars, no
+# whitespace or other punctuation. Designed to reject obvious paste
+# mistakes (prompt strings, error messages, paths, URLs) without
+# locking in a specific provider's key format. Real cases we've seen
+# slip through and poison .sourceindex/.env: the literal getpass prompt
+# string, captured when stdin was non-interactive but isatty() lied.
+_API_KEY_PATTERN = re.compile(r"^[A-Za-z0-9_\-]{20,}$")
+
+
+def _is_plausible_api_key(key: str) -> bool:
+    return bool(key) and bool(_API_KEY_PATTERN.match(key))
+
+
+def _warn_if_provider_key(key: str) -> None:
+    """Warn only when an explicit pin forces a provider key through the hosted
+    backend (auto-opt-out handles the unpinned case in ``backend_base``)."""
+    from ..lib.backend import looks_like_provider_key, backend_base
+    if not looks_like_provider_key(key):
+        return
+    base = backend_base(api_key=key)
+    if not base:
+        return
+    _log.warning(
+        f"SOURCEINDEX_API_KEY looks like a direct-provider key but sourceindex "
+        f"is routing through {base} (pinned via SOURCEINDEX_BACKEND_URL or the "
+        f"admin config), which expects a sourceindex bearer. Unset the pin to "
+        f"auto-route direct, or re-run `sourceindex init` with a sourceindex "
+        f"bearer key.",
+        extra={"event": "api_key.provider_key_with_backend", "backend": base},
+    )
+
+
+def _require_api_key(cli_arg: str | None, *, daemon_managed: bool = False) -> str | None:
+    """Resolve the API key from --api-key/env, asserting it exists.
+
+    ``daemon_managed=True`` tolerates a missing key on encrypted-store
+    repos: the daemon loaded ``SOURCEINDEX_API_KEY`` from its own encrypted
+    .env at startup (see ``daemon/server.py:_load_env_from_store``), so RPC
+    handlers fall back to env when the client passes no key. Necessary for
+    hook-triggered subprocesses (post-commit ``sourceindex update``, the
+    Claude Code subagent's ``sourceindex search``) that spawn fresh and
+    don't inherit the user's shell env after init prompted for the key.
+    """
+    from ..lib.llm import resolve_api_key
+    key = resolve_api_key(cli_arg)
+    if key:
+        _warn_if_provider_key(key)
+        return key
+    if daemon_managed:
+        return None
+    assert key, (
+        "No API key found. Pass --api-key or set SOURCEINDEX_API_KEY "
+        "(a sourceindex bearer key from the hosted backend, or a direct "
+        "provider key if SOURCEINDEX_BACKEND_URL=\"\" disables the backend)."
+    )
+    return None
+
+
+def _prompt_api_key(cli_arg: str | None) -> str:
+    """Like _require_api_key, but prompts on a TTY if no key is available.
+    Used only by `init` — non-interactive callers (post-commit hook, subagent,
+    MCP server) should keep using _require_api_key so they fail loudly."""
+    from ..lib.llm import resolve_api_key
+    key = resolve_api_key(cli_arg)
+    if not key:
+        if not sys.stdin.isatty():
+            raise SystemExit(
+                "No API key found. Pass --api-key or set SOURCEINDEX_API_KEY."
+            )
+        _log.info("Paste your sourceindex API key (input hidden):")
+        key = getpass.getpass("API key: ").strip()
+        if not key:
+            raise SystemExit("[sourceindex] Empty API key — aborting.")
+        if not _is_plausible_api_key(key):
+            raise SystemExit(
+                f"[sourceindex] That doesn't look like an API key ({len(key)} chars, "
+                "expected ≥20 alphanumeric/_-). Aborting before persisting junk."
+            )
+    _warn_if_provider_key(key)
+    return key
+
+
+def _parse_env_file(path: Path) -> dict[str, str]:
+    from ..lib.env import parse_env_text
+    try:
+        return parse_env_text(path.read_text())
+    except OSError:
+        return {}
+
+
+def _persist_env_var(index_dir: Path, key: str, value: str) -> None:
+    """Merge ``key=value`` into ``<index_dir>/.env`` without clobbering other keys.
+
+    Refuses on an encrypted layout — the daemon owns those writes."""
+    from ..daemon import IndexDir
+    idx = IndexDir(path=index_dir, repo_hash="")
+    if idx.is_encrypted_layout():
+        raise RuntimeError(
+            f"{index_dir} is an encrypted store; persist .env values via the "
+            "daemon RPC instead of writing the file directly."
+        )
+    index_dir.mkdir(parents=True, exist_ok=True)
+    env_path = index_dir / PERSISTED_KEY_FILENAME
+    existing = _parse_env_file(env_path)
+    existing[key] = value
+    env_path.write_text("".join(f"{k}={v}\n" for k, v in existing.items()))
+    env_path.chmod(0o600)
+
+
+def _persist_api_key(index_dir: Path, key: str) -> None:
+    if not _is_plausible_api_key(key):
+        raise SystemExit(
+            f"[sourceindex] Refusing to persist key ({len(key)} chars) — does "
+            "not match the expected shape (≥20 alphanumeric/_-, no whitespace)."
+        )
+    _persist_env_var(index_dir, "SOURCEINDEX_API_KEY", key)
+    _log.info(
+        f"Persisted API key to {index_dir / PERSISTED_KEY_FILENAME}",
+        extra={"event": "api_key.persisted", "path": str(index_dir / PERSISTED_KEY_FILENAME)},
+    )
+
+
+def _persist_backend_url(index_dir: Path, url: str) -> None:
+    """Persist a non-default ``SOURCEINDEX_BACKEND_URL`` next to the API key.
+    Only needed when overriding the default backend baked into
+    ``lib/backend.py`` (e.g. pointing at a local ``wrangler dev`` for testing
+    or an alternate operator's deployment)."""
+    if not url.startswith(("http://", "https://")):
+        raise SystemExit(
+            f"[sourceindex] Invalid backend URL ({url!r}) — must start with http(s)://"
+        )
+    _persist_env_var(index_dir, "SOURCEINDEX_BACKEND_URL", url.rstrip("/"))
+    _log.info(
+        f"Persisted backend URL to {index_dir / PERSISTED_KEY_FILENAME}",
+        extra={"event": "api_key.backend_persisted", "path": str(index_dir / PERSISTED_KEY_FILENAME)},
+    )
+
+
+def _load_persisted_env(repo_root: Path) -> None:
+    """Merge plaintext .sourceindex/.env into os.environ (pre-existing vars
+    win, standard dotenv semantics). Encrypted .env is loaded by the
+    daemon itself at startup — client processes can't read it."""
+    from ..daemon import IndexDir
+    env_path = IndexDir.for_repo(repo_root).path / PERSISTED_KEY_FILENAME
+    if env_path.is_file():
+        for k, v in _parse_env_file(env_path).items():
+            if k and k not in os.environ:
+                os.environ[k] = v