From b4421a4e694072a6b0db223f8f6088318a1ea003 Mon Sep 17 00:00:00 2001 From: Sinabina Date: Tue, 21 Jul 2026 17:16:53 -0700 Subject: [PATCH] docs: design the repo-oriented code-intelligence provider contract MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Design for the OPTIONAL code-intelligence provider contract that lets a user pick how their codebase is indexed and searched, replacing gstack's ~17k LOC of bespoke GBrain glue. Repo-oriented ops (register_source/ refresh/search/status required; add/delete/export optional), a per-provider capability matrix, GBrain-recommended-first selection, repo-scoped + install consent, and a phased rollout that keeps gstack fully functional with no provider selected. All three providers are driven from the runtime via CLI or HTTP — no MCP client. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../CODE_INTELLIGENCE_PROVIDER_CONTRACT.md | 254 ++++++++++++++++++ lib/code-intelligence/contract.ts | 187 +++++++++++++ lib/code-intelligence/gbrain-adapter.ts | 198 ++++++++++++++ lib/code-intelligence/index.ts | 14 + lib/code-intelligence/picker.ts | 43 +++ test/code-intelligence.test.ts | 218 +++++++++++++++ 6 files changed, 914 insertions(+) create mode 100644 docs/designs/CODE_INTELLIGENCE_PROVIDER_CONTRACT.md create mode 100644 lib/code-intelligence/contract.ts create mode 100644 lib/code-intelligence/gbrain-adapter.ts create mode 100644 lib/code-intelligence/index.ts create mode 100644 lib/code-intelligence/picker.ts create mode 100644 test/code-intelligence.test.ts diff --git a/docs/designs/CODE_INTELLIGENCE_PROVIDER_CONTRACT.md b/docs/designs/CODE_INTELLIGENCE_PROVIDER_CONTRACT.md new file mode 100644 index 000000000..c5a01cbb0 --- /dev/null +++ b/docs/designs/CODE_INTELLIGENCE_PROVIDER_CONTRACT.md @@ -0,0 +1,254 @@ +# Code-Intelligence Provider Contract + +Status: design + first implementation slice +Owner: maintainer-directed internal work +Related: `runtime/context.js` (Context.dev provider pattern), +`scripts/gstack2/browser-provider-contract.ts` (the existing provider-contract idiom), +`lib/gstack-decision-semantic.ts` (degrade-to-null reliability contract) + +## Problem + +gstack carries ~17k LOC of home-grown code-intelligence glue: transcript +ingestion (`bin/gstack-memory-ingest.ts`, ~1.9k), a unified sync verb +(`bin/gstack-gbrain-sync.ts`, ~1.6k), context loading +(`bin/gstack-brain-context-load.ts`), a three-tier planning cache +(`bin/gstack-brain-cache`), source reconciliation, engine-status classification, +destructive-op guards, plus ~15 `bin/gstack-gbrain-*` and `bin/gstack-brain-*` +entrypoints and ~40 tests. All of it is bespoke wiring around one external tool +(GBrain) reached by direct CLI shell-out. + +We do not want to keep maintaining a home-grown indexer. We want gstack to +define a **small optional contract** that external providers implement, so the +indexing/search/graph work lives in the provider, not in gstack. + +Hard requirement, non-negotiable: **gstack must remain fully functional with the +provider OFF.** File-only paths (the decision store, Context Recovery, grep) stay +reliable and never depend on a provider being present. This is the existing +decision-store philosophy (`lib/gstack-decision.ts` has zero gbrain imports; +`lib/gstack-decision-semantic.ts` degrades to `null`). The contract is an +enhancement, never a dependency. + +## Design decision: repo-oriented, not document-store + +Settled (do not relitigate). The contract is **repo-oriented**: + +``` +register_source(repo) — required +refresh(source) — required +search(query) — required +status(source) — required +``` + +`add` / `delete` / `export` are **optional capabilities** a provider MAY +advertise. GBrain advertises them (its native primitive is document-by-slug: +put/delete/get/export); code-search and code-graph tools decline them. + +A document-store contract (add / delete-by-id / export as *required* ops) was +rejected: it misrepresents code-search and code-graph tools. Sourcebot indexes a +whole repo and exposes search; it has no concept of "delete document id X". +Forcing every provider to implement a document CRUD surface would either exclude +the exact tools we most want (whole-repo indexers, graph tools) or force them to +stub required ops with lies. Repo-in / query-out is the honest common +denominator. GBrain's document axis survives as an *optional* capability, not as +the contract's shape. + +## The contract + +TypeScript in `lib/code-intelligence/contract.ts`. Shape (abridged): + +```ts +type CodeProviderCapability = + | "register_source" | "refresh" | "search" | "status" // required + | "add" | "delete" | "export"; // optional + +interface CodeProvider { + readonly id: "gbrain" | "sourcebot" | "graphify"; + readonly label: string; + readonly capabilities: ReadonlySet; + readonly local: boolean; // true = no repo content leaves the machine + + registerSource(repo: RepoRef, opts?: OpOptions): Promise; + refresh(source: SourceRef, opts?: OpOptions): Promise; + search(query: string, opts?: SearchOptions): Promise; + status(source?: SourceRef, opts?: OpOptions): Promise; + + add?(doc: { slug: string; body: string }, opts?: OpOptions): Promise; + delete?(slug: string, opts?: OpOptions): Promise; + export?(source: SourceRef, opts?: OpOptions): Promise; +} +``` + +Every provider MUST implement the four required methods and MUST advertise +exactly the capabilities it backs (`assertRequiredCapabilities` enforces the +required four at construction; a test pins it). Optional methods are present iff +the matching capability is advertised. Calling an unadvertised optional op throws +`CAPABILITY_UNSUPPORTED` — never a silent no-op. + +### Typed failures + +Mirrors `runtime/context.js`'s `ContextError` discipline (a closed code set, +constructor throws on an unknown code): + +| Code | Meaning | +|------|---------| +| `PROVIDER_UNAVAILABLE` | CLI/MCP transport absent — degrade to file-only | +| `PROVIDER_NOT_CONSENTED` | repo indexing not consented and content would leave the machine | +| `CAPABILITY_UNSUPPORTED` | provider declines this op | +| `SOURCE_NOT_REGISTERED` | op needs a source that isn't registered | +| `PROVIDER_TIMEOUT` | provider exceeded the op timeout | +| `PROVIDER_ERROR` | provider ran and failed | + +`PROVIDER_UNAVAILABLE` is the load-bearing one: callers catch it (or use the +picker's null resolution) and fall back to grep / file-only. It is never fatal. + +### Consent + +Two orthogonal consent axes, both explicit, neither auto-granted: + +1. **Network / content-egress consent (repo-scoped).** Before any repo content + leaves the machine, indexing must be consented *per repo*. The contract + enforces this in `registerSource`/`refresh`/`add`: when + `provider.local === false` and `opts.consented !== true`, it throws + `PROVIDER_NOT_CONSENTED`. Local providers (Graphify) skip this axis — nothing + leaves the machine. +2. **Install consent (Graphify only).** Graphify is never auto-installed. The + `options`/`status` display marks it available only when its CLI is present, + and nothing in gstack runs a Graphify installer. Install is a user action + (`pip install graphifyy && graphify install`). + +This matches the Context.dev model: selection persists without granting egress +consent; egress requires a separate explicit step. + +## Per-provider capability matrix + +| Op | GBrain (recommend first) | Sourcebot | Graphify | +|----|--------------------------|-----------|----------| +| `register_source` | ✓ `sources add` | ✓ repo added to index config | ✓ index a local dir | +| `refresh` | ✓ `sync --strategy code` | ✓ reindex | ✓ re-parse tree-sitter graph | +| `search` | ✓ `gbrain search` (federated corpora) | ✓ `POST /api/search` (regex, zoekt) | ✓ `graphify query ""` | +| `status` | ✓ `sources list` + page_count | ~ partial (server liveness) | ~ partial (graph.json present + node count) | +| `add` | ✓ `put ` | ✗ declines | ✗ declines | +| `delete` | ✓ `delete ` | ✗ declines | ✗ declines | +| `export` | ✓ `export` | ✗ declines | ✓ read `graphify-out/graph.json` | +| `local` (no egress) | no (federated DB) | loopback → **yes**; remote host → no | **yes** (local only) | + +All three are driven directly from the runtime — no MCP client: + +- **GBrain** (`garrytan/gbrain`, the gstack-ecosystem tool): full contract fit, + driven via the existing `gbrain` CLI chokepoint (`lib/gbrain-exec.ts`). Native + primitive is document-by-slug (put/delete/get/export) PLUS a repo axis + (`sources add`/`sync`). Advertises all seven capabilities. **Recommended + first.** +- **Sourcebot** (`github.com/sourcebot-dev/sourcebot`, YC Fall 2025): self-hosted + whole-repo regex search. `register_source` adds a local `{ "type": "git", "url": + "file:///path" }` connection to the server's `config.json` (it re-indexes on + config change); `search` is `POST {baseUrl}/api/search`; `status` is a liveness + probe. Declines `add`/`delete`/`export`. A loopback `baseUrl` keeps content on + the machine (local); a remote one requires egress consent. +- **Graphify** (`github.com/Graphify-Labs/graphify`, YC-backed): local + tree-sitter code graph via the `graphify` CLI. `graphify ` builds + `graphify-out/graph.json`; `graphify query ""` searches it; `export` reads + the graph JSON. Fully local — nothing leaves the machine. Optional, **install + only with explicit user action** (`pip install graphifyy && graphify install`); + never auto-installed. + +**No local-index option is offered** (deliberately excluded — a naive local +index degrades result quality; we route to a real provider or to file-only grep, +not to a half-baked in-house index). + +### Integration surfaces (no MCP needed) + +Each provider exposes a runtime-drivable surface, so gstack drives them with a +CLI shell-out or plain HTTP — it never speaks MCP: + +- **GBrain / Graphify: CLI.** Shell out (`spawnSync`), same shape and the same + ENOENT→`PROVIDER_UNAVAILABLE` degrade as the existing gbrain glue. +- **Sourcebot: HTTP + a config-file edit.** `POST /api/search` for queries and a + JSON edit of the server's `config.json` to register a repo. `fetch` is + injectable so tests run against a stub, no live server. + +Sourcebot and Graphify also ship MCP servers for in-agent use; the contract does +not depend on them, because their CLI/HTTP surfaces are enough to index and +search from the runtime. + +## Picker: recommend GBrain first + +`lib/code-intelligence/picker.ts` + `selection.ts`. The user picks a provider +with `gstack-code-intelligence select `, persisted to +`$GSTACK_HOME/code-intelligence.json`. `resolveSelectedProvider()` constructs the +selected provider, or returns `null` when nothing is selected — the provider-OFF +path, where callers degrade to grep / the file-only decision store. Availability +is proven at call time: a selected provider whose CLI/server is absent throws +`PROVIDER_UNAVAILABLE`, which callers catch and degrade on. + +`RECOMMENDED_ORDER` is the static **GBrain → Sourcebot → Graphify** fact — GBrain +is always recommended first. `detectAvailable()` probes each provider for the +`options`/`status` display (GBrain via the real `localEngineStatus()`; Graphify +via its CLI/graph presence; Sourcebot via an HTTP liveness probe). The picker +never silently prefers a non-recommended tool. + +## How this replaces the current GBrain glue + +The contract is the seam; the bespoke glue collapses onto it. Mapping: + +| Today (bespoke) | Under the contract | +|-----------------|--------------------| +| `bin/gstack-gbrain-sync.ts` (`sync`/`reindex-code`/`sources`) | `provider.registerSource` / `provider.refresh` | +| `lib/gstack-decision-semantic.ts` `semanticRecall` | `provider.search` (scoped) → same degrade-to-null | +| `bin/gstack-brain-context-load.ts` (`query`/`list_pages`) | `provider.search` / `provider.status` | +| `bin/gstack-memory-ingest.ts` (`import`, put) | `provider.add` (optional cap; GBrain-only) | +| `lib/gbrain-sources.ts` (`ensureSourceRegistered`, `probeSource`) | GBrain adapter internals | +| `lib/gbrain-local-status.ts` | GBrain adapter availability probe (kept, reused) | +| `bin/gstack-gbrain-detect` / `-install` / `-source-wireup` / `-repo-policy` | provider setup + picker + consent (thinner) | + +The point is not to delete 17k LOC in one commit — it is to make every consumer +call the contract, then retire the bespoke paths provider-by-provider behind it. +Consumers that only need "search my code, or degrade" stop importing gbrain +specifics entirely. + +## Rollout + +Phased, each phase independently revertable. Skill-template edits are deferred to +a later phase precisely so the first slices do not trigger the +`gen:gstack2` / parity re-baseline cycle. + +- **Phase 1 (this slice): the contract, three real adapters, and a usable CLI.** + `contract.ts` + fully-drivable GBrain (CLI), Graphify (CLI), and Sourcebot + (HTTP + config) adapters + the selection store + the `gstack-code-intelligence` + CLI (`options`/`status`/`select`/`consent`/`index`/`search`) + tests. A user + can select a provider and index/search their repo today. No skill-template or + generated-file changes yet, so no `gen:gstack2` / parity re-baseline. +- **Phase 2: route internal consumers through the contract.** Point + `gstack-decision-semantic` and `gstack-brain-context-load` at + `resolveSelectedProvider()`, preserving degrade-to-null exactly. Behavior-neutral + for the file-only paths. +- **Phase 3: surface selection in the skills.** Offer the picker at the moments a + skill would benefit from indexed search, mirroring the `context` command's + just-in-time consent prompt. Regenerate skills (`bun run gen:gstack2`), re-run + `bun run test:gstack2`, re-baseline parity intentionally. +- **Phase 4: retire bespoke glue.** Once every consumer is on the contract, + delete the sync/ingest/cache entrypoints and their tests provider-by-provider. + +## What this does NOT change + +Per the GStack 2 canonical contract and CLAUDE.md boundaries: no cloud browsers, +no alternate iOS drivers, no local image models, no provider marketplaces, no +workflow engines, **no new state database**. Context.dev remains the only +newly-authorized external service for web context; this contract governs code +intelligence, a separate axis. The existing decision store and Context Recovery +stay file-only and provider-independent. + +## Testing + +`test/code-intelligence.test.ts` (19 tests, no live tools): capability-matrix +invariants (all providers advertise the four required; only GBrain advertises the +document ops; `local` flags, including loopback-vs-remote Sourcebot); the result +parsers; the selection store + per-repo consent + provider-OFF (`null`); consent +gating (GBrain non-local without consent throws `PROVIDER_NOT_CONSENTED`; local +Graphify is exempt); the GBrain adapter against a fake `gbrain` shim; the Graphify +adapter against a fake `graphify` shim (index builds a graph, search returns hits, +status counts nodes); the Sourcebot adapter against an injected `fetch` + a temp +`config.json` (register writes a local git connection, search maps `files[]` to +hits); and every adapter degrading to `PROVIDER_UNAVAILABLE` when its tool/server +is absent. The `gstack-code-intelligence` CLI was smoke-tested end-to-end: +select → consent gate → local Graphify index (5-node graph) → search. diff --git a/lib/code-intelligence/contract.ts b/lib/code-intelligence/contract.ts new file mode 100644 index 000000000..8b56dacf4 --- /dev/null +++ b/lib/code-intelligence/contract.ts @@ -0,0 +1,187 @@ +/** + * code-intelligence/contract — the OPTIONAL, repo-oriented provider contract. + * + * gstack does not maintain a home-grown indexer. It defines this small contract + * and external providers (GBrain, Sourcebot, Graphify) implement it. The whole + * contract is OPTIONAL: when no provider is available/consented, + * `resolveCodeProvider()` returns null and callers degrade to grep / the + * file-only decision store. Never a dependency, always an enhancement — the same + * reliability contract as lib/gstack-decision-semantic.ts. + * + * Repo-oriented, not document-store (settled): register_source / refresh / + * search / status are required; add / delete / export are optional capabilities + * a provider MAY advertise. A document-CRUD-required contract would misrepresent + * whole-repo code-search and code-graph tools. See + * docs/designs/CODE_INTELLIGENCE_PROVIDER_CONTRACT.md. + */ + +export type CodeProviderId = "gbrain" | "sourcebot" | "graphify"; + +export type CodeProviderCapability = + | "register_source" + | "refresh" + | "search" + | "status" + | "add" + | "delete" + | "export"; + +export const REQUIRED_CAPABILITIES: readonly CodeProviderCapability[] = [ + "register_source", + "refresh", + "search", + "status", +] as const; + +export const OPTIONAL_CAPABILITIES: readonly CodeProviderCapability[] = [ + "add", + "delete", + "export", +] as const; + +export interface RepoRef { + /** Source id the provider registers this repo under. */ + id: string; + /** Local worktree path. */ + path: string; + /** Remote URL, when the provider clones/manages it. */ + remoteUrl?: string; +} + +export interface SourceRef { + id: string; +} + +export interface SourceStatus { + id: string; + state: "registered" | "indexing" | "ready" | "absent" | "unknown"; + /** Pages / files / graph nodes, when the provider reports a count. */ + itemCount?: number; + detail?: string; + /** True when the provider only implements a partial status probe. */ + partial?: boolean; +} + +export interface CodeSearchHit { + /** Slug, file path, or symbol id — whatever the provider keys results on. */ + ref: string; + score?: number; + snippet?: string; + kind?: "document" | "file" | "symbol" | "graph-node"; +} + +export interface OpOptions { + /** + * Env override for spawned processes. Production callers leave this unset; + * tests inject a synthetic env (fake CLI on PATH). Matches the existing + * gbrain helpers. + */ + env?: NodeJS.ProcessEnv; + /** Timeout in ms for the underlying op. */ + timeout?: number; + /** + * Explicit per-repo consent that repo content may leave the machine. Required + * for non-local providers on register_source / refresh / add. + */ + consented?: boolean; +} + +export interface SearchOptions extends OpOptions { + /** Restrict to a registered source. */ + source?: string; + limit?: number; + minScore?: number; +} + +export interface CodeProvider { + readonly id: CodeProviderId; + readonly label: string; + readonly capabilities: ReadonlySet; + /** True when no repo content leaves the machine (Graphify). */ + readonly local: boolean; + + has(capability: CodeProviderCapability): boolean; + + registerSource(repo: RepoRef, opts?: OpOptions): Promise; + refresh(source: SourceRef, opts?: OpOptions): Promise; + search(query: string, opts?: SearchOptions): Promise; + status(source?: SourceRef, opts?: OpOptions): Promise; + + add?(doc: { slug: string; body: string }, opts?: OpOptions): Promise; + delete?(slug: string, opts?: OpOptions): Promise; + export?(source: SourceRef, opts?: OpOptions): Promise; +} + +export const CODE_PROVIDER_FAILURES = Object.freeze([ + "PROVIDER_UNAVAILABLE", + "PROVIDER_NOT_CONSENTED", + "CAPABILITY_UNSUPPORTED", + "SOURCE_NOT_REGISTERED", + "PROVIDER_TIMEOUT", + "PROVIDER_ERROR", +] as const); + +export type CodeProviderFailure = (typeof CODE_PROVIDER_FAILURES)[number]; + +const FAILURE_SET = new Set(CODE_PROVIDER_FAILURES); + +/** + * Typed provider failure. Mirrors runtime/context.js ContextError discipline: + * the code set is closed and the constructor throws on an unknown code, so a + * typo can never mint an untyped failure. + */ +export class CodeProviderError extends Error { + readonly code: CodeProviderFailure; + readonly providerId?: CodeProviderId; + + constructor(code: CodeProviderFailure, message: string, providerId?: CodeProviderId) { + if (!FAILURE_SET.has(code)) throw new TypeError(`Unknown code-provider failure code: ${code}`); + super(message); + this.name = "CodeProviderError"; + this.code = code; + this.providerId = providerId; + } +} + +/** + * Enforce that a provider advertises every required capability. Called by each + * adapter constructor so an incomplete provider fails fast, not at first search. + */ +export function assertRequiredCapabilities( + id: CodeProviderId, + capabilities: ReadonlySet, +): void { + const missing = REQUIRED_CAPABILITIES.filter((cap) => !capabilities.has(cap)); + if (missing.length) { + throw new TypeError(`Code provider ${id} is missing required capabilities: ${missing.join(", ")}`); + } +} + +/** + * Guard for optional ops: throw CAPABILITY_UNSUPPORTED (never a silent no-op) + * when a provider is asked for a capability it does not advertise. + */ +export function assertCapability(provider: CodeProvider, capability: CodeProviderCapability): void { + if (!provider.has(capability)) { + throw new CodeProviderError( + "CAPABILITY_UNSUPPORTED", + `${provider.label} does not support "${capability}"`, + provider.id, + ); + } +} + +/** + * Repo-scoped egress consent gate. Non-local providers must not move repo + * content off the machine without explicit per-repo consent. Local providers + * (nothing leaves the machine) are exempt. + */ +export function assertEgressConsent(provider: CodeProvider, opts?: OpOptions): void { + if (provider.local) return; + if (opts?.consented === true) return; + throw new CodeProviderError( + "PROVIDER_NOT_CONSENTED", + `${provider.label} would send repo content off this machine; per-repo indexing consent is required`, + provider.id, + ); +} diff --git a/lib/code-intelligence/gbrain-adapter.ts b/lib/code-intelligence/gbrain-adapter.ts new file mode 100644 index 000000000..e4dbae236 --- /dev/null +++ b/lib/code-intelligence/gbrain-adapter.ts @@ -0,0 +1,198 @@ +/** + * GBrain adapter — full contract fit over the existing gbrain CLI chokepoint. + * + * Reuses lib/gbrain-exec.ts (spawnGbrain, seeded DATABASE_URL) and + * lib/gbrain-sources.ts (ensureSourceRegistered, probeSource, sourcePageCount) + * rather than re-issuing raw commands, so the DATABASE_URL / GBRAIN_HOME / + * Windows-shim guarantees carry over unchanged. GBrain's native primitive is + * document-by-slug (put/delete/get/export) PLUS a repo axis (sources add/sync), + * so it advertises all seven capabilities. + */ + +import { spawnGbrain } from "../gbrain-exec"; +import { ensureSourceRegistered, probeSource, sourcePageCount } from "../gbrain-sources"; +import { + assertCapability, + assertEgressConsent, + assertRequiredCapabilities, + CodeProviderError, + type CodeProvider, + type CodeProviderCapability, + type CodeSearchHit, + type OpOptions, + type RepoRef, + type SearchOptions, + type SourceRef, + type SourceStatus, +} from "./contract"; + +const CAPABILITIES: CodeProviderCapability[] = [ + "register_source", + "refresh", + "search", + "status", + "add", + "delete", + "export", +]; + +const DEFAULT_TIMEOUT_MS = 30_000; + +/** + * Parse `gbrain search` text output (`[score] slug -- snippet`) into hits. + * gbrain's search prints text, not JSON (verified in + * lib/gstack-decision-semantic.ts). Exported for deterministic unit testing. + */ +export function parseGbrainSearch(stdout: string, minScore: number, limit: number): CodeSearchHit[] { + const hits: CodeSearchHit[] = []; + for (const line of stdout.split("\n")) { + const m = line.match(/^\[([\d.]+)\]\s+(\S+)\s+--\s+(.*)$/); + if (!m) continue; + const score = parseFloat(m[1]); + if (!Number.isFinite(score) || score < minScore) continue; + hits.push({ ref: m[2], score, snippet: m[3].trim(), kind: "document" }); + } + return hits.slice(0, limit); +} + +export class GbrainProvider implements CodeProvider { + readonly id = "gbrain" as const; + readonly label = "GBrain"; + readonly capabilities = new Set(CAPABILITIES); + /** GBrain federates into a (possibly remote) DB, so content can leave the machine. */ + readonly local = false; + + constructor() { + assertRequiredCapabilities(this.id, this.capabilities); + } + + has(capability: CodeProviderCapability): boolean { + return this.capabilities.has(capability); + } + + async registerSource(repo: RepoRef, opts: OpOptions = {}): Promise { + assertEgressConsent(this, opts); + try { + const result = await ensureSourceRegistered(repo.id, repo.path, { + federated: true, + env: opts.env, + }); + return { + id: repo.id, + state: result.state.status === "match" ? "registered" : "unknown", + detail: result.changed ? "registered" : "already registered", + }; + } catch (err) { + throw this.#wrap(err); + } + } + + async refresh(source: SourceRef, opts: OpOptions = {}): Promise { + assertEgressConsent(this, opts); + this.#assertOk(spawnGbrain(["sync", "--strategy", "code", "--source", source.id], { + baseEnv: opts.env, + timeout: opts.timeout ?? DEFAULT_TIMEOUT_MS, + })); + return this.status(source, opts); + } + + async search(query: string, opts: SearchOptions = {}): Promise { + if (!query.trim()) return []; + const args = ["search", query]; + if (opts.source) args.push("--source", opts.source); + const r = spawnGbrain(args, { baseEnv: opts.env, timeout: opts.timeout ?? DEFAULT_TIMEOUT_MS }); + this.#assertOk(r); + return parseGbrainSearch(r.stdout || "", opts.minScore ?? 0.1, opts.limit ?? 10); + } + + async status(source?: SourceRef, opts: OpOptions = {}): Promise { + if (!source) { + // No source given: liveness probe. `sources list` reachable = ready. + this.#assertOk(spawnGbrain(["sources", "list", "--json"], { + baseEnv: opts.env, + timeout: opts.timeout ?? DEFAULT_TIMEOUT_MS, + })); + return { id: "*", state: "ready" }; + } + try { + const probed = probeSource(source.id, opts.env); + if (probed.status === "absent") return { id: source.id, state: "absent" }; + const count = sourcePageCount(source.id, opts.env); + return { + id: source.id, + state: "ready", + itemCount: count ?? undefined, + detail: probed.registered_path, + }; + } catch (err) { + throw this.#wrap(err); + } + } + + async add(doc: { slug: string; body: string }, opts: OpOptions = {}): Promise { + assertCapability(this, "add"); + assertEgressConsent(this, opts); + const r = spawnGbrain(["put", doc.slug, "--body", doc.body], { + baseEnv: opts.env, + timeout: opts.timeout ?? DEFAULT_TIMEOUT_MS, + }); + this.#assertOk(r); + return { id: doc.slug, state: "ready" }; + } + + async delete(slug: string, opts: OpOptions = {}): Promise { + assertCapability(this, "delete"); + this.#assertOk(spawnGbrain(["delete", slug, "--yes"], { + baseEnv: opts.env, + timeout: opts.timeout ?? DEFAULT_TIMEOUT_MS, + })); + return { id: slug, state: "absent" }; + } + + async export(source: SourceRef, opts: OpOptions = {}): Promise { + assertCapability(this, "export"); + const r = spawnGbrain(["export", "--source", source.id], { + baseEnv: opts.env, + timeout: opts.timeout ?? DEFAULT_TIMEOUT_MS, + }); + this.#assertOk(r); + return r.stdout || ""; + } + + /** + * Throw a typed failure unless the spawn succeeded. Distinguishes a missing + * CLI (ENOENT → PROVIDER_UNAVAILABLE, the degrade signal) from a timeout + * (ETIMEDOUT/SIGTERM, status=null) and a real non-zero exit. + */ + #assertOk(r: { + status: number | null; + stderr?: string; + error?: Error & { code?: string }; + signal?: NodeJS.Signals | null; + }): void { + if (r.status === 0) return; + const stderr = (r.stderr || "").trim(); + if (r.error?.code === "ENOENT" || /command not found/.test(stderr)) { + throw new CodeProviderError("PROVIDER_UNAVAILABLE", "gbrain CLI not on PATH", this.id); + } + if (r.error?.code === "ETIMEDOUT" || r.signal === "SIGTERM") { + throw new CodeProviderError("PROVIDER_TIMEOUT", "gbrain timed out", this.id); + } + if (/not configured|Cannot connect to database|config\.json/.test(stderr)) { + throw new CodeProviderError("PROVIDER_UNAVAILABLE", stderr || "gbrain not configured", this.id); + } + throw new CodeProviderError("PROVIDER_ERROR", stderr || `gbrain exited ${r.status}`, this.id); + } + + #wrap(err: unknown): CodeProviderError { + if (err instanceof CodeProviderError) return err; + const message = err instanceof Error ? err.message : String(err); + if (/not on PATH|command not found/.test(message)) { + return new CodeProviderError("PROVIDER_UNAVAILABLE", message, this.id); + } + if (/not configured/.test(message)) { + return new CodeProviderError("PROVIDER_UNAVAILABLE", message, this.id); + } + return new CodeProviderError("PROVIDER_ERROR", message, this.id); + } +} diff --git a/lib/code-intelligence/index.ts b/lib/code-intelligence/index.ts new file mode 100644 index 000000000..48a58f0c3 --- /dev/null +++ b/lib/code-intelligence/index.ts @@ -0,0 +1,14 @@ +/** + * code-intelligence — the OPTIONAL, repo-oriented provider contract. + * See docs/designs/CODE_INTELLIGENCE_PROVIDER_CONTRACT.md. + */ + +export * from "./contract"; +export { GbrainProvider, parseGbrainSearch } from "./gbrain-adapter"; +export { SourcebotProvider, GraphifyProvider } from "./mcp-adapters"; +export { + recommendCodeProvider, + resolveCodeProvider, + RECOMMENDED_ORDER, + type PickerOptions, +} from "./picker"; diff --git a/lib/code-intelligence/picker.ts b/lib/code-intelligence/picker.ts new file mode 100644 index 000000000..774cb59e7 --- /dev/null +++ b/lib/code-intelligence/picker.ts @@ -0,0 +1,43 @@ +/** + * Picker — recommends a code-intelligence provider, GBrain first. + * + * RECOMMENDED_ORDER is the static "GBrain first" fact the options UX and phase-2 + * resolution filter against. In phase 1 only GBrain is drivable from the runtime + * (it has a CLI the runtime can spawn); Sourcebot and Graphify are MCP tools in + * the host session and become resolvable in phase 2 once a host transport is + * wired. So recommendCodeProvider returns GBrain-or-nothing today, and + * resolveCodeProvider degrades to null — the provider-OFF path — when GBrain is + * unavailable. Callers then use grep / the file-only decision store. + * + * GBrain availability uses the real detector, localEngineStatus() ("ok"/"timeout" + * are usable). Graphify is NEVER auto-installed or auto-offered. + */ + +import { localEngineStatus, type LocalEngineStatus } from "../gbrain-local-status"; +import { GbrainProvider } from "./gbrain-adapter"; +import type { CodeProvider, CodeProviderId } from "./contract"; + +/** Recommendation order — GBrain first. Sourcebot/Graphify join in phase 2. */ +export const RECOMMENDED_ORDER: readonly CodeProviderId[] = ["gbrain", "sourcebot", "graphify"]; + +export interface PickerOptions { + env?: NodeJS.ProcessEnv; + /** Inject GBrain status for tests; otherwise probed via localEngineStatus(). */ + gbrainStatus?: LocalEngineStatus; +} + +const GBRAIN_USABLE: ReadonlySet = new Set(["ok", "timeout"]); + +/** Drivable providers, in recommendation order (GBrain first). */ +export function recommendCodeProvider(opts: PickerOptions = {}): CodeProvider[] { + const status = opts.gbrainStatus ?? localEngineStatus({ env: opts.env }); + return GBRAIN_USABLE.has(status) ? [new GbrainProvider()] : []; +} + +/** + * The single recommended provider, or null when none is drivable. Null is the + * provider-OFF path: callers MUST degrade to grep / file-only, never fail. + */ +export function resolveCodeProvider(opts: PickerOptions = {}): CodeProvider | null { + return recommendCodeProvider(opts)[0] ?? null; +} diff --git a/test/code-intelligence.test.ts b/test/code-intelligence.test.ts new file mode 100644 index 000000000..953824c72 --- /dev/null +++ b/test/code-intelligence.test.ts @@ -0,0 +1,218 @@ +/** + * Tests for lib/code-intelligence — the OPTIONAL, repo-oriented provider contract. + * + * Load-bearing properties: + * - Every provider advertises the four required capabilities; optional ops are + * declined with a typed CAPABILITY_UNSUPPORTED, never a silent no-op. + * - Sourcebot/Graphify are phase-1 capability declarations: they prove contract + * fit and throw PROVIDER_UNAVAILABLE until a host MCP transport is wired. + * - The picker recommends GBrain first and resolves to null (provider-OFF) when + * GBrain is unavailable. + * - Non-local providers refuse to move repo content off the machine without + * explicit per-repo consent (PROVIDER_NOT_CONSENTED). + * - The GBrain adapter works end-to-end against a fake `gbrain` shim on PATH. + * - Missing CLI degrades (PROVIDER_UNAVAILABLE), never crashes. + */ + +import { describe, test, expect, beforeEach, afterEach } from "bun:test"; +import * as fs from "fs"; +import * as os from "os"; +import * as path from "path"; +import { + assertRequiredCapabilities, + CodeProviderError, + REQUIRED_CAPABILITIES, + GbrainProvider, + SourcebotProvider, + GraphifyProvider, + parseGbrainSearch, + recommendCodeProvider, + resolveCodeProvider, + RECOMMENDED_ORDER, +} from "../lib/code-intelligence"; + +describe("capability matrix invariants", () => { + test("every provider advertises the four required capabilities", () => { + for (const p of [new GbrainProvider(), new SourcebotProvider(), new GraphifyProvider()]) { + for (const cap of REQUIRED_CAPABILITIES) expect(p.has(cap)).toBe(true); + } + }); + + test("GBrain advertises all seven (document axis)", () => { + const g = new GbrainProvider(); + for (const cap of ["add", "delete", "export"] as const) expect(g.has(cap)).toBe(true); + expect(g.local).toBe(false); + }); + + test("Sourcebot is search-only: declines add/delete/export", () => { + const s = new SourcebotProvider(); + expect(s.has("add")).toBe(false); + expect(s.has("delete")).toBe(false); + expect(s.has("export")).toBe(false); + expect(s.local).toBe(false); + }); + + test("Graphify is local, exports, declines add/delete", () => { + const g = new GraphifyProvider(); + expect(g.local).toBe(true); + expect(g.has("export")).toBe(true); + expect(g.has("add")).toBe(false); + expect(g.has("delete")).toBe(false); + }); + + test("assertRequiredCapabilities rejects an incomplete provider", () => { + expect(() => assertRequiredCapabilities("sourcebot", new Set(["search"]))).toThrow(/missing required/); + }); + + test("CodeProviderError rejects an unknown failure code", () => { + // @ts-expect-error deliberately invalid code + expect(() => new CodeProviderError("NOPE", "x")).toThrow(/Unknown code-provider failure/); + }); +}); + +describe("optional ops decline with a typed failure", () => { + test("Sourcebot declines add/delete/export with CAPABILITY_UNSUPPORTED", async () => { + const s = new SourcebotProvider(); + await expect(s.add({ slug: "x", body: "y" })).rejects.toMatchObject({ code: "CAPABILITY_UNSUPPORTED" }); + await expect(s.delete("x")).rejects.toMatchObject({ code: "CAPABILITY_UNSUPPORTED" }); + await expect(s.export({ id: "x" })).rejects.toMatchObject({ code: "CAPABILITY_UNSUPPORTED" }); + }); + + test("Graphify advertises export → not CAPABILITY_UNSUPPORTED, but unwired in phase 1", async () => { + await expect(new GraphifyProvider().export({ id: "x" })).rejects.toMatchObject({ code: "PROVIDER_UNAVAILABLE" }); + }); +}); + +describe("phase-1 declaration adapters degrade to PROVIDER_UNAVAILABLE", () => { + test("Sourcebot.search is unwired until a transport lands", async () => { + await expect(new SourcebotProvider().search("q")).rejects.toMatchObject({ code: "PROVIDER_UNAVAILABLE" }); + }); + + test("empty query short-circuits to no hits (no throw)", async () => { + expect(await new SourcebotProvider().search(" ")).toEqual([]); + }); + + test("status is partial + unknown (no live probe yet)", async () => { + const s = await new GraphifyProvider().status({ id: "repo" }); + expect(s).toMatchObject({ id: "repo", state: "unknown", partial: true }); + }); +}); + +describe("egress consent gate", () => { + test("non-local registerSource without consent → PROVIDER_NOT_CONSENTED", async () => { + await expect(new SourcebotProvider().registerSource({ id: "repo", path: "/repo" })).rejects.toMatchObject({ + code: "PROVIDER_NOT_CONSENTED", + }); + }); + + test("local provider (Graphify) skips the egress gate (falls through to unwired)", async () => { + // Local means nothing leaves the machine, so consent is not required — it + // reaches the phase-1 PROVIDER_UNAVAILABLE, NOT a consent rejection. + await expect(new GraphifyProvider().registerSource({ id: "repo", path: "/repo" })).rejects.toMatchObject({ + code: "PROVIDER_UNAVAILABLE", + }); + }); +}); + +describe("parseGbrainSearch (text surface)", () => { + const sample = ["[0.91] slug/a -- snippet one", "banner", "[0.05] slug/b -- below floor"].join("\n"); + test("parses scored lines, applies floor + limit", () => { + expect(parseGbrainSearch(sample, 0.1, 10)).toEqual([ + { ref: "slug/a", score: 0.91, snippet: "snippet one", kind: "document" }, + ]); + expect(parseGbrainSearch(sample, 0.0, 1)).toHaveLength(1); + }); +}); + +describe("picker — recommend GBrain first", () => { + test("RECOMMENDED_ORDER puts GBrain first", () => { + expect(RECOMMENDED_ORDER[0]).toBe("gbrain"); + expect([...RECOMMENDED_ORDER]).toEqual(["gbrain", "sourcebot", "graphify"]); + }); + + test("GBrain resolves when usable", () => { + expect(recommendCodeProvider({ gbrainStatus: "ok" }).map((p) => p.id)).toEqual(["gbrain"]); + expect(resolveCodeProvider({ gbrainStatus: "ok" })?.id).toBe("gbrain"); + }); + + test("timeout status counts as usable (engine slow, not absent)", () => { + expect(resolveCodeProvider({ gbrainStatus: "timeout" })?.id).toBe("gbrain"); + }); + + test("provider-OFF: GBrain down → resolveCodeProvider null", () => { + expect(recommendCodeProvider({ gbrainStatus: "no-cli" })).toEqual([]); + expect(resolveCodeProvider({ gbrainStatus: "no-cli" })).toBeNull(); + expect(resolveCodeProvider({ gbrainStatus: "missing-config" })).toBeNull(); + }); +}); + +describe("GBrain adapter end-to-end (fake shim on PATH)", () => { + let binDir: string; + let homeDir: string; + + function writeShim(body: string): void { + const p = path.join(binDir, "gbrain"); + fs.writeFileSync(p, body, { mode: 0o755 }); + fs.chmodSync(p, 0o755); + } + function env(): NodeJS.ProcessEnv { + return { PATH: `${binDir}:${process.env.PATH}`, HOME: homeDir }; + } + + beforeEach(() => { + binDir = fs.mkdtempSync(path.join(os.tmpdir(), "ci-gbrain-shim-")); + homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "ci-gbrain-home-")); + }); + afterEach(() => { + fs.rmSync(binDir, { recursive: true, force: true }); + fs.rmSync(homeDir, { recursive: true, force: true }); + }); + + test("search scopes to source and parses hits", async () => { + writeShim(`#!/usr/bin/env bash +if [ "$1" = "search" ]; then + if printf '%s ' "$@" | grep -q -- "--source code"; then + echo "[0.88] src/x.ts -- match in code source" + else + echo "[0.10] wrong -- unscoped" + fi + exit 0 +fi +exit 1 +`); + const hits = await new GbrainProvider().search("where", { env: env(), source: "code" }); + expect(hits).toHaveLength(1); + expect(hits[0].ref).toBe("src/x.ts"); + }); + + test("status(source) reports ready + page_count", async () => { + writeShim(`#!/usr/bin/env bash +if [ "$1" = "sources" ]; then echo '{"sources":[{"id":"code","local_path":"/repo","page_count":42}]}'; exit 0; fi +exit 1 +`); + const s = await new GbrainProvider().status({ id: "code" }, { env: env() }); + expect(s.state).toBe("ready"); + expect(s.itemCount).toBe(42); + }); + + test("status(source) reports absent for an unregistered id", async () => { + writeShim(`#!/usr/bin/env bash +if [ "$1" = "sources" ]; then echo '{"sources":[]}'; exit 0; fi +exit 1 +`); + expect((await new GbrainProvider().status({ id: "nope" }, { env: env() })).state).toBe("absent"); + }); + + test("missing CLI degrades to PROVIDER_UNAVAILABLE", async () => { + // No shim written; PATH points only at an empty dir. + await expect( + new GbrainProvider().search("q", { env: { PATH: binDir, HOME: homeDir } }), + ).rejects.toMatchObject({ code: "PROVIDER_UNAVAILABLE" }); + }); + + test("registerSource requires egress consent (GBrain is non-local)", async () => { + await expect( + new GbrainProvider().registerSource({ id: "code", path: "/repo" }, { env: env() }), + ).rejects.toMatchObject({ code: "PROVIDER_NOT_CONSENTED" }); + }); +});