feat(core): add the github source adapter

[siracusa5]

Implements the github source kind from specs/contextcake-integrations/spec.md §4/§5. First remote adapter — until now a layer had to be an OKF bundle you authored, a local folder, or a foreign MCP server.

What this does

A repo becomes a context layer with no clone and no OKF authoring. The markdown a team already keeps — CLAUDE.md, AGENTS.md, README.md, docs/**, .context/** — resolves alongside local layers.

{
  "name": "payments-repo",
  "level": 3,
  "source": "github",
  "repo": "acme/payments",
  "paths": ["CLAUDE.md", "docs/**"],
  "auth": "keychain:github",
  "cache": { "ttlSeconds": 900 }
}

One recursive git-tree call builds the concept index, so loadConcept never guesses an extension. Concept ids are repo-qualified (acme/payments/docs/runbook), so several repos layer without colliding. Section dates come from each file's last commit rather than the repo's last push — staleness is per document, which is what the conflict surface needs.

Design notes worth a reviewer's attention

Shared parsing seam. Document parsing moved into parseDocument in files.mjs, called by both adapters. If these ever diverge, a repo-hosted CLAUDE.md and a local one stop merging and silently split into parallel sections instead. The suite pins this with a real cascade assertion (one merged engine section across two adapter kinds, github winning, okf-local dissent in conflicts[]).

Credentials are referenced, never carried. auth accepts only "keychain:<alias>" — resolved from a tokens map the caller injects, so the app owns the keychain and the engine never opens it — or {"tokenEnv":"NAME"} for headless runs. Every other shape throws. That's structural rather than advisory: a raw token cannot sit in a manifest by accident. An alias with nothing injected reads anonymously rather than failing.

Failure degrades, it doesn't break. An unreachable, rate-limited, or unauthorized repo keeps serving its last good index with the cache age surfaced, pauses retries for a 60s cooldown, and warns once per window. Without the cooldown an mcp-server search sweep would mean one API call and one stderr line per concept against a rate-limited API — the worst possible response to a rate limit.

withCache.sync() now calls through to the wrapped adapter's own sync(). Remote adapters hold their own index memo, so previously a user-triggered Sync cleared only the outer half. withGitSync already used this convention.

Testing

packages/core/tests/github-source-test.sh runs against a local node:http fixture speaking the GitHub API shape — no network. Covers glob selection, commit dates with pushed_at fallback, OKF-frontmatter delegation, cross-adapter section merging, credential indirection, foreign/traversal id rejection, truncated trees, stale-serve, cooldown, warn-once, and the cache wrapper.

Eight mutations of the adapter were each confirmed to fail the suite: glob matcher disabled, repo-prefix guard removed, traversal guard removed, per-file commit date dropped, warn-and-continue removed, stale-serve removed, cooldown removed, warn-once removed.

npm test && npm run build --prefix apps/site

Engine: exit 0, 12 suites. Site: exit 0.

Deliberately not here

• GitHub device-flow OAuth UI — spec §8 puts OAuth in apps/desktop/apps/console; the engine only ever sees tokens by value. Until that ships this is usable via tokenEnv and on public repos.
• Write-side credential scan — the read-side invariant is enforced here; the "fail the write" half belongs with the desktop Sources UI, the only thing that writes manifests.
• Profiles (manifest v2) — the natural next PR, and what makes "one MCP config line, ever" literally true.

🤖 Generated with Claude Code