Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
feat(brain): hold the push until the brain is built, and land the browser on it (#422)
anirudhkumar-nanonets8c05769618d4
diff --git a/src/brain/link.ts b/src/brain/link.tsindex f23b75a3..a432e605 100644--- a/src/brain/link.ts+++ b/src/brain/link.ts@@ -14,6 +14,8 @@*/import { readBuildConfig, patchBuildConfig, cacheDir, readJson, writeJsonAtomic } from '../util/state.js';import { join } from 'node:path';+import { ensureGitignored, LINK_NOTE } from '../context/node-file.js';+import { BUILD_CONFIG_DIR } from '../util/state.js';/** Default API host. Overridden by GRAFT_BRAIN_URL, for staging and self-hosted. */const DEFAULT_BRAIN_BASE_URL = 'https://agents.nanonets.com';@@ -83,9 +85,17 @@ export function readLink(dir: string): BrainLink | null {return stored;}-/** Persist the link for repo `dir`, merging into any existing build config. */+/** Persist the link for repo `dir`, merging into any existing build config.+ *+ * The write is what creates `.graft/config.json`, and that file holds the read+ * token — which is exactly why this is also where it gets ignored. The comment+ * on {@link BrainLink} has claimed `.graft/` was "git-ignored" since the day it+ * was written, and nothing ever made it true: `ensureGitignored` only ever ran+ * for the graph cache. Every repository anyone ran `graft brain connect` in was+ * therefore one `git add -A` away from publishing a credential. */export function writeLink(dir: string, link: BrainLink): void {patchBuildConfig(dir, { brain: link });+ ensureGitignored(dir, join(dir, BUILD_CONFIG_DIR), LINK_NOTE);}/** Forget the link for repo `dir`. Leaves the cached rules for `uninstall` to remove. */diff --git a/src/brain/signup.ts b/src/brain/signup.tsindex 6cc0e86a..d27faf28 100644--- a/src/brain/signup.ts+++ b/src/brain/signup.ts@@ -181,12 +181,19 @@ export function webBaseUrl(baseUrl?: string): string {/** Where the browser is sent once the handoff has been accepted.*- * Back into Trail, at the brain it just made. The alternative — leaving the- * person on a local page that says "go back to your terminal" — ends the flow- * on a blank throwaway served by a port that is about to close, at exactly the- * moment the brain starts being mined and there is something to watch. */+ * Back into Trail, at the screen that shows the brain being built. The+ * alternative — leaving the person on a local page that says "go back to your+ * terminal" — ends the flow on a blank throwaway served by a port that is about+ * to close, at exactly the moment there is something to watch.+ *+ * NOT `/brain/<id>`, which is where this pointed first. That route redirects to+ * the brain's graph, and the redirect fires the instant the row exists — which+ * is minutes before it has any rules in it. Every terminal signup therefore+ * landed on an empty visualisation of a brain that was, at that moment, being+ * built perfectly well. The build screen is the same wait the browser-first+ * flow shows, and it leads to the graph once there is a graph. */export function brainUrl(brainId: string, baseUrl?: string): string {- return `${webBaseUrl(baseUrl)}/brain/${encodeURIComponent(brainId)}`;+ return `${webBaseUrl(baseUrl)}/get-started?step=build&brain=${encodeURIComponent(brainId)}`;}/** Where to send the browser for a repo's brain. */diff --git a/src/brain/watch.ts b/src/brain/watch.tsnew file mode 100644index 00000000..3e36648e--- /dev/null+++ b/src/brain/watch.ts@@ -0,0 +1,207 @@+/**+ * Watching a brain being built, from the terminal.+ *+ * `graft brain push` used to end at "it is being mined into rules now — a few+ * minutes. Watch it finish in your browser." and hand the prompt straight back.+ * That sentence is the last thing this process ever says about the work, and it+ * is said BEFORE the part that actually fails: of the repo brains attempted in+ * production, roughly a third die inside the miner, after the push succeeded.+ * The terminal has already returned by then, so on this side the failure does+ * not exist at all — and on a CI runner or over SSH, where nobody is going to+ * open a browser, it exists nowhere.+ *+ * So the push now holds the line and reports the same four stages the browser+ * shows, off the same row. Ctrl-C detaches without cancelling anything, because+ * the work is server-side and killing a watcher must never look like killing+ * the build.+ */+import type { BrainLink } from "./link.js";+import { baseUrlFor } from "./link.js";++/** The stages, in the order they happen. The wording matches Trail's build+ * screen deliberately: two products describing one process differently is how+ * a person ends up unsure whether they are looking at the same thing. */+export const STAGES = [+ { id: "reach", label: "reaching the repository" },+ { id: "read", label: "reading its history" },+ { id: "mine", label: "mining the rules" },+ { id: "file", label: "filing them into the brain" },+] as const;++export type StageId = (typeof STAGES)[number]["id"];+export type StageState = "waiting" | "doing" | "done" | "failed";++export interface Stage {+ id: StageId;+ label: string;+ state: StageState;+ /** A count worth printing beside a stage that has produced one. */+ detail?: string;+}++/** The repo row, as the public endpoint returns it. Only the fields the stages+ * read, so a field added server-side cannot quietly change what is printed. */+export interface RepoState {+ status: string;+ errorMessage?: string;+ ruleCount: number;+ commitCount: number;+ threadCount: number;+}++export interface BuildView {+ stages: Stage[];+ done: boolean;+ /** The server's own words, when it failed. */+ error: string | null;+}++const num = (v: unknown): number => (typeof v === "number" && v > 0 ? v : 0);++/**+ * Which stage the work is in.+ *+ * The rule that matters is where a failure lands. A row that never left+ * `pending` failed at the access check; one that read 412 commits and then died+ * failed in the miner. Reporting both as "could not reach it" would send someone+ * to fix repository access for a problem that has nothing to do with it.+ */+export function stagesFrom(repo: RepoState | null): BuildView {+ const commits = num(repo?.commitCount);+ const threads = num(repo?.threadCount);+ const rules = num(repo?.ruleCount);++ const reached = !!repo && repo.status !== "pending";+ const readIt = commits > 0 || threads > 0;+ const filed = rules > 0;+ const failed = repo?.status === "failed";++ const failedAt: StageId | null = !failed ? null : !reached || !readIt ? "reach" : !filed ? "mine" : "file";++ const order = STAGES.map((s) => s.id);+ const state = (id: StageId): StageState => {+ if (failedAt === id) return "failed";+ if (failedAt && order.indexOf(id) > order.indexOf(failedAt)) return "waiting";+ switch (id) {+ case "reach":+ return reached ? "done" : "doing";+ case "read":+ return readIt ? "done" : reached ? "doing" : "waiting";+ case "mine":+ return filed ? "done" : readIt ? "doing" : "waiting";+ case "file":+ return filed ? "done" : readIt ? "doing" : "waiting";+ }+ };++ const detail = (id: StageId): string | undefined => {+ if (id === "read" && (commits || threads)) {+ return [commits ? `${commits} commits` : null, threads ? `${threads} discussions` : null].filter(Boolean).join(", ");+ }+ if (id === "file" && rules) return `${rules} rules`;+ return undefined;+ };++ return {+ stages: STAGES.map((s) => ({ id: s.id, label: s.label, state: state(s.id), detail: detail(s.id) })),+ done: repo?.status === "completed" && filed,+ error: failed ? (repo?.errorMessage?.trim() || "the read stopped before it finished") : null,+ };+}++/**+ * Read the repo row this brain is building.+ *+ * The same endpoint `fetchExpectedRepo` uses, read for its counts rather than+ * its slug. Null on any failure, so a watcher that cannot reach the API prints+ * nothing new rather than inventing a failure the build did not have.+ */+export async function fetchRepoState(link: BrainLink, fetchImpl: typeof fetch = fetch): Promise<RepoState | null> {+ try {+ const res = await fetchImpl(`${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/repo`, {+ headers: { authorization: `Bearer ${link.token}`, accept: "application/json" },+ signal: AbortSignal.timeout(5000),+ });+ if (!res.ok) return null;+ const body = (await res.json()) as {+ repo?: { status?: string; error_message?: string; rule_count?: number; commit_count?: number; thread_count?: number } | null;+ };+ if (!body.repo) return null;+ return {+ status: String(body.repo.status ?? ""),+ errorMessage: body.repo.error_message,+ ruleCount: num(body.repo.rule_count),+ commitCount: num(body.repo.commit_count),+ threadCount: num(body.repo.thread_count),+ };+ } catch {+ return null;+ }+}++/** One printable line per stage that has moved since it was last printed. */+export function linesFor(view: BuildView, already: Set<string>): string[] {+ const out: string[] = [];+ for (const s of view.stages) {+ // Only settled states are printed. A line per poll for a stage that is+ // merely still running would bury the four that matter under a hundred+ // that do not — this is a log, not a redrawn frame.+ if (s.state !== "done" && s.state !== "failed") continue;+ const key = `${s.id}:${s.state}`;+ if (already.has(key)) continue;+ already.add(key);+ const mark = s.state === "done" ? "✓" : "✗";+ out.push(` ${mark} ${s.label}${s.detail ? ` — ${s.detail}` : ""}`);+ }+ return out;+}++export interface WatchOptions {+ /** How long to hold before giving up on a build that is still running. */+ timeoutMs?: number;+ pollMs?: number;+ fetchImpl?: typeof fetch;+ /** Where the lines go. Injected so the tests do not need a console. */+ write?: (line: string) => void;+ sleep?: (ms: number) => Promise<void>;+}++export type WatchOutcome = "completed" | "failed" | "timed_out" | "unreachable";++/**+ * Hold until the brain is built, printing each stage as it settles.+ *+ * Fifteen minutes by default: a large repository's mining is minutes of work,+ * and a watcher that gives up before the build does would report a healthy+ * build as a timeout — the exact confusion this is meant to remove. Giving up+ * says so and says the work continues, because it does.+ */+export async function watchBuild(link: BrainLink, opts: WatchOptions = {}): Promise<WatchOutcome> {+ const timeoutMs = opts.timeoutMs ?? 15 * 60 * 1000;+ const pollMs = opts.pollMs ?? 4000;+ const write = opts.write ?? ((l: string) => console.error(l));+ const sleep = opts.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms).unref?.()));++ const printed = new Set<string>();+ const startedAt = Date.now();+ // A row we could never read at all, as opposed to one that answered once and+ // then stopped answering: the first is a broken link or a host that is down+ // and is worth saying, the second is a blip the next poll usually covers.+ let everRead = false;++ for (;;) {+ const repo = await fetchRepoState(link, opts.fetchImpl);+ if (repo) {+ everRead = true;+ const view = stagesFrom(repo);+ for (const line of linesFor(view, printed)) write(line);+ if (view.error) {+ write(`✗ ${view.error}`);+ return "failed";+ }+ if (view.done) return "completed";+ }+ if (Date.now() - startedAt >= timeoutMs) return everRead ? "timed_out" : "unreachable";+ await sleep(pollMs);+ }+}diff --git a/src/cli.ts b/src/cli.tsindex 5f54f856..ef4eb5d8 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -22,6 +22,7 @@ import { rulesForPointers } from "./brain/attach.js";import { clearLink, type BrainLink } from "./brain/link.js";import { buildLocalDigest, fetchExpectedRepo, pushDigest, repoSlugFromGit, sameRepo } from "./brain/push.js";import { readLink, writeLink } from "./brain/link.js";+import { watchBuild } from "./brain/watch.js";import { openBrowser, signupUrl, startHandoff } from "./brain/signup.js";import { contextDirFor } from "./context/node-file.js";import { loadGraphCached } from "./graph/load.js";@@ -1348,7 +1349,8 @@ brain.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 }) => {+ .option("--no-watch", "return as soon as the push is sent, without following the build")+ .action(async (dir: string, opts: { approve?: boolean; watch?: boolean }) => {const repo = resolve(dir);// Resolved before the link, because an unlinked repo now signs up for a// brain and Trail creates that brain FOR a named repository. Without a slug@@ -1410,8 +1412,38 @@ brain}const brainLabel = expected?.brainName ? `“${expected.brainName}”` : link.brainId;console.error(`✓ sent ${d.owner}/${d.name} to ${brainLabel}`);- console.error("· it is being mined into rules now — a few minutes. Watch it finish in your browser.");- console.error(" The rules reach this repo on their own; nothing else to run.");++ // Held rather than handed back. Everything above this line succeeded even+ // in the runs that end badly: the push lands, and then the miner fails —+ // which is where roughly a third of production's repo brains die. Returning+ // the prompt here is what made that invisible from this side, on CI and+ // over SSH permanently so. `--no-watch` is for a caller that genuinely+ // wants fire-and-forget, and it prints the old two lines instead.+ if (opts.watch === false) {+ console.error("· it is being mined into rules now — a few minutes. Watch it finish in your browser.");+ console.error(" The rules reach this repo on their own; nothing else to run.");+ return;+ }++ console.error("· building the brain — Ctrl-C detaches, it keeps going without you");+ const outcome = await watchBuild(link);+ if (outcome === "completed") {+ console.error("✓ the brain is built — its rules reach this repo on their own; nothing else to run");+ return;+ }+ if (outcome === "failed") {+ // A non-zero exit, unlike every other ending here: this is the one case+ // where the work did not produce a brain, and a CI step that ran the push+ // should hear about it the way it hears about any other failure.+ console.error(" Nothing was lost — the brain is still there. Run `graft brain push` again to retry the read.");+ process.exitCode = 1;+ return;+ }+ if (outcome === "unreachable") {+ console.error("· could not reach Trail to follow the build — it is still running. Watch it finish in your browser.");+ return;+ }+ console.error("· still building after 15 minutes — it has not failed, it is just long. Watch it finish in your browser.");});braindiff --git a/src/context/node-file.ts b/src/context/node-file.tsindex 3162069d..c86c883e 100644--- a/src/context/node-file.ts+++ b/src/context/node-file.ts@@ -120,7 +120,13 @@ export function contextDirFor(root: string, override?: string): string {* expressed as a repo-relative ignore). Best-effort: an unwritable `.gitignore`* must never abort a build, so write failures are swallowed.*/-export function ensureGitignored(root: string, contextDir: string): void {+const GRAPH_CACHE_NOTE = "graft's local graph cache — regenerable, not committed (run `graft build`).";++/** Why `.graft/` is ignored, which is a different reason: not that it is cheap+ * to regenerate, but that it holds a token. */+export const LINK_NOTE = "graft's brain link — holds a read token, never commit it.";++export function ensureGitignored(root: string, contextDir: string, note = GRAPH_CACHE_NOTE): void {if (envTruthy("GRAFT_NO_GITIGNORE")) return;const rel = relPosix(root, contextDir);if (rel === "" || rel.startsWith("..")) return; // dir is at/above the repo root — nothing sane to ignore@@ -141,7 +147,7 @@ export function ensureGitignored(root: string, contextDir: string): void {});if (present) return;const gap = current === "" ? "" : current.endsWith("\n") ? "\n" : "\n\n";- const block = `${gap}# graft's local graph cache — regenerable, not committed (run \`graft build\`).\n${entry}\n`;+ const block = `${gap}# ${note}\n${entry}\n`;try { writeFileSync(path, current + block); } catch { /* best-effort — build already succeeded */ }}diff --git a/test/brain-signup.test.ts b/test/brain-signup.test.tsindex d368f5b7..1561f14c 100644--- a/test/brain-signup.test.ts+++ b/test/brain-signup.test.ts@@ -94,7 +94,12 @@ test("signup url: GRAFT_BRAIN_URL points signup at staging too", () => {// The browser's last stop is Trail, not a local page that is about to stop// answering. Ending on "go back to your terminal" wasted the one moment the// brain is actually being built and there is something on screen worth seeing.-test('the accepted handoff sends the browser back into Trail, at its new brain', async () => {+//+// And specifically the BUILD screen, not `/brain/<id>`, which is where this went+// first: that route redirects to the brain's graph the instant the row exists,+// which is minutes before it holds a single rule. So every terminal signup was+// landing on an empty visualisation of a brain that was building perfectly well.+test('the accepted handoff sends the browser to the build screen, not an empty graph', async () => {process.env.GRAFT_BRAIN_URL = 'http://localhost:5173';const handoff = await startHandoff();try {@@ -103,7 +108,7 @@ test('the accepted handoff sends the browser back into Trail, at its new brain',{ redirect: 'manual' },);assert.equal(res.status, 303);- assert.equal(res.headers.get('location'), 'http://localhost:5173/brain/abc-123');+ assert.equal(res.headers.get('location'), 'http://localhost:5173/get-started?step=build&brain=abc-123');const got = await handoff.wait(1000);assert.deepEqual(got, { link: { brainId: 'abc-123', token: 'gbt_1.xyz' } });} finally {diff --git a/test/brain-watch.test.ts b/test/brain-watch.test.tsnew file mode 100644index 00000000..3766680b--- /dev/null+++ b/test/brain-watch.test.ts@@ -0,0 +1,153 @@+/**+ * The push now holds the line instead of handing the prompt back, so what is+ * worth testing is the thing that made holding worthwhile: that a build which+ * dies is reported, and reported at the stage it actually died at.+ */+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { linesFor, stagesFrom, watchBuild, type RepoState } from '../src/brain/watch.js';+import { brainUrl } from '../src/brain/signup.js';++const row = (over: Partial<RepoState> = {}): RepoState => ({+ status: 'ingesting',+ ruleCount: 0,+ commitCount: 0,+ threadCount: 0,+ ...over,+});++const stateOf = (repo: RepoState | null, id: string) => stagesFrom(repo).stages.find((s) => s.id === id)?.state;++// --- where a failure lands ---------------------------------------------------++// The one that matters. A repo read successfully and then lost in the miner+// must not report itself as unreachable: that sends someone to fix repository+// access for a problem that has nothing to do with access.+test('a build that read the history and then died fails at the miner, not the access check', () => {+ const repo = row({+ status: 'failed',+ commitCount: 412,+ threadCount: 89,+ errorMessage: 'mine repository history: parse response: unexpected end of JSON input',+ });+ assert.equal(stateOf(repo, 'reach'), 'done');+ assert.equal(stateOf(repo, 'read'), 'done');+ assert.equal(stateOf(repo, 'mine'), 'failed');+ assert.match(stagesFrom(repo).error ?? '', /unexpected end of JSON input/);+});++test('a build that never read anything fails at the access check', () => {+ const repo = row({ status: 'failed', errorMessage: 'repo not accessible' });+ assert.equal(stateOf(repo, 'reach'), 'failed');+ assert.equal(stateOf(repo, 'mine'), 'waiting');+});++test('no stage after the failed one is left looking live', () => {+ const view = stagesFrom(row({ status: 'failed', commitCount: 10 }));+ const at = view.stages.findIndex((s) => s.state === 'failed');+ assert.ok(at >= 0);+ for (const s of view.stages.slice(at + 1)) assert.equal(s.state, 'waiting');+});++test('a failure with no message still says something', () => {+ assert.equal(stagesFrom(row({ status: 'failed' })).error, 'the read stopped before it finished');+});++test('done means the rules are in the brain, not just that the row closed', () => {+ assert.equal(stagesFrom(row({ status: 'completed', commitCount: 412, ruleCount: 0 })).done, false);+ assert.equal(stagesFrom(row({ status: 'completed', commitCount: 412, ruleCount: 42 })).done, true);+});++// --- what gets printed -------------------------------------------------------++// This is a log, not a redrawn frame: a line per poll for a stage that is merely+// still running would bury the four that matter under a hundred that do not.+test('only settled stages print, and each prints once', () => {+ const printed = new Set<string>();+ const first = linesFor(stagesFrom(row({ commitCount: 412, threadCount: 89 })), printed);+ assert.equal(first.length, 2, 'reach and read have settled; mine and file have not');+ assert.match(first[1], /412 commits, 89 discussions/);+ assert.deepEqual(linesFor(stagesFrom(row({ commitCount: 412, threadCount: 89 })), printed), [], 'nothing reprints');+ const later = linesFor(stagesFrom(row({ status: 'completed', commitCount: 412, threadCount: 89, ruleCount: 42 })), printed);+ assert.equal(later.length, 2, 'mine and file settle later and print then');+ assert.match(later.join('\n'), /42 rules/);+});++// --- the watcher ------------------------------------------------------------++/** A fetch that answers with each row in turn, then repeats the last. */+function fetchSeries(rows: (Record<string, unknown> | null)[]): typeof fetch {+ let i = 0;+ return (async () => {+ const repo = rows[Math.min(i++, rows.length - 1)];+ return { ok: true, json: async () => ({ repo }) } as unknown as Response;+ }) as unknown as typeof fetch;+}++const LINK = { brainId: '8f2a1c04-0000-0000-0000-000000000000', token: 'gbt_1.sig' };+const NOW = { timeoutMs: 60_000, pollMs: 0, sleep: async () => {} };++test('the watcher holds until the brain is built', async () => {+ const lines: string[] = [];+ const outcome = await watchBuild(LINK, {+ ...NOW,+ write: (l) => lines.push(l),+ fetchImpl: fetchSeries([+ { status: 'pending', rule_count: 0, commit_count: 0, thread_count: 0 },+ { status: 'ingesting', rule_count: 0, commit_count: 412, thread_count: 89 },+ { status: 'completed', rule_count: 42, commit_count: 412, thread_count: 89 },+ ]),+ });+ assert.equal(outcome, 'completed');+ assert.match(lines.join('\n'), /reaching the repository/);+ assert.match(lines.join('\n'), /42 rules/);+});++test('the watcher reports a failure rather than waiting out the clock', async () => {+ const lines: string[] = [];+ const outcome = await watchBuild(LINK, {+ ...NOW,+ write: (l) => lines.push(l),+ fetchImpl: fetchSeries([+ { status: 'ingesting', rule_count: 0, commit_count: 412, thread_count: 0 },+ { status: 'failed', rule_count: 0, commit_count: 412, thread_count: 0, error_message: 'repo job carries no history to mine' },+ ]),+ });+ assert.equal(outcome, 'failed');+ assert.match(lines.join('\n'), /carries no history to mine/);+});++// A host that is down must not be reported as a build that failed: one is our+// problem and the other is the user's, and they lead to opposite next steps.+test('a build it could never read is unreachable, not failed', async () => {+ const outcome = await watchBuild(LINK, {+ ...NOW,+ timeoutMs: 0,+ write: () => {},+ fetchImpl: (async () => {+ throw new Error('ECONNREFUSED');+ }) as unknown as typeof fetch,+ });+ assert.equal(outcome, 'unreachable');+});++test('a build still running when the clock runs out is a timeout, not a failure', async () => {+ const outcome = await watchBuild(LINK, {+ ...NOW,+ timeoutMs: 0,+ write: () => {},+ fetchImpl: fetchSeries([{ status: 'ingesting', rule_count: 0, commit_count: 1, thread_count: 0 }]),+ });+ assert.equal(outcome, 'timed_out');+});++// --- where the browser lands -------------------------------------------------++// /brain/<id> redirects to the graph, and it redirected the moment the row+// existed — minutes before it had any rules. Every terminal signup landed on an+// empty visualisation of a brain that was building perfectly well.+test('the handoff lands on the build screen, never on an empty graph', () => {+ const url = brainUrl('8f2a1c04-0000-0000-0000-000000000000', 'https://app.trailhq.com');+ assert.ok(!url.includes('/brain/'), 'must not go to the brain route, which redirects to the graph');+ assert.match(url, /\/get-started\?step=build&brain=8f2a1c04-0000-0000-0000-000000000000$/);+});