Optional code-intelligence provider contract (GBrain / Sourcebot / Graphify)#16
Merged
time-attack merged 9 commits intoJul 22, 2026
Merged
Conversation
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) <noreply@anthropic.com>
…adapters contract.ts: repo-oriented interface (four required ops, three optional), typed CodeProviderError, egress + capability consent guards. Three real, runtime-drivable adapters: - GbrainProvider: gbrain CLI (reuses lib/gbrain-exec + lib/gbrain-sources), all seven capabilities. - GraphifyProvider: graphify CLI — `graphify <dir>` builds the local graph, `graphify query` searches it, export reads graphify-out/graph.json. Fully local; never auto-installed. - SourcebotProvider: self-hosted server over HTTP — register writes a local git connection to config.json, search is POST /api/search, status is a liveness probe. Loopback base URL = local (no egress); remote = consent. selection.ts persists the chosen provider + per-repo indexing consent under $GSTACK_HOME. picker.ts recommends GBrain first, resolves the selected provider or null (provider-OFF), and probes live availability. Every adapter degrades to PROVIDER_UNAVAILABLE when its tool/server is absent. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
User-facing command tying the contract together: `options`/`status` show providers with GBrain first and live availability, `select <provider>` persists the choice, `consent [path]` records per-repo indexing consent, `index [path]` registers + indexes the repo with the selected provider (refusing non-local providers until consented), and `search <query>` runs a query, degrading with a clear message when the provider is unavailable. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…consent Capability matrix, result parsers, selection store + per-repo consent + provider-OFF, egress gating, and each adapter end-to-end against a fake CLI shim (gbrain, graphify) or injected fetch + temp config.json (sourcebot), plus PROVIDER_UNAVAILABLE degrade for every provider. 19 tests, no live tools required. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…e testing) Parallel real-environment tests (graphify 0.9.23, Sourcebot v5 in Docker, gbrain 0.42.56) surfaced real mismatches: - graphify: build via `graphify update <dir>` (the local, no-LLM path) instead of `graphify <dir>` (which runs an LLM backend needing a key + network, so the old path wasn't actually local); query via `graphify query --graph <graph.json>` so it reads the indexed graph regardless of cwd; parse the real NODE/EDGE output (file lives at src=/at=) instead of an invented format. - sourcebot: Sourcebot v5 gates /api/search behind auth — send `Authorization: Bearer <SOURCEBOT_API_KEY>`; treat 401/403 as PROVIDER_UNAVAILABLE; make status probe /api/search without following the login redirect. - gbrain: degrade engine/DB init failures (e.g. pglite WASM, garrytan/gbrain#223) to PROVIDER_UNAVAILABLE with a one-line message instead of PROVIDER_ERROR + a raw stack dump; drop flags the real CLI doesn't define (`sync --strategy`, `search --source`); align put/delete to stdin, export to brain-wide. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
search was running in cwd and missing the repo you indexed. Persist the indexed path per provider in the selection store and resolve it back so `search` reads the same graph `index` built. Graphify availability now checks `graphify --version` (installed = selectable) instead of "a graph already exists here", and the CLI keys Graphify sources on the repo path. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rewrite the Graphify and Sourcebot expectations against the real formats captured from live tools (graphify NODE/EDGE query output; Sourcebot v5 response + Bearer auth), add a gbrain engine-down -> PROVIDER_UNAVAILABLE degrade test and a no-phantom-`--source` search assertion, and cover the persisted indexed-root path. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Update the capability matrix and provider notes to the verified real interfaces (graphify update, Sourcebot v5 Bearer auth) and add a "Verified against real environments" section documenting what the live tests found and fixed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Ran real backends in isolated environments (real Postgres-backed gbrain, live Sourcebot v6.5.0 with anonymous access, real graphify 0.9.23). All three now index + search end-to-end. Fixes: - gbrain: RESTORE `--strategy code` in refresh — round 1 removed it on a --help misread, which silently stopped code from ever being indexed. refresh now runs the verified two-pass (`sync`, then `sync --strategy code --full`). Pinned by a new test so the regression can't return. - sourcebot: an API key is NOT required for local use — anonymous access (FORCE_ENABLE_ANONYMOUS_ACCESS=true) serves /api/search keyless (verified). Key stays optional; only the messaging changed (anonymous-access first, key as fallback) plus a note that a local repo needs remote.origin.url to index. - graphify: correct the docstring — for CODE both `graphify <dir>` and `graphify update` are AST-only (no LLM); the LLM only renames clusters and ingests non-code, which our parser ignores. No LLM mode; local=true is correct. Docs: capability matrix + "Verified against real environments" updated to record all three proven end-to-end and to correct the two first-round mistakes. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Bugbot is not enabled for your account, so this pull request was not reviewed. Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs. |
time-attack
pushed a commit
that referenced
this pull request
Jul 22, 2026
…ical rules Documents the #16 code-intelligence marketplace (GBrain/Sourcebot/Graphify) as an authorized optional external-service category: off by default, grep fallback, per-repo egress consent for off-machine providers. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
time-attack
pushed a commit
that referenced
this pull request
Jul 22, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Optional code-intelligence provider contract
Adds a small, optional way to pick how your codebase gets indexed and
searched, so gstack stops maintaining a home-grown indexer and instead defines a
contract that external providers implement. gstack stays fully functional with
nothing selected — callers fall back to grep / the file-only decision store.
What you can do
The contract
Repo-oriented, not document-store:
register_source/refresh/search/statusare required;add/delete/exportare optional capabilities aprovider may advertise. Typed failures; a closed capability set enforced at
construction. Consent is two-axis and explicit: per-repo egress consent before
any content leaves the machine (skipped for local providers), and install consent
for Graphify (never auto-installed).
Three real, runtime-driven adapters (no MCP client)
gbrainCLI; full contract fit incl. the document ops.POST /api/search+ aconfig.jsonedit). Local tool; no API key needed with anonymous access.graphifyCLI (graphify update+graphify query);fully local, never auto-installed.
Verified against real environments
Every adapter was driven against the real running tool in an isolated environment,
not just unit fakes: real Postgres-backed GBrain 0.42.56, live Sourcebot
v6.5.0 (keyless via anonymous access), and real Graphify 0.9.23 — all three
index + search a real repo end-to-end. Two of the first-round fixes were wrong and
real execution reversed them (a gbrain flag removal that broke code indexing, and
a graphify LLM claim); both are corrected and recorded honestly in
docs/designs/CODE_INTELLIGENCE_PROVIDER_CONTRACT.md. 24 unit tests, pinned to thereal captured output formats, no live tools required.
Scope / not in this PR
Standalone library + CLI + design doc; no skill-template, runtime-config, or
generated-file changes (so no
gen:gstack2/ parity re-baseline). Routing theexisting
gstack-decision-semantic/brain-context-loadconsumers through thecontract, and retiring the bespoke GBrain glue, are the documented phase 2–4
rollout — the old glue is untouched here.
🤖 Generated with Claude Code
Summary by cubic
Adds an optional code‑intelligence provider contract and CLI so repos can index and search code via GBrain, Sourcebot, or Graphify. Keeps existing flows working with zero setup and falls back to grep when no provider is selected.
New Features
gbrainCLI; Sourcebot over HTTP (POST /api/search); Graphify viagraphifyCLI. Live availability checks with graceful PROVIDER_UNAVAILABLE degrade.gstack-code-intelligence options|status|select|consent|index|search.Migration
gstack-code-intelligence select <gbrain|sourcebot|graphify>, thenconsent(for non‑local),index, andsearch "<query>".Written for commit ab7989c. Summary will update on new commits.