Skip to content

feat: make the code-intel engine swappable behind the tldr contract#71

Merged
arzafran merged 3 commits into
mainfrom
feat/code-intel-engine-contract
Jun 30, 2026
Merged

feat: make the code-intel engine swappable behind the tldr contract#71
arzafran merged 3 commits into
mainfrom
feat/code-intel-engine-contract

Conversation

@arzafran

Copy link
Copy Markdown
Member

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 the tldr MCP 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 tldr server key, the 18 mcp__tldr__* tool names, and the serverInstructions are byte-for-byte identical. Set CC_CODE_INTEL_ENGINE=native-ts to 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 — zod EngineDescriptor + a 3-engine registry (llm-tldr default, native-ts, codebase-memory placeholder). resolveEngine resolves 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 binary engines. Mismatch deletes the download and throws (security boundary); missing checksum or network error fails soft. SLSA/sigstore provenance is a designed stub. Mirrors hooks-fingerprint.ts.
  • Wiring threads the resolved engine through setup.ts (deps, MCP-block rewrite, sentinel engine field), session-start.ts (engine-aware daemon/warm + status line), post-edit.ts (gated daemon notify), and verify-hooks.ts (third fail-open pin-integrity check).
  • The MCP server key, tool names, and serverInstructions semantics 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/)

  • TypeScript-compiler-based, zero runtime deps, TS/JS only. Covers the daily-80%: structure, tree, arch, imports/importers, calls, context, impact, change-impact (no semantic/dataflow/slice/dead — those return a structured unsupported-by-native-engine).
  • A newline-delimited JSON-RPC 2.0 stdio MCP server exposes all 18 contract tool names so the skill's allowed-tools stays valid regardless of engine.

Docs: mcp-configs/recommended.json + skills/tldr/SKILL.md describe the pluggable engine (allowed-tools untouched).

A separate chore: commit carries an unrelated biome line-reflow in settings.ts (kept because reverting fails bun run lint), isolated from the feature diff.

Test Plan

  • bun run typecheck
  • bun 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)
  • Install smoke (throwaway HOME): default → tldr=tldr-mcp, sentinel engine: "llm-tldr"; CC_CODE_INTEL_ENGINE=native-tstldr=bun …/codemap/mcp-server.ts, sentinel engine: "native-ts"
  • MCP smoke: tools/list returns 18 tools; impact resolves a symbol cross-file; unsupported tool returns the structured error

arzafran added 3 commits June 30, 2026 13:04
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.
@arzafran arzafran merged commit 8e07026 into main Jun 30, 2026
15 checks passed
@arzafran arzafran deleted the feat/code-intel-engine-contract branch June 30, 2026 18:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant