feat: make the code-intel engine swappable behind the tldr contract#71
Merged
Conversation
Pre-existing line-reflow nit surfaced by biome check; unrelated to the code-intel engine work. Isolated so the feature diff stays clean.
cc-settings got all its code intelligence from llm-tldr, an abandoned pipx tool wired into ~6 places. This makes the engine behind the `tldr` MCP server a single, swappable choice, and ships a native zero-dependency TypeScript engine as an opt-in alternative. The default stays llm-tldr, so nothing changes for anyone who doesn't opt in. Part B — engine indirection + pin/verify: - src/lib/code-intel-engine.ts: zod EngineDescriptor + a 3-engine registry (llm-tldr default, native-ts, codebase-memory placeholder). resolveEngine picks env CC_CODE_INTEL_ENGINE > install sentinel > default; finalize fills install-location paths; ensureEngineInstalled provisions per install method. - src/lib/engine-pin.ts: checksum-pinned download/verify for "rented" binary engines — mismatch deletes + throws, missing checksum / network error fails soft. SLSA/sigstore provenance is a designed stub. Mirrors hooks-fingerprint. - Wiring threads the resolved engine through setup (deps, MCP block rewrite, sentinel), session-start (engine-aware daemon/warm + status), post-edit (gated notify), and verify-hooks (third fail-open pin check). The MCP server key, the 18 mcp__tldr__* tool names, and serverInstructions semantics are unchanged — only the engine behind them swaps. Part A — native TS codemap engine (src/codemap/): - TypeScript-compiler-based, zero runtime deps, TS/JS only. Covers the daily 80%: structure, tree, arch, imports/importers, calls, context, impact, change-impact. A newline-delimited JSON-RPC stdio MCP server exposes all 18 contract tool names (7 unsupported ones return a structured error so the skill's allowed-tools stays valid). Opt in with CC_CODE_INTEL_ENGINE=native-ts. Docs: recommended.json + tldr SKILL.md describe the pluggable engine (skill allowed-tools untouched). Tests: engine resolver/descriptor/regression, pin install/mismatch/fail-soft, and a codemap fixture suite. Verified: typecheck, lint, lint:skills, schemas:check, 655 tests; both install paths and the MCP server smoke-tested.
The finalize test hardcoded a posix path; nativeMcpServerPath uses path.join, which emits backslashes on Windows, failing test (windows-latest). Construct the expected path with join so the assertion is platform-agnostic.
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
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.
What this does
cc-settings gets all its code intelligence (the
mcp__tldr__*tools — call graphs, semantic search, impact) from llm-tldr, a pipx tool whose last commit was January 2026 — effectively abandoned, and wired into ~6 places. This makes the engine behind thetldrMCP server a single swappable choice instead of a hardcoded dependency, and ships a native, zero-dependency TypeScript engine as an opt-in alternative built on the TypeScript compiler.Nothing changes unless you opt in: the default stays llm-tldr, and the
tldrserver key, the 18mcp__tldr__*tool names, and theserverInstructionsare byte-for-byte identical. SetCC_CODE_INTEL_ENGINE=native-tsto switch the engine behind the same contract.The point is resilience: own the interface, rent the engine defensively. A future external engine ships as a checksum-pinned binary that's verified before it ever runs, so an upstream going dark can't strand us.
Summary
Part B — engine indirection + pin/verify
src/lib/code-intel-engine.ts— zodEngineDescriptor+ a 3-engine registry (llm-tldrdefault,native-ts,codebase-memoryplaceholder).resolveEngineresolves envCC_CODE_INTEL_ENGINE> install sentinel > default;finalizefills install-location paths;ensureEngineInstalledprovisions per install method.src/lib/engine-pin.ts— checksum-pinned download/verify for binary engines. Mismatch deletes the download and throws (security boundary); missing checksum or network error fails soft. SLSA/sigstore provenance is a designed stub. Mirrorshooks-fingerprint.ts.setup.ts(deps, MCP-block rewrite, sentinelenginefield),session-start.ts(engine-aware daemon/warm + status line),post-edit.ts(gated daemon notify), andverify-hooks.ts(third fail-open pin-integrity check).serverInstructionssemantics are unchanged — only the engine behind them swaps. Per-project routing behind the same name is deferred to a future MCP proxy (not built here).Part A — native TS codemap engine (
src/codemap/)unsupported-by-native-engine).allowed-toolsstays valid regardless of engine.Docs:
mcp-configs/recommended.json+skills/tldr/SKILL.mddescribe the pluggable engine (allowed-toolsuntouched).A separate
chore:commit carries an unrelated biome line-reflow insettings.ts(kept because reverting failsbun run lint), isolated from the feature diff.Test Plan
bun run typecheckbun run lint(exit 0)bun run lint:skills(0 errors)bun run schemas:check(no schema drift)bun test— 655 pass / 0 fail (engine resolver/descriptor/regression, pin install/mismatch/fail-soft, codemap fixture suite)tldr=tldr-mcp, sentinelengine: "llm-tldr";CC_CODE_INTEL_ENGINE=native-ts→tldr=bun …/codemap/mcp-server.ts, sentinelengine: "native-ts"tools/listreturns 18 tools;impactresolves a symbol cross-file; unsupported tool returns the structured error