codesearch AGENTS.md

AGENTS.md — codesearch

Last updated: 2026-08-14

Current state

• Version: Major.Minor.Patch (semver). Patch auto-bumps +1 on every PR merged to develop (CI via .github/workflows/bump-develop.yml); minor bumps manually at release (scripts/bump-version.sh --type minor, resets patch→0). Per-commit uniqueness comes from build.rs's +<commit_count> suffix. See RELEASING.md.
• Validation: cargo check for iteration, cargo clippy -D warnings for lint, cargo test --lib --bins before a branch is considered done. No --release builds during the fix loop — build only at the very end.
• Deploy: cloud peer runs the per-vendor federation split (one index per vendor sub-folder + custom-kb), image built locally via BuildKit docker buildx --push, all vendors reindexed and federation validated end-to-end (project=cloud/<vendor>).

Implemented Features

Release narratives live in CHANGELOG.md; this list keeps only the load-bearing facts.

• Federation peers — codesearch remote add/rm/list (local repos.json peer config: alias → url, api_key, group, into_group) + @peer group references; FederationClient search/get_chunk fan-out with RRF.
• Opt-in remote mount selection — the remote_mounts allowlist in repos.json is the single source of truth for routing (resolve_remote_project), discoverability (list_projects/scope_required), TUI display, and @peer group fan-out (restricted to mounted projects, never the whole peer). Nothing a peer exposes is auto-mounted. CLI: codesearch remote available|mount|unmount|mounts.
• Remote project mounting (1-to-1 passthrough) — each mounted project is addressable locally as project=<peer>/<alias>; FederationClient::search_project forwards a single-project query straight to the peer. The TUI renders mounts in italic/cyan with a peer URL + live-status panel, and disables doctor/reindex/remove (those act on a local index a mount doesn't have).
• Remote index management (--remote) — --remote <peer> on index list/add/rm plus an index reindex verb, driven through FederationClient (ManagementOutcome: Ok / HttpError{status,reason} / Unreachable). Endpoints: GET /status, POST /repos {path}, DELETE /repos/:alias, POST /repos/:alias/reindex[?force=]. --json on List/Reindex requires --remote. Without --remote every index verb is local and unchanged.
• Cloud indexer-job split — a heavy 4 vCPU/8 GiB build job uploads a snapshot; a light 1 vCPU/2 GiB serve restores it. The DOCS-read-only state is enforced by a per-repo repo_read_only flag in repos.json (set by the job's mark_docs_readonly step): serve's warmup opens those repos read-only and returns early, so no embedding happens on the replica. Only custom-kb stays writable and gets a memory-bounded incremental reindex (fire-and-forget POST /repos/custom-kb/reindex) after each KB git pull moves HEAD. The job also prunes ghost vendors before publishing. See integrations/cloud/README.md.
• Language coverage — 17 tree-sitter grammars (table in README). find_impact has SCIP symbol precision for C# (bundled scip-csharp) and TypeScript (npx scip-typescript, host-resolved). Protobuf is Niveau 1 (text-aware chunking on message/enum/service/rpc) only — no scip-protobuf emitter exists today.
• Scale-to-zero-safe federation: a federated peer is NEVER polled on a timer — ⚠️ design constraint, do not "improve" this. Background polling of local repos is fine; a federated peer must never be contacted on any cadence. The embedded TUI's discovery tick is config-only (REMOTE_ROW_REFRESH_SECS = 5s, zero HTTP): it rebuilds mounted-remote rows from the remote_mounts allowlist so mount/unmount edits and l reloads surface, and contacts nobody. A peer is contacted only by (a) an activity poke — a real federated tool call just hit it, detected via remote_peer_activity in ServeState, refreshing that one peer, never a fan-out — or (b) the explicit i info-overlay keypress. Idle mounts therefore render activity as -, which is the correct steady state, not a fault. Rejected reasoning (was shipped twice, PR #181/#184, and reverted): "polling no faster than the host's idle-suspend term is harmless." It is not — each poll woke the peer's scale-to-zero replica, which then self-warmed for its own full idle window (~1h), giving ~50% duty cycle on a peer nobody queried (measured: wakes 120/121/120 min apart, zero searches). Not keeping a peer awake past its suspend term is strictly weaker than not waking it, and the two windows are unrelated values anyway (local host vs. remote peer).
• Standalone remote TUI auth — codesearch serve tui --url ... resolves the API key from repos.json (remotes.*.url match) or a --api-key override and threads the authenticated client through every TUI action, with distinct errors for "no key configured" vs. "key rejected (401)".
• Keep-warm ping observability + spurious-wake fix (branch fix/federated-silent-poll-diagnosis) — the keep_warm_url self-ping loop logs every ping (debug! on success, warn! on failure) instead of discarding both outcomes, and warns at startup when the target host isn't this server's own bind host — except on a wildcard bind (0.0.0.0 / ::), where our externally-visible host is unknown so the comparison proves nothing; without that carve-out the warning fired on every cold start of the only deployment where keep-warm is correct (Azure binds 0.0.0.0, target is the ingress FQDN), which just trains operators to ignore it. Rule lives in the testable keep_warm_foreign_target helper. Keep-warm also requires a real recorded tool call: the old most_recent_tool_call().unwrap_or(start) fallback meant any wake that wasn't a tool call (/status and /healthz don't call record_tool_call) made the replica self-warm for its whole idle window — reachable only when the wake wasn't real work, so its sole practical effect was rewarding spurious wakes (~11× amplification). Full diagnosis, with Azure Log Analytics ground truth: .docs/DIAGNOSE_FEDERATED_KEEP_WARM.md.
• CLI aliases — ls for list (index/groups/remote), rm for remove. index rm <alias> resolves a registered alias before falling back to path interpretation.