Skip to content

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

feat(trail): chunked upload, live watch and pull for all context files (#493)

anirudhkumar-nanonetse91e194df470
diff --git a/TELEMETRY.md b/TELEMETRY.md
index 3736ac0d..d00fc73a 100644
--- a/TELEMETRY.md
+++ b/TELEMETRY.md
@@ -47,7 +47,7 @@ The events:
| `build_failed` | `stage`, `code` — both fixed enums | A build throws |
| `query` | `command`, `surface` (`cli`/`mcp`/`hook`), `hit` (`ask` only) | Any query command |
| `brain_signup_opened` | — | `graft trail push` on a repo with no brain opens your browser to make one |
-| `brain_signup_settled` | `outcome` (`linked`/`timed_out`/`no_tty`/`bad_callback`), `duration_bucket` | That handoff ends, one way or the other |
+| `brain_signup_settled` | `outcome` (`linked`/`timed_out`/`no_tty`/`bad_callback`/`stopped`), `duration_bucket` | That handoff ends, one way or the other |
| `session_summary` | `graft_reads_bucket`, `source_reads_bucket`, `saved_tokens_bucket`, `graft_turns_bucket`, `reported_turns_bucket` | Once, after an agent session ends |
Two rules govern every value above, and both are enforced in code rather than by
diff --git a/src/app/history.ts b/src/app/history.ts
index b2677e06..71e13e83 100644
--- a/src/app/history.ts
+++ b/src/app/history.ts
@@ -127,11 +127,48 @@ export function readCommits(root: string, max = MAX_COMMITS): HistoryCommit[] {
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;
+ * request, so this is the real cost of a repository read. A pool of 24 (so at
+ * most 48 requests in flight) stays well under GitHub's secondary limit on
+ * concurrent requests, and a slow thread no longer holds up the seven that
+ * happened to share its batch. */
+export const THREAD_FETCH_CONCURRENCY = 24;
-interface PullListItem {
+/**
+ * What one push has already asked GitHub, shared between its reads.
+ *
+ * The early upload reads the newest pull requests and the full read reads them
+ * again as part of the 200. Promises rather than results, so a full read that
+ * starts while the early one is still in flight waits on the same request
+ * instead of sending a second — and threads with no discussion are remembered
+ * too, which a map of finished threads could not say.
+ */
+export interface ThreadReadCache {
+ /** Pages of the closed-pull-request list, by page number. */
+ pages: Map<number, Promise<PullListItem[] | null>>;
+ /** One pull request's discussion, by number; null when it had none. */
+ threads: Map<number, Promise<HistoryThread | null>>;
+}
+
+export function newThreadReadCache(): ThreadReadCache {
+ return { pages: new Map(), threads: new Map() };
+}
+
+/** Run `fn` over `items` with at most `limit` in flight, results in input order. */
+export async function mapPool<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]> {
+ const out = new Array<R>(items.length);
+ let next = 0;
+ const worker = async () => {
+ for (;;) {
+ const i = next++;
+ if (i >= items.length) return;
+ out[i] = await fn(items[i]!, i);
+ }
+ };
+ await Promise.all(Array.from({ length: Math.min(Math.max(1, limit), items.length) }, worker));
+ return out;
+}
+
+export interface PullListItem {
number?: number;
title?: string;
body?: string | null;
@@ -172,53 +209,79 @@ export async function readThreads(
// Threads already read (the early upload's newest ones), reused rather than
// fetched a second time.
known: ReadonlyMap<number, HistoryThread> = new Map(),
+ // Everything this push has already asked GitHub, in flight or finished. See
+ // ThreadReadCache; a fresh one when the caller has nothing to share.
+ cache: ThreadReadCache = newThreadReadCache(),
): Promise<HistoryThread[]> {
const headers = ghHeaders(token);
+ const readPage = (page: number): Promise<PullListItem[] | null> => {
+ const cached = cache.pages.get(page);
+ if (cached) return cached;
+ const pending = (async () => {
+ const res = await fetchImpl(
+ `${api}/repos/${owner}/${repo}/pulls?state=closed&sort=updated&direction=desc&per_page=100&page=${page}`,
+ { headers },
+ );
+ if (!res.ok) return null;
+ const batch = JSON.parse(await res.text()) as PullListItem[];
+ return Array.isArray(batch) ? batch : null;
+ })();
+ // A failed page is forgotten, so the next read asks again rather than
+ // inheriting one blip for the rest of the push.
+ pending.catch(() => cache.pages.delete(page));
+ cache.pages.set(page, pending);
+ return pending;
+ };
+
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;
+ const batch = await readPage(page);
+ if (!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);
+ // Deduplicated: a pull request updated between two page reads moves up the
+ // list and would otherwise be read, and sent, twice.
+ const seenNumbers = new Set<number>();
+ const candidates = pulls
+ .filter((p): p is PullListItem & { number: number } => typeof p.number === "number")
+ .filter((p) => !seenNumbers.has(p.number) && (seenNumbers.add(p.number), true))
+ .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 seen = known.get(p.number);
- if (seen) return seen;
- 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);
- }
+ const readThread = (p: PullListItem & { number: number }): Promise<HistoryThread | null> => {
+ const seen = known.get(p.number);
+ if (seen) return Promise.resolve(seen);
+ const cached = cache.threads.get(p.number);
+ if (cached) return cached;
+ const pending = (async () => {
+ 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;
+ })();
+ pending.catch(() => cache.threads.delete(p.number));
+ cache.threads.set(p.number, pending);
+ return pending;
+ };
+
+ // A pool 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 fetched = await mapPool(candidates, THREAD_FETCH_CONCURRENCY, readThread);
+ const threads: HistoryThread[] = fetched.filter((t): t is HistoryThread => t !== null);
// 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
diff --git a/src/app/sources.ts b/src/app/sources.ts
index a4365558..48017e10 100644
--- a/src/app/sources.ts
+++ b/src/app/sources.ts
@@ -87,11 +87,130 @@ export function readAgentInstructions(root: string): HistorySource[] {
".github/copilot-instructions.md",
".windsurf/rules/graft.md",
...filesIn(root, ".cursor/rules", (n) => n.endsWith(".mdc") || n.endsWith(".md")),
+ // The same files one folder down: a monorepo keeps its frontend's rules in
+ // web/CLAUDE.md, and those are as deliberate as the root's.
+ ...folderInstructionFiles(root),
+ // Skills a team wrote for its agents. Graft's own is left out for the same
+ // reason its managed blocks are: the brain must not learn graft from graft.
+ ...skillFiles(root),
];
const out: HistorySource[] = [];
+ const seen = new Set<string>();
for (const rel of candidates) {
+ const key = rel.replace(/\\/g, "/");
+ if (seen.has(key)) continue;
+ seen.add(key);
const text = stripManagedBlocks(readText(root, rel) ?? "");
- if (text.trim()) out.push({ kind: "agent_instructions", path: rel, text });
+ if (text.trim()) out.push({ kind: "agent_instructions", path: key, text });
+ }
+ return out;
+}
+
+/** Instruction files below the root that are worth reading as instructions. */
+const FOLDER_INSTRUCTION_NAMES = new Set(["CLAUDE.md", "AGENTS.md"]);
+/** How deep below the root a folder instruction file may sit (a/b/c/d/CLAUDE.md). */
+const MAX_FOLDER_DEPTH = 4;
+/** Most folder instruction files, and most skills, carried per push. */
+export const MAX_FOLDER_FILES = 30;
+export const MAX_SKILL_FILES = 30;
+
+/** Directories never searched for instruction files: dependencies, build
+ * output, graft's own cache. Dot-directories are skipped as a class. */
+const SKIP_INSTRUCTION_DIRS = new Set([
+ "node_modules",
+ "dist",
+ "build",
+ "out",
+ "vendor",
+ "graft",
+ "target",
+ "coverage",
+ "__pycache__",
+ "venv",
+ "bower_components",
+]);
+
+function skippedSegment(seg: string): boolean {
+ return seg.startsWith(".") || SKIP_INSTRUCTION_DIRS.has(seg);
+}
+
+/**
+ * `**\/CLAUDE.md` and `**\/AGENTS.md` below the root, shallowest first.
+ *
+ * Asked of git first, because git already knows what the repository ignores:
+ * a CLAUDE.md inside an ignored folder is someone's scratch, not the team's.
+ * The walk is the fallback for a checkout git cannot answer for.
+ */
+export function folderInstructionFiles(root: string, max = MAX_FOLDER_FILES): string[] {
+ const keep = (rel: string): boolean => {
+ const parts = rel.split("/");
+ const name = parts[parts.length - 1] ?? "";
+ const dirs = parts.slice(0, -1);
+ if (!FOLDER_INSTRUCTION_NAMES.has(name)) return false;
+ if (dirs.length === 0 || dirs.length > MAX_FOLDER_DEPTH) return false;
+ return !dirs.some(skippedSegment);
+ };
+ let found: string[] | null = null;
+ const listed = git(root, ["ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", "*CLAUDE.md", "*AGENTS.md"]);
+ if (listed !== null) found = [...new Set(listed.split("\0").filter(Boolean))].filter(keep);
+ if (found === null) found = walkFor(root, keep);
+ const depth = (p: string) => p.split("/").length;
+ return found
+ .filter((rel) => existsSync(join(root, rel)))
+ .sort((a, b) => depth(a) - depth(b) || a.localeCompare(b))
+ .slice(0, max);
+}
+
+/** The filesystem walk behind folderInstructionFiles, for a tree git cannot list. */
+function walkFor(root: string, keep: (rel: string) => boolean): string[] {
+ const out: string[] = [];
+ const visit = (rel: string, depth: number) => {
+ if (depth > MAX_FOLDER_DEPTH) return;
+ let names: string[];
+ try {
+ names = readdirSync(join(root, rel));
+ } catch {
+ return;
+ }
+ for (const name of names) {
+ const child = rel ? `${rel}/${name}` : name;
+ let isDir = false;
+ try {
+ isDir = statSync(join(root, child)).isDirectory();
+ } catch {
+ continue;
+ }
+ if (isDir) {
+ if (!skippedSegment(name)) visit(child, depth + 1);
+ } else if (depth > 0 && keep(child)) {
+ out.push(child);
+ }
+ }
+ };
+ visit("", 0);
+ return out;
+}
+
+/** `.claude/skills/<name>/SKILL.md`, graft's own skill excluded. */
+export function skillFiles(root: string, max = MAX_SKILL_FILES): string[] {
+ const dir = join(root, ".claude", "skills");
+ let names: string[];
+ try {
+ names = readdirSync(dir).sort();
+ } catch {
+ return [];
+ }
+ const out: string[] = [];
+ for (const name of names) {
+ if (name === "graft" || name.startsWith(".")) continue;
+ const rel = `.claude/skills/${name}/SKILL.md`;
+ try {
+ if (!statSync(join(root, rel)).isFile()) continue;
+ } catch {
+ continue;
+ }
+ out.push(rel);
+ if (out.length >= max) break;
}
return out;
}
diff --git a/src/brain/claude-md.ts b/src/brain/claude-md.ts
index 0aeb132a..8267861e 100644
--- a/src/brain/claude-md.ts
+++ b/src/brain/claude-md.ts
@@ -1,6 +1,7 @@
/**
- * `graft claude-md pull`: write the CLAUDE.md changes accepted in Trail into
- * this checkout's instruction file.
+ * The CLAUDE.md half of `graft trail pull` (and of `graft claude-md pull`, its
+ * old name): write the CLAUDE.md changes accepted in Trail into this checkout's
+ * instruction file.
*
* Trail compares the repository's CLAUDE.md with what its history says and
* suggests edits and new sections; a person accepts some of them on the brain's
@@ -50,7 +51,7 @@ export interface ApplyResult {
export async function fetchAcceptedChanges(
link: BrainLink,
fetchImpl: typeof fetch = fetch,
-): Promise<ClaudeMdPull | { error: string }> {
+): Promise<ClaudeMdPull | { error: string; unsupported?: boolean }> {
const url = `${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/claude-md`;
try {
const res = await fetchImpl(url, {
@@ -59,7 +60,7 @@ export async function fetchAcceptedChanges(
});
const body = await res.text();
if (res.status === 404 || res.status === 503) {
- return { error: "this brain has no CLAUDE.md suggestions yet — its Trail may be older than the feature" };
+ return { error: "this trail has no CLAUDE.md suggestions yet — its Trail may be older than the feature", unsupported: true };
}
if (!res.ok) return { error: `Trail refused the pull: ${res.status} ${body.slice(0, 200)}` };
const parsed = JSON.parse(body) as Partial<ClaudeMdPull>;
diff --git a/src/brain/context-files.ts b/src/brain/context-files.ts
new file mode 100644
index 00000000..c727c074
--- /dev/null
+++ b/src/brain/context-files.ts
@@ -0,0 +1,281 @@
+/**
+ * `graft trail pull`, for every context file rather than only the root CLAUDE.md.
+ *
+ * Trail suggests changes to the files a repository hands its coding agents —
+ * AGENTS.md, a folder's own CLAUDE.md, Cursor rules, Claude skills — and a
+ * person accepts some of them. This fetches the accepted ones and writes them.
+ *
+ * Edits and new sections go through the same line-by-line patcher as the root
+ * CLAUDE.md (see claude-md.ts), so everything a change does not name comes back
+ * byte for byte. A `create` carries a whole file, and it is never allowed to
+ * overwrite a file someone wrote here: an existing file with other content is a
+ * conflict to report, unless graft itself owns that file. A `replace` (how a
+ * Cursor rule is edited) carries the whole new file and the whole file it was
+ * computed against, and is written only while the file here is still that one.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
+import { applyChanges, type ClaudeMdChange } from "./claude-md.js";
+import { baseUrlFor, type BrainLink } from "./link.js";
+
+export type ContextFileKind = "agents_md" | "folder_claude_md" | "cursor_rule" | "skill";
+
+/** One accepted change to one context file. */
+export interface ContextFileChange {
+ id: string;
+ kind: "edit" | "add" | "create" | "replace";
+ heading?: string;
+ after_heading?: string;
+ find?: string;
+ /** edit/add: as in claude-md.ts. create/replace: the whole file. For
+ * replace, `find` is the whole file the suggestion was computed against. */
+ text: string;
+ reason?: string;
+}
+
+export interface ContextFile {
+ kind: ContextFileKind | string;
+ path: string;
+ exists?: boolean;
+ managed_by_graft?: boolean;
+ changes: ContextFileChange[];
+}
+
+export interface ContextFilesPull {
+ head_sha: string;
+ files: ContextFile[];
+}
+
+/**
+ * Which picked agents read a file of this kind. A file whose readers were not
+ * picked is neither listed nor written: `graft init` is where someone said which
+ * agents this repo is for, and a pull must not quietly add files for others.
+ */
+const READERS: Record<string, string[]> = {
+ claude_md: ["claude"],
+ folder_claude_md: ["claude"],
+ skill: ["claude"],
+ agents_md: ["agents", "hermes", "antigravity"],
+ cursor_rule: ["cursor"],
+};
+
+/** The kind of a context file, from its path — for the root CLAUDE.md pull,
+ * which names a path but no kind. */
+export function kindForPath(path: string): string {
+ const p = path.replace(/\\/g, "/");
+ const name = p.split("/").pop() ?? "";
+ if (name === "CLAUDE.md") return p.includes("/") ? "folder_claude_md" : "claude_md";
+ if (name === "AGENTS.md") return "agents_md";
+ if (p.startsWith(".cursor/rules/")) return "cursor_rule";
+ if (p.startsWith(".claude/skills/")) return "skill";
+ return "";
+}
+
+/**
+ * Whether a file of `kind` is for one of the `wired` agents. Everything passes
+ * when nothing is wired — there is no choice to respect — and so does a kind
+ * graft does not know, rather than dropping what Trail sent.
+ */
+export function readByWired(kind: string, wired: readonly string[]): boolean {
+ if (wired.length === 0) return true;
+ const readers = READERS[kind];
+ if (!readers) return true;
+ return readers.some((r) => wired.includes(r));
+}
+
+/** The agents among `wired` that read a file of `kind`. */
+export function readersOf(kind: string, wired: readonly string[]): string[] {
+ const readers = READERS[kind] ?? [];
+ return wired.filter((w) => readers.includes(w));
+}
+
+/** GET /api/public/brains/:id/context-files. `unsupported` on a 404: an older Trail. */
+export async function fetchContextFiles(
+ link: BrainLink,
+ fetchImpl: typeof fetch = fetch,
+): Promise<ContextFilesPull | { unsupported: true } | { error: string }> {
+ const url = `${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/context-files`;
+ try {
+ const res = await fetchImpl(url, {
+ headers: { authorization: `Bearer ${link.token}`, accept: "application/json" },
+ signal: AbortSignal.timeout(15_000),
+ });
+ const body = await res.text();
+ if (res.status === 404) return { unsupported: true };
+ if (!res.ok) return { error: `Trail refused the pull: ${res.status} ${body.slice(0, 200)}` };
+ const parsed = JSON.parse(body) as Partial<ContextFilesPull>;
+ const files = Array.isArray(parsed.files) ? parsed.files : [];
+ return {
+ head_sha: String(parsed.head_sha ?? ""),
+ files: files
+ .filter((f) => f && typeof f.path === "string")
+ .map((f) => ({ ...f, changes: Array.isArray(f.changes) ? f.changes : [] })),
+ };
+ } catch (e) {
+ return { error: `could not reach Trail: ${e instanceof Error ? e.message : e}` };
+ }
+}
+
+/** POST /api/public/brains/:id/context-files/applied, 100 ids per request. */
+export async function markContextFilesApplied(link: BrainLink, ids: string[], fetchImpl: typeof fetch = fetch): Promise<boolean> {
+ if (ids.length === 0) return true;
+ const url = `${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/context-files/applied`;
+ try {
+ for (let i = 0; i < ids.length; i += 100) {
+ const res = await fetchImpl(url, {
+ method: "POST",
+ headers: {
+ authorization: `Bearer ${link.token}`,
+ "content-type": "application/json",
+ accept: "application/json",
+ },
+ body: JSON.stringify({ ids: ids.slice(i, i + 100) }),
+ signal: AbortSignal.timeout(15_000),
+ });
+ if (!res.ok) return false;
+ }
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+/** What a pull will do (or did) to one file. */
+export interface FilePlan {
+ /** Repo-relative, forward slashes. */
+ path: string;
+ /** M: an existing file changes. A: a new file. "": nothing to write. */
+ status: "M" | "A" | "";
+ /** The file's new text, when status is set. */
+ text?: string;
+ written: ContextFileChange[];
+ /** Already there: counts as applied, nothing to write. */
+ present: ContextFileChange[];
+ skipped: Array<{ change: ContextFileChange; why: string }>;
+}
+
+/**
+ * The repo-relative form of a path Trail sent, or null when it points
+ * anywhere but a file inside this checkout. Trail is trusted to suggest text,
+ * not to choose where on this machine it lands.
+ */
+export function safeRelPath(root: string, path: string): string | null {
+ const raw = path.replace(/\\/g, "/").trim();
+ if (!raw || isAbsolute(raw) || /^[a-zA-Z]:/.test(raw)) return null;
+ const parts = raw.split("/");
+ if (parts.some((p) => p === ".." || p === "")) return null;
+ if (parts[0] === ".git") return null;
+ const abs = resolve(root, normalize(raw));
+ const rel = relative(resolve(root), abs);
+ if (!rel || rel.startsWith("..") || isAbsolute(rel)) return null;
+ return rel.split(sep).join("/");
+}
+
+/**
+ * Work out one file's changes against what is on disk. Pure but for reading
+ * the file, so the command, the dry run and the tests share it.
+ */
+export function planContextFile(root: string, file: ContextFile): FilePlan {
+ const rel = safeRelPath(root, file.path);
+ const plan: FilePlan = { path: rel ?? file.path, status: "", written: [], present: [], skipped: [] };
+ if (!rel) {
+ for (const c of file.changes) plan.skipped.push({ change: c, why: "the path points outside this repo" });
+ return plan;
+ }
+ const abs = join(root, rel);
+ const existed = existsSync(abs);
+ let original = "";
+ if (existed) {
+ try {
+ original = readFileSync(abs, "utf8");
+ } catch {
+ for (const c of file.changes) plan.skipped.push({ change: c, why: "the file here could not be read" });
+ return plan;
+ }
+ }
+
+ let text = original;
+ let changed = false;
+ // Whole files first; the edits and sections after them may be relative to one.
+ for (const c of file.changes.filter((x) => x.kind === "create")) {
+ const want = c.text.replace(/\r\n/g, "\n");
+ const have = text.replace(/\r\n/g, "\n");
+ if (!existed && !changed) {
+ text = c.text.endsWith("\n") ? c.text : `${c.text}\n`;
+ changed = true;
+ plan.written.push(c);
+ } else if (have.trimEnd() === want.trimEnd()) {
+ plan.present.push(c);
+ } else if (file.managed_by_graft) {
+ text = c.text.endsWith("\n") ? c.text : `${c.text}\n`;
+ changed = true;
+ plan.written.push(c);
+ } else {
+ plan.skipped.push({ change: c, why: "a file with other content is already there" });
+ }
+ }
+
+ // Whole-file replacements, guarded by the text they were computed against.
+ const same = (a: string, b: string) => a.replace(/\r\n/g, "\n").trimEnd() === b.replace(/\r\n/g, "\n").trimEnd();
+ for (const c of file.changes.filter((x) => x.kind === "replace")) {
+ if (same(text, c.text)) {
+ plan.present.push(c);
+ } else if (same(text, c.find ?? "") && (existed || changed || (c.find ?? "").trim() === "")) {
+ text = c.text.endsWith("\n") ? c.text : `${c.text}\n`;
+ changed = true;
+ plan.written.push(c);
+ } else {
+ plan.skipped.push({ change: c, why: "the file changed here since Trail read it" });
+ }
+ }
+
+ const patches = file.changes.filter((x) => x.kind === "edit" || x.kind === "add");
+ if (patches.length > 0) {
+ // A file that is not here yet is an empty one: an edit to a section of it
+ // becomes that section, so the change lands rather than being skipped for
+ // a heading nobody could have written.
+ const fresh = !existed && !changed;
+ const r = applyChanges(
+ text,
+ patches.map(
+ (c) =>
+ ({
+ ...c,
+ heading: c.heading ?? "",
+ kind: fresh && c.kind === "edit" ? "add" : c.kind,
+ ...(fresh && c.kind === "edit" ? { after_heading: "" } : {}),
+ }) as ClaudeMdChange,
+ ),
+ );
+ const byId = new Map(patches.map((c) => [c.id, c]));
+ for (const w of r.written) plan.written.push(byId.get(w.id)!);
+ for (const p of r.present) plan.present.push(byId.get(p.id)!);
+ for (const s of r.skipped) plan.skipped.push({ change: byId.get(s.change.id)!, why: s.why });
+ if (r.written.length > 0) {
+ text = r.text;
+ changed = true;
+ }
+ }
+
+ if (changed && text !== original) {
+ plan.status = existed ? "M" : "A";
+ plan.text = text;
+ }
+ return plan;
+}
+
+/** Write a planned file, making its folder when it is new. */
+export function writePlannedFile(root: string, plan: FilePlan): void {
+ if (!plan.status || plan.text === undefined) return;
+ const abs = join(root, plan.path);
+ mkdirSync(dirname(abs), { recursive: true });
+ writeFileSync(abs, plan.text);
+}
+
+/** `+ Money · ~ Commands` — a new section is +, an edited one ~, a whole file nothing. */
+export function changeSummary(changes: Array<{ kind: string; heading?: string }>): string {
+ return changes
+ .filter((c) => c.kind === "add" || c.kind === "edit")
+ .map((c) => `${c.kind === "add" ? "+" : "~"} ${c.heading ?? ""}`.trim())
+ .join(" · ");
+}
diff --git a/src/brain/pull.ts b/src/brain/pull.ts
new file mode 100644
index 00000000..6c62d53e
--- /dev/null
+++ b/src/brain/pull.ts
@@ -0,0 +1,165 @@
+/**
+ * `graft trail pull`: one command for both things a trail hands this repo.
+ *
+ * First the rules, refreshed into graft's own blocks in the agent files (what
+ * `graft trail pull` always did). Then every change accepted in Trail, for every
+ * context file the picked agents read — the root CLAUDE.md (what `graft
+ * claude-md pull` did, and still does, as an alias of this), and then AGENTS.md,
+ * folder CLAUDE.md files, Cursor rules and skills when Trail serves them.
+ *
+ * Files for agents that were not picked are neither listed nor written.
+ */
+import { isAbsolute, relative } from "node:path";
+import { connectBrain, type ConnectResult } from "./connect.js";
+import { fetchAcceptedChanges, markApplied } from "./claude-md.js";
+import {
+ changeSummary,
+ fetchContextFiles,
+ kindForPath,
+ markContextFilesApplied,
+ planContextFile,
+ readByWired,
+ writePlannedFile,
+ type ContextFile,
+ type FilePlan,
+} from "./context-files.js";
+import type { BrainLink } from "./link.js";
+import { reviewUrl } from "./signup.js";
+
+export interface PullOptions {
+ home: string;
+ /** The agents this repo is wired for; empty means no choice was recorded. */
+ wired: string[];
+ dryRun?: boolean;
+ fetchImpl?: typeof fetch;
+ write?: (line: string) => void;
+}
+
+/** Repo-relative, forward slashes, for printing. */
+function show(repo: string, path: string): string {
+ const rel = isAbsolute(path) ? relative(repo, path) : path;
+ return rel.split("\\").join("/");
+}
+
+/** The rules line: how many, and which files they are in. */
+export function rulesLine(repo: string, res: ConnectResult): string | null {
+ if (res.warning) return `⚠ ${res.warning}`;
+ if (res.ruleCount === 0) return "· the trail has no rules yet — run graft trail push to read this repo into it";
+ const n = res.ruleCount.toLocaleString("en-US");
+ const where = res.writes.map((w) => show(repo, w.path)).join(", ");
+ const rules = `${n} rule${res.ruleCount === 1 ? "" : "s"}`;
+ if (!where) return `✓ ${rules} pulled · no instruction file to write them into — graft ask still carries them`;
+ if (res.writes.every((w) => w.action === "unchanged")) return `✓ rules already current · ${n} in ${where}`;
+ return `✓ ${rules} refreshed in ${where}`;
+}
+
+/** Everything the pull will write, file by file, with where each change came from. */
+interface Planned {
+ plan: FilePlan;
+ source: "claude-md" | "context-files";
+}
+
+/**
+ * Run the pull. Returns the exit code; every line goes through `write`.
+ */
+export async function runTrailPull(repo: string, link: BrainLink, opts: PullOptions): Promise<number> {
+ const write = opts.write ?? ((l: string) => console.error(l));
+ const fetchImpl = opts.fetchImpl ?? fetch;
+ let code = 0;
+
+ // 1. The rules. Skipped on a dry run, which writes nothing at all.
+ if (!opts.dryRun) {
+ const res = await connectBrain(repo, link, {
+ home: opts.home,
+ ids: opts.wired.length > 0 ? opts.wired : undefined,
+ fetchImpl,
+ });
+ const line = rulesLine(repo, res);
+ if (line) write(line);
+ if (res.warning) code = 1;
+ }
+
+ // 2. Accepted changes: the root CLAUDE.md, then every other context file.
+ const planned: Planned[] = [];
+ let accepted = 0;
+
+ const md = await fetchAcceptedChanges(link, fetchImpl);
+ if ("error" in md) {
+ if (!md.unsupported) {
+ write(`✗ ${md.error}`);
+ code = 1;
+ }
+ } else if (md.changes.length > 0) {
+ const file: ContextFile = { kind: kindForPath(md.path || "CLAUDE.md"), path: md.path || "CLAUDE.md", changes: md.changes };
+ if (readByWired(file.kind, opts.wired)) {
+ accepted += file.changes.length;
+ planned.push({ plan: planContextFile(repo, file), source: "claude-md" });
+ }
+ }
+
+ const ctx = await fetchContextFiles(link, fetchImpl);
+ if ("error" in ctx) {
+ write(`✗ ${ctx.error}`);
+ code = 1;
+ } else if (!("unsupported" in ctx)) {
+ for (const file of ctx.files) {
+ if (file.changes.length === 0 || !readByWired(file.kind, opts.wired)) continue;
+ accepted += file.changes.length;
+ planned.push({ plan: planContextFile(repo, file), source: "context-files" });
+ }
+ }
+
+ if (accepted === 0) {
+ if (code === 0) {
+ write("· nothing accepted in Trail yet — review:");
+ write(` ${reviewUrl(link.brainId)}`);
+ }
+ return code;
+ }
+
+ const writing = planned.filter((p) => p.plan.status);
+ const changes = writing.reduce((n, p) => n + p.plan.written.length, 0);
+ if (writing.length > 0) {
+ write(`✓ ${opts.dryRun ? "would write" : "wrote"} ${changes} accepted change${changes === 1 ? "" : "s"}`);
+ const width = Math.max(30, ...writing.map((p) => p.plan.path.length)) + 2;
+ for (const { plan } of writing) {
+ const summary = changeSummary(plan.written);
+ write(` ${plan.status} ${summary ? plan.path.padEnd(width) : plan.path}${summary}`.trimEnd());
+ }
+ } else if (planned.some((p) => p.plan.present.length > 0)) {
+ write("✓ every accepted change is already in these files");
+ }
+
+ for (const { plan } of planned) {
+ for (const s of plan.skipped) {
+ const what = s.change.kind === "edit" || s.change.kind === "add" ? `${changeSummary([s.change])} in ${plan.path}` : plan.path;
+ write(`⚠ skipped ${what} — ${s.why}; edit it in Trail, then pull again`);
+ code = 1;
+ }
+ }
+
+ if (opts.dryRun) {
+ write("· dry run — nothing written, and Trail was not told");
+ return code;
+ }
+
+ for (const { plan } of writing) {
+ try {
+ writePlannedFile(repo, plan);
+ } catch (e) {
+ write(`✗ could not write ${plan.path}: ${e instanceof Error ? e.message : e}`);
+ // Nothing from a file that was not written is reported as applied.
+ plan.written = [];
+ plan.present = [];
+ code = 1;
+ }
+ }
+
+ // Written now or already there: either way Trail should stop listing it.
+ const done = (source: Planned["source"]) =>
+ planned.filter((p) => p.source === source).flatMap((p) => [...p.plan.written, ...p.plan.present].map((c) => c.id));
+ const told = (await markApplied(link, done("claude-md"), fetchImpl)) && (await markContextFilesApplied(link, done("context-files"), fetchImpl));
+ if (!told) write("⚠ could not tell Trail which changes were written; it may still list them");
+ if (writing.length > 0) write("· review with git diff, then commit");
+ return code;
+}
diff --git a/src/brain/push.ts b/src/brain/push.ts
index 9cbf5d01..fefa2343 100644
--- a/src/brain/push.ts
+++ b/src/brain/push.ts
@@ -17,11 +17,13 @@
import { spawnSync } from "node:child_process";
import {
buildDigest,
+ newThreadReadCache,
readCommits,
readSymbols,
readThreads,
type HistoryThread,
type RepoDigest,
+ type ThreadReadCache,
} from "../app/history.js";
import {
budgetSources,
@@ -36,6 +38,7 @@ import {
} from "../app/sources.js";
import type { GraphV1 } from "../graph/types.js";
import { baseUrlFor, type BrainLink } from "./link.js";
+import { postDigestOnce, uploadDigest, type UploadCaps, type UploadOptions } from "./upload.js";
/** What a local ingest read, for the caller to print. */
export interface PushResult {
@@ -115,8 +118,16 @@ export interface ExpectedRepo {
slug: string;
status: string;
brainName: string;
+ /** Rules the trail already holds; 0 before its first build. */
+ ruleCount: number;
/** The brain accepts an early upload (see pushEarlyDigest). */
earlyUpload: boolean;
+ /** POST /repo takes a gzipped body (`gzip_upload`). */
+ gzipUpload: boolean;
+ /** The chunked /repo/uploads routes exist (`chunked_upload`). */
+ chunkedUpload: boolean;
+ /** GET /events streams the build (`events`). */
+ events: boolean;
}
/**
@@ -128,6 +139,10 @@ export interface ExpectedRepo {
* afterwards — the rules simply describe someone else's codebase — so the round
* trip is worth it.
*
+ * The same read says what the server can take: gzip, chunks, a live event
+ * stream. Every flag defaults to off, so an older Trail gets exactly the
+ * requests it always did.
+ *
* Null on any failure, which keeps an older brain (or an unreachable one)
* working exactly as it did before this check existed.
*/
@@ -139,22 +154,34 @@ export async function fetchExpectedRepo(link: BrainLink, fetchImpl: typeof fetch
});
if (!res.ok) return null;
const body = (await res.json()) as {
- repo?: { slug?: string; status?: string } | null;
+ repo?: { slug?: string; status?: string; rule_count?: number } | null;
brain_name?: string;
early_upload?: boolean;
+ gzip_upload?: boolean;
+ chunked_upload?: boolean;
+ events?: boolean;
};
if (!body.repo?.slug) return null;
return {
slug: body.repo.slug,
status: String(body.repo.status ?? ""),
brainName: String(body.brain_name ?? ""),
+ ruleCount: typeof body.repo.rule_count === "number" && body.repo.rule_count > 0 ? body.repo.rule_count : 0,
earlyUpload: body.early_upload === true,
+ gzipUpload: body.gzip_upload === true,
+ chunkedUpload: body.chunked_upload === true,
+ events: body.events === true,
};
} catch {
return null;
}
}
+/** The upload capabilities an expected-repo read advertised. */
+export function uploadCaps(expected: ExpectedRepo | null): UploadCaps {
+ return { gzip: expected?.gzipUpload === true, chunked: expected?.chunkedUpload === true };
+}
+
/** Whether two repo slugs name the same repository. GitHub is case-insensitive. */
export function sameRepo(a: string, b: string): boolean {
return a.trim().toLowerCase() === b.trim().toLowerCase();
@@ -165,6 +192,42 @@ export function sameRepo(a: string, b: string): boolean {
export const EARLY_THREADS = 30;
export const EARLY_COMMITS = 80;
+/**
+ * What one push reads once and shares between its early and full digests: the
+ * repository's identity, the GitHub token, whether it is private, and every
+ * request already made to GitHub for its pull requests.
+ */
+export interface PushContext {
+ owner: string;
+ name: string;
+ token: string | null;
+ fetchImpl: typeof fetch;
+ headSha: string;
+ branch: string;
+ /** Asked once, when first needed. */
+ isPrivate: () => Promise<boolean>;
+ threads: ThreadReadCache;
+}
+
+/** The shared context for a push from `root`, or null without a GitHub origin. */
+export function pushContext(root: string, opts: { fetchImpl?: typeof fetch } = {}): PushContext | null {
+ const slug = repoSlugFromGit(root);
+ if (!slug) return null;
+ const fetchImpl = opts.fetchImpl ?? fetch;
+ const token = githubToken();
+ let privacy: Promise<boolean> | null = null;
+ return {
+ owner: slug.owner,
+ name: slug.name,
+ token,
+ fetchImpl,
+ headSha: git(root, ["rev-parse", "HEAD"]) ?? "",
+ branch: currentBranch(root),
+ isPrivate: () => (privacy ??= isPrivate(slug.owner, slug.name, token, fetchImpl)),
+ threads: newThreadReadCache(),
+ };
+}
+
/**
* The early upload: the instruction files, the newest pull requests and the
* newest commits, read before the rest of the history.
@@ -174,34 +237,36 @@ export const EARLY_COMMITS = 80;
* beyond the newest few. Sent first, they start while the full read is still
* going here, and the full upload that follows mines as before.
*
- * Returns the threads it read, so the full read reuses them instead of asking
- * GitHub twice. Null when there is nothing worth sending early.
+ * Only the newest commits are read here, not the thousand the full read takes,
+ * so nothing but these few requests stands between the push starting and Trail
+ * starting. The pull requests go through the shared cache, so the full read
+ * asks GitHub for none of them again — not even one still in flight.
+ *
+ * Null when there is nothing worth sending early.
*/
export async function buildEarlyDigest(
root: string,
- opts: { fetchImpl?: typeof fetch } = {},
+ opts: { fetchImpl?: typeof fetch; context?: PushContext } = {},
): Promise<{ digest: RepoDigest; threads: HistoryThread[] } | null> {
- const slug = repoSlugFromGit(root);
- if (!slug) return null;
- const fetchImpl = opts.fetchImpl ?? fetch;
- const token = githubToken();
+ const ctx = opts.context ?? pushContext(root, opts);
+ if (!ctx) return null;
// Oldest first, like the full read, so the newest are the tail.
- const commits = readCommits(root).slice(-EARLY_COMMITS);
+ const commits = readCommits(root, EARLY_COMMITS);
if (commits.length === 0) return null;
let threads: HistoryThread[] = [];
- if (token) {
+ if (ctx.token) {
try {
- threads = await readThreads(slug.owner, slug.name, token, fetchImpl as never, undefined, EARLY_THREADS);
+ threads = await readThreads(ctx.owner, ctx.name, ctx.token, ctx.fetchImpl as never, undefined, EARLY_THREADS, undefined, ctx.threads);
} catch {
threads = [];
}
}
const digest = buildDigest({
- owner: slug.owner,
- name: slug.name,
- headSha: git(root, ["rev-parse", "HEAD"]) ?? "",
- defaultBranch: currentBranch(root),
- isPrivate: await isPrivate(slug.owner, slug.name, token, fetchImpl),
+ owner: ctx.owner,
+ name: ctx.name,
+ headSha: ctx.headSha,
+ defaultBranch: ctx.branch,
+ isPrivate: await ctx.isPrivate(),
commits,
threads,
symbols: [],
@@ -212,20 +277,15 @@ export async function buildEarlyDigest(
}
/** Send the early upload. Best-effort: false on any failure, and the full
- * upload still does everything. */
-export async function pushEarlyDigest(link: BrainLink, digest: RepoDigest, fetchImpl: typeof fetch = fetch): Promise<boolean> {
- const url = `${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/repo?stage=early`;
+ * upload still does everything. Gzipped when the server takes it. */
+export async function pushEarlyDigest(
+ link: BrainLink,
+ digest: RepoDigest,
+ fetchImpl: typeof fetch = fetch,
+ opts: { gzip?: boolean } = {},
+): Promise<boolean> {
try {
- const res = await fetchImpl(url, {
- method: "POST",
- headers: {
- authorization: `Bearer ${link.token}`,
- "content-type": "application/json",
- accept: "application/json",
- },
- body: JSON.stringify(digest),
- signal: AbortSignal.timeout(15_000),
- });
+ const res = await postDigestOnce(link, digest, { gzip: opts.gzip, fetchImpl, query: "?stage=early", timeoutMs: 15_000 });
if (!res.ok) return false;
return ((await res.json()) as { early?: boolean }).early === true;
} catch {
@@ -237,14 +297,13 @@ export async function pushEarlyDigest(link: BrainLink, digest: RepoDigest, fetch
export async function buildLocalDigest(
root: string,
graph: GraphV1 | null,
- opts: { autoApprove?: boolean; fetchImpl?: typeof fetch; knownThreads?: HistoryThread[] } = {},
+ opts: { autoApprove?: boolean; fetchImpl?: typeof fetch; knownThreads?: HistoryThread[]; context?: PushContext } = {},
): Promise<{ digest: RepoDigest; warning?: string } | { error: string }> {
- const slug = repoSlugFromGit(root);
- if (!slug) {
+ const ctx = opts.context ?? pushContext(root, opts);
+ if (!ctx) {
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 { token, fetchImpl } = ctx;
const commits = readCommits(root);
if (commits.length === 0) {
@@ -254,10 +313,18 @@ export async function buildLocalDigest(
let threads: Awaited<ReturnType<typeof readThreads>> = [];
let warning: string | undefined;
+ // The GitHub-side sources start with the threads rather than after them:
+ // they are a request or two each, and waiting behind 400 is waiting for no reason.
+ const remote = token
+ ? Promise.all([
+ readBranchProtection(ctx.owner, ctx.name, ctx.branch, token, fetchImpl as never),
+ readDeclinedIssues(ctx.owner, ctx.name, token, fetchImpl as never),
+ ])
+ : Promise.resolve([[], []] as const);
if (token) {
try {
const known = new Map((opts.knownThreads ?? []).map((t) => [t.number, t]));
- threads = await readThreads(slug.owner, slug.name, token, fetchImpl as never, undefined, undefined, known);
+ threads = await readThreads(ctx.owner, ctx.name, token, fetchImpl as never, undefined, undefined, known, ctx.threads);
} catch {
warning = "could not read pull-request discussion; mining commits and repo files only";
}
@@ -265,8 +332,8 @@ export async function buildLocalDigest(
warning =
"no GitHub token found (`gh auth login`, or GH_TOKEN) — mining commits and repo files only, without pull-request discussion";
}
+ const [protection, declined] = await remote;
- const branch = currentBranch(root);
const sources = budgetSources([
...readAgentInstructions(root),
...readDecisionDocs(root),
@@ -274,16 +341,16 @@ export async function buildLocalDigest(
...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) : []),
+ ...protection,
+ ...declined,
]);
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),
+ owner: ctx.owner,
+ name: ctx.name,
+ headSha: ctx.headSha,
+ defaultBranch: ctx.branch,
+ isPrivate: await ctx.isPrivate(),
commits,
threads,
symbols,
@@ -293,27 +360,18 @@ export async function buildLocalDigest(
return { digest, warning };
}
-/** Send a digest to the brain and return the job to poll. */
+/**
+ * Send a digest to the brain and return the job to poll.
+ *
+ * Chunked and gzipped when the server advertises both, gzipped in one POST when
+ * it advertises only gzip, and today's plain POST otherwise.
+ */
export async function pushDigest(
link: BrainLink,
digest: RepoDigest,
fetchImpl: typeof fetch = fetch,
+ caps: UploadCaps = {},
+ opts: Omit<UploadOptions, "fetchImpl"> = {},
): 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}` };
- }
+ return uploadDigest(link, digest, caps, { ...opts, fetchImpl });
}
diff --git a/src/brain/signup.ts b/src/brain/signup.ts
index d9da4952..fe3f87e8 100644
--- a/src/brain/signup.ts
+++ b/src/brain/signup.ts
@@ -76,8 +76,8 @@ function sameState(got: string, want: string): boolean {
* about to close, so there is nothing to style around. */
function donePage(ok: boolean): string {
const msg = ok
- ? "Your brain is connected. Return to your terminal — the push is already running."
- : "That handoff did not match this terminal. Run `graft trail push` again.";
+ ? "Your trail is connected. Return to your terminal — the push is already running."
+ : "That sign-up doesn't match this terminal. Run graft trail push again.";
return `<!doctype html><meta charset="utf-8"><title>graft</title><body style="font:15px/1.5 system-ui,sans-serif;margin:3rem auto;max-width:32rem;color:#1F2129"><p>${msg}</p><p style="color:#676767">You can close this tab.</p>`;
}
@@ -116,7 +116,7 @@ export async function startHandoff(): Promise<Handoff> {
if (!brainId || !token) {
res.writeHead(400, { "content-type": "text/html; charset=utf-8" });
res.end(donePage(false));
- settle({ error: "the browser came back without a brain id and token", reason: "bad_callback" });
+ settle({ error: "sign-up came back incomplete · nothing was sent — run graft trail push again", reason: "bad_callback" });
return;
}
@@ -155,7 +155,13 @@ export async function startHandoff(): Promise<Handoff> {
let timer: NodeJS.Timeout | undefined;
const timeout = new Promise<HandoffResult>((resolve) => {
timer = setTimeout(
- () => resolve({ error: "timed out waiting for the browser — run `graft trail push` again, or use the link above", reason: "timed_out" }),
+ () =>
+ resolve({
+ error: `no sign-up after ${
+ timeoutMs >= 60_000 ? `${Math.round(timeoutMs / 60_000)} minutes` : `${Math.max(1, Math.round(timeoutMs / 1000))} seconds`
+ } · nothing was sent — run graft trail push again`,
+ reason: "timed_out",
+ }),
timeoutMs,
);
// The timer must not hold the process open once the browser has answered.
@@ -196,6 +202,11 @@ export function brainUrl(brainId: string, baseUrl?: string): string {
return `${webBaseUrl(baseUrl)}/get-started?step=build&brain=${encodeURIComponent(brainId)}`;
}
+/** Where a trail's suggested context-file changes are reviewed and accepted. */
+export function reviewUrl(brainId: string, baseUrl?: string): string {
+ return `${webBaseUrl(baseUrl)}/brain/${encodeURIComponent(brainId)}/claude-md`;
+}
+
/** Where to send the browser for a repo's brain. */
export function signupUrl(opts: { repo: string; port: number; state: string; baseUrl?: string }): string {
const base = webBaseUrl(opts.baseUrl);
diff --git a/src/brain/upload.ts b/src/brain/upload.ts
new file mode 100644
index 00000000..b9fc70df
--- /dev/null
+++ b/src/brain/upload.ts
@@ -0,0 +1,254 @@
+/**
+ * Getting a digest to Trail quickly, and getting it there at all.
+ *
+ * A busy repository's digest is several megabytes of JSON — a thousand commit
+ * messages, two hundred threads of discussion, four thousand symbols — and it
+ * used to go up as one uncompressed POST with no retry. On a hotel connection
+ * that is a minute of upload and one dropped packet from starting over.
+ *
+ * JSON compresses about tenfold, so the body is gzipped whenever the server
+ * says it takes gzip. When it also says it takes chunked uploads, the gzip is
+ * cut into 1 MiB pieces and sent four at a time, each retried on its own: a
+ * blip costs one chunk, not the push. Against an older Trail neither flag is
+ * set and the upload is exactly the single POST it always was.
+ */
+import { gzip as gzipCb } from "node:zlib";
+import { promisify } from "node:util";
+import type { RepoDigest } from "../app/history.js";
+import { baseUrlFor, type BrainLink } from "./link.js";
+
+const gzipAsync = promisify(gzipCb);
+
+/** The size of one chunk: the index-th slice of the gzip is bytes [i*CHUNK, (i+1)*CHUNK). */
+export const CHUNK_BYTES = 1024 * 1024;
+/** Chunks in flight at once. */
+export const CHUNK_CONCURRENCY = 4;
+/** Waits before each retry. Four retries, so five attempts in all. */
+export const RETRY_DELAYS_MS = [500, 1000, 2000, 4000] as const;
+
+/** What the server said it accepts, from GET /repo. */
+export interface UploadCaps {
+ /** `gzip_upload: true` — POST /repo takes `Content-Encoding: gzip`. */
+ gzip?: boolean;
+ /** `chunked_upload: true` — the /repo/uploads routes exist. */
+ chunked?: boolean;
+}
+
+export interface UploadOptions {
+ fetchImpl?: typeof fetch;
+ sleep?: (ms: number) => Promise<void>;
+ chunkBytes?: number;
+ concurrency?: number;
+}
+
+export type UploadResult = { jobId: string } | { error: string };
+
+const realSleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+/** The digest as the exact bytes a single POST would carry, gzipped. */
+export async function gzipDigest(digest: RepoDigest): Promise<Buffer> {
+ return gzipAsync(Buffer.from(JSON.stringify(digest), "utf8"));
+}
+
+/** Retry on what a retry can fix: the network, the server, the rate limit. */
+function retryable(status: number): boolean {
+ return status >= 500 || status === 429;
+}
+
+/**
+ * One request, retried with backoff on network errors, 5xx and 429.
+ *
+ * Returns the last response when retries run out on a status (so the caller
+ * can print the server's own words), or throws the last network error.
+ */
+async function withRetry(
+ send: () => Promise<Response>,
+ sleep: (ms: number) => Promise<void>,
+): Promise<{ res: Response; attempts: number; sawNetworkError: boolean }> {
+ let sawNetworkError = false;
+ let lastError: unknown;
+ for (let attempt = 0; attempt <= RETRY_DELAYS_MS.length; attempt++) {
+ if (attempt > 0) await sleep(RETRY_DELAYS_MS[attempt - 1]!);
+ try {
+ const res = await send();
+ if (!retryable(res.status) || attempt === RETRY_DELAYS_MS.length) {
+ return { res, attempts: attempt + 1, sawNetworkError };
+ }
+ // Drain it so the connection is released before the next attempt.
+ await res.arrayBuffer().catch(() => undefined);
+ } catch (e) {
+ sawNetworkError = true;
+ lastError = e;
+ }
+ }
+ throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
+
+function authHeaders(link: BrainLink, extra: Record<string, string> = {}): Record<string, string> {
+ return { authorization: `Bearer ${link.token}`, accept: "application/json", ...extra };
+}
+
+/** Today's response to an ingest, read the same way for every route that returns it. */
+async function ingestResult(res: Response): Promise<UploadResult> {
+ const text = await res.text();
+ if (!res.ok) return { error: `Trail refused the upload: ${res.status} ${text.slice(0, 200)}` };
+ try {
+ return { jobId: String((JSON.parse(text) as { job_id?: string }).job_id ?? "") };
+ } catch {
+ return { jobId: "" };
+ }
+}
+
+/**
+ * The single POST to /repo — gzipped when the server takes it, plain otherwise.
+ * Not retried: a repeated POST of a whole ingest is not idempotent, and a 409
+ * for "already running" on the retry would read as a refusal.
+ */
+export async function postDigestOnce(
+ link: BrainLink,
+ digest: RepoDigest,
+ opts: { gzip?: boolean; fetchImpl?: typeof fetch; query?: string; timeoutMs?: number } = {},
+): Promise<Response> {
+ const fetchImpl = opts.fetchImpl ?? fetch;
+ const url = `${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/repo${opts.query ?? ""}`;
+ const json = JSON.stringify(digest);
+ const body = opts.gzip ? await gzipAsync(Buffer.from(json, "utf8")) : json;
+ const headers = authHeaders(link, { "content-type": "application/json" });
+ if (opts.gzip) headers["content-encoding"] = "gzip";
+ return fetchImpl(url, {
+ method: "POST",
+ headers,
+ body: body as unknown as RequestInit["body"],
+ ...(opts.timeoutMs ? { signal: AbortSignal.timeout(opts.timeoutMs) } : {}),
+ });
+}
+
+/**
+ * Upload the full digest by whichever route the server advertises.
+ *
+ * Chunked when `caps.chunked`; if the upload session cannot even be opened
+ * (a 404 from a server that advertised the flag but not the route), it falls
+ * back to the single POST rather than failing a push that would otherwise work.
+ */
+export async function uploadDigest(
+ link: BrainLink,
+ digest: RepoDigest,
+ caps: UploadCaps,
+ opts: UploadOptions = {},
+): Promise<UploadResult> {
+ if (caps.chunked) {
+ const chunked = await uploadChunked(link, digest, opts);
+ if (!("fallback" in chunked)) return chunked;
+ }
+ try {
+ return await ingestResult(await postDigestOnce(link, digest, { gzip: caps.gzip, fetchImpl: opts.fetchImpl }));
+ } catch (e) {
+ return { error: `could not reach Trail: ${e instanceof Error ? e.message : e}` };
+ }
+}
+
+/**
+ * The chunked route:
+ *
+ * POST /repo/uploads {stage, auto_approve, chunks, bytes} → {upload_id}
+ * PUT /repo/uploads/:id/chunks/:index raw gzip slice, idempotent → 204
+ * POST /repo/uploads/:id/complete → today's /repo response
+ *
+ * `{fallback: true}` means the session could not be opened and nothing was
+ * sent, so the caller may use the single POST instead.
+ */
+export async function uploadChunked(
+ link: BrainLink,
+ digest: RepoDigest,
+ opts: UploadOptions = {},
+): Promise<UploadResult | { fallback: true }> {
+ const fetchImpl = opts.fetchImpl ?? fetch;
+ const sleep = opts.sleep ?? realSleep;
+ const chunkBytes = opts.chunkBytes ?? CHUNK_BYTES;
+ const base = `${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/repo/uploads`;
+
+ const gz = await gzipDigest(digest);
+ const chunks = Math.max(1, Math.ceil(gz.length / chunkBytes));
+
+ let uploadId = "";
+ try {
+ const { res } = await withRetry(
+ () =>
+ fetchImpl(base, {
+ method: "POST",
+ headers: authHeaders(link, { "content-type": "application/json" }),
+ body: JSON.stringify({ stage: "full", auto_approve: digest.auto_approve, chunks, bytes: gz.length }),
+ }),
+ sleep,
+ );
+ const text = await res.text();
+ if (res.status === 404 || res.status === 405) return { fallback: true };
+ if (!res.ok) {
+ // 409 is the one refusal worth passing on as-is: an ingest is already
+ // running, and a single POST would be told the same.
+ if (res.status === 409) return { error: `Trail refused the upload: ${res.status} ${text.slice(0, 200)}` };
+ return { fallback: true };
+ }
+ uploadId = String((JSON.parse(text) as { upload_id?: string }).upload_id ?? "");
+ } catch {
+ return { fallback: true };
+ }
+ if (!uploadId) return { fallback: true };
+
+ // Chunks, four at a time, each retried on its own.
+ const concurrency = Math.max(1, opts.concurrency ?? CHUNK_CONCURRENCY);
+ let next = 0;
+ let failure: string | null = null;
+ const worker = async () => {
+ for (;;) {
+ if (failure) return;
+ const i = next++;
+ if (i >= chunks) return;
+ const slice = gz.subarray(i * chunkBytes, Math.min(gz.length, (i + 1) * chunkBytes));
+ try {
+ const { res } = await withRetry(
+ () =>
+ fetchImpl(`${base}/${encodeURIComponent(uploadId)}/chunks/${i}`, {
+ method: "PUT",
+ headers: authHeaders(link, { "content-type": "application/octet-stream" }),
+ body: slice as unknown as RequestInit["body"],
+ }),
+ sleep,
+ );
+ if (!res.ok) {
+ const text = await res.text().catch(() => "");
+ failure = `Trail refused part ${i + 1} of ${chunks}: ${res.status} ${text.slice(0, 200)}`;
+ return;
+ }
+ await res.arrayBuffer().catch(() => undefined);
+ } catch (e) {
+ failure = `could not send part ${i + 1} of ${chunks} to Trail: ${e instanceof Error ? e.message : e}`;
+ return;
+ }
+ }
+ };
+ await Promise.all(Array.from({ length: Math.min(concurrency, chunks) }, worker));
+ if (failure) return { error: failure };
+
+ try {
+ const { res, sawNetworkError } = await withRetry(
+ () =>
+ fetchImpl(`${base}/${encodeURIComponent(uploadId)}/complete`, {
+ method: "POST",
+ headers: authHeaders(link, { "content-type": "application/json" }),
+ body: "{}",
+ }),
+ sleep,
+ );
+ // A complete that was lost on the way back may have started the ingest, so
+ // its retry being told "already running" means it worked. The watcher that
+ // follows reads the build either way.
+ if (res.status === 409 && sawNetworkError) {
+ await res.arrayBuffer().catch(() => undefined);
+ return { jobId: "" };
+ }
+ return await ingestResult(res);
+ } catch (e) {
+ return { error: `could not reach Trail to finish the upload: ${e instanceof Error ? e.message : e}` };
+ }
+}
diff --git a/src/brain/watch.ts b/src/brain/watch.ts
index 43e3ab57..c72066ff 100644
--- a/src/brain/watch.ts
+++ b/src/brain/watch.ts
@@ -67,6 +67,24 @@ export interface RepoState {
/** Rules the miner has handed over so far. Grows with every slice of the
* history that comes back, so it is a floor and never a total. */
foundSoFar?: number;
+ /** Suggested changes to the repo's context files, when Trail sends them. */
+ suggestions?: Suggestions;
+}
+
+/**
+ * The suggestions Trail has for this repository's context files so far.
+ *
+ * Counts, because that is all the terminal prints; the changes themselves are
+ * reviewed in Trail and written by `graft trail pull`.
+ */
+export interface Suggestions {
+ /** Changes suggested for the root CLAUDE.md. */
+ claudeMd: number;
+ /** Changes suggested for every other context file, all kinds together. */
+ contextFiles: number;
+ /** Per file, when Trail lists them — which is what lets the count be cut to
+ * the files the wired agents actually read. */
+ files?: Array<{ kind: string; path: string; changes: number }>;
}
export interface BuildView {
@@ -148,6 +166,51 @@ export function stagesFrom(repo: RepoState | null): BuildView {
};
}
+/** A count from a field Trail may send as a number or as the list itself. */
+const countOf = (v: unknown): number => (Array.isArray(v) ? v.length : num(v));
+
+/** The fields of an expected-repo body the watcher reads, as Trail sends them. */
+interface RepoBody {
+ repo?: { status?: string; error_message?: string; rule_count?: number; commit_count?: number; thread_count?: number } | null;
+ // Absent on an older API, which is why every read of it defaults to zero:
+ // a graft that cannot see the in-flight counts falls back to waiting for
+ // the finished row, exactly as it did before.
+ build?: { found_so_far?: number; filed_so_far?: number } | null;
+ claude_md?: { status?: string; quick_ready?: boolean; full_ready?: boolean; changes?: unknown } | null;
+ context_files?: { files?: unknown; changes?: unknown } | null;
+}
+
+/**
+ * The repo state out of an expected-repo body — the polled GET and every SSE
+ * `progress` event carry the same shape. Null when there is no repo row.
+ */
+export function parseRepoBody(body: unknown): RepoState | null {
+ const b = (body ?? {}) as RepoBody;
+ if (!b.repo || typeof b.repo !== "object") return null;
+ const state: RepoState = {
+ status: String(b.repo.status ?? ""),
+ errorMessage: b.repo.error_message,
+ ruleCount: num(b.repo.rule_count),
+ commitCount: num(b.repo.commit_count),
+ threadCount: num(b.repo.thread_count),
+ filedSoFar: num(b.build?.filed_so_far),
+ foundSoFar: num(b.build?.found_so_far),
+ };
+ if (b.claude_md || b.context_files) {
+ const files = Array.isArray(b.context_files?.files)
+ ? (b.context_files!.files as Array<{ kind?: unknown; path?: unknown; changes?: unknown }>)
+ .filter((f) => f && typeof f === "object")
+ .map((f) => ({ kind: String(f.kind ?? ""), path: String(f.path ?? ""), changes: countOf(f.changes) }))
+ : undefined;
+ state.suggestions = {
+ claudeMd: countOf(b.claude_md?.changes),
+ contextFiles: b.context_files?.changes !== undefined ? countOf(b.context_files.changes) : (files ?? []).reduce((n, f) => n + f.changes, 0),
+ ...(files ? { files } : {}),
+ };
+ }
+ return state;
+}
+
/**
* Read the repo row this brain is building.
*
@@ -162,45 +225,72 @@ export async function fetchRepoState(link: BrainLink, fetchImpl: typeof fetch =
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;
- // Absent on an older API, which is why every read of it defaults to zero:
- // a graft that cannot see the in-flight counts falls back to waiting for
- // the finished row, exactly as it did before.
- build?: { found_so_far?: number; filed_so_far?: 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),
- filedSoFar: num(body.build?.filed_so_far),
- foundSoFar: num(body.build?.found_so_far),
- };
+ return parseRepoBody(await res.json());
} 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[] {
+/** Past tense, for the no-TTY log: each line reports a stage that finished. */
+const DONE_LABEL: Record<StageId, string> = {
+ reach: "reached the repository",
+ read: "read its history",
+ mine: "mined the rules",
+ file: "filed them into the trail",
+};
+
+/** What the spinner says while a stage is running. */
+export const DOING_LABEL: Record<StageId, string> = {
+ reach: "reaching the repository",
+ read: "reading its history",
+ mine: "mining rules",
+ file: "filing the rules",
+};
+
+/** The first rules there are, from whichever count the row has. */
+export function rulesSoFar(repo: RepoState | null): number {
+ return Math.max(num(repo?.ruleCount), num(repo?.filedSoFar), num(repo?.foundSoFar));
+}
+
+/**
+ * One printable line per stage that has finished since it was last printed.
+ *
+ * Only for a log with no terminal to redraw — on a TTY the spinner says which
+ * stage is running and these lines are never printed. Filing is left out: the
+ * watcher hands the prompt back on the first rules, before filing finishes, and
+ * the closing line says how many there are.
+ */
+export function linesFor(view: BuildView, already: Set<string>, repo: RepoState | null = null): 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;
+ if (s.state !== "done" || s.id === "file") 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}` : ""}`);
+ const rules = rulesSoFar(repo);
+ const label =
+ s.id === "mine" && rules > 0
+ ? `mined the first ${rules.toLocaleString("en-US")} rule${rules === 1 ? "" : "s"}`
+ : DONE_LABEL[s.id];
+ out.push(` ✓ ${label}`);
}
return out;
}
+/** The stage the build is in now, for the spinner. */
+export function currentStage(view: BuildView): StageId {
+ return (view.stages.find((s) => s.state === "doing" || s.state === "failed") ?? view.stages[view.stages.length - 1]!).id;
+}
+
+/** The failure line: where it stopped, and that nothing was lost. The server's
+ * own words follow on the next line, in full. */
+export function failureLines(view: BuildView): string[] {
+ const at = view.stages.find((s) => s.state === "failed")?.id ?? "mine";
+ const lines = [`✗ the build stopped while ${DOING_LABEL[at]} · nothing was lost — run graft trail push again`];
+ if (view.error) lines.push(` ${view.error}`);
+ return lines;
+}
+
export interface WatchOptions {
/** How long to hold before giving up on a build that is still running. */
timeoutMs?: number;
@@ -209,6 +299,16 @@ export interface WatchOptions {
/** Where the lines go. Injected so the tests do not need a console. */
write?: (line: string) => void;
sleep?: (ms: number) => Promise<void>;
+ /** Print a line per finished stage. Off on a TTY, where a spinner says it. */
+ stageLines?: boolean;
+ /** Every state read, with its view — the spinner's feed. */
+ onState?: (view: BuildView, repo: RepoState) => void;
+ /** Follow `GET /events` instead of polling (the server advertised `events`). */
+ events?: boolean;
+ /** Silence on the stream for this long counts as a drop. Keep-alives come every 15 s. */
+ idleMs?: number;
+ /** Stream reconnects before falling back to polling. */
+ maxReconnects?: number;
}
/**
@@ -222,12 +322,17 @@ export interface WatchOptions {
export type WatchOutcome = "completed" | "building" | "failed" | "timed_out" | "unreachable";
/**
- * Hold until the brain has rules, printing each stage as it settles.
+ * Hold until the brain has rules, reporting each stage as it settles.
*
* Returns on the first rules rather than on the finished job: mining is what
* fails and it is done by then, and filing the rest is minutes of work nobody
* needs to watch. The caller prints where to see the rest.
*
+ * Live when the server streams events: each change arrives as it happens
+ * instead of up to four seconds late. A stream that drops is reopened up to
+ * three times, and after that the watcher polls as it always did — so the
+ * worst a broken stream costs is the old behaviour.
+ *
* Fifteen minutes by default. That is far more than the mining now takes, and it
* stays generous on purpose: a watcher that gives up before the build does would
* report a healthy build as a timeout, which is the exact confusion this is
@@ -238,32 +343,182 @@ export async function watchBuild(link: BrainLink, opts: WatchOptions = {}): Prom
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?.()));
+ // Not unref'd: between polls this timer is the only thing the process is
+ // waiting on, and an unref'd one let it exit mid-watch with nothing printed.
+ const sleep = opts.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+ const fetchImpl = opts.fetchImpl ?? fetch;
+ const stageLines = opts.stageLines !== false;
const printed = new Set<string>();
const startedAt = Date.now();
+ const deadline = startedAt + timeoutMs;
// 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";
+ /** One state read → the outcome it settles, or null to keep watching. */
+ const settle = (repo: RepoState | null): WatchOutcome | null => {
+ if (!repo) return null;
+ everRead = true;
+ const view = stagesFrom(repo);
+ opts.onState?.(view, repo);
+ if (stageLines) for (const line of linesFor(view, printed, repo)) write(line);
+ if (view.error) {
+ for (const line of failureLines(view)) write(line);
+ return "failed";
+ }
+ if (view.done) return "completed";
+ // The ordinary ending now. The job is still filing the rules the miner
+ // has handed over, and still mining the older slices of the history, and
+ // neither is worth a terminal sitting on it.
+ if (view.ready) return "building";
+ return null;
+ };
+
+ if (opts.events) {
+ let drops = 0;
+ const maxReconnects = opts.maxReconnects ?? 3;
+ while (drops <= maxReconnects && Date.now() < deadline) {
+ const r = await streamOnce(link, fetchImpl, settle, deadline, opts.idleMs ?? 45_000);
+ if (r.outcome) return r.outcome;
+ if (r.end === "unsupported" || r.end === "deadline") break;
+ if (r.end === "done") {
+ // The build ended without the event saying how: read the row once.
+ const final = settle(await fetchRepoState(link, fetchImpl));
+ if (final) return final;
+ break;
}
- if (view.done) return "completed";
- // The ordinary ending now. The job is still filing the rules the miner
- // has handed over, and still mining the older slices of the history, and
- // neither is worth a terminal sitting on it.
- if (view.ready) return "building";
+ drops++;
+ if (drops <= maxReconnects) await sleep(Math.min(1000 * drops, 4000));
}
- if (Date.now() - startedAt >= timeoutMs) return everRead ? "timed_out" : "unreachable";
+ }
+
+ for (;;) {
+ const outcome = settle(await fetchRepoState(link, fetchImpl));
+ if (outcome) return outcome;
+ if (Date.now() >= deadline) return everRead ? "timed_out" : "unreachable";
await sleep(pollMs);
}
}
+
+/** One server-sent event. */
+export interface SseEvent {
+ event: string;
+ data: string;
+}
+
+/**
+ * An incremental text/event-stream parser: feed it chunks as they arrive,
+ * get back the events they completed. Comments (`: ping`) are dropped; a
+ * missing `event:` field means `message`, per the spec.
+ */
+export class SseParser {
+ private buf = "";
+ private event = "";
+ private data: string[] = [];
+
+ push(chunk: string): SseEvent[] {
+ this.buf += chunk;
+ const out: SseEvent[] = [];
+ for (;;) {
+ const nl = this.buf.search(/\r\n|\r|\n/);
+ if (nl < 0) break;
+ const sep = this.buf.startsWith("\r\n", nl) ? 2 : 1;
+ // A lone \r at the very end may be the first half of \r\n: wait for more.
+ if (this.buf[nl] === "\r" && sep === 1 && nl === this.buf.length - 1) break;
+ const line = this.buf.slice(0, nl);
+ this.buf = this.buf.slice(nl + sep);
+ if (line === "") {
+ if (this.data.length > 0) out.push({ event: this.event || "message", data: this.data.join("\n") });
+ this.event = "";
+ this.data = [];
+ continue;
+ }
+ if (line.startsWith(":")) continue;
+ const colon = line.indexOf(":");
+ const field = colon < 0 ? line : line.slice(0, colon);
+ let value = colon < 0 ? "" : line.slice(colon + 1);
+ if (value.startsWith(" ")) value = value.slice(1);
+ if (field === "event") this.event = value;
+ else if (field === "data") this.data.push(value);
+ // id and retry are not used: a reconnect starts from a fresh `progress`.
+ }
+ return out;
+ }
+}
+
+type StreamEnd = "done" | "dropped" | "unsupported" | "deadline";
+
+/**
+ * One connection to `GET /events`. Resolves with the outcome when an event
+ * settled the watch, or with how the stream ended when none did.
+ */
+async function streamOnce(
+ link: BrainLink,
+ fetchImpl: typeof fetch,
+ settle: (repo: RepoState | null) => WatchOutcome | null,
+ deadline: number,
+ idleMs: number,
+): Promise<{ outcome?: WatchOutcome; end?: StreamEnd }> {
+ const ctl = new AbortController();
+ let res: Response;
+ try {
+ res = await fetchImpl(`${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/events`, {
+ headers: { authorization: `Bearer ${link.token}`, accept: "text/event-stream", "cache-control": "no-cache" },
+ signal: ctl.signal,
+ });
+ } catch {
+ return { end: "dropped" };
+ }
+ // A server without the route, or one that answered with something other
+ // than a stream: polling is the answer, not three more tries.
+ if (res.status === 404 || res.status === 405 || res.status === 501) return { end: "unsupported" };
+ if (!res.ok) return { end: "dropped" };
+ const type = res.headers?.get?.("content-type") ?? "text/event-stream";
+ if (!res.body || !/event-stream/i.test(type)) return { end: "unsupported" };
+
+ const reader = res.body.getReader();
+ const decoder = new TextDecoder();
+ const parser = new SseParser();
+ try {
+ for (;;) {
+ const left = deadline - Date.now();
+ if (left <= 0) return { end: "deadline" };
+ let timer: NodeJS.Timeout | undefined;
+ const idle = new Promise<"idle">((r) => {
+ // Not unref'd: while the stream is quiet this timer is what the
+ // process is waiting on, and it is cleared the moment a chunk lands.
+ timer = setTimeout(() => r("idle"), Math.min(idleMs, left));
+ });
+ const got = await Promise.race([reader.read(), idle]).finally(() => clearTimeout(timer));
+ if (got === "idle") return { end: Date.now() >= deadline ? "deadline" : "dropped" };
+ if (got.done) return { end: "dropped" };
+ for (const ev of parser.push(decoder.decode(got.value, { stream: true }))) {
+ let payload: unknown = null;
+ try {
+ payload = ev.data ? JSON.parse(ev.data) : null;
+ } catch {
+ payload = null;
+ }
+ if (ev.event === "progress" || ev.event === "message") {
+ const outcome = settle(parseRepoBody(payload));
+ if (outcome) return { outcome };
+ } else if (ev.event === "done") {
+ const outcome = settle(parseRepoBody(payload));
+ if (outcome) return { outcome };
+ return { end: "done" };
+ }
+ }
+ }
+ } catch {
+ return { end: "dropped" };
+ } finally {
+ ctl.abort();
+ try {
+ reader.releaseLock();
+ } catch {
+ /* already released by the abort */
+ }
+ }
+}
diff --git a/src/claude/build-progress.ts b/src/claude/build-progress.ts
new file mode 100644
index 00000000..035bf160
--- /dev/null
+++ b/src/claude/build-progress.ts
@@ -0,0 +1,83 @@
+/**
+ * `graft build`, run from `graft init` as one line that redraws in place.
+ *
+ * `buildGraphIfMissing` hands the child the terminal, which prints a `parsing
+ * N/M: path` line and four more after it. That is the right output for someone
+ * who ran `graft build`, and five lines of someone else's output in the middle
+ * of init. Here the child's output is read instead: its progress becomes the
+ * spinner's `1,204 of 1,942 files`, its totals become init's one summary line,
+ * and any warning or error it printed is passed on whole.
+ */
+import { spawn } from "node:child_process";
+import { hasGraftIndex } from "../graph/root.js";
+import { startSpinner } from "../util/spinner.js";
+
+export interface BuiltGraph {
+ nodes: number;
+ edges: number;
+ files: number;
+}
+
+const n = (s: string | undefined) => Number((s ?? "0").replace(/,/g, "")) || 0;
+
+/** The totals out of `graft build`'s stdout, or null when it printed none. */
+export function parseBuildSummary(stdout: string): BuiltGraph | null {
+ const wiring = /✓ wiring: ([\d,]+) nodes.*?, ([\d,]+) edges/.exec(stdout);
+ if (!wiring) return null;
+ const parsed = /parsed: [\d,]+ of ([\d,]+) files/.exec(stdout);
+ return { nodes: n(wiring[1]), edges: n(wiring[2]), files: n(parsed?.[1]) };
+}
+
+/** The last `parsing N/M` in a chunk of the child's stderr. */
+export function parseProgress(chunk: string): { index: number; total: number } | null {
+ let last: { index: number; total: number } | null = null;
+ for (const m of chunk.matchAll(/(?:parsing|summarizing) (\d+)\/(\d+)/g)) last = { index: n(m[1]), total: n(m[2]) };
+ return last;
+}
+
+/**
+ * Build the graph for `dir` unless it has one, showing progress on a spinner.
+ *
+ * `built: false` with no `failed` means there was nothing to do (`--no-build`,
+ * or a graph already there). Warning and error lines the build printed come
+ * back in `messages`, for the caller to print in full.
+ */
+export async function buildGraphWithProgress(
+ dir: string,
+ opts: { build?: boolean; cliPath?: string },
+): Promise<{ built: boolean; graph?: BuiltGraph; failed?: boolean; messages: string[] }> {
+ if (opts.build === false || !opts.cliPath || hasGraftIndex(dir)) return { built: false, messages: [] };
+ const spinner = startSpinner("building the graph");
+ let stdout = "";
+ let stderr = "";
+ const fmt = (x: number) => x.toLocaleString("en-US");
+ const code = await new Promise<number | null>((resolve) => {
+ const child = spawn(process.execPath, [...process.execArgv, opts.cliPath!, "build", "."], {
+ cwd: dir,
+ stdio: ["ignore", "pipe", "pipe"],
+ });
+ const timer = setTimeout(() => child.kill(), 300_000);
+ timer.unref?.();
+ child.stdout.setEncoding("utf8");
+ child.stderr.setEncoding("utf8");
+ child.stdout.on("data", (d: string) => (stdout += d));
+ child.stderr.on("data", (d: string) => {
+ stderr += d;
+ const p = parseProgress(d);
+ if (p) spinner.update(`building the graph · ${fmt(p.index)} of ${fmt(p.total)} files`);
+ });
+ child.on("error", () => resolve(null));
+ child.on("close", (c) => {
+ clearTimeout(timer);
+ resolve(c);
+ });
+ });
+ spinner.stop();
+ const messages = `${stdout}\n${stderr.replace(/\r[^\n]*/g, "\n")}`
+ .split("\n")
+ .map((l) => l.trimEnd())
+ .filter((l) => /^\s*[⚠✗]/.test(l));
+ const graph = parseBuildSummary(stdout) ?? undefined;
+ if (code !== 0) return { built: false, failed: true, messages };
+ return { built: true, graph, messages };
+}
diff --git a/src/cli-picker.ts b/src/cli-picker.ts
index 40b0db4c..6e0b816a 100644
--- a/src/cli-picker.ts
+++ b/src/cli-picker.ts
@@ -56,6 +56,43 @@ export function describeWrites(
return parts.join(' · ');
}
+/**
+ * The picker's and init's one-line summary: at most two repo entries, a folder
+ * written into several times shown once as `folder/` when something else sits
+ * beside it, then the count of writes outside the repo. `.claude/, .mcp.json ·
+ * + 3 in ~/` rather than five paths nobody reads.
+ */
+export function compactWrites(writes: PlannedWrite[], repo: string, home: string, maxShown = 2): string {
+ const repoPaths = writes.filter((w) => w.scope === 'repo').map((w) => relative(repo, w.path));
+ const tops = new Map<string, string[]>();
+ for (const p of repoPaths) {
+ const top = p.split(sep)[0] ?? p;
+ const list = tops.get(top) ?? [];
+ list.push(p);
+ tops.set(top, list);
+ }
+ const entries: string[] = [];
+ if (tops.size >= 2) {
+ for (const [top, paths] of tops) entries.push(paths.length >= 2 ? `${top}${sep}` : paths[0]!);
+ } else {
+ entries.push(...repoPaths);
+ }
+ const parts: string[] = [];
+ if (entries.length > 0) {
+ parts.push(
+ entries.length <= maxShown
+ ? entries.join(', ')
+ : `${entries.slice(0, maxShown).join(', ')} +${entries.length - maxShown} more`,
+ );
+ }
+ const globals = writes.filter((w) => w.scope === 'global');
+ if (globals.length > 0) {
+ const where = tilde(commonDir(globals.map((w) => w.path)), home);
+ parts.push(`+ ${globals.length} in ${where}${where.endsWith(sep) ? '' : sep}`);
+ }
+ return parts.join(' · ');
+}
+
export interface PickerRow {
id: string;
detected: boolean;
@@ -85,10 +122,18 @@ export const TELEMETRY_ROW_ID = '__telemetry';
export interface PickerState {
rows: PickerRow[];
+ /** Index into {@link visibleRows}, not into `rows`. */
cursor: number;
checked: ReadonlySet<string>;
done: boolean;
aborted: boolean;
+ /** Agents graft cannot find on this machine are folded into one line until `m`. */
+ showHidden?: boolean;
+}
+
+/** The rows on screen: undetected agents only once `m` has unfolded them. */
+export function visibleRows(state: PickerState): PickerRow[] {
+ return state.rows.filter((r) => r.kind === 'setting' || r.detected || state.showHidden);
}
/**
@@ -108,7 +153,7 @@ export function initialPickerState(
label: p.id,
kind: 'host' as const,
detected: p.detected,
- summary: describeWrites(p.writes, repo, home),
+ summary: compactWrites(p.writes, repo, home),
hasGlobal: p.writes.some((w) => w.scope === 'global'),
}));
const checked = new Set(plan.some((p) => p.id === 'claude') ? ['claude'] : []);
@@ -118,7 +163,7 @@ export function initialPickerState(
label: 'anonymous usage stats',
kind: 'setting',
detected: true,
- summary: 'no code, no file paths, no queries · TELEMETRY.md',
+ summary: 'no code, no file paths, no queries',
hasGlobal: false,
});
checked.add(TELEMETRY_ROW_ID);
@@ -126,7 +171,7 @@ export function initialPickerState(
return { rows, cursor: 0, checked, done: false, aborted: false };
}
-export type PickerKey = 'up' | 'down' | 'space' | 'all' | 'enter' | 'abort';
+export type PickerKey = 'up' | 'down' | 'space' | 'all' | 'more' | 'enter' | 'abort';
export const KEY_UP = '\x1b[A';
export const KEY_DOWN = '\x1b[B';
@@ -140,6 +185,7 @@ export function keyOf(chunk: string): PickerKey | null {
case KEY_DOWN: case 'j': return 'down';
case ' ': return 'space';
case 'a': return 'all';
+ case 'm': return 'more';
case '\r': case '\n': return 'enter';
case KEY_ESC: case KEY_CTRL_C: case 'q': return 'abort';
default: return null;
@@ -173,7 +219,8 @@ export function keysOf(chunk: string): PickerKey[] {
}
export function reducePicker(state: PickerState, key: PickerKey): PickerState {
- const n = state.rows.length;
+ const visible = visibleRows(state);
+ const n = visible.length;
switch (key) {
case 'up':
return { ...state, cursor: (state.cursor - 1 + n) % n };
@@ -181,20 +228,37 @@ export function reducePicker(state: PickerState, key: PickerKey): PickerState {
return { ...state, cursor: (state.cursor + 1) % n };
case 'space': {
const next = new Set(state.checked);
- const id = state.rows[state.cursor].id;
+ const id = visible[state.cursor]!.id;
if (next.has(id)) next.delete(id); else next.add(id);
return { ...state, checked: next };
}
case 'all': {
- // Hosts only. `a` means "wire everything"; a user who pressed it to select
- // every agent has not thereby said anything about usage stats, so whatever
- // they chose on that row survives untouched.
- const hosts = state.rows.filter((r) => r.kind === 'host');
+ // The agents on screen only: `a` must never select one the user cannot
+ // see. And agents only — a user who pressed it to select every agent has
+ // not thereby said anything about usage stats, so whatever they chose on
+ // that row survives untouched.
+ const hosts = visible.filter((r) => r.kind === 'host');
const allOn = hosts.every((r) => state.checked.has(r.id));
- const next = new Set(state.rows.filter((r) => r.kind === 'setting' && state.checked.has(r.id)).map((r) => r.id));
- if (!allOn) for (const r of hosts) next.add(r.id);
+ const next = new Set(state.checked);
+ for (const r of hosts) {
+ if (allOn) next.delete(r.id);
+ else next.add(r.id);
+ }
return { ...state, checked: next };
}
+ case 'more': {
+ if (!state.rows.some((r) => r.kind === 'host' && !r.detected)) return state;
+ // Keep the cursor on the row it was on, wherever that row lands.
+ const at = visible[state.cursor]?.id;
+ const toggled = { ...state, showHidden: !state.showHidden };
+ const after = visibleRows(toggled);
+ // Folding away the row under the cursor puts the cursor back at the top.
+ const idx = after.findIndex((r) => r.id === at);
+ // Anything the fold hides is unchecked, so nothing invisible gets wired.
+ const checked = new Set(state.checked);
+ if (!toggled.showHidden) for (const r of state.rows) if (r.kind === 'host' && !r.detected) checked.delete(r.id);
+ return { ...toggled, cursor: idx >= 0 ? idx : 0, checked };
+ }
case 'enter':
return { ...state, done: true };
case 'abort':
@@ -202,33 +266,49 @@ export function reducePicker(state: PickerState, key: PickerKey): PickerState {
}
}
-export function renderPicker(state: PickerState, tty = true): string {
+export function renderPicker(state: PickerState, tty = true, opts: { title?: string | null } = {}): string {
const dim = tty ? muted : (s: string) => s;
const hot = tty ? indigo : (s: string) => s;
const warn = tty ? amber : (s: string) => s;
+ const visible = visibleRows(state);
+ const hidden = state.rows.filter((r) => r.kind === 'host' && !r.detected);
// Pad on the plain label so the summary column lines up regardless of which
// rows carry the '(not detected)' tag or the cursor's colour codes.
- const label = (r: PickerRow) => `${r.label}${r.detected ? '' : ' (not detected)'}`;
- const width = Math.max(...state.rows.map((r) => label(r).length));
- const lines = ['graft init — select what to wire into this repo:', ''];
+ const label = (r: PickerRow) => `${r.label}${r.detected || r.kind === 'setting' ? '' : ' (not detected)'}`;
+ const width = Math.max(...visible.filter((r) => r.kind === 'host').map((r) => label(r).length), 12);
+ const title = opts.title === undefined ? 'graft init — pick the agents your team uses:' : opts.title;
+ const lines = title ? [title, ''] : [];
let ruled = false;
- for (const [i, row] of state.rows.entries()) {
+ const foldLine = () => {
+ if (hidden.length === 0) return;
+ lines.push(
+ dim(
+ state.showHidden
+ ? ` m to fold the ${hidden.length} not detected`
+ : ` + ${hidden.length} not detected (${hidden.map((r) => r.label).join(', ')}) · m to show`,
+ ),
+ );
+ };
+ for (const [i, row] of visible.entries()) {
// One rule between the agents and the settings, so the consent row reads as
// a separate question rather than as another thing being installed.
if (row.kind === 'setting' && !ruled) {
- lines.push(dim(` ${'─'.repeat(width + 24)}`));
+ foldLine();
+ lines.push(dim(` ${'─'.repeat(40)}`));
ruled = true;
}
const here = i === state.cursor;
const box = state.checked.has(row.id) ? '[x]' : '[ ]';
- const gap = ' '.repeat(width - label(row).length);
+ const gap = ' '.repeat(Math.max(0, width - label(row).length));
const name = here ? hot(row.label) : row.label;
const tag = row.detected || row.kind === 'setting' ? '' : dim(' (not detected)');
const summary = row.hasGlobal ? warn(row.summary) : dim(row.summary);
- lines.push(`${here ? '›' : ' '} ${box} ${name}${tag}${gap} ${summary}`);
+ lines.push(`${here ? '›' : ' '} ${box} ${name}${tag}${gap} ${summary}`);
}
- lines.push('', dim('↑↓ move · space toggle · a all · enter confirm · esc cancel'));
+ if (!ruled) foldLine();
+ const keys = ['↑↓ move', 'space toggle', 'a all', ...(hidden.length ? ['m more'] : []), 'enter confirm', 'esc cancel'];
+ lines.push('', dim(keys.join(' · ')));
return lines.join('\n');
}
@@ -265,7 +345,7 @@ export async function runPicker(
plan: HostPlan[],
repo: string,
home: string,
- opts: { offerTelemetry?: boolean } = {},
+ opts: { offerTelemetry?: boolean; title?: string | null } = {},
): Promise<Picked | null> {
let state = initialPickerState(plan, repo, home, opts);
const out = process.stderr;
@@ -274,7 +354,7 @@ export async function runPicker(
let lastLines = 0;
const draw = () => {
if (lastLines > 0) out.write(`\x1b[${lastLines}A\x1b[0J`);
- const text = renderPicker(state);
+ const text = renderPicker(state, true, { title: opts.title });
out.write(`${text}\n`);
lastLines = text.split('\n').length;
};
@@ -291,7 +371,10 @@ export async function runPicker(
const finish = (onData: (b: Buffer) => void) => {
stdin.off('data', onData);
stdin.off('end', onEnd);
- draw();
+ // Erased, not redrawn: the choice is reported by what init prints next,
+ // and an interactive widget left in the scrollback is noise.
+ if (lastLines > 0) out.write(`\x1b[${lastLines}A\x1b[0J`);
+ lastLines = 0;
resolve(state.aborted ? null : { hosts: pickedHostIds(state), telemetry: pickedTelemetry(state) });
};
const onData = (buf: Buffer) => {
diff --git a/src/cli.ts b/src/cli.ts
index e3d64c78..f8c661a4 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -24,22 +24,25 @@ import {
buildEarlyDigest,
buildLocalDigest,
fetchExpectedRepo,
+ pushContext,
pushDigest,
pushEarlyDigest,
repoSlugFromGit,
sameRepo,
+ uploadCaps,
} from "./brain/push.js";
-import type { HistoryThread } from "./app/history.js";
import { readLink, writeLink } from "./brain/link.js";
import { withLegacyNames } from "./legacy-args.js";
-import { applyChanges, fetchAcceptedChanges, markApplied } from "./brain/claude-md.js";
-import { watchBuild } from "./brain/watch.js";
-import { openBrowser, signupUrl, startHandoff } from "./brain/signup.js";
+import { currentStage, DOING_LABEL, rulesSoFar, watchBuild, type RepoState, type Suggestions } from "./brain/watch.js";
+import { brainUrl, openBrowser, reviewUrl, signupUrl, startHandoff } from "./brain/signup.js";
+import { runTrailPull } from "./brain/pull.js";
+import { readByWired, readersOf } from "./brain/context-files.js";
+import { startSpinner } from "./util/spinner.js";
import { contextDirFor } from "./context/node-file.js";
import { loadGraphCached } from "./graph/load.js";
import { ensureFreshChildren, ensureFreshGraph, refreshNote } from "./graph/refresh.js";
import { isWorkspaceBuildRoot, readWorkspace } from "./graph/workspace.js";
-import { nearestGraftRoot } from "./graph/root.js";
+import { hasGraftIndex, nearestGraftRoot } from "./graph/root.js";
import { unsupportedExtensions, supportedExtensions } from "./graph/source-files.js";
import { discoverWorkspaceChildren } from "./graph/scopes.js";
import {
@@ -53,14 +56,15 @@ import {
import { formatInitEpilogue } from "./cli-epilogue.js";
import { planInit, selectedWrites } from "./hosts/plan.js";
import { planRetract, runRetract, changed, type Retraction } from "./hosts/retract.js";
-import { formatNonInteractiveHelp, formatPlan, runPicker } from "./cli-picker.js";
+import { compactWrites, formatNonInteractiveHelp, formatPlan, runPicker } from "./cli-picker.js";
+import { buildGraphWithProgress } from "./claude/build-progress.js";
import { homedir } from "node:os";
import { formatUpgradeReport, formatVersionReport, getNpmViewVersion, readCurrentVersion, runUpgrade } from "./cli-meta.js";
import { patchBuildConfig, type BuildConfig } from "./util/state.js";
import { normalizePathPrefix } from "./util/paths.js";
import { latestSession, formatSessionStats, sessionInputRate } from "./claude/session-metrics.js";
import { setInputRate } from "./context/savings.js";
-import { formatUpdateNudge, maybeRefreshInBackground, readUpdateCache, refreshUpdateCache, wiredHostIds, writeStamp } from "./upkeep.js";
+import { formatUpdateNudge, maybeRefreshInBackground, readStamp, readUpdateCache, refreshUpdateCache, wiredHostIds, writeStamp } from "./upkeep.js";
import {
errorCode,
filesBucket,
@@ -960,10 +964,24 @@ program
.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)")
.option("--trail <handoff>", "attach a Trail: <brainId>:<token> (or a bare id with GRAFT_BRAIN_TOKEN set)")
- .action((dir: string, opts: InitOptions) => runInitCommand(dir, opts));
+ .option("--verbose", "print every file written, the graph build's own output and the closing banner")
+ .action(async (dir: string, opts: InitOptions) => {
+ await runInitCommand(dir, opts);
+ });
/** `graft init`'s flags, as commander hands them over. */
-interface InitOptions { build?: boolean; agents?: string[]; allAgents?: boolean; listAgents?: boolean; mcp?: boolean; hooks?: boolean; statusline?: boolean; dryRun?: boolean; yes?: boolean; global?: boolean; trail?: string }
+interface InitOptions { build?: boolean; agents?: string[]; allAgents?: boolean; listAgents?: boolean; mcp?: boolean; hooks?: boolean; statusline?: boolean; dryRun?: boolean; yes?: boolean; global?: boolean; trail?: string; verbose?: boolean }
+
+/** `a, b and c`. */
+function joinAnd(items: string[]): string {
+ if (items.length <= 1) return items.join("");
+ return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+}
+
+/** Repo-relative with forward slashes, for printing. */
+function shown(repo: string, path: string): string {
+ return relative(repo, path).split("\\").join("/");
+}
/**
* `graft init`. Also run by `graft trail push` on a repo graft has not been set
@@ -971,10 +989,14 @@ interface InitOptions { build?: boolean; agents?: string[]; allAgents?: boolean;
* coding agent reads is only half set up. `epilogue: false` leaves out the
* closing banner when push is going to keep talking.
*/
-async function runInitCommand(dir: string, opts: InitOptions, how: { epilogue?: boolean } = {}): Promise<void> {
+async function runInitCommand(
+ dir: string,
+ opts: InitOptions,
+ how: { epilogue?: boolean; push?: boolean } = {},
+): Promise<{ ids: string[] } | null> {
if (opts.listAgents) {
for (const id of [...hostIds(), "claude"]) console.log(id);
- return;
+ return null;
}
// 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.
@@ -984,7 +1006,7 @@ async function runInitCommand(dir: string, opts: InitOptions, how: { epilogue?:
if ("error" in parsed) {
console.error(`✗ --trail: ${parsed.error}`);
process.exitCode = 1;
- return;
+ return null;
}
brainLink = parsed;
}
@@ -1023,16 +1045,18 @@ async function runInitCommand(dir: string, opts: InitOptions, how: { epilogue?:
const reason = offReason();
const picked = await runPicker(plan, repo, home, {
offerTelemetry: reason === null || reason === "disabled",
+ // From push, the line above the picker already asks the question.
+ ...(how.push ? { title: null } : {}),
});
if (picked === null) {
console.error("· cancelled — nothing written");
- return;
+ return null;
}
ids = picked.hosts;
consent = picked.telemetry;
} else {
console.error(formatNonInteractiveHelp(detectedIds));
- return;
+ return null;
}
// The picker's answer, recorded before anything is wired: a user who
@@ -1056,11 +1080,11 @@ async function runInitCommand(dir: string, opts: InitOptions, how: { epilogue?:
console.error(formatPlan(plan, ids, repo, home));
for (const child of children)
console.error(`\n— ${child}/ (workspace child)\n` + formatPlan(planInit(join(repo, child), { home }), ids, join(repo, child), home));
- return;
+ return null;
}
if (ids.length === 0) {
console.error("· no agents selected — nothing written");
- return;
+ return null;
}
const wantClaude = ids.includes("claude");
@@ -1069,9 +1093,60 @@ async function runInitCommand(dir: string, opts: InitOptions, how: { epilogue?:
if (children.length)
console.error(`· workspace: wiring ${repo} and ${children.length} child repo(s) — ${children.join(", ")}`);
+ // Today's output, file by file, behind --verbose. Everything else gets one
+ // line per step: the graph, then one per agent.
+ const verbose = opts.verbose === true;
+ const reports: WireReport[] = [];
for (const target of targets) {
- if (target !== repo) console.error(`\n— ${relative(repo, target)}/`);
- wireTarget(target, ids, { home, cliPath, plan, opts, wantClaude });
+ if (verbose && target !== repo) console.error(`\n— ${relative(repo, target)}/`);
+ reports.push(wireTarget(target, ids, { home, cliPath, plan, opts, wantClaude, quiet: !verbose }));
+ }
+
+ // The graph, built once after the wiring: a workspace parent's build is
+ // the workspace build, so it covers every child.
+ let graphLine: string | null = null;
+ let graphNodes = 0;
+ if (!verbose) {
+ const res = await buildGraphWithProgress(repo, { build: opts.build, cliPath });
+ for (const m of res.messages) console.error(m);
+ const existing = res.built ? null : loadGraphCached(contextDirFor(repo, children.length ? undefined : program.opts<GlobalOpts>().dir));
+ const fmt = (x: number) => x.toLocaleString("en-US");
+ if (res.graph) {
+ graphNodes = res.graph.nodes;
+ graphLine = `✓ graph built · ${fmt(res.graph.nodes)} nodes, ${fmt(res.graph.edges)} edges${res.graph.files ? ` from ${fmt(res.graph.files)} file${res.graph.files === 1 ? "" : "s"}` : ""}`;
+ } else if (res.built) {
+ graphLine = "✓ graph built";
+ } else if (res.failed) {
+ graphLine = "⚠ the graph build failed — run graft build to see why";
+ } else if (existing) {
+ graphNodes = existing.meta.nodeCount;
+ graphLine = `✓ graph ready · ${fmt(existing.meta.nodeCount)} nodes, ${fmt(existing.meta.edgeCount)} edges`;
+ } else if (hasGraftIndex(repo)) {
+ graphLine = "✓ graph ready";
+ } else {
+ graphLine = "· skipped the graph build — run graft build";
+ }
+ }
+
+ if (!verbose) {
+ // Warnings and removals in full, whatever else is folded.
+ const removed = [...new Set(reports.flatMap((r) => r.retracted))];
+ for (const id of removed) console.error(`- removed ${id} — agent not selected`);
+ for (const w of reports.flatMap((r) => r.warnings)) console.error(w);
+ const writesFor = (id: string) =>
+ (plan.find((p) => p.id === id)?.writes ?? []).filter((w) => opts.global !== false || w.scope !== "global");
+ if (how.push) {
+ const built = graphLine?.startsWith("✓ graph built") ? `graph built, ${graphNodes.toLocaleString("en-US")} nodes` : graphLine?.startsWith("✓") ? "graph ready" : null;
+ console.error(`✓ wired ${joinAnd(ids)}${built ? ` · ${built}` : ""}`);
+ if (graphLine && !graphLine.startsWith("✓")) console.error(graphLine);
+ } else {
+ if (graphLine) console.error(graphLine);
+ const width = Math.max(...ids.map((id) => id.length));
+ for (const id of ids) {
+ const summary = compactWrites(writesFor(id), repo, home);
+ console.error(`✓ ${id.padEnd(width)} ${summary}`.trimEnd());
+ }
+ }
}
// The brain comes last, after the graph exists: its rules are anchored to
@@ -1079,11 +1154,35 @@ async function runInitCommand(dir: string, opts: InitOptions, how: { epilogue?:
// 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");
+ if (verbose) {
+ 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");
+ } else if (res.warning) {
+ console.error(`⚠ trail: ${res.warning}`);
+ } else if (res.ruleCount === 0) {
+ console.error("✓ trail connected · no rules yet — graft trail push reads this repo into it");
+ } else {
+ const where = res.writes.map((w) => shown(repo, w.path)).join(", ");
+ const n = `${res.ruleCount.toLocaleString("en-US")} rule${res.ruleCount === 1 ? "" : "s"}`;
+ console.error(`✓ trail connected · ${n}${where ? ` in ${where}` : ""}`);
+ }
+ }
+
+ if (!verbose && how.epilogue !== false) {
+ // What there is to commit: the top-level entries the picked agents wrote.
+ const tops: string[] = [];
+ for (const w of selectedWrites(plan, ids)) {
+ if (w.scope !== "repo") continue;
+ const parts = shown(repo, w.path).split("/");
+ const top = parts.length > 1 ? `${parts[0]}/` : parts[0]!;
+ if (!tops.includes(top)) tops.push(top);
+ }
+ console.error("· restart your agents so a new session picks up graft");
+ if (tops.length)
+ console.error(`· commit ${tops.slice(0, 4).join(" ")}${tops.length > 4 ? ` +${tops.length - 4} more` : ""} to share it — graft/ stays local and git-ignored`);
}
// One epilogue for the whole run. A workspace parent holds no nodes of its
@@ -1092,7 +1191,7 @@ async function runInitCommand(dir: string, opts: InitOptions, how: { epilogue?:
const graphs = (children.length ? children.map((c) => join(repo, c)) : [repo])
.map((d) => loadGraphCached(contextDirFor(d, children.length ? undefined : globalDir)))
.filter((g): g is NonNullable<typeof g> => g !== null);
- if (how.epilogue !== false) console.error(
+ if (verbose && how.epilogue !== false) console.error(
"\n" +
formatInitEpilogue({
graphBuilt: graphs.length > 0,
@@ -1106,6 +1205,15 @@ async function runInitCommand(dir: string, opts: InitOptions, how: { epilogue?:
{ agents: [...ids].sort().join(","), consent: consent === undefined ? "unasked" : String(consent) },
{ repo },
);
+ return { ids };
+}
+
+/** What one target's wiring did, for the compact summary to report. */
+interface WireReport {
+ /** Hosts whose files were removed because they were not selected. */
+ retracted: string[];
+ /** ⚠ lines, printed in full. */
+ warnings: string[];
}
/** One repo's worth of `init` writes — the parent, then each workspace child. */
@@ -1118,9 +1226,20 @@ function wireTarget(
plan: ReturnType<typeof planInit>;
wantClaude: boolean;
opts: { build?: boolean; mcp?: boolean; hooks?: boolean; global?: boolean; statusline?: boolean };
+ /** Collect warnings and removals instead of printing a line per file, and
+ * leave the graph build to the caller (see buildGraphWithProgress). */
+ quiet?: boolean;
},
-): void {
- const { home, cliPath, plan, wantClaude, opts } = ctx;
+): WireReport {
+ const { home, cliPath, plan, wantClaude } = ctx;
+ const quiet = ctx.quiet === true;
+ const opts = quiet ? { ...ctx.opts, build: false } : ctx.opts;
+ const report: WireReport = { retracted: [], warnings: [] };
+ // Every per-file line goes through here; in quiet mode only ⚠ lines survive.
+ const say = (line: string) => {
+ if (!quiet) console.error(line);
+ else if (line.startsWith("⚠")) report.warnings.push(line);
+ };
const wantStatusline = statuslineWanted({ statusline: opts.statusline });
// Converge, don't just add. init writes the selected hosts; without this it
@@ -1132,25 +1251,26 @@ function wireTarget(
const retracted = changed(
runRetract(repo, { home, apply: true, global: opts.global, cache: false, exclude: ids }),
).filter((r) => r.action !== "skipped-unparseable");
- for (const r of retracted) console.error(`- removed ${r.path} (${r.what}) — agent not selected`);
+ for (const r of retracted) say(`- removed ${r.path} (${r.what}) — agent not selected`);
+ report.retracted = [...new Set(retracted.map((r) => r.hostId))];
if (wantClaude) {
// `global`/`home` are threaded through alongside `statusline`: the claude layer
// writes under `~/.claude` now (hosts/claude-global.ts), so --no-global has to
// reach it or the flag would silently mean "no out-of-repo writes, except three".
const res = runInit(repo, { build: opts.build, cliPath, statusline: wantStatusline, global: opts.global, home });
- console.error(`✓ wrote ${res.settingsPath}`);
- for (const s of res.shims) console.error(`✓ wrote ${s}`);
- console.error(`✓ wrote ${res.skill}`);
+ say(`✓ wrote ${res.settingsPath}`);
+ for (const s of res.shims) say(`✓ wrote ${s}`);
+ say(`✓ wrote ${res.skill}`);
if (res.mcp.action === "skipped-unparseable")
- console.error(`⚠ .mcp.json: ${res.mcp.path} left unchanged (not valid JSON) — add the graft server manually`);
+ say(`⚠ .mcp.json: ${res.mcp.path} left unchanged (not valid JSON) — add the graft server manually`);
else if (res.mcp.action === "unchanged")
- console.error(`· mcp claude: ${res.mcp.path} (already registered)`);
+ say(`· mcp claude: ${res.mcp.path} (already registered)`);
else
- console.error(`✓ mcp claude: ${res.mcp.path} (${res.mcp.action}) — restart Claude Code to load the graft MCP server`);
- console.error(res.built ? "✓ built the graph (graft build)" : "· skipped graph build");
- if (!wantStatusline) console.error("· skipped Claude Code statusLine (--no-statusline)");
- for (const w of res.warnings) console.error(`⚠ ${w}`);
+ say(`✓ mcp claude: ${res.mcp.path} (${res.mcp.action}) — restart Claude Code to load the graft MCP server`);
+ say(res.built ? "✓ built the graph (graft build)" : "· skipped graph build");
+ if (!wantStatusline) say("· skipped Claude Code statusLine (--no-statusline)");
+ for (const w of res.warnings) say(`⚠ ${w}`);
}
// `ids` is already resolved, so hosts init is always driven by an explicit
@@ -1164,12 +1284,12 @@ function wireTarget(
hooks: opts.hooks,
global: opts.global,
});
- for (const w of r.written) console.error(`✓ ${w.id}: ${w.path} (${w.action})`);
- for (const m of r.mcp) console.error(`✓ mcp ${m.id}: ${m.path} (${m.action})`);
- for (const h of r.hooks) console.error(`✓ hook ${h.id}: ${h.path} (${h.action})`);
+ for (const w of r.written) say(`✓ ${w.id}: ${w.path} (${w.action})`);
+ for (const m of r.mcp) say(`✓ mcp ${m.id}: ${m.path} (${m.action})`);
+ for (const h of r.hooks) say(`✓ hook ${h.id}: ${h.path} (${h.action})`);
// Only worth saying when there was actually something out-of-repo to skip.
if (opts.global === false && selectedWrites(plan, ids).some((w) => w.scope === "global"))
- console.error("· skipped out-of-repo writes (--no-global)");
+ say("· skipped out-of-repo writes (--no-global)");
}
// Record WHICH graft wrote this repo's agent files, and under which flags.
@@ -1187,13 +1307,14 @@ function wireTarget(
// Every host's wiring points at graft/, so the graph is built whatever was
// selected — not only when Claude Code is in the list (runInit does its own).
if (!wantClaude) {
- console.error(
- buildGraphIfMissing(repo, { build: opts.build, cliPath })
- ? "✓ built the graph (graft build)"
- : "· skipped graph build",
- );
+ if (!quiet)
+ say(
+ buildGraphIfMissing(repo, { build: opts.build, cliPath })
+ ? "✓ built the graph (graft build)"
+ : "· skipped graph build",
+ );
}
-
+ return report;
}
/** Group a retraction report by host, so the output reads as "what leaves each agent". */
@@ -1265,12 +1386,13 @@ const brain = program
.description("The Trail attached to this repo: the rules mined from its own history");
/**
- * Get this repo a brain from the terminal, by sending the user through signup
+ * Get this repo a trail from the terminal, by sending the user through signup
* in their browser and catching the handoff on loopback.
*
* Returns the link, already saved, or null when the user should be left alone —
* every failure prints its own reason first, because the caller only needs to
- * know whether to carry on.
+ * know whether to carry on. Nothing about the repository has been read or sent
+ * by then, and every message says so.
*/
async function signUpForBrain(repo: string, slug: string): Promise<BrainLink | null> {
const handoff = await startHandoff();
@@ -1286,13 +1408,14 @@ async function signUpForBrain(repo: string, slug: string): Promise<BrainLink | n
// Printed before the browser opens, and printed whether or not it opens: on a
// remote shell nothing can open, and on a desktop the window sometimes lands
// behind the terminal. The URL is the thing that always works.
- console.error(`· ${slug} has no brain yet. Opening your browser to make one:`);
+ // "Opening your browser" only where one is about to open.
+ console.error(`· ${slug} has no trail yet — ${process.stderr.isTTY ? "opening your browser to make one" : "make one at"}:`);
console.error(` ${url}`);
// A non-interactive shell has nobody to click anything, so waiting five
// minutes for a browser that will never come is worse than saying so now.
if (!process.stderr.isTTY) {
- console.error("· not a terminal — open that link, then run `graft trail connect <brainId>:<token>` here");
+ console.error("· not a terminal — open the link above, then run graft trail connect <trailId>:<token> here");
// Its own outcome, not a timeout: nothing here could have opened a browser,
// so folding the two together would read as people abandoning signup when
// it is only a remote shell doing what it has to.
@@ -1302,9 +1425,25 @@ async function signUpForBrain(repo: string, slug: string): Promise<BrainLink | n
}
openBrowser(url);
- console.error("· waiting for you to finish signing up…");
-
- const got = await handoff.wait();
+ const spinner = startSpinner("waiting for you to finish signing up · Ctrl-C to stop");
+
+ // Ctrl-C while waiting is a person changing their mind, not a crash: say that
+ // nothing was sent, and leave with the usual interrupted exit code.
+ let onSigint: (() => void) | undefined;
+ const stopped = new Promise<"stopped">((resolve) => {
+ onSigint = () => resolve("stopped");
+ process.once("SIGINT", onSigint);
+ });
+ const got = await Promise.race([handoff.wait(), stopped]);
+ if (onSigint) process.off("SIGINT", onSigint);
+ spinner.stop();
+ if (got === "stopped") {
+ handoff.close();
+ console.error("· stopped — nothing was sent; run graft trail push again when you're ready");
+ track("brain_signup_settled", { outcome: "stopped", duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });
+ process.exitCode = 130;
+ return null;
+ }
if ("error" in got) {
console.error(`✗ ${got.error}`);
// The category, never the sentence: `got.error` names the repo and the link.
@@ -1312,7 +1451,7 @@ async function signUpForBrain(repo: string, slug: string): Promise<BrainLink | n
return null;
}
writeLink(repo, got.link);
- console.error(`✓ brain connected to ${slug}`);
+ console.error(`✓ trail connected · ${slug} — your browser shows it building`);
track("brain_signup_settled", { outcome: "linked", duration_bucket: durationBucket(Date.now() - startedAt) }, { repo });
return got.link;
}
@@ -1349,94 +1488,142 @@ brain
brain
.command("pull")
- .description("Re-pull the attached brain's rules and rewrite the agent instruction files")
+ .description("Refresh the trail's rules and write every change you accepted in Trail into this repo's context 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 trail 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})`);
+ .option("--dry-run", "show what would change without writing anything or telling Trail")
+ .action(async (dir: string, opts: { dryRun?: boolean }) => {
+ await runTrailPullCommand(dir, opts);
});
+/** `graft trail pull`, and `graft claude-md pull` which is now the same thing. */
+async function runTrailPullCommand(dir: string, opts: { dryRun?: boolean }): Promise<void> {
+ const repo = resolve(dir);
+ const link = readLink(repo);
+ if (!link) {
+ console.error("✗ this repo has no trail yet — run graft trail push first");
+ process.exitCode = 1;
+ return;
+ }
+ const stamp = readStamp(repo);
+ const wired = [...new Set([...(stamp?.hosts ?? []), ...wiredHostIds(repo)])];
+ const code = await runTrailPull(repo, link, { home: homedir(), wired, dryRun: opts.dryRun });
+ if (code !== 0) process.exitCode = code;
+}
+
+/**
+ * The suggestions line after a build, cut to the files the wired agents read:
+ * `● 18 suggestions for the files claude, agents and cursor read`. Null when
+ * there are none to mention.
+ */
+function suggestionsLine(s: Suggestions | undefined, wired: string[], again: boolean): string | null {
+ if (!s) return null;
+ let count = 0;
+ const kinds = new Set<string>();
+ if (s.claudeMd > 0 && readByWired("claude_md", wired)) {
+ count += s.claudeMd;
+ kinds.add("claude_md");
+ }
+ if (s.files) {
+ for (const f of s.files) {
+ if (f.changes <= 0 || !readByWired(f.kind, wired)) continue;
+ count += f.changes;
+ kinds.add(f.kind);
+ }
+ } else if (s.contextFiles > 0) {
+ // No per-file list from this Trail, so no way to cut it to the wired agents'
+ // files: the count is Trail's total.
+ count += s.contextFiles;
+ for (const k of ["agents_md", "folder_claude_md", "cursor_rule", "skill"]) kinds.add(k);
+ }
+ if (count === 0) return null;
+ const readers = wired.length
+ ? wired.filter((w) => [...kinds].some((k) => readersOf(k, [w]).length > 0))
+ : [];
+ const whose = readers.length ? `the files ${joinAnd(readers)} read` : "this repo's context files";
+ return `● ${count.toLocaleString("en-US")} ${again ? "new " : ""}suggestion${count === 1 ? "" : "s"} for ${whose}`;
+}
+
brain
.command("push")
- .description("Read THIS repo on your machine and build its brain — no GitHub App, works on private repos")
+ .description("Read THIS repo on your machine and build its trail — no GitHub App, works on private repos")
.argument("[dir]", "target repo directory", ".")
.option("--no-approve", "leave the mined rules as drafts for review")
.option("--no-watch", "return as soon as the push is sent, without following the build")
- .action(async (dir: string, opts: { approve?: boolean; watch?: boolean }) => {
+ .option("--verbose", "print each step's counts and every build stage as it finishes")
+ .action(async (dir: string, opts: { approve?: boolean; watch?: boolean; verbose?: boolean }) => {
const repo = resolve(dir);
+ const tty = Boolean(process.stderr.isTTY);
+ const verbose = opts.verbose === true;
// 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
+ // trail and Trail creates that trail FOR a named repository. Without a slug
// there is nothing to name it after — and the digest builder would fail on
// the same missing remote a moment later regardless.
const here = repoSlugFromGit(repo);
let link = readLink(repo);
+ // Set when this run opened the browser, which then sits on Trail's build
+ // page: the closing lines point at that tab instead of printing a new link.
+ let browserOpen = false;
if (!link) {
if (!here) {
- console.error("✗ this directory has no GitHub `origin` remote — graft can only push a GitHub repository today");
+ console.error("✗ this directory has no GitHub origin remote — graft can only push a GitHub repository today");
process.exitCode = 1;
return;
}
const signedUp = await signUpForBrain(repo, `${here.owner}/${here.name}`);
if (!signedUp) {
- process.exitCode = 1;
+ if (!process.exitCode) process.exitCode = 1;
return;
}
link = signedUp;
+ browserOpen = true;
}
- // What the website said this brain is for. Checked BEFORE any reading, so
- // standing in the wrong checkout costs a message rather than a brain full
+ // What the website said this trail is for. Checked BEFORE any reading, so
+ // standing in the wrong checkout costs a message rather than a trail full
// of another repository's rules — a mistake that is silent afterwards,
// because the rules look perfectly plausible, just not about your code.
const expected = await fetchExpectedRepo(link);
if (expected && here && !sameRepo(expected.slug, `${here.owner}/${here.name}`)) {
- console.error(`✗ this brain is for ${expected.slug}, but you are in ${here.owner}/${here.name}`);
- console.error(` cd into ${expected.slug} and run this again, or attach a different brain here.`);
+ console.error(`✗ this trail is for ${expected.slug}, but you are in ${here.owner}/${here.name}`);
+ console.error(` cd into ${expected.slug} and run this again, or attach a different trail here.`);
process.exitCode = 1;
return;
}
+ const ctx = pushContext(repo);
+ if (!ctx) {
+ console.error("✗ this directory has no GitHub origin remote — graft can only push a GitHub repository today");
+ process.exitCode = 1;
+ return;
+ }
+ const firstPush = !expected || expected.ruleCount === 0;
-
- const label = expected?.slug ?? (here ? `${here.owner}/${here.name}` : "this repository");
- console.error(`· reading ${label} — commit messages, pull-request discussion and the docs in the tree.`);
- console.error(" No file contents leave this machine.");
- // The instruction file and the newest pull requests go first, when the brain
- // takes them: its CLAUDE.md suggestions start from those while the rest of
- // the history is still being read here. Not awaited — the full read starts
- // at once, reusing the threads the early one already fetched.
- let early: Promise<unknown> = Promise.resolve();
- let knownThreads: HistoryThread[] = [];
+ // The instruction files and the newest pull requests go first, when the
+ // trail takes them: its suggestions start from those while the rest of the
+ // history is still being read here. In the background, from here on — the
+ // picker, the graph build and the full read all happen while it goes, and
+ // the full read reuses every GitHub request it made.
+ let early: Promise<void> = Promise.resolve();
if (expected?.earlyUpload) {
- const first = await buildEarlyDigest(repo);
- if (first) {
- knownThreads = first.threads;
- early = pushEarlyDigest(link, first.digest).then((ok) => {
- if (ok) console.error("· CLAUDE.md suggestions are on their way in your browser, from the newest pull requests");
- });
- }
+ early = (async () => {
+ const first = await buildEarlyDigest(repo, { context: ctx });
+ if (!first) return;
+ const ok = await pushEarlyDigest(link!, first.digest, fetch, { gzip: expected.gzipUpload });
+ if (ok && verbose) console.error("· sent the instruction files and the newest pull requests first, so suggestions start now");
+ })().catch(() => undefined);
}
- // A repo graft was never set up in gets `graft init` first — after the early
- // upload has gone, so the CLAUDE.md suggestions are not held up by the graph
- // build. Same picker as init: it is how someone agrees to what gets written,
- // so a non-interactive push only says what to run.
+
+ // A repo graft was never set up in gets `graft init` first. Same picker as
+ // init: it is how someone agrees to what gets written, so a
+ // non-interactive push only says what to run.
if (wiredHostIds(repo).length === 0) {
- if (process.stdin.isTTY && process.stderr.isTTY) {
- // Its one line of output lands before the picker, not across it.
- await early;
- console.error("· graft is not set up in this repo yet — setting it up first, the same as `graft init`");
- await runInitCommand(repo, { build: true, mcp: true, hooks: true, statusline: true, global: true }, { epilogue: false });
+ if (process.stdin.isTTY && tty) {
+ console.error("· graft isn't set up here yet — pick the agents your team uses:");
+ await runInitCommand(
+ repo,
+ { build: true, mcp: true, hooks: true, statusline: true, global: true, verbose },
+ { epilogue: false, push: !verbose },
+ );
} else {
- console.error("· graft is not set up in this repo — run `graft init` so your coding agent reads these rules");
+ console.error("· graft isn't set up here — run graft init so your agents read these rules");
}
}
@@ -1444,130 +1631,133 @@ brain
// 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");
- const built = await buildLocalDigest(repo, graph, { autoApprove: opts.approve !== false, knownThreads });
- await early;
+ if (!graph) console.error("· no graph yet — run graft build so rules can be anchored to symbols");
+ const reading = startSpinner(`reading ${ctx.owner}/${ctx.name} · commits, pull-request discussion and the docs in the tree`);
+ const built = await buildLocalDigest(repo, graph, { autoApprove: opts.approve !== false, context: ctx });
if ("error" in built) {
+ reading.stop();
console.error(`✗ ${built.error}`);
process.exitCode = 1;
return;
}
const d = built.digest;
+ reading.update("sending it to Trail");
+ await early;
+ const sent = await pushDigest(link, d, fetch, uploadCaps(expected));
+ reading.stop();
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;
}
- const brainLabel = expected?.brainName ? `“${expected.brainName}”` : link.brainId;
- console.error(`✓ sent ${d.owner}/${d.name} to ${brainLabel}`);
+ const fmt = (x: number) => x.toLocaleString("en-US");
+ const trailLabel = expected?.brainName ? `“${expected.brainName}”` : `${d.owner}/${d.name}`;
+ console.error(
+ `✓ sent ${fmt(d.commits.length)} commits and ${fmt(d.threads.length)} discussions to ${trailLabel} · no file contents left this machine`,
+ );
+ if (verbose) console.error(` ${fmt(d.symbols.length)} symbols, ${fmt(d.sources.length)} stated sources`);
+ const buildPage = brainUrl(link.brainId);
// 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
+ // which is where roughly a third of production's repo trails 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.
+ // wants fire-and-forget.
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.");
+ console.error("· building now — the rules reach this repo on their own; watch it at");
+ console.error(` ${buildPage}`);
return;
}
- console.error("· building the brain — Ctrl-C detaches, it keeps going without you");
- const outcome = await watchBuild(link);
+ const live = tty && !verbose;
+ if (!live) console.error("· building the trail");
+ const spinner = live ? startSpinner("building the trail · reaching the repository · Ctrl-C detaches") : null;
+ let last: RepoState | null = null;
+ // Ctrl-C detaches: the work is server-side, and killing a watcher must
+ // never look like killing the build.
+ const onSigint = () => {
+ spinner?.stop();
+ console.error("· detached — the build keeps going; watch it at");
+ console.error(` ${buildPage}`);
+ process.exit(130);
+ };
+ process.once("SIGINT", onSigint);
+ const outcome = await watchBuild(link, {
+ events: expected?.events === true,
+ stageLines: !live,
+ write: (line) => (spinner ? spinner.print(line) : console.error(line)),
+ onState: (view, repoState) => {
+ last = repoState;
+ spinner?.update(`building the trail · ${DOING_LABEL[currentStage(view)]} · Ctrl-C detaches`);
+ },
+ });
+ process.off("SIGINT", onSigint);
+ spinner?.stop();
+
+ const ruleCount = rulesSoFar(last);
+ const rules = `${fmt(ruleCount)} rule${ruleCount === 1 ? "" : "s"}`;
+ const wired = [...new Set([...(readStamp(repo)?.hosts ?? []), ...wiredHostIds(repo)])];
+ const closing = () => {
+ const line = suggestionsLine((last as RepoState | null)?.suggestions, wired, !firstPush);
+ if (!line) return;
+ if (browserOpen) {
+ console.error(`${line} — they are in the Trail tab in your browser`);
+ console.error(` ${reviewUrl(link!.brainId)}`);
+ } else {
+ console.error(line);
+ console.error(` review: ${reviewUrl(link!.brainId)}`);
+ }
+ };
if (outcome === "completed") {
- console.error("✓ the brain is built — its rules reach this repo on their own; nothing else to run");
+ console.error(`✓ trail built · ${rules}, reaching this repo on their own`);
+ closing();
return;
}
// The ordinary ending for anything but a small repository. The history is
// mined in slices, and the prompt comes back on the first of them: mining is
// the part that fails and it has now succeeded, and the rest is filing,
- // which is minutes of reliable work nobody gains by watching. The rules
- // already in the brain are already being served.
+ // which is minutes of reliable work nobody gains by watching.
if (outcome === "building") {
- console.error("✓ the brain has its first rules — they reach this repo on their own; nothing else to run");
- console.error(" The rest of the history is still being read. Watch it fill in your browser.");
+ console.error(
+ firstPush
+ ? `✓ trail has its first ${rules} · they reach this repo on their own`
+ : `✓ trail updated · ${rules}, reaching this repo on their own`,
+ );
+ closing();
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 trail push` again to retry the read.");
+ // where the work did not produce a trail, and a CI step that ran the push
+ // should hear about it the way it hears about any other failure. The
+ // watcher has already printed where it stopped and why.
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("· lost touch with Trail — the build keeps going; watch it at the link below");
+ } else {
+ console.error("· still building after 15 minutes — not failed, just long; watch it at the link below");
}
- console.error("· still building after 15 minutes — it has not failed, it is just long. Watch it finish in your browser.");
+ console.error(` ${buildPage}`);
});
+// `graft claude-md pull` is `graft trail pull` now: the CLAUDE.md changes are
+// the first half of what that writes. Kept so the old name keeps working.
const claudeMd = program
.command("claude-md")
- .description("The CLAUDE.md changes this repo's brain suggested and you accepted in Trail");
+ .description("The CLAUDE.md changes this repo's trail suggested (now part of graft trail pull)");
claudeMd
.command("pull")
- .description("Write the CLAUDE.md changes you accepted in Trail into this repo's instruction file")
+ .description("Same as graft trail pull: write every change you accepted in Trail into this repo")
.argument("[dir]", "target repo directory", ".")
- .option("--dry-run", "show what would change without writing the file or telling Trail")
+ .option("--dry-run", "show what would change without writing anything or telling Trail")
.action(async (dir: string, opts: { dryRun?: boolean }) => {
- const repo = resolve(dir);
- const link = readLink(repo);
- if (!link) {
- console.error("✗ this repo has no brain attached — run `graft trail push` first");
- process.exitCode = 1;
- return;
- }
- const pulled = await fetchAcceptedChanges(link);
- if ("error" in pulled) {
- console.error(`✗ ${pulled.error}`);
- process.exitCode = 1;
- return;
- }
- if (pulled.changes.length === 0) {
- console.error("· nothing accepted yet — accept suggestions on the brain's CLAUDE.md page, then pull again");
- return;
- }
- // The file Trail read, or a new CLAUDE.md when the repo had none.
- const rel = pulled.path || "CLAUDE.md";
- const file = join(repo, rel);
- const { existsSync, readFileSync, writeFileSync } = await import("node:fs");
- const before = existsSync(file) ? readFileSync(file, "utf8") : "";
- const result = applyChanges(before, pulled.changes);
-
- for (const c of result.written) console.error(` + ${c.kind === "add" ? "new section" : "edit"} · ${c.heading}`);
- for (const c of result.present) console.error(` = already in the file · ${c.heading}`);
- for (const s of result.skipped) console.error(` ! skipped · ${s.change.heading} — ${s.why}`);
-
- if (opts.dryRun) {
- console.error(`· dry run: ${result.written.length} change(s) would be written to ${rel}; nothing was written`);
- return;
- }
- if (result.written.length > 0) writeFileSync(file, result.text);
- // Written now or already there: either way the page should stop listing it.
- const done = [...result.written, ...result.present].map((c) => c.id);
- const told = await markApplied(link, done);
- if (result.written.length > 0) {
- console.error(`✓ wrote ${result.written.length} change(s) to ${rel} — review and commit it like any other edit`);
- } else if (result.present.length > 0) {
- console.error(`✓ ${rel} already has every accepted change`);
- }
- if (!told) console.error("⚠ could not tell Trail which changes were written; the page may still list them");
- if (result.skipped.length > 0) {
- console.error(
- `· ${result.skipped.length} change(s) no longer match the local file — edit them on the CLAUDE.md page, or apply them by hand`,
- );
- process.exitCode = 1;
- }
+ console.error("· graft claude-md pull is now part of graft trail pull — running that");
+ await runTrailPullCommand(dir, opts);
});
brain
diff --git a/src/telemetry/contract.ts b/src/telemetry/contract.ts
index 2933b1af..49c09378 100644
--- a/src/telemetry/contract.ts
+++ b/src/telemetry/contract.ts
@@ -109,14 +109,15 @@ export function isTrackedCommand(name: string): name is TrackedCommand {
/**
* How a `graft trail push` signup ended.
*
- * Four categories and nothing else, because the alternative — the error string
+ * Five categories and nothing else, because the alternative — the error string
* the CLI already prints — carries a repo slug and a URL. `timed_out` and
* `no_tty` are deliberately apart: one is a person who opened the browser and
* did not finish, the other is a machine that was never able to open one, and
* treating them alike would read as a product problem where there is only a
- * remote shell.
+ * remote shell. `stopped` is Ctrl-C while waiting: a person changing their
+ * mind, not a browser that never came back.
*/
-export const BRAIN_SIGNUP_OUTCOMES = ['linked', 'timed_out', 'no_tty', 'bad_callback'] as const;
+export const BRAIN_SIGNUP_OUTCOMES = ['linked', 'timed_out', 'no_tty', 'bad_callback', 'stopped'] as const;
export type BrainSignupOutcome = (typeof BRAIN_SIGNUP_OUTCOMES)[number];
/** Where a failing build died. Coarse on purpose: enough to route a bug, not
diff --git a/src/util/spinner.ts b/src/util/spinner.ts
new file mode 100644
index 00000000..149a7e8f
--- /dev/null
+++ b/src/util/spinner.ts
@@ -0,0 +1,63 @@
+/**
+ * One line that redraws in place while something runs, and is erased when it
+ * stops — so nothing interactive is left in the scrollback.
+ *
+ * Only on a TTY. Anywhere else every method is a no-op, and the caller prints
+ * whatever finished lines it wants a log to keep.
+ */
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+export interface Spinner {
+ /** Change the text after the frame. */
+ update(text: string): void;
+ /** Print a finished line above the spinner, which keeps spinning below it. */
+ print(line: string): void;
+ /** Erase the line and stop. Safe to call more than once. */
+ stop(): void;
+ readonly active: boolean;
+}
+
+export function startSpinner(
+ text: string,
+ opts: { stream?: NodeJS.WriteStream; enabled?: boolean; intervalMs?: number } = {},
+): Spinner {
+ const out = opts.stream ?? process.stderr;
+ const enabled = opts.enabled ?? Boolean(out.isTTY);
+ if (!enabled) {
+ return { update() {}, print: (line) => out.write(`${line}\n`), stop() {}, active: false };
+ }
+ let current = text;
+ let frame = 0;
+ let stopped = false;
+ const width = () => Math.max(20, (out.columns || 100) - 1);
+ const draw = () => {
+ if (stopped) return;
+ const line = `${FRAMES[frame % FRAMES.length]} ${current}`;
+ out.write(`\r\x1b[2K${line.length > width() ? line.slice(0, width()) : line}`);
+ frame++;
+ };
+ const clear = () => out.write("\r\x1b[2K");
+ draw();
+ const timer = setInterval(draw, opts.intervalMs ?? 80);
+ timer.unref?.();
+ return {
+ get active() {
+ return !stopped;
+ },
+ update(next: string) {
+ current = next;
+ draw();
+ },
+ print(line: string) {
+ clear();
+ out.write(`${line}\n`);
+ draw();
+ },
+ stop() {
+ if (stopped) return;
+ stopped = true;
+ clearInterval(timer);
+ clear();
+ },
+ };
+}
diff --git a/test/app-sources-context.test.ts b/test/app-sources-context.test.ts
new file mode 100644
index 00000000..14b64d51
--- /dev/null
+++ b/test/app-sources-context.test.ts
@@ -0,0 +1,80 @@
+/**
+ * The early upload carries every file a team wrote for its agents, not only
+ * the root ones: folder CLAUDE.md / AGENTS.md files and Claude skills. What
+ * matters is which ones — shallow enough, outside dependencies and build
+ * output, not ignored, never graft's own — and that there is a cap.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { folderInstructionFiles, readAgentInstructions, skillFiles } from '../src/app/sources.js';
+import { tmpRepo } from './helpers.js';
+
+function put(root: string, rel: string, text: string): void {
+ mkdirSync(dirname(join(root, rel)), { recursive: true });
+ writeFileSync(join(root, rel), text);
+}
+
+function fixture(): string {
+ const root = tmpRepo('sources');
+ put(root, 'CLAUDE.md', '# root\n\nUse pnpm.\n');
+ put(root, 'web/CLAUDE.md', '# web\n\nComponents are PascalCase.\n');
+ put(root, 'services/api/AGENTS.md', '# api\n\nHandlers stay thin.\n');
+ put(root, 'a/b/c/d/CLAUDE.md', '# depth four\n\nStill read.\n');
+ put(root, 'a/b/c/d/e/CLAUDE.md', '# depth five\n\nToo deep.\n');
+ put(root, 'node_modules/pkg/CLAUDE.md', '# dependency\n');
+ put(root, 'dist/CLAUDE.md', '# build output\n');
+ put(root, 'graft/CLAUDE.md', '# graft cache\n');
+ put(root, '.hidden/CLAUDE.md', '# dot dir\n');
+ put(root, 'scratch/CLAUDE.md', '# ignored by the repo\n');
+ put(root, '.gitignore', 'scratch/\n');
+ put(root, '.claude/skills/deploy/SKILL.md', '---\nname: deploy\n---\nAlways deploy from main.\n');
+ put(root, '.claude/skills/graft/SKILL.md', '---\nname: graft\n---\ngraft teaches graft\n');
+ put(root, '.claude/skills/empty/README.md', 'no skill file here\n');
+ put(root, 'web/AGENTS.md', 'before\n<!-- graft:start -->\ngraft block\n<!-- graft:end -->\nafter\n');
+ return root;
+}
+
+test('folder instruction files: shallow ones, outside ignored and generated dirs, shallowest first', () => {
+ const root = fixture();
+ spawnSync('git', ['init', '-q'], { cwd: root });
+ const got = folderInstructionFiles(root);
+ assert.deepEqual(got, ['web/AGENTS.md', 'web/CLAUDE.md', 'services/api/AGENTS.md', 'a/b/c/d/CLAUDE.md']);
+});
+
+test('folder instruction files are found without git too', () => {
+ const root = fixture();
+ const got = folderInstructionFiles(root);
+ // No git to read .gitignore, so scratch/ is read; everything else is the same.
+ assert.ok(got.includes('web/CLAUDE.md') && got.includes('a/b/c/d/CLAUDE.md'));
+ assert.ok(!got.some((p) => /node_modules|dist|graft\/|\.hidden|\/e\//.test(p)), got.join(', '));
+});
+
+test('folder instruction files are capped', () => {
+ const root = tmpRepo('sources-cap');
+ for (let i = 0; i < 40; i++) put(root, `pkg${String(i).padStart(2, '0')}/CLAUDE.md`, `# ${i}\n\nrule ${i}\n`);
+ assert.equal(folderInstructionFiles(root).length, 30);
+ assert.equal(folderInstructionFiles(root, 5).length, 5);
+});
+
+test('skills: every SKILL.md but graft\'s own', () => {
+ const root = fixture();
+ assert.deepEqual(skillFiles(root), ['.claude/skills/deploy/SKILL.md']);
+});
+
+test('readAgentInstructions carries them all as agent_instructions, graft blocks stripped', () => {
+ const root = fixture();
+ spawnSync('git', ['init', '-q'], { cwd: root });
+ const got = readAgentInstructions(root);
+ const paths = got.map((s) => s.path);
+ for (const p of ['CLAUDE.md', 'web/CLAUDE.md', 'services/api/AGENTS.md', '.claude/skills/deploy/SKILL.md']) {
+ assert.ok(paths.includes(p), `${p} missing from ${paths.join(', ')}`);
+ }
+ assert.ok(got.every((s) => s.kind === 'agent_instructions'));
+ const web = got.find((s) => s.path === 'web/AGENTS.md')!;
+ assert.doesNotMatch(web.text, /graft block/);
+ assert.match(web.text, /before[\s\S]*after/);
+ assert.ok(!paths.includes('.claude/skills/graft/SKILL.md'));
+});
diff --git a/test/brain-context-files-pull.test.ts b/test/brain-context-files-pull.test.ts
new file mode 100644
index 00000000..6449429b
--- /dev/null
+++ b/test/brain-context-files-pull.test.ts
@@ -0,0 +1,215 @@
+/**
+ * `graft trail pull` writes accepted changes into every context file, not only
+ * the root CLAUDE.md. It edits files people also edit by hand, so the tests are
+ * about restraint: a whole-file change never overwrites someone's file, a
+ * replace only lands on the file it was computed against, a path from Trail
+ * never escapes the repo, and files for agents nobody picked are left alone.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { planContextFile, readByWired, safeRelPath, writePlannedFile, type ContextFile } from '../src/brain/context-files.js';
+import { runTrailPull } from '../src/brain/pull.js';
+import type { BrainLink } from '../src/brain/link.js';
+import { tmpRepo } from './helpers.js';
+
+function put(root: string, rel: string, text: string): void {
+ mkdirSync(dirname(join(root, rel)), { recursive: true });
+ writeFileSync(join(root, rel), text);
+}
+
+const AGENTS = ['# api', '', '## Commands', '', '- `make test` runs the unit tests.', '', '## Style', '', '- gofmt everything.', ''].join('\n');
+
+test('edit and add patch the file exactly as the CLAUDE.md pull does', () => {
+ const root = tmpRepo('ctx-edit');
+ put(root, 'services/api/AGENTS.md', AGENTS);
+ const plan = planContextFile(root, {
+ kind: 'agents_md',
+ path: 'services/api/AGENTS.md',
+ changes: [
+ { id: 'e1', kind: 'edit', heading: 'Commands', find: '- `make test` runs the unit tests.', text: '- `make test` runs unit and integration tests.' },
+ { id: 'a1', kind: 'add', heading: 'Money', after_heading: 'Commands', text: 'Amounts are integer cents.' },
+ ],
+ });
+ assert.equal(plan.status, 'M');
+ assert.deepEqual(plan.written.map((c) => c.id), ['e1', 'a1']);
+ assert.match(plan.text!, /## Commands\n\n- `make test` runs unit and integration tests\.\n\n## Money\n\nAmounts are integer cents\.\n\n## Style/);
+ assert.match(plan.text!, /- gofmt everything\./, 'untouched sections come back as they were');
+});
+
+test('create writes a new file, folders and all', () => {
+ const root = tmpRepo('ctx-create');
+ const plan = planContextFile(root, {
+ kind: 'cursor_rule',
+ path: '.cursor/rules/money.mdc',
+ changes: [{ id: 'c1', kind: 'create', text: '---\ndescription: money\n---\nAmounts are integer cents.' }],
+ });
+ assert.equal(plan.status, 'A');
+ writePlannedFile(root, plan);
+ assert.equal(readFileSync(join(root, '.cursor/rules/money.mdc'), 'utf8'), '---\ndescription: money\n---\nAmounts are integer cents.\n');
+});
+
+test('create over an identical file counts as applied and writes nothing', () => {
+ const root = tmpRepo('ctx-same');
+ put(root, 'web/CLAUDE.md', '# web\r\n\r\nPascalCase components.\r\n');
+ const plan = planContextFile(root, {
+ kind: 'folder_claude_md',
+ path: 'web/CLAUDE.md',
+ changes: [{ id: 'c2', kind: 'create', text: '# web\n\nPascalCase components.' }],
+ });
+ assert.equal(plan.status, '');
+ assert.deepEqual(plan.present.map((c) => c.id), ['c2']);
+});
+
+test('create over a different file is a conflict, and the file is left alone', () => {
+ const root = tmpRepo('ctx-conflict');
+ put(root, 'web/CLAUDE.md', '# web\n\nOurs.\n');
+ const plan = planContextFile(root, {
+ kind: 'folder_claude_md',
+ path: 'web/CLAUDE.md',
+ changes: [{ id: 'c3', kind: 'create', text: '# web\n\nTheirs.\n' }],
+ });
+ assert.equal(plan.status, '');
+ assert.equal(plan.skipped.length, 1);
+ assert.match(plan.skipped[0].why, /other content/);
+});
+
+test('create over a file graft owns replaces it', () => {
+ const root = tmpRepo('ctx-managed');
+ put(root, '.cursor/rules/graft.mdc', 'old graft rule\n');
+ const plan = planContextFile(root, {
+ kind: 'cursor_rule',
+ path: '.cursor/rules/graft.mdc',
+ managed_by_graft: true,
+ changes: [{ id: 'c4', kind: 'create', text: 'new graft rule\n' }],
+ });
+ assert.equal(plan.status, 'M');
+ assert.equal(plan.text, 'new graft rule\n');
+});
+
+test('replace lands only on the file it was computed against', () => {
+ const root = tmpRepo('ctx-replace');
+ put(root, '.cursor/rules/style.mdc', 'Use tabs.\r\n');
+ const change = { id: 'r1', kind: 'replace' as const, find: 'Use tabs.\n', text: 'Use two spaces.\n' };
+ const ok = planContextFile(root, { kind: 'cursor_rule', path: '.cursor/rules/style.mdc', changes: [change] });
+ assert.equal(ok.status, 'M');
+ assert.equal(ok.text, 'Use two spaces.\n');
+
+ put(root, '.cursor/rules/style.mdc', 'Use tabs. And semicolons.\n');
+ const moved = planContextFile(root, { kind: 'cursor_rule', path: '.cursor/rules/style.mdc', changes: [change] });
+ assert.equal(moved.status, '');
+ assert.match(moved.skipped[0].why, /changed here since Trail read it/);
+
+ put(root, '.cursor/rules/style.mdc', 'Use two spaces.\n');
+ const done = planContextFile(root, { kind: 'cursor_rule', path: '.cursor/rules/style.mdc', changes: [change] });
+ assert.deepEqual(done.present.map((c) => c.id), ['r1']);
+});
+
+test('an edit to a file that is not here yet creates it', () => {
+ const root = tmpRepo('ctx-missing');
+ const plan = planContextFile(root, {
+ kind: 'folder_claude_md',
+ path: 'web/CLAUDE.md',
+ changes: [{ id: 'e2', kind: 'edit', heading: 'Frontend', find: '', text: 'Components are PascalCase.' }],
+ });
+ assert.equal(plan.status, 'A');
+ assert.equal(plan.text, '## Frontend\n\nComponents are PascalCase.\n');
+});
+
+test('a path from Trail never leaves the repo', () => {
+ const root = tmpRepo('ctx-safe');
+ for (const bad of ['../outside.md', '/etc/passwd', 'a/../../b.md', '.git/config', 'C:/x.md', '']) {
+ assert.equal(safeRelPath(root, bad), null, bad);
+ }
+ assert.equal(safeRelPath(root, 'web/CLAUDE.md'), 'web/CLAUDE.md');
+ const plan = planContextFile(root, { kind: 'agents_md', path: '../AGENTS.md', changes: [{ id: 'x', kind: 'create', text: 'x' }] });
+ assert.equal(plan.status, '');
+ assert.equal(plan.skipped.length, 1);
+});
+
+test('files are only for the agents that were picked', () => {
+ assert.equal(readByWired('cursor_rule', ['claude']), false);
+ assert.equal(readByWired('agents_md', ['claude', 'agents']), true);
+ assert.equal(readByWired('skill', ['claude']), true);
+ assert.equal(readByWired('cursor_rule', []), true, 'nothing wired means no choice to respect');
+});
+
+// --- the whole pull, against a fake Trail ---------------------------------------
+
+const link = { brainId: 'b1', token: 'gbt_1.x', baseUrl: 'http://trail.test' } as unknown as BrainLink;
+const json = (body: unknown, status = 200) =>
+ new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
+
+function fakeTrail(files: ContextFile[], opts: { contextFiles?: 'ok' | 'missing' } = {}) {
+ const applied: Record<string, string[]> = {};
+ const f = (async (u: string, init?: RequestInit) => {
+ const path = new URL(u).pathname;
+ if (path.endsWith('/rules/anchors')) return json({ anchors: [] });
+ if (path.endsWith('/claude-md')) {
+ return json({ path: 'CLAUDE.md', head_sha: 'abc', changes: [{ id: 'm1', kind: 'add', heading: 'Money', after_heading: '', text: 'Integer cents.' }] });
+ }
+ if (path.endsWith('/context-files')) {
+ return opts.contextFiles === 'missing' ? json({ error: 'not found' }, 404) : json({ head_sha: 'abc', files });
+ }
+ if (path.endsWith('/applied')) {
+ applied[path] = (JSON.parse(String(init?.body)) as { ids: string[] }).ids;
+ return json({ applied: 1 });
+ }
+ return json({ error: 'unexpected' }, 500);
+ }) as typeof fetch;
+ return { f, applied };
+}
+
+test('a pull writes the CLAUDE.md changes, then every other file, and tells Trail which', async () => {
+ const root = tmpRepo('ctx-pull');
+ put(root, 'CLAUDE.md', '# app\n\n## Commands\n\n- `npm test`\n');
+ put(root, 'web/CLAUDE.md', '# web\n\nOurs.\n');
+ const { f, applied } = fakeTrail([
+ { kind: 'agents_md', path: 'AGENTS.md', changes: [{ id: 'g1', kind: 'create', text: '# agents\n\nInteger cents.\n' }] },
+ { kind: 'folder_claude_md', path: 'web/CLAUDE.md', changes: [{ id: 'w1', kind: 'create', text: '# web\n\nTheirs.\n' }] },
+ { kind: 'cursor_rule', path: '.cursor/rules/money.mdc', changes: [{ id: 'k1', kind: 'create', text: 'cents\n' }] },
+ ]);
+ const lines: string[] = [];
+ const code = await runTrailPull(root, link, { home: root, wired: ['claude', 'agents'], fetchImpl: f, write: (l) => lines.push(l) });
+ const out = lines.join('\n');
+
+ assert.equal(code, 1, 'the conflict makes it exit non-zero, as claude-md pull did');
+ assert.match(out, /✓ wrote 2 accepted changes/);
+ assert.match(out, / M CLAUDE\.md +\+ Money/);
+ assert.match(out, / A AGENTS\.md/);
+ assert.match(out, /⚠ skipped web\/CLAUDE\.md — a file with other content is already there; edit it in Trail, then pull again/);
+ assert.doesNotMatch(out, /money\.mdc/, 'cursor was not picked, so its rule is neither listed nor written');
+ assert.match(out, /review with git diff, then commit/);
+
+ assert.match(readFileSync(join(root, 'CLAUDE.md'), 'utf8'), /## Money\n\nInteger cents\./);
+ assert.equal(readFileSync(join(root, 'AGENTS.md'), 'utf8'), '# agents\n\nInteger cents.\n');
+ assert.equal(readFileSync(join(root, 'web/CLAUDE.md'), 'utf8'), '# web\n\nOurs.\n');
+ assert.ok(!existsSync(join(root, '.cursor/rules/money.mdc')));
+
+ assert.deepEqual(applied['/api/public/brains/b1/claude-md/applied'], ['m1']);
+ assert.deepEqual(applied['/api/public/brains/b1/context-files/applied'], ['g1'], 'only what was written, never the conflict');
+});
+
+test('a dry run writes nothing and tells Trail nothing', async () => {
+ const root = tmpRepo('ctx-dry');
+ const { f, applied } = fakeTrail([
+ { kind: 'agents_md', path: 'AGENTS.md', changes: [{ id: 'g1', kind: 'create', text: 'x\n' }] },
+ ]);
+ const lines: string[] = [];
+ await runTrailPull(root, link, { home: root, wired: [], dryRun: true, fetchImpl: f, write: (l) => lines.push(l) });
+ assert.match(lines.join('\n'), /✓ would write 2 accepted changes/);
+ assert.match(lines.join('\n'), /dry run — nothing written, and Trail was not told/);
+ assert.ok(!existsSync(join(root, 'AGENTS.md')) && !existsSync(join(root, 'CLAUDE.md')));
+ assert.deepEqual(applied, {});
+});
+
+test('a Trail without context files still pulls CLAUDE.md, silently', async () => {
+ const root = tmpRepo('ctx-older');
+ const { f } = fakeTrail([], { contextFiles: 'missing' });
+ const lines: string[] = [];
+ const code = await runTrailPull(root, link, { home: root, wired: ['claude'], fetchImpl: f, write: (l) => lines.push(l) });
+ assert.equal(code, 0);
+ assert.match(lines.join('\n'), /✓ wrote 1 accepted change\n A CLAUDE\.md +\+ Money/);
+ assert.doesNotMatch(lines.join('\n'), /✗/);
+});
diff --git a/test/brain-early-upload.test.ts b/test/brain-early-upload.test.ts
index 52613dd3..741efab3 100644
--- a/test/brain-early-upload.test.ts
+++ b/test/brain-early-upload.test.ts
@@ -8,7 +8,7 @@
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { fetchExpectedRepo, pushEarlyDigest } from '../src/brain/push.js';
-import { readThreads, type HistoryThread, type RepoDigest } from '../src/app/history.js';
+import { newThreadReadCache, readThreads, THREAD_FETCH_CONCURRENCY, type HistoryThread, type RepoDigest } from '../src/app/history.js';
import type { BrainLink } from '../src/brain/link.js';
const link = { brainId: 'b1', token: 'gbt_1.x', baseUrl: 'http://trail.test' } as unknown as BrainLink;
@@ -71,3 +71,48 @@ test('the full read reuses threads the early upload already fetched', async () =
assert.ok(!fetched.some((u) => /\/(issues|pulls)\/2\/comments/.test(u)), 'no comment request for #2');
assert.ok(fetched.some((u) => /\/(issues|pulls)\/1\/comments/.test(u)));
});
+
+// The early read and the full read share one cache, so a thread the early read
+// is still fetching is waited on, not fetched again — and one with no
+// discussion is remembered too, which a map of finished threads cannot say.
+test('the early and full reads share every GitHub request, even ones in flight', async () => {
+ const fetched: string[] = [];
+ const fake = (async (u: string) => {
+ fetched.push(u);
+ await new Promise((r) => setTimeout(r, 5));
+ if (u.includes('/pulls?state=closed')) {
+ return json(/&page=1$/.test(u) ? Array.from({ length: 40 }, (_, i) => ({ number: 40 - i, title: `pr ${40 - i}` })) : []);
+ }
+ // Odd pull requests have no discussion at all.
+ const n = Number(/\/(\d+)\/comments/.exec(u)?.[1]);
+ return json(n % 2 ? [] : [{ body: `on #${n}`, user: { type: 'User' } }]);
+ }) as never;
+
+ const cache = newThreadReadCache();
+ const [early, full] = await Promise.all([
+ readThreads('chalk', 'chalk', 'tok', fake, 'https://api.test', 30, undefined, cache),
+ readThreads('chalk', 'chalk', 'tok', fake, 'https://api.test', 200, undefined, cache),
+ ]);
+ assert.equal(early.length, 15);
+ assert.equal(full.length, 20);
+ const perThread = fetched.filter((u) => /\/issues\/\d+\/comments/.test(u));
+ assert.equal(perThread.length, 40, 'each pull request asked about once, however many reads wanted it');
+ assert.equal(fetched.filter((u) => u.includes('/pulls?state=closed') && /&page=1$/.test(u)).length, 1, 'the first page of the list is read once');
+});
+
+test('comment reads run in a pool, not in batches that wait for their slowest', async () => {
+ let inFlight = 0;
+ let peak = 0;
+ const fake = (async (u: string) => {
+ if (u.includes('/pulls?state=closed')) {
+ return json(/&page=1$/.test(u) ? Array.from({ length: 60 }, (_, i) => ({ number: i + 1 })) : []);
+ }
+ inFlight++;
+ peak = Math.max(peak, inFlight);
+ await new Promise((r) => setTimeout(r, 2));
+ inFlight--;
+ return json([]);
+ }) as never;
+ await readThreads('chalk', 'chalk', 'tok', fake, 'https://api.test', 60);
+ assert.equal(peak, THREAD_FETCH_CONCURRENCY * 2, 'two comment endpoints per pull request, 24 pull requests at once');
+});
diff --git a/test/brain-signup.test.ts b/test/brain-signup.test.ts
index 1561f14c..84c0b0eb 100644
--- a/test/brain-signup.test.ts
+++ b/test/brain-signup.test.ts
@@ -64,7 +64,7 @@ test("handoff: the wait gives up rather than hanging forever", async () => {
const h = await startHandoff();
const got = await h.wait(150);
assert.ok("error" in got);
- assert.match((got as { error: string }).error, /timed out/);
+ assert.match((got as { error: string }).error, /no sign-up after .* · nothing was sent — run graft trail push again/);
});
test("signup url: carries the repo, the port and the state", () => {
diff --git a/test/brain-upload.test.ts b/test/brain-upload.test.ts
new file mode 100644
index 00000000..6daf4520
--- /dev/null
+++ b/test/brain-upload.test.ts
@@ -0,0 +1,243 @@
+/**
+ * The full digest goes up gzipped, and in retried 1 MiB chunks when Trail says
+ * it takes them. What matters: the chunks reassemble into exactly the gzip of
+ * the body a single POST would have sent, a blip costs one chunk rather than
+ * the push, and an older Trail still gets the plain POST it always did.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { gunzipSync } from 'node:zlib';
+import { uploadDigest, uploadChunked, RETRY_DELAYS_MS } from '../src/brain/upload.js';
+import { fetchExpectedRepo, pushEarlyDigest, uploadCaps } from '../src/brain/push.js';
+import type { RepoDigest } from '../src/app/history.js';
+import type { BrainLink } from '../src/brain/link.js';
+
+const link = { brainId: 'b1', token: 'gbt_1.x', baseUrl: 'http://trail.test' } as unknown as BrainLink;
+const json = (body: unknown, status = 200) =>
+ new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
+
+/** A digest big enough to need several chunks at a small chunk size. */
+function digest(): RepoDigest {
+ return {
+ provider: 'github',
+ owner: 'chalk',
+ name: 'chalk',
+ head_sha: 'abc',
+ default_branch: 'main',
+ is_private: false,
+ commits: Array.from({ length: 400 }, (_, i) => ({
+ sha: `${i}`.padStart(40, '0'),
+ subject: `commit ${i} ${Math.random().toString(36)}`,
+ body: '',
+ files: [`src/${i}.ts`],
+ symbols: [],
+ })),
+ threads: [],
+ symbols: [],
+ sources: [],
+ auto_approve: true,
+ };
+}
+
+interface Call {
+ method: string;
+ url: string;
+ headers: Record<string, string>;
+ body: unknown;
+}
+
+function recorder(respond: (c: Call, n: number) => Response | Promise<Response>) {
+ const calls: Call[] = [];
+ const f = (async (u: string, init?: RequestInit) => {
+ const c: Call = {
+ method: init?.method ?? 'GET',
+ url: u,
+ headers: (init?.headers ?? {}) as Record<string, string>,
+ body: init?.body,
+ };
+ calls.push(c);
+ return respond(c, calls.length);
+ }) as typeof fetch;
+ return { calls, f };
+}
+
+const noSleep = { sleep: async () => {} };
+
+test('chunks reassemble into the gzip of exactly the body a single POST would send', async () => {
+ const d = digest();
+ const chunks = new Map<number, Buffer>();
+ let opened: Record<string, unknown> = {};
+ const { calls, f } = recorder((c) => {
+ if (c.method === 'POST' && c.url.endsWith('/repo/uploads')) {
+ opened = JSON.parse(String(c.body));
+ return json({ upload_id: 'u-1' }, 201);
+ }
+ const m = /\/uploads\/u-1\/chunks\/(\d+)$/.exec(c.url);
+ if (c.method === 'PUT' && m) {
+ chunks.set(Number(m[1]), Buffer.from(c.body as Uint8Array));
+ return new Response(null, { status: 204 });
+ }
+ if (c.url.endsWith('/uploads/u-1/complete')) return json({ repo: {}, job_id: 'job-9', status: 'queued' }, 202);
+ return json({ error: 'unexpected' }, 500);
+ });
+
+ const got = await uploadDigest(link, d, { gzip: true, chunked: true }, { fetchImpl: f, chunkBytes: 2048, ...noSleep });
+ assert.deepEqual(got, { jobId: 'job-9' });
+
+ assert.equal(opened.stage, 'full');
+ assert.equal(opened.auto_approve, true);
+ assert.equal(opened.chunks, chunks.size);
+ assert.ok(chunks.size > 1, 'the test digest must need more than one chunk');
+ const joined = Buffer.concat([...chunks.keys()].sort((a, b) => a - b).map((i) => chunks.get(i)!));
+ assert.equal(opened.bytes, joined.length);
+ assert.equal(gunzipSync(joined).toString('utf8'), JSON.stringify(d));
+
+ const put = calls.find((c) => c.method === 'PUT')!;
+ assert.equal(put.headers['content-type'], 'application/octet-stream');
+ assert.equal(put.headers.authorization, 'Bearer gbt_1.x');
+ assert.match(put.url, /^http:\/\/trail\.test\/api\/public\/brains\/b1\/repo\/uploads\/u-1\/chunks\/\d+$/);
+});
+
+test('a chunk that fails is retried on its own, on 5xx, 429 and network errors', async () => {
+ const attempts = new Map<string, number>();
+ const waits: number[] = [];
+ const { f } = recorder((c) => {
+ if (c.url.endsWith('/repo/uploads')) return json({ upload_id: 'u-2' }, 201);
+ if (c.method === 'PUT') {
+ const n = (attempts.get(c.url) ?? 0) + 1;
+ attempts.set(c.url, n);
+ if (c.url.endsWith('/chunks/1')) {
+ if (n === 1) return json({ error: 'busy' }, 503);
+ if (n === 2) return json({ error: 'slow down' }, 429);
+ if (n === 3) throw new Error('ECONNRESET');
+ }
+ return new Response(null, { status: 204 });
+ }
+ return json({ job_id: 'job-2' }, 202);
+ });
+ const got = await uploadChunked(link, digest(), {
+ fetchImpl: f,
+ chunkBytes: 2048,
+ sleep: async (ms) => void waits.push(ms),
+ });
+ assert.deepEqual(got, { jobId: 'job-2' });
+ assert.equal(attempts.get('http://trail.test/api/public/brains/b1/repo/uploads/u-2/chunks/1'), 4);
+ assert.equal(attempts.get('http://trail.test/api/public/brains/b1/repo/uploads/u-2/chunks/0'), 1, 'the others went once');
+ assert.deepEqual(waits, [500, 1000, 2000], 'backoff doubles from half a second');
+});
+
+test('a chunk that keeps failing gives up after four retries and says which part', async () => {
+ let tries = 0;
+ const { f } = recorder((c) => {
+ if (c.url.endsWith('/repo/uploads')) return json({ upload_id: 'u-3' }, 201);
+ if (c.method === 'PUT') {
+ tries++;
+ return json({ error: 'down' }, 502);
+ }
+ return json({ job_id: 'never' }, 202);
+ });
+ const got = await uploadChunked(link, digest(), { fetchImpl: f, chunkBytes: 1 << 20, ...noSleep });
+ assert.ok('error' in got && /part 1 of 1: 502/.test(got.error), JSON.stringify(got));
+ assert.equal(tries, RETRY_DELAYS_MS.length + 1);
+});
+
+test('complete is retried on 5xx, and returns today\'s ingest response', async () => {
+ let completes = 0;
+ const { f } = recorder((c) => {
+ if (c.url.endsWith('/repo/uploads')) return json({ upload_id: 'u-4' }, 201);
+ if (c.method === 'PUT') return new Response(null, { status: 204 });
+ completes++;
+ return completes < 3 ? json({ error: 'hiccup' }, 500) : json({ repo: {}, job_id: 'job-4', status: 'queued' }, 202);
+ });
+ assert.deepEqual(await uploadChunked(link, digest(), { fetchImpl: f, ...noSleep }), { jobId: 'job-4' });
+ assert.equal(completes, 3);
+});
+
+test('a 409 from complete is passed on as a refusal, as the single POST would be', async () => {
+ const { f } = recorder((c) => {
+ if (c.url.endsWith('/repo/uploads')) return json({ upload_id: 'u-5' }, 201);
+ if (c.method === 'PUT') return new Response(null, { status: 204 });
+ return json({ error: 'an ingest is already running' }, 409);
+ });
+ const got = await uploadChunked(link, digest(), { fetchImpl: f, ...noSleep });
+ assert.ok('error' in got && /409 .*already running/.test(got.error));
+});
+
+test('a complete lost on the way back, then told 409 on its retry, counts as started', async () => {
+ let completes = 0;
+ const { f } = recorder((c) => {
+ if (c.url.endsWith('/repo/uploads')) return json({ upload_id: 'u-6' }, 201);
+ if (c.method === 'PUT') return new Response(null, { status: 204 });
+ completes++;
+ if (completes === 1) throw new Error('socket hang up');
+ return json({ error: 'an ingest is already running' }, 409);
+ });
+ assert.deepEqual(await uploadChunked(link, digest(), { fetchImpl: f, ...noSleep }), { jobId: '' });
+});
+
+test('a server that advertised chunks but has no route falls back to the single POST', async () => {
+ const { calls, f } = recorder((c) => {
+ if (c.url.endsWith('/repo/uploads')) return json({ error: 'not found' }, 404);
+ return json({ job_id: 'job-7' }, 202);
+ });
+ const got = await uploadDigest(link, digest(), { chunked: true, gzip: true }, { fetchImpl: f, ...noSleep });
+ assert.deepEqual(got, { jobId: 'job-7' });
+ const post = calls.at(-1)!;
+ assert.equal(post.url, 'http://trail.test/api/public/brains/b1/repo');
+ assert.equal(post.headers['content-encoding'], 'gzip');
+});
+
+test('an older Trail gets the plain POST it always did', async () => {
+ const d = digest();
+ const { calls, f } = recorder(() => json({ job_id: 'job-8' }, 202));
+ assert.deepEqual(await uploadDigest(link, d, {}, { fetchImpl: f }), { jobId: 'job-8' });
+ assert.equal(calls.length, 1);
+ assert.equal(calls[0].headers['content-encoding'], undefined);
+ assert.equal(calls[0].body, JSON.stringify(d));
+});
+
+test('gzip alone is one gzipped POST of the same body', async () => {
+ const d = digest();
+ const { calls, f } = recorder(() => json({ job_id: 'job-10' }, 202));
+ await uploadDigest(link, d, { gzip: true }, { fetchImpl: f });
+ assert.equal(calls.length, 1);
+ assert.equal(calls[0].headers['content-encoding'], 'gzip');
+ assert.equal(gunzipSync(Buffer.from(calls[0].body as Uint8Array)).toString('utf8'), JSON.stringify(d));
+});
+
+test('the early upload is gzipped only when Trail says it takes gzip', async () => {
+ const { calls, f } = recorder(() => json({ early: true }, 202));
+ assert.equal(await pushEarlyDigest(link, digest(), f, { gzip: true }), true);
+ assert.equal(calls[0].headers['content-encoding'], 'gzip');
+ assert.match(calls[0].url, /\/repo\?stage=early$/);
+ await pushEarlyDigest(link, digest(), f);
+ assert.equal(calls[1].headers['content-encoding'], undefined);
+});
+
+test('the capability flags are read off the expected-repo response, and default to off', async () => {
+ const older = await fetchExpectedRepo(link, (async () => json({ repo: { slug: 'chalk/chalk' } })) as typeof fetch);
+ assert.deepEqual(uploadCaps(older), { gzip: false, chunked: false });
+ assert.equal(older?.events, false);
+ const newer = await fetchExpectedRepo(link, (async () =>
+ json({ repo: { slug: 'chalk/chalk', rule_count: 12 }, gzip_upload: true, chunked_upload: true, events: true })) as typeof fetch);
+ assert.deepEqual(uploadCaps(newer), { gzip: true, chunked: true });
+ assert.equal(newer?.events, true);
+ assert.equal(newer?.ruleCount, 12);
+});
+
+test('every call honours GRAFT_BRAIN_URL', async () => {
+ const before = process.env.GRAFT_BRAIN_URL;
+ process.env.GRAFT_BRAIN_URL = 'https://staging-agents.test/';
+ try {
+ const { calls, f } = recorder((c) => {
+ if (c.url.endsWith('/repo/uploads')) return json({ upload_id: 'u-9' }, 201);
+ if (c.method === 'PUT') return new Response(null, { status: 204 });
+ return json({ job_id: 'j' }, 202);
+ });
+ await uploadChunked(link, digest(), { fetchImpl: f, ...noSleep });
+ for (const c of calls) assert.ok(c.url.startsWith('https://staging-agents.test/api/public/brains/b1/repo/uploads'), c.url);
+ } finally {
+ if (before === undefined) delete process.env.GRAFT_BRAIN_URL;
+ else process.env.GRAFT_BRAIN_URL = before;
+ }
+});
diff --git a/test/brain-watch-events.test.ts b/test/brain-watch-events.test.ts
new file mode 100644
index 00000000..3ee65fe9
--- /dev/null
+++ b/test/brain-watch-events.test.ts
@@ -0,0 +1,183 @@
+/**
+ * The live watch: when Trail streams the build, the terminal follows it as it
+ * happens instead of polling every four seconds. What matters is that the
+ * stream is parsed exactly (keep-alives, split chunks, CRLF), that the suggestion
+ * counts ride along, and that a stream which drops costs nothing but the old
+ * polling behaviour.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { parseRepoBody, SseParser, watchBuild } from '../src/brain/watch.js';
+
+const LINK = { brainId: 'b1', token: 'gbt_1.sig', baseUrl: 'http://trail.test' };
+
+// --- the parser ---------------------------------------------------------------
+
+test('events are parsed across chunk boundaries, and keep-alives are dropped', () => {
+ const p = new SseParser();
+ assert.deepEqual(p.push(': ping\n\nevent: prog'), []);
+ assert.deepEqual(p.push('ress\ndata: {"a":'), []);
+ assert.deepEqual(p.push('1}\n\n'), [{ event: 'progress', data: '{"a":1}' }]);
+ assert.deepEqual(p.push('event: done\r\ndata: {}\r\n\r\n'), [{ event: 'done', data: '{}' }]);
+});
+
+test('multi-line data is joined, and a missing event name means message', () => {
+ const p = new SseParser();
+ assert.deepEqual(p.push('data: one\ndata:two\n\n'), [{ event: 'message', data: 'one\ntwo' }]);
+});
+
+test('a lone CR at the end of a chunk waits for its LF', () => {
+ const p = new SseParser();
+ assert.deepEqual(p.push('data: x\r'), []);
+ assert.deepEqual(p.push('\n\r\n'), [{ event: 'message', data: 'x' }]);
+});
+
+test('the suggestion counts are read whether Trail sends numbers or lists', () => {
+ const counted = parseRepoBody({
+ repo: { status: 'ingesting' },
+ claude_md: { status: 'ready', quick_ready: true, changes: 3 },
+ context_files: { files: 2, changes: 5 },
+ });
+ assert.deepEqual(counted?.suggestions, { claudeMd: 3, contextFiles: 5 });
+ const listed = parseRepoBody({
+ repo: { status: 'ingesting' },
+ claude_md: { changes: [{}, {}] },
+ context_files: { files: [{ kind: 'agents_md', path: 'AGENTS.md', changes: [{}, {}, {}] }] },
+ });
+ assert.deepEqual(listed?.suggestions, {
+ claudeMd: 2,
+ contextFiles: 3,
+ files: [{ kind: 'agents_md', path: 'AGENTS.md', changes: 3 }],
+ });
+ assert.equal(parseRepoBody({ repo: { status: 'ingesting' } })?.suggestions, undefined, 'an older Trail sends none');
+});
+
+// --- the stream ---------------------------------------------------------------
+
+/** A text/event-stream response that sends each part in turn, then ends (or not). */
+function stream(parts: string[], opts: { end?: boolean } = {}): Response {
+ const enc = new TextEncoder();
+ let i = 0;
+ const body = new ReadableStream<Uint8Array>({
+ pull(ctl) {
+ if (i < parts.length) ctl.enqueue(enc.encode(parts[i++]));
+ else if (opts.end !== false) ctl.close();
+ },
+ });
+ return new Response(body, { status: 200, headers: { 'content-type': 'text/event-stream' } });
+}
+
+const progress = (body: unknown) => `event: progress\ndata: ${JSON.stringify(body)}\n\n`;
+const NOW = { timeoutMs: 60_000, pollMs: 0, sleep: async () => {} };
+
+test('the stream settles the watch on the first rules, with the suggestions it carried', async () => {
+ const urls: string[] = [];
+ const accepts: string[] = [];
+ let seen: unknown = null;
+ const outcome = await watchBuild(LINK, {
+ ...NOW,
+ events: true,
+ write: () => {},
+ onState: (_v, repo) => (seen = repo.suggestions),
+ fetchImpl: (async (u: string, init?: RequestInit) => {
+ urls.push(u);
+ accepts.push(String((init?.headers as Record<string, string>).accept));
+ return stream([
+ ': ping\n\n',
+ progress({ repo: { status: 'ingesting', commit_count: 412 } }),
+ progress({
+ repo: { status: 'ingesting', commit_count: 412 },
+ build: { found_so_far: 40, filed_so_far: 5 },
+ claude_md: { changes: 4 },
+ context_files: { changes: 2 },
+ }),
+ ], { end: false });
+ }) as typeof fetch,
+ });
+ assert.equal(outcome, 'building');
+ assert.deepEqual(urls, ['http://trail.test/api/public/brains/b1/events'], 'one connection, no polling');
+ assert.equal(accepts[0], 'text/event-stream');
+ assert.deepEqual(seen, { claudeMd: 4, contextFiles: 2 });
+});
+
+test('a done event reports a failed build the same way polling would', async () => {
+ const lines: string[] = [];
+ const outcome = await watchBuild(LINK, {
+ ...NOW,
+ events: true,
+ write: (l) => lines.push(l),
+ fetchImpl: (async () =>
+ stream([
+ progress({ repo: { status: 'ingesting', commit_count: 10 } }),
+ `event: done\ndata: ${JSON.stringify({ repo: { status: 'failed', commit_count: 10, error_message: 'miner fell over' } })}\n\n`,
+ ])) as typeof fetch,
+ });
+ assert.equal(outcome, 'failed');
+ assert.match(lines.join('\n'), /the build stopped while mining rules · nothing was lost/);
+ assert.match(lines.join('\n'), /miner fell over/);
+});
+
+test('a stream that keeps dropping is reopened three times, then the watcher polls', async () => {
+ const hits: string[] = [];
+ const outcome = await watchBuild(LINK, {
+ ...NOW,
+ events: true,
+ write: () => {},
+ fetchImpl: (async (u: string) => {
+ hits.push(u.endsWith('/events') ? 'events' : 'poll');
+ if (u.endsWith('/events')) return stream([progress({ repo: { status: 'ingesting' } })]);
+ return new Response(JSON.stringify({ repo: { status: 'completed', rule_count: 42, commit_count: 9 } }), { status: 200 });
+ }) as typeof fetch,
+ });
+ assert.equal(outcome, 'completed');
+ assert.deepEqual(hits, ['events', 'events', 'events', 'events', 'poll']);
+});
+
+test('a Trail without the stream falls straight back to polling', async () => {
+ const hits: string[] = [];
+ const outcome = await watchBuild(LINK, {
+ ...NOW,
+ events: true,
+ write: () => {},
+ fetchImpl: (async (u: string) => {
+ hits.push(u.endsWith('/events') ? 'events' : 'poll');
+ if (u.endsWith('/events')) return new Response('not found', { status: 404 });
+ return new Response(JSON.stringify({ repo: { status: 'completed', rule_count: 1, commit_count: 1 } }), { status: 200 });
+ }) as typeof fetch,
+ });
+ assert.equal(outcome, 'completed');
+ assert.deepEqual(hits, ['events', 'poll']);
+});
+
+test('a silent stream counts as dropped once the keep-alives stop', async () => {
+ let connections = 0;
+ const outcome = await watchBuild(LINK, {
+ ...NOW,
+ events: true,
+ idleMs: 20,
+ maxReconnects: 0,
+ write: () => {},
+ fetchImpl: (async (u: string) => {
+ if (u.endsWith('/events')) {
+ connections++;
+ return stream([], { end: false });
+ }
+ return new Response(JSON.stringify({ repo: { status: 'completed', rule_count: 3, commit_count: 1 } }), { status: 200 });
+ }) as typeof fetch,
+ });
+ assert.equal(outcome, 'completed');
+ assert.equal(connections, 1);
+});
+
+test('without the events flag nothing asks for the stream', async () => {
+ const hits: string[] = [];
+ await watchBuild(LINK, {
+ ...NOW,
+ write: () => {},
+ fetchImpl: (async (u: string) => {
+ hits.push(u);
+ return new Response(JSON.stringify({ repo: { status: 'completed', rule_count: 1, commit_count: 1 } }), { status: 200 });
+ }) as typeof fetch,
+ });
+ assert.ok(hits.every((u) => u.endsWith('/repo')));
+});
diff --git a/test/brain-watch.test.ts b/test/brain-watch.test.ts
index cbd64a85..b9a9c162 100644
--- a/test/brain-watch.test.ts
+++ b/test/brain-watch.test.ts
@@ -5,7 +5,7 @@
*/
import { test } from 'node:test';
import assert from 'node:assert/strict';
-import { linesFor, stagesFrom, watchBuild, type RepoState } from '../src/brain/watch.js';
+import { failureLines, linesFor, stagesFrom, watchBuild, type RepoState } from '../src/brain/watch.js';
import { brainUrl } from '../src/brain/signup.js';
const row = (over: Partial<RepoState> = {}): RepoState => ({
@@ -62,15 +62,23 @@ test('done means the rules are in the brain, not just that the row closed', () =
// 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', () => {
+test('only finished stages print, each once, in the past tense', () => {
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/);
+ const reading = row({ commitCount: 412, threadCount: 89 });
+ const first = linesFor(stagesFrom(reading), printed, reading);
+ assert.deepEqual(first, [' ✓ reached the repository', ' ✓ read its history'], 'reach and read have settled; mine has not');
+ assert.deepEqual(linesFor(stagesFrom(reading), printed, reading), [], 'nothing reprints');
+ const done = row({ status: 'completed', commitCount: 412, threadCount: 89, ruleCount: 42 });
+ const later = linesFor(stagesFrom(done), printed, done);
+ assert.deepEqual(later, [' ✓ mined the first 42 rules'], 'filing is left to the closing line');
+});
+
+test('a failure says where it stopped, that nothing was lost, and the server\'s own words', () => {
+ const view = stagesFrom(row({ status: 'failed', commitCount: 412, errorMessage: 'parse response: unexpected end of JSON input' }));
+ assert.deepEqual(failureLines(view), [
+ '✗ the build stopped while mining rules · nothing was lost — run graft trail push again',
+ ' parse response: unexpected end of JSON input',
+ ]);
});
// --- the watcher ------------------------------------------------------------
@@ -109,8 +117,8 @@ test('the watcher holds until the brain is built', async () => {
]),
});
assert.equal(outcome, 'completed');
- assert.match(lines.join('\n'), /reaching the repository/);
- assert.match(lines.join('\n'), /42 rules/);
+ assert.match(lines.join('\n'), /reached the repository/);
+ assert.match(lines.join('\n'), /mined the first 42 rules/);
});
test('the watcher reports a failure rather than waiting out the clock', async () => {
@@ -201,7 +209,7 @@ test('the watcher hands the prompt back on the first rules, while the job runs o
]),
});
assert.equal(outcome, 'building');
- assert.match(lines.join('\n'), /mining the rules — 62 rules so far/);
+ assert.match(lines.join('\n'), /mined the first 62 rules/);
});
// A graft pointed at a Trail that does not send the in-flight counts must fall
diff --git a/test/claude-init.test.ts b/test/claude-init.test.ts
index 2a7fbf6d..3894bf04 100644
--- a/test/claude-init.test.ts
+++ b/test/claude-init.test.ts
@@ -84,7 +84,7 @@ test('CLI: --no-statusline leaves statusLine unset', () => {
const d = fresh();
const res = spawnSync(
process.execPath,
- ['--import', 'tsx', 'src/cli.ts', 'init', d, '--no-build', '--no-agents', '--no-statusline'],
+ ['--import', 'tsx', 'src/cli.ts', 'init', d, '--no-build', '--no-agents', '--no-statusline', '--verbose'],
{ encoding: 'utf8' },
);
assert.equal(res.status, 0, res.stderr);
@@ -160,7 +160,7 @@ test('formatInitEpilogue: graph not built shows "build the graph" as step 1, no
assert.equal(col(built, 'restart your agent'), col(notBuilt, 'restart your agent'));
});
-test('CLI: graft init epilogue has the wordmark + next steps, and never mentions OPENROUTER', () => {
+test('CLI: graft init prints one line per step, and no banner', () => {
const d = fresh();
const res = spawnSync(
process.execPath,
@@ -168,6 +168,22 @@ test('CLI: graft init epilogue has the wordmark + next steps, and never mentions
{ encoding: 'utf8' },
);
assert.equal(res.status, 0, res.stderr);
+ assert.match(res.stderr, /skipped the graph build — run graft build/);
+ assert.match(res.stderr, /✓ claude +\.claude[\\/], \.mcp\.json/);
+ assert.match(res.stderr, /restart your agents so a new session picks up graft/);
+ assert.match(res.stderr, /commit \.claude\/ \.mcp\.json to share it — graft\/ stays local and git-ignored/);
+ assert.ok(!res.stderr.includes('|___/'), 'the banner is --verbose only');
+ assert.ok(!res.stderr.includes('✓ wrote'), 'file-by-file lines are --verbose only');
+});
+
+test('CLI: graft init --verbose epilogue has the wordmark + next steps, and never mentions OPENROUTER', () => {
+ const d = fresh();
+ const res = spawnSync(
+ process.execPath,
+ ['--import', 'tsx', 'src/cli.ts', 'init', d, '--no-build', '--no-agents', '--verbose'],
+ { encoding: 'utf8' },
+ );
+ assert.equal(res.status, 0, res.stderr);
assert.ok(res.stderr.includes('|___/'), 'wordmark present');
assert.ok(res.stderr.includes('code as usual'));
assert.ok(res.stderr.includes('restart your agent'));
diff --git a/test/cli-picker.test.ts b/test/cli-picker.test.ts
index d13f049c..a519f5fb 100644
--- a/test/cli-picker.test.ts
+++ b/test/cli-picker.test.ts
@@ -7,7 +7,7 @@ import { planInit } from '../src/hosts/plan.js';
import {
KEY_CTRL_C, KEY_DOWN, KEY_ESC, KEY_UP,
describeWrites, formatNonInteractiveHelp, formatPlan, initialPickerState,
- keyOf, keysOf, pickedHostIds, pickedIds, pickedTelemetry, reducePicker, renderPicker, tilde,
+ compactWrites, keyOf, keysOf, pickedHostIds, pickedIds, pickedTelemetry, reducePicker, renderPicker, tilde, visibleRows,
TELEMETRY_ROW_ID,
type PickerKey,
} from '../src/cli-picker.js';
@@ -100,16 +100,21 @@ test('down then space adds the second host', () => {
assert.deepEqual(pickedIds(state), ['claude', 'agents']);
});
+/** Rows on screen before `m`: the agents graft found, and nothing else. */
+function shownCount(repo: string, home: string): number {
+ return visibleRows(initialPickerState(planInit(repo, { home }), repo, home)).length;
+}
+
test('cursor wraps at both ends', () => {
const repo = fresh(); const home = fullHome();
- const n = planInit(repo, { home }).length;
+ const n = shownCount(repo, home);
assert.equal(drive(repo, home, ['up']).cursor, n - 1);
assert.equal(drive(repo, home, Array(n).fill('down') as PickerKey[]).cursor, 0);
});
test('a toggles all on, then all off', () => {
const repo = fresh(); const home = fullHome();
- const n = planInit(repo, { home }).length;
+ const n = shownCount(repo, home);
assert.equal(pickedIds(drive(repo, home, ['all'])).length, n);
assert.deepEqual(pickedIds(drive(repo, home, ['all', 'all'])), []);
});
@@ -169,15 +174,38 @@ test('describeWrites truncates long path lists', () => {
assert.match(describeWrites(claude.writes, repo, home), /\+2 more/);
});
-test('renderPicker marks the cursor, the checkboxes and undetected hosts', () => {
+test('renderPicker marks the cursor and folds undetected hosts into one line', () => {
const repo = fresh(); const home = fresh(); // nothing installed
const state = initialPickerState(planInit(repo, { home }), repo, home);
const text = renderPicker(state, false);
+ assert.match(text, /^graft init — pick the agents your team uses:/);
assert.match(text, /› \[x\] claude/);
- assert.match(text, /\[ \] cursor.*\(not detected\)/);
- assert.match(text, /space toggle/);
- // Every host gets a row, plus header, blank lines and the key legend.
- assert.equal(text.split('\n').filter((l) => /\[[ x]\]/.test(l)).length, state.rows.length);
+ assert.doesNotMatch(text, /\[ \] cursor/, 'an agent graft cannot find is folded away');
+ assert.match(text, /\+ \d+ not detected \(.*cursor.*\) · m to show/);
+ assert.match(text, /space toggle · a all · m more · enter confirm/);
+ // Only the detected rows get a checkbox until `m`.
+ assert.equal(text.split('\n').filter((l) => /\[[ x]\]/.test(l)).length, visibleRows(state).length);
+
+ const opened = reducePicker(state, 'more');
+ const all = renderPicker(opened, false);
+ assert.match(all, /\[ \] cursor \(not detected\)/);
+ assert.equal(all.split('\n').filter((l) => /\[[ x]\]/.test(l)).length, state.rows.length);
+});
+
+test('a never selects an agent that is folded away', () => {
+ const repo = fresh(); const home = fresh();
+ const state = reducePicker(initialPickerState(planInit(repo, { home }), repo, home), 'all');
+ for (const id of pickedIds(state)) {
+ assert.ok(state.rows.find((r) => r.id === id)?.detected, `${id} was folded and must not be picked`);
+ }
+});
+
+test('compactWrites shows a folder written into several times once, and two entries at most', () => {
+ const repo = fresh(); const home = fullHome();
+ const [claude] = planInit(repo, { home, ids: ['claude'] });
+ assert.equal(compactWrites(claude.writes, repo, home), `.claude${sep}, .mcp.json · + 3 in ~${sep}`);
+ const cursor = planInit(repo, { home, ids: ['cursor'] })[0];
+ assert.match(compactWrites(cursor.writes, repo, home), /^[^,]+, [^,]+ \+\d+ more$/);
});
test('formatPlan separates repo writes from machine-wide ones', () => {
@@ -273,7 +301,7 @@ test('the consent row is never returned as an agent to wire', () => {
test('a (toggle all) is about agents and leaves the consent answer alone', () => {
const repo = fresh(); const home = fullHome();
- const n = planInit(repo, { home }).length;
+ const n = shownCount(repo, home);
// On: every agent selected, consent still the default yes.
const on = driveWithConsent(repo, home, ['all']);
assert.equal(pickedHostIds(on).length, n);
@@ -293,7 +321,6 @@ test('the rendered row shows the label, a rule, and what is not collected', () =
const out = renderPicker(initialPickerState(planInit(repo, { home }), repo, home, { offerTelemetry: true }), false);
assert.match(out, /\[x\] anonymous usage stats/);
assert.match(out, /no code, no file paths, no queries/);
- assert.match(out, /TELEMETRY\.md/);
assert.equal(out.includes(TELEMETRY_ROW_ID), false, 'the internal id must never be shown');
assert.match(out, /─/, 'a rule separates the settings from the agents');
});
diff --git a/test/hosts-init.test.ts b/test/hosts-init.test.ts
index cbbd3c37..f7b7d188 100644
--- a/test/hosts-init.test.ts
+++ b/test/hosts-init.test.ts
@@ -218,7 +218,7 @@ test('CLI: --yes wires every detected agent (the pre-0.8 default)', () => {
test('CLI: --no-global writes AGENTS.md but leaves ~/.codex alone', () => {
const home = fresh(); const repo = fresh();
mkdirSync(join(home, '.codex'), { recursive: true });
- const out = cliStderr(repo, home, ['--agents', 'agents', '--no-global']);
+ const out = cliStderr(repo, home, ['--agents', 'agents', '--no-global', '--verbose']);
assert.ok(existsSync(join(repo, 'AGENTS.md')));
assert.deepEqual(readdirSync(join(home, '.codex')), []);
assert.match(out, /skipped out-of-repo writes/);
@@ -230,7 +230,7 @@ test('CLI: the graph build is attempted even when claude is not selected', () =>
// Regression: the build used to sit inside `if (wantClaude)`, so picking only
// cursor wired .cursor/ and never built the graph its rule file points at.
const out = cliStderr(repo, home, ['--agents', 'cursor']);
- assert.match(out, /(built the graph|skipped graph build)/);
+ assert.match(out, /(built the graph|graph built|skipped graph build|skipped the graph build)/);
});
test('CLI: --no-global stays quiet when the selection has nothing out-of-repo', () => {