Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
feat(brain): two-way Trail integration — carry rules into every ask, and build a brain from a repo (#322)
anirudhkumar-nanonets0b5e434a93ce
diff --git a/.gitignore b/.gitignoreindex 32e11a89..b6bb7d03 100644--- a/.gitignore+++ b/.gitignore@@ -25,3 +25,6 @@ transcripts/# Cursor project config — written per machine by `graft init` (hooks, MCP, rule),# a personal setup like the Claude settings above, not a shared artifact..cursor/++# graft's local repository settings — not committed.+/.graft/diff --git a/docs/github-app.md b/docs/github-app.mdindex b4f78e9d..0170b5f7 100644--- a/docs/github-app.md+++ b/docs/github-app.md@@ -85,6 +85,52 @@ App settings → Install App → pick the repos. **Installing requires admin onrepository** (or org-owner for an org-wide install) — the one thing an App doesnot get you around.+## Reading a repository into a Trail brain++The App has a second, optional job: reading one repository's own history so+Trail can mine rules out of it. That is what backs "paste a repo URL" during+brain onboarding, and it lives here because this is the only service holding the+GitHub App credentials and the only one that can build a symbol graph.++`POST /brain/build`, off unless `GRAFT_BRAIN_BUILD_SECRET` is set:++```bash+curl -X POST https://<your-host>/brain/build \+ -H "authorization: Bearer $GRAFT_BRAIN_BUILD_SECRET" \+ -H 'content-type: application/json' \+ -d '{"owner":"acme","repo":"api"}'+```++It resolves the installation for `acme/api` (`GET /repos/{owner}/{repo}/installation`,+App-JWT authed), clones it shallow, builds the graph, and reads:++- **commit subjects and bodies**, `--no-merges --reverse`, up to 1000+- **closed pull requests and their discussion**, most-discussed first, bots dropped+- **exported symbols**, with the body hash that later tells Trail whether a rule+ still describes the code it was mined from++What comes back is a digest of that — **messages, titles, comments, symbol ids+and hashes. No source code.** Two modes:++| Request | Response |+| --- | --- |+| `owner` + `repo` | `202` with the digest, for the caller to ingest itself |+| plus `brainId` + `brainToken` | the digest is POSTed to the brain; `202` with its job id |++The platform uses the first: it already holds the user's session and writes to+the brain directly, so handing this service a workspace key just to have it call+back would mean minting a credential per build for nothing.++`404` with an `error` means the App is not installed on the repository — the+expected answer for "someone pasted a repo we cannot see", not a failure. The+caller turns it into a choice: install the App, or run `graft init --brain`+locally, where the code never leaves the machine.++| Variable | Meaning |+| --- | --- |+| `GRAFT_BRAIN_BUILD_SECRET` | Bearer secret for the route. Unset disables it entirely. |+| `GRAFT_BRAIN_URL` | Platform base URL the digest is posted to, when a `brainToken` is sent. Overrides anything a request supplies, so a caller cannot redirect a repository's history elsewhere. |+## SecurityThe App clones code written by strangers on every fork PR while holding a token@@ -100,6 +146,10 @@ for the base repository, so:- **Pages are capabilities, not public URLs.** `/p/<id>?t=<hmac>` — an unknownpage and a bad token are both `404`, so the endpoint cannot be used todiscover which pull requests exist. Links expire with the page they point at.+- **`/brain/build` sends no source.** Its digest is commit messages, pull-request+ discussion, symbol ids and hashes; the checkout is deleted in a `finally`. The+ route is off until `GRAFT_BRAIN_BUILD_SECRET` is set, and the secret is+ compared in constant time — it is long-lived, unlike a per-payload signature.## What is not built yetdiff --git a/src/app/brain-build.ts b/src/app/brain-build.tsnew file mode 100644index 00000000..c0909d5b--- /dev/null+++ b/src/app/brain-build.ts@@ -0,0 +1,262 @@+/**+ * Building one repository into a brain, on demand.+ *+ * The whole point of the onboarding flow this serves: someone pastes a+ * repository URL, and a minute later they are looking at rules mined from their+ * own history. Nothing is installed and nobody has signed up yet, so this has to+ * work from the repository name alone.+ *+ * Runs in the app rather than in the platform because only the app has the+ * GitHub App credentials, only it can clone, and only graft can build a symbol+ * graph. What crosses back to the platform is a digest of messages and symbol+ * ids — never source.+ */+import { buildGraph } from "../graph/build.js";+import { contextDirFor } from "../context/node-file.js";+import { loadGraphCached } from "../graph/load.js";+import { checkoutRepository } from "./checkout.js";+import { appJwt, installationFor, repoAccessGap, type AppCredentials, type Fetch, type RepoAccessGap } from "./identity.js";+import { buildDigest, postDigest, readCommits, readSymbols, readThreads, type RepoDigest } from "./history.js";+import {+ budgetSources,+ readAgentInstructions,+ readBranchProtection,+ readCodeowners,+ readCodifiedRules,+ readDecisionDocs,+ readDeclinedIssues,+ readReverts,+ readTestNames,+ type HistorySource,+} from "./sources.js";++/** One request to build a repository into a brain. */+export interface BrainBuildJob {+ owner: string;+ repo: string;+ /** Branch to read; empty means the repository's default. */+ ref?: string;+ /**+ * The brain the rules land in, and the workspace key to write it with.+ *+ * Both optional, and omitting them changes the mode: with them, the digest is+ * posted straight to the brain and only a job id comes back; without them the+ * digest is RETURNED and the caller ingests it itself.+ *+ * The second mode is what the platform's own proxy uses. It already holds the+ * user's session and can write to the brain directly, so handing graft a+ * workspace key just to have it call back would mean minting a credential per+ * build for no gain.+ */+ brainId?: string;+ brainToken?: string;+ /** Platform base URL. Defaults to production. */+ brainBaseUrl?: string;+ /** File the rules as approved rather than as drafts. Onboarding sets it:+ * a brain whose every rule is an invisible draft answers nothing. */+ autoApprove?: boolean;+}++export interface BrainBuildResult {+ /** Set only when the digest was posted; empty in return-the-digest mode. */+ jobId: string;+ headSha: string;+ commits: number;+ threads: number;+ symbols: number;+ sources: number;+ /** Set only in return-the-digest mode. */+ digest?: RepoDigest;+}++export interface BrainBuildDeps {+ creds: AppCredentials;+ fetch: Fetch;+ api?: string;+ githubHost?: string;+ log?: (msg: string) => void;+ now?: () => number;+}++/** Raised when the App cannot see the repository. Distinct because the caller+ * turns it into a specific answer — "install the app, or run it locally" — and+ * not into a 500. */+export class RepoNotAccessibleError extends Error {+ constructor(+ message: string,+ /** Which gap it is, so the caller can send the user to the right place. */+ readonly gap: RepoAccessGap = { reason: "not_installed", ownerId: null, installationId: null },+ ) {+ super(message);+ }+}++/**+ * Read the repository and hand its history to the brain.+ *+ * Public repositories still go through the installation lookup, because the App+ * needs a token to clone at any useful rate limit, and a repository the App is+ * not installed on is exactly the case the UI has to distinguish.+ */+export async function buildRepoIntoBrain(+ job: BrainBuildJob,+ deps: BrainBuildDeps,+): Promise<BrainBuildResult> {+ const log = deps.log ?? ((): void => {});+ const api = deps.api ?? "https://api.github.com";+ const tag = `${job.owner}/${job.repo}`;++ const installationId = await installationFor(+ deps.creds,+ job.owner,+ job.repo,+ deps.fetch,+ (deps.now ?? Date.now)(),+ api,+ );+ if (installationId === null) {+ // Which of the two gaps it is decides what the UI can offer, so it is+ // resolved here rather than guessed there.+ const gap = await repoAccessGap(deps.creds, job.owner, deps.fetch, (deps.now ?? Date.now)(), api);+ throw new RepoNotAccessibleError(+ gap.reason === "repo_not_selected"+ ? `graft is installed on ${job.owner} but ${tag} is not in the list of repositories it can see`+ : `graft is not installed on ${job.owner}`,+ gap,+ );+ }++ const tokenRes = await deps.fetch(`${api}/app/installations/${installationId}/access_tokens`, {+ method: "POST",+ headers: {+ authorization: `Bearer ${appJwt(deps.creds, (deps.now ?? Date.now)())}`,+ accept: "application/vnd.github+json",+ "user-agent": "graft-app",+ },+ });+ if (!tokenRes.ok) {+ throw new Error(`installation token for ${tag} failed: ${tokenRes.status}`);+ }+ const token = (JSON.parse(await tokenRes.text()) as { token: string }).token;++ // Whether the repository is private decides what the UI may show before+ // signup, and the default branch is not discoverable from a shallow+ // single-ref fetch (there is no origin/HEAD to resolve), so both are read from+ // the API in one call rather than guessed.+ const meta = await repoMeta(job.owner, job.repo, token, deps.fetch, api);++ const checkout = checkoutRepository({+ owner: job.owner,+ repo: job.repo,+ ref: job.ref || meta.defaultBranch,+ token,+ api: deps.githubHost,+ log,+ });+ try {+ // `graphOnly`: the symbol ids and their hashes are all the digest needs, and+ // the markdown projections cost real time on a large repo.+ await buildGraph(checkout.dir, { graphOnly: true });+ const graph = loadGraphCached(contextDirFor(checkout.dir));++ const commits = readCommits(checkout.dir);+ const symbols = readSymbols(graph);+ // The threads are the slow part (two API calls per pull request), and the+ // one most likely to fail on a rate limit. A failure here degrades to a+ // commits-only ingest rather than losing the whole build.+ let threads: Awaited<ReturnType<typeof readThreads>> = [];+ try {+ threads = await readThreads(job.owner, job.repo, token, deps.fetch, api);+ } catch (e) {+ log(`${tag}: pull-request discussion unavailable (${e instanceof Error ? e.message : e}); mining commits only`);+ }++ // Everything the repo already states as a rule. All best-effort: the file+ // readers cannot fail the build, and the two API readers swallow their own+ // errors, so a repo with none of this still gets a brain from its history.+ const sources = budgetSources([+ ...readAgentInstructions(checkout.dir),+ ...readDecisionDocs(checkout.dir),+ ...readCodeowners(checkout.dir),+ ...readCodifiedRules(checkout.dir),+ ...readReverts(checkout.dir),+ ...readTestNames(symbols.map((s) => ({ name: s.name, path: s.path }))),+ ...(await readBranchProtection(job.owner, job.repo, meta.defaultBranch, token, deps.fetch, api)),+ ...(await readDeclinedIssues(job.owner, job.repo, token, deps.fetch, api)),+ ]);++ log(+ `${tag}: read ${commits.length} commits, ${threads.length} threads, ${symbols.length} symbols, ${sources.length} stated sources`,+ );++ const digest = buildDigest({+ owner: job.owner,+ name: job.repo,+ headSha: checkout.headSha,+ defaultBranch: job.ref || meta.defaultBranch,+ isPrivate: meta.isPrivate,+ commits,+ threads,+ symbols,+ sources,+ autoApprove: job.autoApprove ?? false,+ });++ const counts = {+ headSha: checkout.headSha,+ commits: commits.length,+ threads: threads.length,+ symbols: symbols.length,+ sources: sources.length,+ };+ if (!job.brainId || !job.brainToken) {+ return { jobId: "", ...counts, digest };+ }+ const { jobId } = await postDigest(+ job.brainBaseUrl ?? "https://agents.nanonets.com",+ job.brainId,+ job.brainToken,+ digest,+ deps.fetch,+ );+ return { jobId, ...counts };+ } finally {+ // Always: the clone was made with an installation token and is not something+ // to leave in /tmp.+ checkout.cleanup();+ }+}++/**+ * The repository's visibility and default branch, in one call.+ *+ * Unknown counts as private: saying a repo is public when it is not would leak+ * its name into a pre-signup screen. An unknown default branch is left empty,+ * and the checkout then falls back to whatever the remote's HEAD points at,+ * which is the same thing by another route.+ */+async function repoMeta(+ owner: string,+ repo: string,+ token: string,+ fetchImpl: Fetch,+ api: string,+): Promise<{ isPrivate: boolean; defaultBranch: string }> {+ try {+ const res = await fetchImpl(`${api}/repos/${owner}/${repo}`, {+ headers: {+ authorization: `Bearer ${token}`,+ accept: "application/vnd.github+json",+ "user-agent": "graft-app",+ },+ });+ if (!res.ok) return { isPrivate: true, defaultBranch: "" };+ const parsed = JSON.parse(await res.text()) as { private?: boolean; default_branch?: string };+ return {+ isPrivate: parsed.private !== false,+ defaultBranch: (parsed.default_branch ?? "").trim(),+ };+ } catch {+ return { isPrivate: true, defaultBranch: "" };+ }+}diff --git a/src/app/checkout.ts b/src/app/checkout.tsindex f5c40a30..7d129af6 100644--- a/src/app/checkout.ts+++ b/src/app/checkout.ts@@ -184,6 +184,81 @@ export function checkoutPullRequest(req: CheckoutRequest): Checkout {return { dir, base: "refs/graft/base", ref, cleanup };}+/** What a plain-repository checkout needs: no pull request, just a ref. */+export interface RepoCheckoutRequest {+ owner: string;+ repo: string;+ /** Branch to read. Empty means "whatever HEAD points at" (the default branch). */+ ref?: string;+ token: string;+ /** How much history to fetch. The default is deeper than a PR review needs+ * because commit MESSAGES are the payload here, not a diff — 50 commits is a+ * fortnight on an active repo and would mine almost nothing. */+ depth?: number;+ api?: string;+ log?: (msg: string) => void;+}++/** A plain checkout: the tree, the commit it landed on, and the cleanup. */+export interface RepoCheckout {+ dir: string;+ headSha: string;+ /** The branch actually checked out, resolved when the caller named none. */+ branch: string;+ cleanup: () => void;+}++/**+ * Clone one repository at a ref, shallow, for reading rather than reviewing.+ *+ * Separate from {@link checkoutPullRequest} rather than a flag on it: that+ * function's whole shape — two refspecs, the merge/head fallback, the diff-base+ * resolution — exists to answer "what does this pull request change", and none+ * of it applies to "read this repository's history". Sharing the hardened `git`+ * runner is the part worth reusing.+ */+export function checkoutRepository(req: RepoCheckoutRequest): RepoCheckout {+ const host = (req.api ?? "https://github.com").replace(/\/$/, "");+ const dir = mkdtempSync(join(tmpdir(), `graft-repo-${req.owner}-${req.repo}-`));+ const cleanup = (): void => rmSync(dir, { recursive: true, force: true });+ const log = req.log ?? ((): void => {});+ const tag = `${req.owner}/${req.repo}`;+ const fail = (step: string, err: string): never => {+ cleanup();+ throw new Error(`${tag}: ${step} failed: ${redact(err, req.token)}`);+ };++ const init = git(dir, ["init", "--quiet", "--initial-branch=graft-tmp"]);+ if (!init.ok) fail("init", init.err);+ const remote = git(dir, ["remote", "add", "origin", `${host}/${req.owner}/${req.repo}.git`]);+ if (!remote.ok) fail("remote", remote.err);++ const depth = req.depth ?? REPO_FETCH_DEPTH;+ // A named branch is fetched by name; with none, `HEAD` resolves to whatever+ // the remote's default branch is, which is what the caller means by "the+ // repository" and saves an API round trip to look the name up.+ const refspec = req.ref+ ? `+refs/heads/${req.ref}:refs/graft/head`+ : `+HEAD:refs/graft/head`;+ const fetched = git(+ dir,+ ["fetch", "--quiet", `--depth=${depth}`, "--no-recurse-submodules", "origin", refspec],+ req.token,+ );+ if (!fetched.ok) fail("fetch", fetched.err);++ const co = git(dir, ["checkout", "--quiet", "--detach", "refs/graft/head"]);+ if (!co.ok) fail("checkout", co.err);++ const headSha = line(dir, ["rev-parse", "HEAD"]) ?? "";+ const branch = req.ref ?? line(dir, ["rev-parse", "--abbrev-ref", "origin/HEAD"]) ?? "";+ log(`${tag}: read ${req.ref || "HEAD"} at ${short(headSha)} (${depth} commits deep)`);+ return { dir, headSha, branch: branch.replace(/^origin\//, ""), cleanup };+}++/** Default history depth for a repository read. See RepoCheckoutRequest.depth. */+const REPO_FETCH_DEPTH = 500;+/** The one fetch each attempt makes: the PR ref to review plus the base branch. */function fetchArgs(req: CheckoutRequest, pull: "merge" | "head", deepen = false): string[] {return [diff --git a/src/app/history.ts b/src/app/history.tsnew file mode 100644index 00000000..24afd31d--- /dev/null+++ b/src/app/history.ts@@ -0,0 +1,367 @@+/**+ * Reading a repository's history into a rule-bearing digest.+ *+ * What a code graph cannot tell you is why the code is the way it is. That+ * lives in two places: commit messages, and the discussion under pull requests.+ * This module reads both, plus the symbol ids from the graph so a rule mined+ * out of them can be anchored to the code it governs.+ *+ * It deliberately sends NO source code onward. The digest is messages, titles,+ * comments, symbol ids and hashes — nothing a reader could reconstruct a private+ * codebase from.+ */+import { spawnSync } from "node:child_process";+import type { GraphV1 } from "../graph/types.js";+import type { Fetch } from "./identity.js";+import type { HistorySource } from "./sources.js";++/** One commit's rule-bearing content. */+export interface HistoryCommit {+ sha: string;+ subject: string;+ body: string;+ files: string[];+}++/** One pull request's discussion. */+export interface HistoryThread {+ number: number;+ title: string;+ body: string;+ mergeSha: string;+ comments: Array<{ body: string; path?: string }>;+}++/** One symbol, as the brain needs it to anchor a rule. */+export interface HistorySymbol {+ id: string;+ path: string;+ name: string;+ kind: string;+ signature: string;+ fingerprint: string;+}++/** The whole payload posted to the brain. */+export interface RepoDigest {+ provider: "github";+ owner: string;+ name: string;+ head_sha: string;+ default_branch: string;+ is_private: boolean;+ commits: Array<{ sha: string; subject: string; body: string; files: string[]; symbols: string[] }>;+ threads: Array<{+ number: number;+ title: string;+ body: string;+ merge_sha: string;+ comments: Array<{ body: string; path?: string }>;+ }>;+ symbols: HistorySymbol[];+ /** Everything in the repo that is already a rule, or nearly one: instruction+ * files, decision records, config, ownership, reverts, test names. One array+ * rather than a field per kind, so adding a source is adding an entry. */+ sources: HistorySource[];+ auto_approve: boolean;+}++/** Field separators inside one `git log` record. Chosen for being bytes no+ * commit message contains, the same trick blast/owners.ts uses. */+const REC = "\x01";+const FIELD = "\x02";++/** Most commits read out of one repository. Above the brain's own per-ingest+ * cap, so the trim happens here where the ordering is known. */+const MAX_COMMITS = 1_000;++/** Run git in `root`, or null when git fails. */+function git(root: string, args: string[]): string | null {+ const res = spawnSync("git", ["-c", "core.quotePath=false", ...args], {+ cwd: root,+ encoding: "utf8",+ stdio: ["ignore", "pipe", "pipe"],+ maxBuffer: 64 * 1024 * 1024,+ });+ if (res.error || res.status !== 0 || typeof res.stdout !== "string") return null;+ return res.stdout;+}++/**+ * Commit subjects, bodies and touched files, oldest first.+ *+ * `--no-merges`: a merge commit's message is "Merge pull request #N from …",+ * which establishes nothing — the decision is in the commits it brings in, and+ * in the thread. `--reverse` so a later reversal reads as a reversal downstream;+ * the extraction prompt relies on that ordering.+ */+export function readCommits(root: string, max = MAX_COMMITS): HistoryCommit[] {+ const fmt = `${REC}%H${FIELD}%s${FIELD}%b${FIELD}`;+ const out = git(root, [+ "log",+ "--no-merges",+ "--reverse",+ `-n`,+ String(max),+ `--format=${fmt}`,+ "--name-only",+ ]);+ if (!out) return [];++ const commits: HistoryCommit[] = [];+ for (const record of out.split(REC)) {+ if (!record.trim()) continue;+ const [sha = "", subject = "", body = "", rest = ""] = record.split(FIELD);+ const files = rest+ .split("\n")+ .map((l) => l.trim())+ .filter((l) => l !== "");+ // A commit with no subject is a broken record, not a commit worth mining.+ if (!sha.trim() || !subject.trim()) continue;+ commits.push({ sha: sha.trim(), subject: subject.trim(), body: body.trim(), files });+ }+ return commits;+}++/** How many pull requests to read, and how many comment pages per thread. */+const MAX_THREADS = 200;+const MAX_COMMENT_PAGES = 3;+/** How many threads' comments are fetched at once. Two requests per pull+ * request, so this is the real cost of a repository read; 8 keeps it quick+ * without crowding an installation's rate limit. */+const THREAD_FETCH_CONCURRENCY = 8;++interface PullListItem {+ number?: number;+ title?: string;+ body?: string | null;+ merge_commit_sha?: string | null;+}++interface CommentItem {+ body?: string | null;+ path?: string | null;+ user?: { type?: string } | null;+}++/**+ * Closed pull requests and their discussion, most-discussed first.+ *+ * Closed only: an open PR's discussion has not concluded, so mining a rule out+ * of it would record a proposal as a decision.+ *+ * Comment counts have to be discovered by fetching, not by reading the list.+ * GitHub's `GET /pulls` list response carries NO `comments` or+ * `review_comments` field — those exist only on the single-PR GET — so an+ * earlier version that pre-filtered on them read `undefined` for every pull+ * request, scored them all zero and skipped the lot. The failure was silent and+ * total: every repository came back with no discussion at all. So the comments+ * are fetched for the most recently updated closed pull requests, and the+ * ranking happens afterwards, on counts that are real.+ *+ * Bot comments are dropped. A CI bot posting a coverage table is the single+ * largest source of text in a busy repo's threads and it establishes nothing.+ */+export async function readThreads(+ owner: string,+ repo: string,+ token: string,+ fetchImpl: Fetch,+ api = "https://api.github.com",+ max = MAX_THREADS,+): Promise<HistoryThread[]> {+ const headers = {+ authorization: `Bearer ${token}`,+ accept: "application/vnd.github+json",+ "user-agent": "graft-app",+ };++ const pulls: PullListItem[] = [];+ // 100 per page, up to the cap. Sorted by GitHub as most-recently-updated,+ // which is the right window: rules decided two years ago that still hold get+ // restated in newer threads, and ones that do not are usually superseded.+ for (let page = 1; pulls.length < max && page <= Math.ceil(max / 100); page++) {+ const res = await fetchImpl(+ `${api}/repos/${owner}/${repo}/pulls?state=closed&sort=updated&direction=desc&per_page=100&page=${page}`,+ { headers },+ );+ if (!res.ok) break;+ const batch = JSON.parse(await res.text()) as PullListItem[];+ if (!Array.isArray(batch) || batch.length === 0) break;+ pulls.push(...batch);+ }++ const candidates = pulls.filter((p): p is PullListItem & { number: number } => typeof p.number === "number").slice(0, max);++ // Bounded concurrency rather than one at a time: two requests per pull+ // request over 200 of them is 400 sequential round trips, which is minutes of+ // a person waiting on a progress screen.+ const threads: HistoryThread[] = [];+ for (let i = 0; i < candidates.length; i += THREAD_FETCH_CONCURRENCY) {+ const slice = candidates.slice(i, i + THREAD_FETCH_CONCURRENCY);+ const fetched = await Promise.all(+ slice.map(async (p) => {+ const [issueComments, reviewComments] = await Promise.all([+ readComments(`${api}/repos/${owner}/${repo}/issues/${p.number}/comments`, headers, fetchImpl),+ readComments(`${api}/repos/${owner}/${repo}/pulls/${p.number}/comments`, headers, fetchImpl),+ ]);+ const comments = [...issueComments, ...reviewComments];+ if (comments.length === 0) return null;+ return {+ number: p.number,+ title: (p.title ?? "").trim(),+ body: (p.body ?? "").trim(),+ mergeSha: (p.merge_commit_sha ?? "").trim(),+ comments,+ } satisfies HistoryThread;+ }),+ );+ for (const t of fetched) if (t) threads.push(t);+ }++ // Most-discussed first, because the digest renderer spends its budget in this+ // order and a twenty-comment thread contains an argument while a one-comment+ // thread contains a rubber stamp.+ threads.sort((a, b) => b.comments.length - a.comments.length);+ return threads;+}++/** One comment endpoint, paginated, bots removed. */+async function readComments(+ url: string,+ headers: Record<string, string>,+ fetchImpl: Fetch,+): Promise<Array<{ body: string; path?: string }>> {+ const out: Array<{ body: string; path?: string }> = [];+ for (let page = 1; page <= MAX_COMMENT_PAGES; page++) {+ const res = await fetchImpl(`${url}?per_page=100&page=${page}`, { headers });+ if (!res.ok) break;+ let batch: CommentItem[];+ try {+ batch = JSON.parse(await res.text()) as CommentItem[];+ } catch {+ break;+ }+ if (!Array.isArray(batch) || batch.length === 0) break;+ for (const c of batch) {+ const body = (c.body ?? "").trim();+ if (!body) continue;+ if (c.user?.type === "Bot") continue;+ out.push(c.path ? { body, path: c.path } : { body });+ }+ if (batch.length < 100) break;+ }+ return out;+}++/** Most symbols to send. The brain only needs enough to anchor rules against. */+const MAX_SYMBOLS = 4_000;++/**+ * Exported symbols from the graph, with the body hash that makes an anchored+ * rule self-invalidating.+ *+ * Exported only, and biggest first: an internal helper is not what a team's+ * rules are about, and the budget is better spent on the surface a rule is+ * likely to govern.+ */+export function readSymbols(graph: GraphV1 | null, max = MAX_SYMBOLS): HistorySymbol[] {+ if (!graph) return [];+ return graph.nodes+ .filter((n) => n.exported && n.kind !== "file")+ .sort((a, b) => (b.chars ?? 0) - (a.chars ?? 0))+ .slice(0, max)+ .map((n) => ({+ id: n.id,+ path: n.path,+ name: n.name,+ kind: n.kind,+ signature: n.signature ?? "",+ fingerprint: n.body_hash,+ }));+}++/**+ * Assemble the digest.+ *+ * Each commit carries the symbol ids its files touched, so a rule mined from a+ * commit message can be anchored even when the message names no symbol — which+ * is most of the time.+ */+export function buildDigest(input: {+ owner: string;+ name: string;+ headSha: string;+ defaultBranch: string;+ isPrivate: boolean;+ commits: HistoryCommit[];+ threads: HistoryThread[];+ symbols: HistorySymbol[];+ sources: HistorySource[];+ autoApprove: boolean;+}): RepoDigest {+ const byPath = new Map<string, string[]>();+ for (const s of input.symbols) {+ const bucket = byPath.get(s.path);+ if (bucket) bucket.push(s.id);+ else byPath.set(s.path, [s.id]);+ }++ return {+ provider: "github",+ owner: input.owner,+ name: input.name,+ head_sha: input.headSha,+ default_branch: input.defaultBranch,+ is_private: input.isPrivate,+ commits: input.commits.map((c) => ({+ sha: c.sha,+ subject: c.subject,+ body: c.body,+ files: c.files,+ // Capped per commit: a sweeping refactor touches hundreds of files, and+ // listing every symbol in all of them would drown the message it belongs to.+ symbols: c.files.flatMap((f) => byPath.get(f) ?? []).slice(0, 20),+ })),+ threads: input.threads.map((t) => ({+ number: t.number,+ title: t.title,+ body: t.body,+ merge_sha: t.mergeSha,+ comments: t.comments,+ })),+ symbols: input.symbols,+ sources: input.sources,+ auto_approve: input.autoApprove,+ };+}++/**+ * Post the digest to a brain.+ *+ * Returns the job id so the caller can hand it back to whoever asked for the+ * build, which is what the onboarding screen polls.+ */+export async function postDigest(+ baseUrl: string,+ brainId: string,+ brainToken: string,+ digest: RepoDigest,+ fetchImpl: Fetch,+): Promise<{ jobId: string }> {+ const res = await fetchImpl(`${baseUrl.replace(/\/+$/, "")}/api/brains/${encodeURIComponent(brainId)}/repo`, {+ method: "POST",+ headers: {+ authorization: `Bearer ${brainToken}`,+ "content-type": "application/json",+ accept: "application/json",+ },+ body: JSON.stringify(digest),+ });+ const text = await res.text();+ if (!res.ok) {+ throw new Error(`brain ingest failed: ${res.status} ${text.slice(0, 300)}`);+ }+ const parsed = JSON.parse(text) as { job_id?: string };+ return { jobId: String(parsed.job_id ?? "") };+}diff --git a/src/app/identity.ts b/src/app/identity.tsindex 06de2968..595e3c13 100644--- a/src/app/identity.ts+++ b/src/app/identity.ts@@ -66,6 +66,109 @@ interface CacheEntry {* Tokens last an hour and a busy repository can fire a dozen webhooks a minute;* without the cache every one of them spends a round trip and a signature.*/+/**+ * The installation id for one repository.+ *+ * Every existing caller gets the id from a webhook payload, because every+ * existing caller is reacting to one. A request that names a repository instead+ * has to look it up, and this is the only endpoint that answers it: it is+ * App-JWT authed, so it works before any installation token exists.+ *+ * Returns null when the App is not installed on the repository — which is the+ * expected answer for "the user pasted a repo we cannot see", not an error.+ */+export async function installationFor(+ creds: AppCredentials,+ owner: string,+ repo: string,+ fetchImpl: Fetch,+ nowMs: number = Date.now(),+ api = "https://api.github.com",+): Promise<number | null> {+ const res = await fetchImpl(`${api}/repos/${owner}/${repo}/installation`, {+ headers: {+ authorization: `Bearer ${appJwt(creds, nowMs)}`,+ accept: "application/vnd.github+json",+ "user-agent": "graft-app",+ },+ });+ if (res.status === 404) return null;+ if (!res.ok) {+ const body = await res.text();+ throw new Error(`installation lookup for ${owner}/${repo} failed: ${res.status} ${body.slice(0, 200)}`);+ }+ const parsed = JSON.parse(await res.text()) as { id?: number };+ return typeof parsed.id === "number" ? parsed.id : null;+}++/**+ * Why a repository is unreachable, and where to send the user to fix it.+ *+ * Two failures look identical from `/repos/{o}/{r}/installation` — both 404 —+ * and they need different sentences and different links. Either the App is not+ * on the account at all, so they install it; or it is installed and this+ * repository simply is not in its selected list, so they edit that list. Telling+ * someone to install an App they already installed is the kind of dead end that+ * ends the session.+ *+ * ownerId is the account's numeric id, which preselects the right account on+ * GitHub's install screen. There is no equivalent for preselecting a repository;+ * GitHub owns that checkbox list.+ */+export interface RepoAccessGap {+ reason: "not_installed" | "repo_not_selected";+ ownerId: number | null;+ installationId: number | null;+}++/** Which of the two gaps applies to owner/repo. */+export async function repoAccessGap(+ creds: AppCredentials,+ owner: string,+ fetchImpl: Fetch,+ nowMs: number = Date.now(),+ api = "https://api.github.com",+): Promise<RepoAccessGap> {+ const headers = {+ authorization: `Bearer ${appJwt(creds, nowMs)}`,+ accept: "application/vnd.github+json",+ "user-agent": "graft-app",+ };+ // An account is an org or a user and the endpoints differ, so try the org one+ // and fall back rather than making the caller know which it is.+ for (const path of [`/orgs/${owner}/installation`, `/users/${owner}/installation`]) {+ try {+ const res = await fetchImpl(`${api}${path}`, { headers });+ if (!res.ok) continue;+ const parsed = JSON.parse(await res.text()) as { id?: number; account?: { id?: number } };+ return {+ reason: "repo_not_selected",+ ownerId: parsed.account?.id ?? null,+ installationId: parsed.id ?? null,+ };+ } catch {+ // Try the other shape; a network failure here only costs a less specific+ // message, never the whole answer.+ }+ }+ return { reason: "not_installed", ownerId: await ownerIdFor(owner, fetchImpl, api), installationId: null };+}++/** The account's numeric id, for preselecting it on the install screen. */+async function ownerIdFor(owner: string, fetchImpl: Fetch, api: string): Promise<number | null> {+ try {+ // Unauthenticated: a public account's id is public, and this runs on a path+ // where the App has no installation token to use anyway.+ const res = await fetchImpl(`${api}/users/${owner}`, {+ headers: { accept: "application/vnd.github+json", "user-agent": "graft-app" },+ });+ if (!res.ok) return null;+ return (JSON.parse(await res.text()) as { id?: number }).id ?? null;+ } catch {+ return null;+ }+}+export class InstallationTokens {private readonly cache = new Map<number, CacheEntry>();diff --git a/src/app/main.ts b/src/app/main.tsindex 381bb7ac..c079e192 100644--- a/src/app/main.ts+++ b/src/app/main.ts@@ -46,6 +46,12 @@ const { server, queue } = createApp({// server that will not start reviews nothing at all, which is strictly worse// than one whose old links go stale.pageDir: process.env.GRAFT_PAGE_DIR,+ // Optional for the same reason as pageDir: unset simply disables+ // `POST /brain/build`, and a deployment that only reviews pull requests wants+ // exactly that. The route is the one place the app writes to the platform, so+ // it stays off until someone deliberately turns it on.+ brainBuildSecret: process.env.GRAFT_BRAIN_BUILD_SECRET,+ brainBaseUrl: process.env.GRAFT_BRAIN_URL,});/**diff --git a/src/app/server.ts b/src/app/server.tsindex 3ddec8ed..2796f69e 100644--- a/src/app/server.ts+++ b/src/app/server.ts@@ -17,8 +17,10 @@* everything in here is I/O again.*/import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";+import { timingSafeEqual } from "node:crypto";import { jobKey, reviewJobFor, type ReviewJob } from "./events.js";import { InstallationTokens, verifySignature, type AppCredentials, type Fetch } from "./identity.js";+import { buildRepoIntoBrain, RepoNotAccessibleError, type BrainBuildJob } from "./brain-build.js";import { PageStore } from "./pages.js";import { WorkQueue } from "./queue.js";import { reviewInChildProcess } from "./review-process.js";@@ -30,6 +32,9 @@ const MAX_BODY_BYTES = 2 * 1024 * 1024;/** Seams for tests: nothing here has a default that touches the network. */export interface AppSeams {fetch?: Fetch;+ /** Swapped out so a test can assert what the route handed the builder without+ * cloning a repository or reaching GitHub. */+ brainBuild?: typeof buildRepoIntoBrain;/** Swapped out to assert what the queue was handed, without a clone — and, being* called in-process, without the fork the default reviewer does. */review?: typeof reviewPullRequest;@@ -38,6 +43,13 @@ export interface AppSeams {export interface AppConfig extends AppCredentials {webhookSecret: string;+ /** Shared secret for `POST /brain/build`. That route is called by the+ * platform, not by GitHub, so it cannot use the webhook's payload signature —+ * it takes a bearer token instead. Unset disables the route entirely, which+ * is the right default for a deployment that only reviews pull requests. */+ brainBuildSecret?: string;+ /** Platform base URL the digest is posted to. Defaults to production. */+ brainBaseUrl?: string;/** Public origin, for the links put in comments, e.g. https://graft.example.com */publicUrl: string;/** Where pages are kept, so a restart does not strand the links already posted. */@@ -128,6 +140,56 @@ export function createApp(return send(res, 202, "application/json", JSON.stringify({ queued: true }));}+ // Build one repository into a brain, on demand. Called by the platform when+ // someone pastes a repository URL during onboarding — there is no webhook+ // behind it, so it authenticates with a bearer token rather than a payload+ // signature.+ if (req.method === "POST" && url.pathname === "/brain/build") {+ if (!config.brainBuildSecret) return send(res, 404, "text/plain", "not found");+ // Compared in constant time for the same reason verifySignature is: this+ // is a long-lived shared secret, and a timing oracle on it is worth more+ // to an attacker than one on a per-payload signature.+ if (!bearerMatches(header(req, "authorization"), config.brainBuildSecret)) {+ return send(res, 401, "text/plain", "unauthorized");+ }+ const body = await readBody(req);+ if (body === null) return send(res, 413, "text/plain", "payload too large");+ let job: BrainBuildJob;+ try {+ job = JSON.parse(body) as BrainBuildJob;+ } catch {+ return send(res, 400, "text/plain", "bad json");+ }+ // brainId/brainToken are optional: without them the digest comes back in+ // the response for the caller to ingest itself. See BrainBuildJob.+ if (!job.owner || !job.repo) {+ return send(res, 400, "application/json", JSON.stringify({ error: "owner and repo are required" }));+ }+ // Synchronous on purpose: the caller is a person waiting on a screen, and+ // the platform's own import job is what makes the SLOW half (extraction and+ // placement) asynchronous. This half is a shallow clone and a graph build.+ try {+ // The deployment's platform URL wins over anything a caller sends, so a+ // request cannot redirect a repository's history to another host.+ if (config.brainBaseUrl) job.brainBaseUrl = config.brainBaseUrl;+ const built = await (seams.brainBuild ?? buildRepoIntoBrain)(job, {+ creds: config,+ fetch: fetchImpl,+ api: config.api,+ log,+ now: seams.now,+ });+ return send(res, 202, "application/json", JSON.stringify(built));+ } catch (e) {+ if (e instanceof RepoNotAccessibleError) {+ return send(res, 404, "application/json", JSON.stringify({ error: e.message, ...e.gap }));+ }+ const msg = e instanceof Error ? e.message : String(e);+ log(`brain build ${job.owner}/${job.repo} failed: ${msg}`);+ return send(res, 502, "application/json", JSON.stringify({ error: msg }));+ }+ }+return send(res, 404, "text/plain", "not found");}@@ -140,6 +202,18 @@ const header = (req: IncomingMessage, name: string): string | undefined => {return Array.isArray(v) ? v[0] : v;};+/** Constant-time `Authorization: Bearer <secret>` check. */+function bearerMatches(headerValue: string | undefined, secret: string): boolean {+ const prefix = "Bearer ";+ if (!headerValue || !headerValue.startsWith(prefix)) return false;+ const given = Buffer.from(headerValue.slice(prefix.length));+ const want = Buffer.from(secret);+ // timingSafeEqual throws on a length mismatch, which is itself a leak of the+ // secret's length — but one byte of length is not worth a branch that skips+ // the comparison, and the lengths here are fixed by deployment config.+ return given.length === want.length && timingSafeEqual(given, want);+}+function send(res: ServerResponse, status: number, type: string, body: string, extra: Record<string, string> = {}): void {res.writeHead(status, { "content-type": type, ...extra });res.end(body);diff --git a/src/app/sources.ts b/src/app/sources.tsnew file mode 100644index 00000000..8d9fb51f--- /dev/null+++ b/src/app/sources.ts@@ -0,0 +1,373 @@+/**+ * Everything in a repository that is already a rule, or nearly one.+ *+ * Commit messages and pull-request discussion say what a team decided in+ * passing. These are the places where they wrote it down on purpose: the+ * instruction files they hand their own agents, the decision records, the linter+ * config, the ownership rules. Higher precision per byte than any amount of+ * history, and most of it is a file read.+ *+ * Every reader returns text, never source code, and every one is best-effort:+ * a repo with none of these still builds a brain from its history.+ */+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";+import { join, relative } from "node:path";+import { spawnSync } from "node:child_process";+import type { Fetch } from "./identity.js";++/** What kind of thing a source is, so extraction can weigh it. */+export type SourceKind =+ | "agent_instructions"+ | "decision_doc"+ | "lint_config"+ | "ci_config"+ | "codeowners"+ | "branch_protection"+ | "revert"+ | "test_name"+ | "declined_issue";++/** One rule-bearing artefact. */+export interface HistorySource {+ kind: SourceKind;+ /** Repo-relative path, or an API-ish label like "branch protection: main". */+ path: string;+ text: string;+ /** Deep link, where one exists (an issue, a reverted commit). */+ url?: string;+}++/** Per-file and total caps, so one enormous doc cannot crowd out everything. */+const MAX_FILE_CHARS = 24_000;+const MAX_TOTAL_CHARS = 300_000;+const MAX_SOURCES = 120;++function readText(root: string, rel: string): string | null {+ try {+ const p = join(root, rel);+ if (!existsSync(p) || !statSync(p).isFile()) return null;+ const raw = readFileSync(p, "utf8");+ const trimmed = raw.trim();+ if (!trimmed) return null;+ return trimmed.length > MAX_FILE_CHARS ? `${trimmed.slice(0, MAX_FILE_CHARS)}\n[…truncated]` : trimmed;+ } catch {+ return null;+ }+}++/** Files directly under `rel`, one level deep, matching `test`. */+function filesIn(root: string, rel: string, test: (name: string) => boolean): string[] {+ try {+ const dir = join(root, rel);+ if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];+ return readdirSync(dir)+ .filter(test)+ .map((n) => join(rel, n))+ .sort();+ } catch {+ return [];+ }+}++/**+ * Instruction files the team already wrote for coding agents.+ *+ * The single highest-precision source in a repository: someone sat down and+ * wrote imperative rules for a machine to follow. Nothing has to be inferred.+ *+ * Graft's own managed blocks are stripped first. Without that the brain reads+ * back graft's instructions about using graft, and then graft carries them into+ * the same file — a loop that fills the rulebook with itself.+ */+export function readAgentInstructions(root: string): HistorySource[] {+ const candidates = [+ "CLAUDE.md",+ "AGENTS.md",+ "GEMINI.md",+ ".github/copilot-instructions.md",+ ".windsurf/rules/graft.md",+ ...filesIn(root, ".cursor/rules", (n) => n.endsWith(".mdc") || n.endsWith(".md")),+ ];+ const out: HistorySource[] = [];+ for (const rel of candidates) {+ const text = stripManagedBlocks(readText(root, rel) ?? "");+ if (text.trim()) out.push({ kind: "agent_instructions", path: rel, text });+ }+ return out;+}++/** Remove graft's own fenced regions, so the brain never learns graft from graft. */+function stripManagedBlocks(text: string): string {+ return text+ .replace(/<!--\s*graft:(brain:)?start\s*-->[\s\S]*?<!--\s*graft:(brain:)?end\s*-->/g, "")+ .trim();+}++/** Architecture decision records and the docs that read like them. */+export function readDecisionDocs(root: string): HistorySource[] {+ const mdIn = (dir: string) => filesIn(root, dir, (n) => n.endsWith(".md"));+ const candidates = [+ "ARCHITECTURE.md",+ "CONTRIBUTING.md",+ "docs/ARCHITECTURE.md",+ "docs/CONTRIBUTING.md",+ ...mdIn("docs/adr"),+ ...mdIn("docs/decisions"),+ ...mdIn("adr"),+ ];+ const out: HistorySource[] = [];+ for (const rel of candidates) {+ const text = readText(root, rel);+ if (text) out.push({ kind: "decision_doc", path: rel, text });+ }+ return out;+}++/**+ * Rules the team already encoded for a machine: linters, formatters, and the+ * checks CI insists on. Nothing to infer — extraction only has to phrase them.+ */+export function readCodifiedRules(root: string): HistorySource[] {+ const lint = [+ ".golangci.yml",+ ".golangci.yaml",+ ".eslintrc.json",+ ".eslintrc.js",+ "eslint.config.js",+ "eslint.config.mjs",+ "ruff.toml",+ ".ruff.toml",+ ".prettierrc",+ ".prettierrc.json",+ "commitlint.config.cjs",+ "commitlint.config.js",+ ".editorconfig",+ ];+ const out: HistorySource[] = [];+ for (const rel of lint) {+ const text = readText(root, rel);+ if (text) out.push({ kind: "lint_config", path: rel, text });+ }+ for (const rel of filesIn(root, ".github/workflows", (n) => n.endsWith(".yml") || n.endsWith(".yaml"))) {+ const text = readText(root, rel);+ if (text) out.push({ kind: "ci_config", path: rel, text });+ }+ return out;+}++/** Who must approve what. A hard constraint, stated as a file. */+export function readCodeowners(root: string): HistorySource[] {+ for (const rel of [".github/CODEOWNERS", "CODEOWNERS", "docs/CODEOWNERS"]) {+ const text = readText(root, rel);+ if (text) return [{ kind: "codeowners", path: rel, text }];+ }+ return [];+}++/** Run git in `root`, or null when it fails. */+function git(root: string, args: string[]): string | null {+ const res = spawnSync("git", ["-c", "core.quotePath=false", ...args], {+ cwd: root,+ encoding: "utf8",+ stdio: ["ignore", "pipe", "pipe"],+ maxBuffer: 64 * 1024 * 1024,+ });+ if (res.error || res.status !== 0 || typeof res.stdout !== "string") return null;+ return res.stdout;+}++/** How many reverts to carry. */+const MAX_REVERTS = 40;++/**+ * Commits that undid another commit.+ *+ * "We tried this and took it back" is a rule available from nowhere else, and+ * it is the one kind of history that says what NOT to do. The body of a revert+ * usually names the commit it undoes and, when the author bothered, why.+ */+export function readReverts(root: string, max = MAX_REVERTS): HistorySource[] {+ const out = git(root, ["log", "--grep=^Revert", "-n", String(max), "--format=%H%x02%s%x02%b%x01"]);+ if (!out) return [];+ const sources: HistorySource[] = [];+ for (const record of out.split("\x01")) {+ if (!record.trim()) continue;+ const [sha = "", subject = "", body = ""] = record.split("\x02");+ if (!sha.trim() || !subject.trim()) continue;+ sources.push({+ kind: "revert",+ path: `revert ${sha.trim().slice(0, 12)}`,+ text: [subject.trim(), body.trim()].filter(Boolean).join("\n"),+ });+ }+ return sources;+}++/** How many test names to carry. */+const MAX_TEST_NAMES = 300;++/**+ * Test names, which are invariants someone wrote deliberately.+ *+ * `never retries on a card decline` is a rule stated as an assertion. Read from+ * the graph's own symbols rather than by re-parsing, so this costs nothing:+ * a test function is already a node.+ *+ * Only names that read like a sentence are kept. `TestFoo` is a label;+ * `rejects an expired token` is a claim about how the system must behave.+ */+export function readTestNames(symbolNames: Array<{ name: string; path: string }>, max = MAX_TEST_NAMES): HistorySource[] {+ const out: HistorySource[] = [];+ for (const s of symbolNames) {+ if (!/(^|[/.])(test|spec)[s]?[/.]|_test\.|\.test\.|\.spec\./i.test(s.path)) continue;+ const sentence = humanizeTestName(s.name);+ if (!sentence) continue;+ out.push({ kind: "test_name", path: s.path, text: sentence });+ if (out.length === max) break;+ }+ return out;+}++/**+ * A test's name as a claim, or null when it is only a label.+ *+ * Requires three words after the prefix is stripped: fewer than that+ * ("TestParse", "handles errors") states no invariant worth a rule, and letting+ * those through fills the brain with noise that reads like content.+ */+function humanizeTestName(name: string): string | null {+ let s = name.replace(/^(Test|it|test|should|describe)[_\s]*/i, "");+ // TestRetriesThreeTimes → Retries Three Times+ if (/^[A-Za-z]+$/.test(s) && /[a-z][A-Z]/.test(s)) s = s.replace(/([a-z0-9])([A-Z])/g, "$1 $2");+ s = s.replace(/[_-]+/g, " ").replace(/\s+/g, " ").trim();+ if (s.split(" ").length < 3) return null;+ return s.toLowerCase();+}++/** How many declined issues to carry. */+const MAX_DECLINED = 40;++/**+ * Issues closed as not planned.+ *+ * A decision NOT to build something, which is half of what a codebase's rules+ * are and is invisible everywhere else — nothing was committed, so no commit+ * message records it.+ */+export async function readDeclinedIssues(+ owner: string,+ repo: string,+ token: string,+ fetchImpl: Fetch,+ api = "https://api.github.com",+ max = MAX_DECLINED,+): Promise<HistorySource[]> {+ try {+ const res = await fetchImpl(`${api}/repos/${owner}/${repo}/issues?state=closed&per_page=100&sort=updated`, {+ headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json", "user-agent": "graft-app" },+ });+ if (!res.ok) return [];+ const items = JSON.parse(await res.text()) as Array<{+ number?: number;+ title?: string;+ body?: string | null;+ html_url?: string;+ state_reason?: string | null;+ pull_request?: unknown;+ }>;+ if (!Array.isArray(items)) return [];+ const out: HistorySource[] = [];+ for (const i of items) {+ // The issues endpoint returns pull requests too; they are already mined as+ // threads and would be counted twice.+ if (i.pull_request) continue;+ if (i.state_reason !== "not_planned") continue;+ if (!i.title?.trim()) continue;+ out.push({+ kind: "declined_issue",+ path: `issue #${i.number}`,+ text: [i.title.trim(), (i.body ?? "").trim()].filter(Boolean).join("\n").slice(0, MAX_FILE_CHARS),+ url: i.html_url,+ });+ if (out.length === max) break;+ }+ return out;+ } catch {+ return [];+ }+}++/** Required checks and reviewers on the default branch. */+export async function readBranchProtection(+ owner: string,+ repo: string,+ branch: string,+ token: string,+ fetchImpl: Fetch,+ api = "https://api.github.com",+): Promise<HistorySource[]> {+ if (!branch) return [];+ try {+ const res = await fetchImpl(`${api}/repos/${owner}/${repo}/branches/${encodeURIComponent(branch)}/protection`, {+ headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json", "user-agent": "graft-app" },+ });+ // 404 simply means the branch is not protected, which is not a failure.+ if (!res.ok) return [];+ const p = JSON.parse(await res.text()) as {+ required_status_checks?: { contexts?: string[] };+ required_pull_request_reviews?: { required_approving_review_count?: number; require_code_owner_reviews?: boolean };+ allow_force_pushes?: { enabled?: boolean };+ };+ const lines: string[] = [];+ const checks = p.required_status_checks?.contexts ?? [];+ if (checks.length) lines.push(`Checks that must pass before merging to ${branch}: ${checks.join(", ")}.`);+ const reviews = p.required_pull_request_reviews;+ if (reviews?.required_approving_review_count) {+ lines.push(`${reviews.required_approving_review_count} approving review(s) required to merge to ${branch}.`);+ }+ if (reviews?.require_code_owner_reviews) lines.push(`A code owner must approve changes to ${branch}.`);+ if (p.allow_force_pushes?.enabled === false) lines.push(`Force pushes to ${branch} are not allowed.`);+ if (!lines.length) return [];+ return [{ kind: "branch_protection", path: `branch protection: ${branch}`, text: lines.join("\n") }];+ } catch {+ return [];+ }+}++/**+ * Trim the collected sources to a budget, best kinds first.+ *+ * The order is the argument of this whole module: a file the team wrote to+ * instruct an agent outranks a decision doc, which outranks a config, which+ * outranks anything inferred. When the budget runs out it should run out on the+ * weakest evidence.+ */+const KIND_RANK: SourceKind[] = [+ "agent_instructions",+ "decision_doc",+ "codeowners",+ "branch_protection",+ "lint_config",+ "ci_config",+ "revert",+ "declined_issue",+ "test_name",+];++export function budgetSources(sources: HistorySource[], maxChars = MAX_TOTAL_CHARS, maxCount = MAX_SOURCES): HistorySource[] {+ const ranked = [...sources].sort((a, b) => KIND_RANK.indexOf(a.kind) - KIND_RANK.indexOf(b.kind));+ const out: HistorySource[] = [];+ let spent = 0;+ for (const s of ranked) {+ if (out.length >= maxCount) break;+ if (spent + s.text.length > maxChars) continue;+ out.push(s);+ spent += s.text.length;+ }+ return out;+}++/** Repo-relative path, for readers handed an absolute one. */+export function relPath(root: string, abs: string): string {+ return relative(root, abs) || abs;+}diff --git a/src/ask/ask.ts b/src/ask/ask.tsindex 1ba860ca..7c3450ff 100644--- a/src/ask/ask.ts+++ b/src/ask/ask.ts@@ -48,6 +48,8 @@ import {} from "./graphrank.js";import { readSourceFile } from "../util/source.js";import { counts, tokenize, type AskIndex, type AskIndexDoc } from "./index-file.js";+import { rulesForPointers, formatRules, type AppliedRule } from "../brain/attach.js";+import { readLink, readRulesCache } from "../brain/link.js";export interface AskHit {kind: "concept" | "symbol" | "caller" | "callee";@@ -131,6 +133,11 @@ export interface AskResult {scopes?: { federated: string[]; alsoMatched: { scope: string; bestId: string }[] };/** @internal Opt-in latent file groups plus the exact pre-file-ranking list. */ranking?: AskRankingMetadata;+ /** Rules from the attached Trail brain that govern the symbols in `hits`.+ * Absent when the repo has no brain linked, or when none of its rules touch+ * this answer. Populated in `--source` mode only, alongside `saved`: a pack+ * the agent does not read the code from has nothing for a rule to sit beside. */+ rules?: AppliedRule[];}/** First real prose line of a node body (skips headings, markers, blanks). */@@ -1383,10 +1390,29 @@ export function ask(dir: string, query: string, opts: AskOptions = {}): AskResul// The pack is truly substitutive only in retriever mode (spans inlined), so// the "vs reading whole files" estimate is only honest here.result.saved = baselineFor(result.hits, corpus.graph);+ // What the team decided about the code this pack just inlined. Read from the+ // local cache only — `ask` is on the agent's hot path and must never wait on+ // the network; `graft brain pull` and `init` are what refresh it.+ const applied = attachBrainRules(root, result.hits, corpus.graph);+ if (applied.length) result.rules = applied;}return result;}+/** Rules for this answer's symbols, or [] when the repo has no brain linked,+ * the cache is missing, or nothing overlaps. Never throws: a broken link must+ * degrade to the code-only answer graft gave before a brain existed. */+function attachBrainRules(root: string, hits: AskHit[], graph: GraphV1 | null): AppliedRule[] {+ try {+ if (!readLink(root)) return [];+ const cache = readRulesCache(root);+ if (!cache?.rules?.length) return [];+ return rulesForPointers(hits.map((h) => h.pointer), cache.rules, graph);+ } catch {+ return [];+ }+}+// ── Skeleton view ────────────────────────────────────────────────────────────export interface SkeletonEntry {@@ -1500,6 +1526,9 @@ export function formatAsk(r: AskResult): string {});lines.push(...scopeFooterLines(r));}+ // Before `body` is joined, so the rules text is counted in the savings line+ // below rather than claimed as free.+ if (r.rules?.length) lines.push(...formatRules(r.rules));const body = lines.join("\n").trimEnd();const savings = askSavingsLine(r, body);return (savings ? `${savings}\n\n${body}` : body) + escalationNudge(r) + "\n";diff --git a/src/brain/attach.ts b/src/brain/attach.tsnew file mode 100644index 00000000..479008ae--- /dev/null+++ b/src/brain/attach.ts@@ -0,0 +1,91 @@+/**+ * Attach a brain's rules to an `ask` answer.+ *+ * The join is the symbol: a rule is mined against a graft node id, and an+ * answer is a set of hits that point at spans. Resolving the hits back to node+ * ids gives the rules that govern exactly what the agent is about to read.+ *+ * Staleness is decided HERE, on the machine that has the code: the rule carries+ * the symbol's body hash from when it was mined, and the local graph carries+ * the hash now. A mismatch means the code moved out from under the rule, which+ * is worth saying rather than hiding — a rule that describes code that no+ * longer exists is the failure mode this whole mechanism exists to catch.+ */+import type { GraphV1 } from '../graph/types.js';+import type { BrainRule } from './link.js';++/** One rule, resolved against the current graph. */+export interface AppliedRule {+ rule: string;+ /** The symbol it governs, as a `path:span` pointer the agent can open. */+ pointer: string;+ /** True when the symbol's body hash no longer matches what the rule was mined at. */+ stale: boolean;+ sourceUrl?: string;+}++/** Most rules to attach to one answer. */+export const MAX_ATTACHED_RULES = 6;++/**+ * The rules governing the symbols in `pointers`, resolved against `graph`.+ *+ * Scoped to the answer, not the repo: attaching every rule a brain holds would+ * turn a token-saving pack into a token-spending one, and `ask` prints the+ * saving it claims. Capped for the same reason.+ */+export function rulesForPointers(+ pointers: string[],+ rules: BrainRule[],+ graph: GraphV1 | null,+): AppliedRule[] {+ if (!rules.length || !graph) return [];++ // node id → its current pointer and body hash. One pass over the graph; the+ // caller does this once per ask, not once per hit.+ const byId = new Map<string, { pointer: string; hash: string }>();+ for (const n of graph.nodes) {+ byId.set(n.id, { pointer: `${n.path}:${n.span}`, hash: n.body_hash });+ }++ const wanted = new Set(pointers);+ const out: AppliedRule[] = [];+ const seen = new Set<string>();+ for (const r of rules) {+ const node = byId.get(r.symbol);+ if (!node || !wanted.has(node.pointer)) continue;+ // The same rule can be mined against two symbols in one answer; show it once.+ if (seen.has(r.rule)) continue;+ seen.add(r.rule);+ out.push({+ rule: r.rule,+ pointer: node.pointer,+ // No recorded fingerprint means the rule was mined before hashing existed+ // (or against a symbol graft could not hash). Unknown is not stale: a+ // false "the code moved" is worse than saying nothing about freshness.+ stale: r.fingerprint !== '' && r.fingerprint !== node.hash,+ sourceUrl: r.sourceUrl,+ });+ if (out.length === MAX_ATTACHED_RULES) break;+ }+ return out;+}++/**+ * Render the rules block appended to an `ask` pack.+ *+ * Deliberately terse. This rides along on every answer, so it has to earn its+ * tokens: one line per rule, the pointer it governs, and a link only when there+ * is one. The `[graft]` prefix is avoided — `sumSavingsFooters` scans for+ * `[graft] tokens saved ≈` and nothing here should look like a savings line.+ */+export function formatRules(applied: AppliedRule[]): string[] {+ if (!applied.length) return [];+ const lines = ['', 'rules that govern these symbols'];+ for (const a of applied) {+ const flag = a.stale ? ' (STALE — the code changed since this was decided)' : '';+ lines.push(`- ${a.rule}${flag}`);+ lines.push(` ${a.pointer}${a.sourceUrl ? ` · ${a.sourceUrl}` : ''}`);+ }+ return lines;+}diff --git a/src/brain/connect.ts b/src/brain/connect.tsnew file mode 100644index 00000000..534f1ca4--- /dev/null+++ b/src/brain/connect.ts@@ -0,0 +1,110 @@+/**+ * The one command a user runs to attach a brain: parse the handoff value,+ * store the link, pull the rules, write them into the agent files.+ */+import {+ readLink,+ writeLink,+ fetchRules,+ writeRulesCache,+ readRulesCache,+ type BrainLink,+ type BrainRule,+} from './link.js';+import { writeBrainSections, type BrainWrite } from './wire.js';+import { basename } from 'node:path';++/**+ * Parse the `--brain` value.+ *+ * The onboarding page hands over one string so there is one thing to copy. Two+ * accepted shapes:+ *+ * `<brainId>:<token>` — the normal case, both halves in one paste+ * `<brainId>` — with the token in `GRAFT_BRAIN_TOKEN`, for CI, where+ * a secret must not appear in a command line+ *+ * A bare token with no brain id is rejected rather than guessed: pointing the+ * wrong brain at a repo would write another team's rules into it.+ */+export function parseBrainArg(value: string): BrainLink | { error: string } {+ const raw = value.trim();+ if (!raw) return { error: 'empty --brain value' };+ const cut = raw.indexOf(':');+ if (cut > 0) {+ const brainId = raw.slice(0, cut).trim();+ const token = raw.slice(cut + 1).trim();+ if (!brainId || !token) return { error: 'expected --brain <brainId>:<token>' };+ return { brainId, token };+ }+ const envToken = process.env.GRAFT_BRAIN_TOKEN;+ if (!envToken) {+ return {+ error:+ 'expected --brain <brainId>:<token>, or a bare brain id with the token in GRAFT_BRAIN_TOKEN',+ };+ }+ return { brainId: raw, token: envToken };+}++/** What connecting a brain did, for the caller to print. */+export interface ConnectResult {+ linked: boolean;+ ruleCount: number;+ writes: BrainWrite[];+ /** Set when the rules could not be fetched; the link is still stored. */+ warning?: string;+}++/**+ * Store the link, pull the rules once, and write them into the agent files.+ *+ * The link is stored even when the pull fails. That is deliberate: a token+ * typed correctly against a brain that is momentarily unreachable should not+ * have to be pasted again — `graft brain pull` retries, and `ask` degrades to+ * the code-only answer meanwhile.+ */+export async function connectBrain(+ repo: string,+ link: BrainLink,+ opts: { home: string; ids?: string[]; fetchImpl?: typeof fetch } = { home: '' },+): Promise<ConnectResult> {+ writeLink(repo, link);+ const rules = await fetchRules(link, opts.fetchImpl ?? fetch);+ if (rules === null) {+ return {+ linked: true,+ ruleCount: 0,+ writes: [],+ warning:+ 'could not reach the brain to pull its rules — the link is saved; run `graft brain pull` to retry',+ };+ }+ writeRulesCache(repo, { brainId: link.brainId, fetchedAt: Date.now(), rules });+ const writes = writeBrainSections(repo, opts.home, rules, basename(repo), opts.ids);+ return { linked: true, ruleCount: rules.length, writes };+}++/**+ * Re-pull the rules for an already-linked repo and rewrite the agent files.+ * Returns null when the repo has no brain linked.+ */+export async function pullBrain(+ repo: string,+ opts: { home: string; ids?: string[]; fetchImpl?: typeof fetch },+): Promise<ConnectResult | null> {+ const link = readLink(repo);+ if (!link) return null;+ return connectBrain(repo, link, opts);+}++/** The linked brain and its cached rule set, for `graft brain status`. */+export function brainStatus(repo: string): {+ link: BrainLink | null;+ rules: BrainRule[];+ fetchedAt: number | null;+} {+ const link = readLink(repo);+ const cache = readRulesCache(repo);+ return { link, rules: cache?.rules ?? [], fetchedAt: cache?.fetchedAt ?? null };+}diff --git a/src/brain/link.ts b/src/brain/link.tsnew file mode 100644index 00000000..c4d786ea--- /dev/null+++ b/src/brain/link.ts@@ -0,0 +1,156 @@+/**+ * The link between a repo's graft graph and a Trail brain.+ *+ * A brain holds the rules mined out of this repository's history — what the+ * team decided and why, which the code graph cannot see. Graft holds the code+ * and can say which symbols an answer touches. This module is the join: the+ * token identifying the brain, and the rules cached beside it so `ask` never+ * waits on the network.+ *+ * The link lives in the per-repo, git-ignored `.graft/config.json`, next to the+ * other persisted build choices. Not in `~/.graft/`: a brain belongs to one+ * repository, and two checkouts of different repos on one machine must not+ * share one.+ */+import { readBuildConfig, patchBuildConfig, cacheDir, readJson, writeJsonAtomic } from '../util/state.js';+import { join } from 'node:path';++/** Default API host. Overridden by GRAFT_BRAIN_URL, for staging and self-hosted. */+const DEFAULT_BRAIN_BASE_URL = 'https://agents.nanonets.com';++/** How long a cached rule set is served before `ask` refreshes it in the background. */+export const RULES_TTL_MS = 6 * 60 * 60 * 1000; // 6 hours++/** One rule from the brain, anchored to a symbol in this repo. */+export interface BrainRule {+ ruleId: string;+ /** A graft node id: `<path>#<QualifiedName>`. */+ symbol: string;+ /** The symbol's body hash when the rule was mined; '' when unrecorded. */+ fingerprint: string;+ rule: string;+ /** Deep link to the commit or pull request that established it. */+ sourceUrl?: string;+}++/** The cached rule set, as stored under the repo's graft cache. */+export interface RulesCache {+ brainId: string;+ fetchedAt: number;+ rules: BrainRule[];+}++/** The persisted brain link. */+export interface BrainLink {+ brainId: string;+ /** Workspace API key (`nn...`). Stored in the git-ignored `.graft/`. */+ token: string;+ /** Set only when the user pointed graft at a non-default host. */+ baseUrl?: string;+}++/**+ * The link for repo `dir`, or null when it has none.+ *+ * `GRAFT_BRAIN_TOKEN` / `GRAFT_BRAIN_ID` override the stored pair, so CI can+ * attach a brain without writing to the checkout.+ */+export function readLink(dir: string): BrainLink | null {+ const envToken = process.env.GRAFT_BRAIN_TOKEN;+ const envBrain = process.env.GRAFT_BRAIN_ID;+ if (envToken && envBrain) {+ return { brainId: envBrain, token: envToken, baseUrl: process.env.GRAFT_BRAIN_URL };+ }+ const stored = readBuildConfig(dir)?.brain;+ if (!stored?.brainId || !stored?.token) return null;+ return stored;+}++/** Persist the link for repo `dir`, merging into any existing build config. */+export function writeLink(dir: string, link: BrainLink): void {+ patchBuildConfig(dir, { brain: link });+}++/** Forget the link for repo `dir`. Leaves the cached rules for `uninstall` to remove. */+export function clearLink(dir: string): void {+ patchBuildConfig(dir, { brain: undefined });+}++/** Where the rule cache lives: beside the graph, since it is derived data. */+export function rulesCachePath(dir: string): string {+ return join(cacheDir(dir), 'brain-rules.json');+}++export function readRulesCache(dir: string): RulesCache | null {+ return readJson<RulesCache>(rulesCachePath(dir));+}++export function writeRulesCache(dir: string, cache: RulesCache): void {+ writeJsonAtomic(rulesCachePath(dir), cache, true);+}++/** Whether a cached set is old enough to refetch. */+export function cacheIsStale(cache: RulesCache | null, now = Date.now()): boolean {+ return !cache || now - cache.fetchedAt > RULES_TTL_MS;+}++/**+ * The base URL for a link, honouring the env override first so a misconfigured+ * stored value can always be corrected without editing a file.+ */+export function baseUrlFor(link: BrainLink): string {+ return (process.env.GRAFT_BRAIN_URL || link.baseUrl || DEFAULT_BRAIN_BASE_URL).replace(/\/+$/, '');+}++/** Timeout for one rules fetch. Short: `ask` must never block on this. */+const FETCH_TIMEOUT_MS = 5000;++interface AnchorsResponse {+ anchors?: Array<{+ rule_id?: string;+ symbol?: string;+ fingerprint?: string;+ rule?: string;+ source_url?: string;+ }>;+}++/**+ * Fetch the brain's symbol-anchored rules.+ *+ * Returns null on any failure — an unreachable brain, a revoked token, a+ * malformed body. Never throws: `ask` degrades to the code-only answer it gave+ * before a brain was attached, which is the whole reason the cache exists.+ */+export async function fetchRules(+ link: BrainLink,+ fetchImpl: typeof fetch = fetch,+): Promise<BrainRule[] | null> {+ // The PUBLIC, token-authenticated route: graft runs on a laptop with no+ // session, and the token it holds is scoped to this one brain rather than the+ // workspace. The protected route is for the app itself.+ const url = `${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/rules/anchors`;+ try {+ const res = await fetchImpl(url, {+ headers: { authorization: `Bearer ${link.token}`, accept: 'application/json' },+ signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),+ });+ if (!res.ok) return null;+ const body = (await res.json()) as AnchorsResponse;+ if (!Array.isArray(body.anchors)) return null;+ const out: BrainRule[] = [];+ for (const a of body.anchors) {+ if (!a?.symbol || !a?.rule) continue;+ out.push({+ ruleId: String(a.rule_id ?? ''),+ symbol: a.symbol,+ fingerprint: String(a.fingerprint ?? ''),+ rule: a.rule,+ sourceUrl: a.source_url || undefined,+ });+ }+ return out;+ } catch {+ return null;+ }+}diff --git a/src/brain/push.ts b/src/brain/push.tsnew file mode 100644index 00000000..6c7fe7f5--- /dev/null+++ b/src/brain/push.ts@@ -0,0 +1,194 @@+/**+ * Building a brain from the repository already on this machine.+ *+ * The server path needs graft's GitHub App installed on the repo, which is an+ * admin action on someone else's org and the first thing asked of a person who+ * has not seen a single rule yet. For a private repository it is often simply+ * unavailable.+ *+ * This is the way round that: the clone is already here, and the user is+ * already authenticated to GitHub for their own work. So read it locally and+ * send up the same digest the server would have built.+ *+ * What leaves the machine is what people wrote — commit messages, pull-request+ * comments, the docs and config already in the tree — plus symbol ids and+ * hashes. No file contents, no diffs, no source.+ */+import { spawnSync } from "node:child_process";+import {+ buildDigest,+ readCommits,+ readSymbols,+ readThreads,+ type RepoDigest,+} from "../app/history.js";+import {+ budgetSources,+ readAgentInstructions,+ readBranchProtection,+ readCodeowners,+ readCodifiedRules,+ readDecisionDocs,+ readDeclinedIssues,+ readReverts,+ readTestNames,+} from "../app/sources.js";+import type { GraphV1 } from "../graph/types.js";+import { baseUrlFor, type BrainLink } from "./link.js";++/** What a local ingest read, for the caller to print. */+export interface PushResult {+ jobId: string;+ repo: string;+ commits: number;+ threads: number;+ symbols: number;+ sources: number;+ /** Set when discussion could not be read; the ingest still went ahead. */+ warning?: string;+}++function git(root: string, args: string[]): string | null {+ const res = spawnSync("git", ["-c", "core.quotePath=false", ...args], {+ cwd: root,+ encoding: "utf8",+ stdio: ["ignore", "pipe", "pipe"],+ });+ if (res.error || res.status !== 0 || typeof res.stdout !== "string") return null;+ return res.stdout.trim();+}++/**+ * owner/name for this checkout, from its origin remote.+ *+ * Only GitHub, because the discussion reader and the forge links are+ * GitHub-shaped; another forge would need its own reader, not a looser regex+ * here that produces links to nowhere.+ */+export function repoSlugFromGit(root: string): { owner: string; name: string } | null {+ const url = git(root, ["remote", "get-url", "origin"]);+ if (!url) return null;+ const m = url.match(/github\.com[:/]+([^/]+)\/(.+?)(?:\.git)?\/?$/i);+ if (!m) return null;+ return { owner: m[1], name: m[2] };+}++/** The branch to attribute the ingest to. */+function currentBranch(root: string): string {+ const head = git(root, ["rev-parse", "--abbrev-ref", "HEAD"]);+ return head && head !== "HEAD" ? head : "";+}++/**+ * A GitHub token from wherever the user already keeps one.+ *+ * `gh auth token` first, because anyone who works with private repositories on+ * the command line has it and it needs no setup at all. The env vars are the+ * CI path. Absent, the ingest still runs on commits alone — pull-request+ * discussion is the richest source, not a required one.+ */+export function githubToken(): string | null {+ const env = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;+ if (env) return env;+ const res = spawnSync("gh", ["auth", "token"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });+ const out = typeof res.stdout === "string" ? res.stdout.trim() : "";+ return res.status === 0 && out ? out : null;+}++/** Whether the repository is private, so the digest records it honestly. */+async function isPrivate(owner: string, name: string, token: string | null, fetchImpl: typeof fetch): Promise<boolean> {+ if (!token) return true; // unknown counts as private+ try {+ const res = await fetchImpl(`https://api.github.com/repos/${owner}/${name}`, {+ headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json" },+ });+ if (!res.ok) return true;+ return ((await res.json()) as { private?: boolean }).private !== false;+ } catch {+ return true;+ }+}++/** Build the digest for the checkout at `root`. Reads nothing but text. */+export async function buildLocalDigest(+ root: string,+ graph: GraphV1 | null,+ opts: { autoApprove?: boolean; fetchImpl?: typeof fetch } = {},+): Promise<{ digest: RepoDigest; warning?: string } | { error: string }> {+ const slug = repoSlugFromGit(root);+ if (!slug) {+ return { error: "this directory has no GitHub `origin` remote — graft can only push a GitHub repository today" };+ }+ const fetchImpl = opts.fetchImpl ?? fetch;+ const token = githubToken();++ const commits = readCommits(root);+ if (commits.length === 0) {+ return { error: "no commits found here — is this a shallow clone with no history?" };+ }+ const symbols = readSymbols(graph);++ let threads: Awaited<ReturnType<typeof readThreads>> = [];+ let warning: string | undefined;+ if (token) {+ try {+ threads = await readThreads(slug.owner, slug.name, token, fetchImpl as never);+ } catch {+ warning = "could not read pull-request discussion; mining commits and repo files only";+ }+ } else {+ warning =+ "no GitHub token found (`gh auth login`, or GH_TOKEN) — mining commits and repo files only, without pull-request discussion";+ }++ const branch = currentBranch(root);+ const sources = budgetSources([+ ...readAgentInstructions(root),+ ...readDecisionDocs(root),+ ...readCodeowners(root),+ ...readCodifiedRules(root),+ ...readReverts(root),+ ...readTestNames(symbols.map((s) => ({ name: s.name, path: s.path }))),+ ...(token ? await readBranchProtection(slug.owner, slug.name, branch, token, fetchImpl as never) : []),+ ...(token ? await readDeclinedIssues(slug.owner, slug.name, token, fetchImpl as never) : []),+ ]);++ const digest = buildDigest({+ owner: slug.owner,+ name: slug.name,+ headSha: git(root, ["rev-parse", "HEAD"]) ?? "",+ defaultBranch: branch,+ isPrivate: await isPrivate(slug.owner, slug.name, token, fetchImpl),+ commits,+ threads,+ symbols,+ sources,+ autoApprove: opts.autoApprove ?? true,+ });+ return { digest, warning };+}++/** Send a digest to the brain and return the job to poll. */+export async function pushDigest(+ link: BrainLink,+ digest: RepoDigest,+ fetchImpl: typeof fetch = fetch,+): Promise<{ jobId: string } | { error: string }> {+ const url = `${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/repo`;+ try {+ const res = await fetchImpl(url, {+ method: "POST",+ headers: {+ authorization: `Bearer ${link.token}`,+ "content-type": "application/json",+ accept: "application/json",+ },+ body: JSON.stringify(digest),+ });+ const text = await res.text();+ if (!res.ok) return { error: `the brain refused the ingest: ${res.status} ${text.slice(0, 200)}` };+ return { jobId: String((JSON.parse(text) as { job_id?: string }).job_id ?? "") };+ } catch (e) {+ return { error: `could not reach the brain: ${e instanceof Error ? e.message : e}` };+ }+}diff --git a/src/brain/wire.ts b/src/brain/wire.tsnew file mode 100644index 00000000..4a10fc5d--- /dev/null+++ b/src/brain/wire.ts@@ -0,0 +1,147 @@+/**+ * Writing a brain's rules into the instruction file each coding agent already+ * reads.+ *+ * Two delivery paths exist and both matter. Every `graft ask` carries the rules+ * for the symbols in its answer — that is the precise one. This is the broad+ * one: the repo-wide conventions, sitting in `AGENTS.md` / `CLAUDE.md` /+ * `.cursor/rules` where the agent picks them up whether or not it ever calls+ * graft.+ *+ * The rules land in their OWN fenced block (`BRAIN_MARKERS`), never inside the+ * instruction block: instructions are static and rewritten by `init`, rules+ * change whenever the brain does, and `uninstall` has to be able to remove+ * either one.+ */+import { join } from 'node:path';+import { HOSTS, detectHosts, type DetectProbe, type HostTarget } from '../hosts/registry.js';+import { upsertSection, BRAIN_MARKERS, type UpsertAction } from '../hosts/sections.js';+import { statSync } from 'node:fs';+import type { BrainRule } from './link.js';++/** How many rules go into an instruction file. */+const MAX_FILE_RULES = 40;++/** What a rules write did to one host's file. */+export interface BrainWrite {+ id: string;+ path: string;+ action: UpsertAction;+}++/**+ * Render the rules block for an instruction file.+ *+ * Grouped by the file the rule governs, because that is how someone reads a+ * codebase, and repo-wide rules (no symbol) come first — they apply everywhere,+ * so they should not be buried under a path heading.+ */+export function renderBrainSection(rules: BrainRule[], repoLabel: string): string {+ const capped = rules.slice(0, MAX_FILE_RULES);+ const lines = [+ '## House rules for this codebase',+ '',+ `Mined from ${repoLabel}'s own history — commit messages and pull-request`,+ 'discussion — by Trail. These are decisions the team has already made, so',+ 'follow them and do not re-litigate them in passing. Each is attributed to',+ 'what established it.',+ '',+ ];++ const byFile = new Map<string, BrainRule[]>();+ for (const r of capped) {+ // A node id is `<path>#<QualifiedName>`; everything before the '#' is the file.+ const file = r.symbol.includes('#') ? r.symbol.slice(0, r.symbol.indexOf('#')) : '';+ const bucket = byFile.get(file);+ if (bucket) bucket.push(r);+ else byFile.set(file, [r]);+ }++ const general = byFile.get('') ?? [];+ for (const r of general) lines.push(`- ${r.rule}${r.sourceUrl ? ` (${r.sourceUrl})` : ''}`);+ if (general.length) lines.push('');++ for (const [file, group] of [...byFile].filter(([f]) => f !== '').sort()) {+ lines.push(`### ${file}`);+ for (const r of group) lines.push(`- ${r.rule}${r.sourceUrl ? ` (${r.sourceUrl})` : ''}`);+ lines.push('');+ }++ if (rules.length > capped.length) {+ lines.push(+ `_${rules.length - capped.length} more rules apply to specific symbols; graft attaches those to each \`graft ask\` answer._`,+ );+ }+ return lines.join('\n').trimEnd();+}++/** Build the probe `detectHosts` needs. Mirrors hosts/init.ts's own. */+function probeFor(repo: string, home: string): DetectProbe {+ return {+ home,+ repo,+ dirExists: (p: string) => {+ try {+ return statSync(p).isDirectory();+ } catch {+ return false;+ }+ },+ };+}++/**+ * Every instruction file a brain section should go in.+ *+ * `section`-kind hosts only. An `owned`-kind host (Cursor's `.mdc`, Kiro's+ * steering file, a `SKILL.md`) is a file graft rewrites whole from a pure+ * template, so a second managed region inside one would be erased by the next+ * `init` — those agents get their rules through `graft ask` instead, which they+ * all call.+ *+ * Deduplicated by path: three hosts target `AGENTS.md`, and writing it three+ * times in one pass is just three identical upserts.+ */+export function brainSectionTargets(repo: string, home: string, ids?: string[]): HostTarget[] {+ const selected = ids?.length+ ? HOSTS.filter((h) => ids.includes(h.id))+ : detectHosts(probeFor(repo, home));+ const seen = new Set<string>();+ const out: HostTarget[] = [];+ for (const h of selected) {+ if (h.kind !== 'section') continue;+ if (seen.has(h.relPath)) continue;+ seen.add(h.relPath);+ out.push(h);+ }+ return out;+}++/**+ * Write the brain's rules into each selected host's instruction file.+ *+ * Best-effort per file: one unwritable path must not stop the rest, since a+ * partially delivered rulebook is strictly better than none.+ */+export function writeBrainSections(+ repo: string,+ home: string,+ rules: BrainRule[],+ repoLabel: string,+ ids?: string[],+): BrainWrite[] {+ if (!rules.length) return [];+ const body = renderBrainSection(rules, repoLabel);+ const out: BrainWrite[] = [];+ for (const host of brainSectionTargets(repo, home, ids)) {+ const path = join(repo, host.relPath);+ try {+ const { action } = upsertSection(path, body, BRAIN_MARKERS);+ out.push({ id: host.id, path, action });+ } catch {+ // Unwritable file (read-only checkout, a directory in the way). Skipped+ // silently here; the caller reports what it did get.+ }+ }+ return out;+}diff --git a/src/cli.ts b/src/cli.tsindex 12130c77..27b50689 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -17,6 +17,11 @@ import { buildGraphIfMissing, runInit } from "./claude/init.js";import { statuslineWanted } from "./claude/settings-merge.js";import { runHostsInit } from "./hosts/init.js";import { hostIds } from "./hosts/registry.js";+import { parseBrainArg, connectBrain, pullBrain, brainStatus } from "./brain/connect.js";+import { rulesForPointers } from "./brain/attach.js";+import { clearLink, type BrainLink } from "./brain/link.js";+import { buildLocalDigest, pushDigest } from "./brain/push.js";+import { readLink } from "./brain/link.js";import { contextDirFor } from "./context/node-file.js";import { loadGraphCached } from "./graph/load.js";import { ensureFreshChildren, ensureFreshGraph, refreshNote } from "./graph/refresh.js";@@ -926,11 +931,24 @@ program.option("--dry-run", "print every file init would touch, then exit without writing").option("-y, --yes", "skip the picker and wire every detected agent (the pre-0.8 default)").option("--no-global", "skip writes outside this repo (the ~/.codex/ config + hooks)")- .action(async (dir: string, opts: { build?: boolean; agents?: string[]; allAgents?: boolean; listAgents?: boolean; mcp?: boolean; hooks?: boolean; statusline?: boolean; dryRun?: boolean; yes?: boolean; global?: boolean }) => {+ .option("--brain <handoff>", "attach a Trail brain: <brainId>:<token> (or a bare brain id with GRAFT_BRAIN_TOKEN set)")+ .action(async (dir: string, opts: { build?: boolean; agents?: string[]; allAgents?: boolean; listAgents?: boolean; mcp?: boolean; hooks?: boolean; statusline?: boolean; dryRun?: boolean; yes?: boolean; global?: boolean; brain?: string }) => {if (opts.listAgents) {for (const id of [...hostIds(), "claude"]) console.log(id);return;}+ // Parsed before anything is written: a mistyped handoff should cost the user+ // an error, not a half-wired repo they have to `graft uninstall` out of.+ let brainLink: BrainLink | undefined;+ if (opts.brain) {+ const parsed = parseBrainArg(opts.brain);+ if ("error" in parsed) {+ console.error(`✗ --brain: ${parsed.error}`);+ process.exitCode = 1;+ return;+ }+ brainLink = parsed;+ }const repo = resolve(dir);const explicit = Array.isArray(opts.agents) ? opts.agents : undefined;@@ -1017,6 +1035,18 @@ programwireTarget(target, ids, { home, cliPath, plan, opts, wantClaude });}+ // The brain comes last, after the graph exists: its rules are anchored to+ // symbols, and `graft brain status` can only report how many of them resolve+ // once there is a graph to resolve them against.+ if (brainLink) {+ const res = await connectBrain(repo, brainLink, { home, ids });+ if (res.warning) console.error(`⚠ brain: ${res.warning}`);+ else console.error(`✓ brain: pulled ${res.ruleCount} rule(s) from ${brainLink.brainId}`);+ for (const w of res.writes) console.error(`✓ brain rules: ${w.path} (${w.action})`);+ if (res.ruleCount > 0 && res.writes.length === 0)+ console.error("· no instruction file to write rules into — graft ask still carries them");+ }+// One epilogue for the whole run. A workspace parent holds no nodes of its// own, so the totals come from the children — the graph the user actually got.const globalDir = program.opts<GlobalOpts>().dir;@@ -1190,6 +1220,146 @@ program);});+const brain = program+ .command("brain")+ .description("The Trail brain attached to this repo: the rules mined from its own history");++brain+ .command("connect")+ .description("Attach a brain to this repo and pull its rules")+ .argument("<handoff>", "<brainId>:<token>, or a bare brain id with GRAFT_BRAIN_TOKEN set")+ .argument("[dir]", "target repo directory", ".")+ .action(async (handoff: string, dir: string) => {+ const parsed = parseBrainArg(handoff);+ if ("error" in parsed) {+ console.error(`✗ ${parsed.error}`);+ process.exitCode = 1;+ return;+ }+ const repo = resolve(dir);+ const res = await connectBrain(repo, parsed, { home: homedir() });+ if (res.warning) {+ console.error(`⚠ ${res.warning}`);+ return;+ }+ console.error(`✓ pulled ${res.ruleCount} rule(s) from ${parsed.brainId}`);+ for (const w of res.writes) console.error(`✓ ${w.path} (${w.action})`);+ });++brain+ .command("pull")+ .description("Re-pull the attached brain's rules and rewrite the agent instruction files")+ .argument("[dir]", "target repo directory", ".")+ .action(async (dir: string) => {+ const repo = resolve(dir);+ const res = await pullBrain(repo, { home: homedir() });+ if (!res) {+ console.error("· no brain attached — run `graft brain connect <brainId>:<token>`");+ return;+ }+ if (res.warning) {+ console.error(`⚠ ${res.warning}`);+ process.exitCode = 1;+ return;+ }+ console.error(`✓ pulled ${res.ruleCount} rule(s)`);+ for (const w of res.writes) console.error(`✓ ${w.path} (${w.action})`);+ });++brain+ .command("push")+ .description("Read THIS repo on your machine and build its brain — no GitHub App, works on private repos")+ .argument("[dir]", "target repo directory", ".")+ .option("--no-approve", "leave the mined rules as drafts for review")+ .action(async (dir: string, opts: { approve?: boolean }) => {+ const repo = resolve(dir);+ const link = readLink(repo);+ if (!link) {+ console.error("· no brain attached — run `graft brain connect <brainId>:<token>` first");+ process.exitCode = 1;+ return;+ }+ // The graph is what symbol anchors are resolved against, so a rule mined+ // here can later go stale on its own. Without one the ingest still works;+ // its rules simply govern the repo rather than a symbol in it.+ const graph = loadGraphCached(contextDirFor(repo, program.opts<GlobalOpts>().dir));+ if (!graph) console.error("· no graph yet — run `graft build` first so rules can be anchored to symbols");++ console.error("· reading this repository (messages and docs only — no code leaves your machine)…");+ const built = await buildLocalDigest(repo, graph, { autoApprove: opts.approve !== false });+ if ("error" in built) {+ console.error(`✗ ${built.error}`);+ process.exitCode = 1;+ return;+ }+ const d = built.digest;+ if (built.warning) console.error(`⚠ ${built.warning}`);+ console.error(+ `· ${d.commits.length} commits, ${d.threads.length} discussions, ${d.symbols.length} symbols, ${d.sources.length} stated sources`,+ );++ const sent = await pushDigest(link, d);+ if ("error" in sent) {+ console.error(`✗ ${sent.error}`);+ process.exitCode = 1;+ return;+ }+ console.error(`✓ sent ${d.owner}/${d.name} to brain ${link.brainId}`);+ console.error("· the brain is mining it now; `graft brain pull` once it finishes to get the rules back");+ });++brain+ .command("status")+ .description("Show the attached brain, how many rules are cached, and how many still match the code")+ .argument("[dir]", "target repo directory", ".")+ .option("--json", "machine-readable output")+ .action((dir: string, opts: { json?: boolean }) => {+ const repo = resolve(dir);+ const { link, rules, fetchedAt } = brainStatus(repo);+ // Resolve every cached rule against the CURRENT graph, so the count of stale+ // rules is the real one rather than what was true at pull time. This is the+ // number worth surfacing: it says how far the codebase has drifted from what+ // the team decided.+ const graph = loadGraphCached(contextDirFor(repo, program.opts<GlobalOpts>().dir));+ const applied = rulesForPointers(+ (graph?.nodes ?? []).map((n) => `${n.path}:${n.span}`),+ rules,+ graph,+ );+ if (opts.json) {+ console.log(JSON.stringify({ brainId: link?.brainId ?? null, cached: rules.length, fetchedAt, anchored: applied.length, stale: applied.filter((a) => a.stale).length }, null, 2));+ return;+ }+ if (!link) {+ console.error("· no brain attached — run `graft brain connect <brainId>:<token>`");+ return;+ }+ console.error(`brain ${link.brainId}`);+ console.error(` ${rules.length} rule(s) cached${fetchedAt ? `, pulled ${new Date(fetchedAt).toISOString()}` : ""}`);+ if (!graph) {+ console.error(" no graph yet — run `graft build` to see which rules still match the code");+ return;+ }+ const stale = applied.filter((a) => a.stale);+ console.error(` ${applied.length} anchored to symbols in this repo`);+ console.error(+ stale.length+ ? ` ${stale.length} describe code that has changed since:`+ : " none describe code that has changed since",+ );+ for (const a of stale.slice(0, 10)) console.error(` - ${a.rule}\n ${a.pointer}`);+ });++brain+ .command("disconnect")+ .description("Forget the attached brain (its rules stay in the instruction files until the next init)")+ .argument("[dir]", "target repo directory", ".")+ .action((dir: string) => {+ const repo = resolve(dir);+ clearLink(resolve(dir));+ console.error(`✓ detached the brain from ${repo}`);+ });+program.parseAsync().catch((err) => {console.error(err instanceof Error ? err.message : err);process.exit(1);diff --git a/src/hosts/retract.ts b/src/hosts/retract.tsindex 8cb7b8a8..801c5aa9 100644--- a/src/hosts/retract.ts+++ b/src/hosts/retract.ts@@ -27,7 +27,7 @@ import { readFileSync, writeFileSync, existsSync, rmSync, rmdirSync, statSync, rimport { join, dirname } from 'node:path';import { homedir } from 'node:os';import { HOSTS } from './registry.js';-import { START, END } from './sections.js';+import { ALL_MARKERS, type Markers } from './sections.js';import { mcpTargets, stripTomlSection } from './mcp-config.js';import { hookTargets } from './codex-hooks.js';import { antigravitySkillTargets } from './antigravity.js';@@ -130,19 +130,27 @@ function pruneEmptyDirs(dir: string): void {* blank line, so a file that had prose either side of the block reads exactly* as it did before graft appended to it.*/-function stripSection(path: string, apply: boolean): RetractAction {+function stripSection(path: string, apply: boolean, markers: Markers[] = ALL_MARKERS): RetractAction {if (!existsSync(path)) return 'absent';const text = readFileSync(path, 'utf8');- if (!text.includes(START)) return 'absent';+ // Every region graft may own, not just the instruction block. A file can hold+ // both the instructions and a brain's rules, and leaving one behind would+ // strand rules in a repo the user has uninstalled graft from.+ if (!markers.some((m) => text.includes(m.start))) return 'absent';const eol = text.includes('\r\n') ? '\r\n' : '\n';const lines = text.split(/\r\n|\n/);const out: string[] = [];- let inside = false;+ let closing: string | null = null;let found = false;for (const line of lines) {const t = line.trim();- if (!inside && t === START) { inside = true; found = true; continue; }- if (inside) { if (t === END) inside = false; continue; }+ if (closing === null) {+ const open = markers.find((m) => m.start === t);+ if (open) { closing = open.end; found = true; continue; }+ } else {+ if (t === closing) closing = null;+ continue;+ }out.push(line);}if (!found) return 'absent';diff --git a/src/hosts/sections.ts b/src/hosts/sections.tsindex fef0e21a..12dd2ed3 100644--- a/src/hosts/sections.ts+++ b/src/hosts/sections.ts@@ -8,15 +8,40 @@ import { dirname } from 'node:path';export const START = '<!-- graft:start -->';export const END = '<!-- graft:end -->';+/**+ * A brain's rules go in their OWN fenced block, not inside the instruction+ * block above.+ *+ * They have to be separately addressable: the instruction body is static and+ * rewritten by `init`, while rules change whenever the brain does and are+ * refreshed on their own. One pair of markers for both would mean every rules+ * refresh rewrites the instructions too, and `graft uninstall` could not remove+ * one without the other.+ */+export const BRAIN_START = '<!-- graft:brain:start -->';+export const BRAIN_END = '<!-- graft:brain:end -->';++/** One addressable managed region in a file the user owns. */+export interface Markers {+ start: string;+ end: string;+}++export const GRAFT_MARKERS: Markers = { start: START, end: END };+export const BRAIN_MARKERS: Markers = { start: BRAIN_START, end: BRAIN_END };++/** Every managed region graft may own in a user-owned file. */+export const ALL_MARKERS: Markers[] = [GRAFT_MARKERS, BRAIN_MARKERS];+export type UpsertAction = 'created' | 'appended' | 'replaced' | 'unchanged';type LineEnding = '\n' | '\r\n';-export function fencedBlock(body: string, eol: LineEnding = '\n'): string {+export function fencedBlock(body: string, eol: LineEnding = '\n', markers: Markers = GRAFT_MARKERS): string {// Normalize any pre-existing '\r' out of the body first so callers passing// a CRLF (or stray-CR) body never get doubled '\r' when eol is '\r\n'.const normalizedBody = body.replace(/\r/g, '');- const block = `${START}\n${normalizedBody.replace(/\s+$/, '')}\n${END}`;+ const block = `${markers.start}\n${normalizedBody.replace(/\s+$/, '')}\n${markers.end}`;return eol === '\n' ? block : block.replace(/\n/g, '\r\n');}@@ -33,9 +58,9 @@ function markerLineIndex(lines: string[], marker: string, from = 0): number {return -1;}-export function upsertSection(filePath: string, body: string): { action: UpsertAction } {+export function upsertSection(filePath: string, body: string, markers: Markers = GRAFT_MARKERS): { action: UpsertAction } {if (!existsSync(filePath)) {- const block = fencedBlock(body);+ const block = fencedBlock(body, '\n', markers);mkdirSync(dirname(filePath), { recursive: true });writeFileSync(filePath, `${block}\n`);return { action: 'created' };@@ -49,17 +74,17 @@ export function upsertSection(filePath: string, body: string): { action: UpsertA// trailing-'\r' element sat next to a '\n' join, e.g. right after END, or// when the block was the entire file).const lines = text.split(/\r\n|\n/);- const s = markerLineIndex(lines, START);- const e = s === -1 ? -1 : markerLineIndex(lines, END, s + 1);+ const s = markerLineIndex(lines, markers.start);+ const e = s === -1 ? -1 : markerLineIndex(lines, markers.end, s + 1);if (s !== -1 && e !== -1) {const current = lines.slice(s, e + 1).join('\n');- if (current === fencedBlock(body)) return { action: 'unchanged' };- const block = fencedBlock(body, eol);+ if (current === fencedBlock(body, '\n', markers)) return { action: 'unchanged' };+ const block = fencedBlock(body, eol, markers);const next = [...lines.slice(0, s), ...block.split(eol), ...lines.slice(e + 1)];writeFileSync(filePath, next.join(eol));return { action: 'replaced' };}- const block = fencedBlock(body, eol);+ const block = fencedBlock(body, eol, markers);const doubleEol = eol + eol;const sep = text.endsWith(doubleEol) ? '' : text.endsWith(eol) ? eol : doubleEol;writeFileSync(filePath, `${text}${sep}${block}${eol}`);diff --git a/src/util/state.ts b/src/util/state.tsindex ae0d7105..3c4aec17 100644--- a/src/util/state.ts+++ b/src/util/state.ts@@ -102,6 +102,11 @@ export interface BuildConfig {* checkout someone parked in the tree. Absent/false keeps the historical* boundary. */followNestedRepos?: boolean;+ /** The Trail brain this repo's rules come from: the brain id and the token to+ * read it with. Persisted here — in the git-ignored `.graft/` — rather than in+ * `~/.graft/`, because a brain belongs to one repository and two checkouts on+ * one machine must not share one. `undefined` clears it. */+ brain?: { brainId: string; token: string; baseUrl?: string };}/** Local, Git-ignored repository configuration. Kept outside generated