Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

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/.gitignore
index 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.md
index 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 on
repository** (or org-owner for an org-wide install) — the one thing an App does
not 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. |
+
## Security
The 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 unknown
page and a bad token are both `404`, so the endpoint cannot be used to
discover 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 yet
diff --git a/src/app/brain-build.ts b/src/app/brain-build.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 @@ program
wireTarget(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.ts
index 8cb7b8a8..801c5aa9 100644
--- a/src/hosts/retract.ts
+++ b/src/hosts/retract.ts
@@ -27,7 +27,7 @@ import { readFileSync, writeFileSync, existsSync, rmSync, rmdirSync, statSync, r
import { 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.ts
index 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.ts
index 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