Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
/**
* A use of the learnings sent to a Trail workspace names only learnings the
* workspace itself got: the ones committed at HEAD or on a pushed branch. A
* learning's file name carries the first words of its title, so a personal
* learning, and one not yet committed, stay on this machine name and all.
*/
import { test } from "node:test";
import assert from "node:assert/strict";
import { spawnSync } from "node:child_process";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { BRAND_ENV } from "../src/brand.js";
import { dropActivity, flushActivity, syncRepo } from "../src/cloud/workspace-sync.js";
import { isError, writeCloud, type Cloud } from "../src/cloud/workspace.js";
import { cacheDir } from "../src/util/state.js";
import { tmpRepo } from "./helpers.js";
import { escapeRe } from "./escape.js";
process.env.DO_NOT_TRACK = "1";
process.env[BRAND_ENV] = "trail";
process.env.TRAIL_NO_FETCH = "1";
process.env.TRAIL_HOME = mkdtempSync(join(tmpdir(), "upload-names-home-"));
const KEY = "github.com/acme/extract";
function git(cwd: string, ...args: string[]): string {
const r = spawnSync("git", ["-c", "commit.gpgsign=false", ...args], { cwd, encoding: "utf8" });
if (r.status !== 0) throw new Error(`git ${args.join(" ")}: ${r.stderr}`);
return r.stdout;
}
const learning = (title: string, touches: string, body: string, date = "2026-10-07") =>
`---\ntitle: ${title}\nauthor: Priya\ndate: ${date}\ntouches:\n - ${touches}\n---\n${body}\n`;
/** A connection, and a fake Trail that records what it's sent. */
function cloudFor(repos: string[]) {
const sent: Array<{ path: string; raw: string; body: any }> = [];
const fetchImpl = (async (url: string, init: RequestInit) => {
const path = new URL(url).pathname;
const raw = init.body ? String(init.body) : "";
const body = raw ? JSON.parse(raw) : undefined;
sent.push({ path, raw, body });
const json = (status: number, b: unknown) => new Response(JSON.stringify(b), { status });
if (path === "/api/cli/learnings") return json(200, { repo: body.repo.key, learnings: body.learnings.length, added: 0 });
if (path === "/api/cli/activity") return json(200, { stored: body.events.length });
return json(404, { error: "no route" });
}) as typeof fetch;
const cloud: Cloud = {
url: "http://trail.test",
token: "trl_x",
user: { name: "Priya", email: "[email protected]" },
workspace: { id: "w", name: "Acme", slug: "acme", url: "http://trail.test/w/acme", invite_url: "http://trail.test/join/x" },
repos,
linkedAt: Date.now() - 60_000,
};
return { cloud, sent, fetchImpl };
}
const down = (async () => {
throw new Error("offline");
}) as typeof fetch;
/**
* A GitHub-backed repo with `files` committed, connected to the workspace
* from a scratch HOME, and `trail` to run there. `personal` is where this
* person's own learnings for the repo live.
*/
function scratch(tag: string, files: Record<string, string>) {
const home = mkdtempSync(join(tmpdir(), `upload-names-${tag}-`));
const trailHome = join(home, ".trail");
const d = tmpRepo(`upload-names-${tag}`);
for (const [p, text] of Object.entries(files)) {
mkdirSync(dirname(join(d, p)), { recursive: true });
writeFileSync(join(d, p), text);
}
git(d, "init", "-q", "-b", "main");
git(d, "config", "user.name", "Priya Raman");
git(d, "config", "user.email", "[email protected]");
git(d, "add", "-A");
git(d, "commit", "-qm", "init");
git(d, "remote", "add", "origin", `https://${KEY}.git`);
const env = { ...process.env, HOME: home, USERPROFILE: home, TRAIL_HOME: trailHome, DO_NOT_TRACK: "1", TRAIL_NO_FETCH: "1", CLAUDECODE: undefined, TRAIL_INVOKED_AS: undefined, CLAUDE_CODE_SESSION_ID: `s-${tag}` };
const cli = (args: string[]) => spawnSync(process.execPath, ["--import", "tsx", join(process.cwd(), "src", "bin", "trail.ts"), ...args], { encoding: "utf8", env, timeout: 120_000 });
const trail = cloudFor([KEY]);
writeCloud(trail.cloud, { ...process.env, TRAIL_HOME: trailHome });
const personal = join(trailHome, "repos", ...KEY.split("/"), "notes");
mkdirSync(personal, { recursive: true });
return { trailHome, d, cli, personal, ...trail };
}
/** Run `fn` with this process's ~/.trail at `trailHome`, as the background sync there would. */
async function inHome<T>(trailHome: string, fn: () => Promise<T>): Promise<T> {
const saved = process.env.TRAIL_HOME;
process.env.TRAIL_HOME = trailHome;
try {
return await fn();
} finally {
process.env.TRAIL_HOME = saved;
}
}
const outboxText = (trailHome: string) => {
const p = join(trailHome, "outbox.jsonl");
return existsSync(p) ? readFileSync(p, "utf8") : "";
};
const BBOX_GO = "package ocr\n\nfunc NormalizeBox(x float64, rotate int) float64 {\n\treturn x\n}\n";
const COMMITTED = "2026-10-07-bbox-rotated-pdf-priya.md";
const committedBbox = learning("Bbox coordinates are off on rotated PDFs", "internal/ocr/bbox.go", "## Decided\nRotate each box by its page's /Rotate before scaling.");
const QUERY = "bbox rotated pdf";
test("a search never names a personal learning: not in the outbox, not in what's sent", async () => {
const s = scratch("personal", { "internal/ocr/bbox.go": BBOX_GO, [`.trail/learnings/${COMMITTED}`]: committedBbox });
const mine = "2026-10-09-bbox-personal-skpersonal999-priya.md";
writeFileSync(join(s.personal, mine), learning("Bbox personal skpersonal999 rotated pdf", "internal/ocr/bbox.go", "## Watch out\nPersonal only, synthetic.", "2026-10-09"));
assert.equal(s.cli(["build", s.d]).status, 0);
const ask = s.cli(["ask", QUERY, s.d, "--json", "-n", "3"]);
assert.equal(ask.status, 0, ask.stderr);
const shown = (JSON.parse(ask.stdout).notes ?? []).map((h: any) => h.note.path as string);
assert.ok(shown.some((p: string) => p.endsWith(mine)), "the personal learning was shown to the agent");
assert.ok(shown.some((p: string) => p.endsWith(COMMITTED)), "and so was the committed one");
const queued = outboxText(s.trailHome);
assert.ok(!queued.includes("skpersonal999"), "queued its name");
assert.deepEqual(JSON.parse(queued.trim()).shown_paths, [COMMITTED]);
await inHome(s.trailHome, async () => {
await syncRepo(s.d, s.cloud, { fetch: false, fetchImpl: s.fetchImpl });
assert.equal(await flushActivity(s.cloud, s.fetchImpl), 1);
});
const req = s.sent.find((x) => x.path === "/api/cli/activity")!;
assert.ok(!req.raw.includes("skpersonal999"), "sent its name");
assert.deepEqual(req.body.events[0].shown_paths, [COMMITTED]);
assert.deepEqual(req.body.events[0].shown_authors, ["Priya"]);
});
test("a search never sends the name of a learning git doesn't have at HEAD, nor keeps it to send later", async () => {
const s = scratch("untracked", { "internal/ocr/bbox.go": BBOX_GO, [`.trail/learnings/${COMMITTED}`]: committedBbox });
const draft = "2026-10-08-bbox-uncommitted-globexdraft-priya.md";
writeFileSync(join(s.d, ".trail", "learnings", draft), learning("Bbox uncommitted globexdraft rotated pdf", "internal/ocr/bbox.go", "## Decided\nUntracked draft.", "2026-10-08"));
assert.equal(s.cli(["build", s.d]).status, 0);
const ask = s.cli(["ask", QUERY, s.d, "--json", "-n", "3"]);
assert.equal(ask.status, 0, ask.stderr);
const shown = (JSON.parse(ask.stdout).notes ?? []).map((h: any) => h.note.path as string);
assert.ok(shown.some((p: string) => p.endsWith(draft)), "the untracked learning was shown to the agent");
await inHome(s.trailHome, async () => {
await syncRepo(s.d, s.cloud, { fetch: false, fetchImpl: s.fetchImpl });
// Trail down: what's put back for next time has lost the name too.
assert.equal(await flushActivity(s.cloud, down), 0);
assert.ok(outboxText(s.trailHome).trim(), "the use is kept");
assert.ok(!outboxText(s.trailHome).includes("globexdraft"), "kept its name to send later");
assert.equal(await flushActivity(s.cloud, s.fetchImpl), 1);
});
for (const x of s.sent) assert.ok(!x.raw.includes("globexdraft"), `sent its name to ${x.path}`);
const req = s.sent.find((x) => x.path === "/api/cli/activity")!;
assert.deepEqual(req.body.events[0].shown_paths, [COMMITTED]);
assert.deepEqual(req.body.events[0].shown_authors, ["Priya"]);
});
test("a check never names a personal learning it checked against", async () => {
const name = "2026-10-03-ocr-retries-priya.md";
const s = scratch("check", {
"internal/ocr/client.go": "package ocr\n\nconst retries = 3\n",
[`.trail/learnings/${name}`]: learning("OCR retries lock us out", "internal/ocr/client.go", "## Watch out\n- 5 retries got us locked out for a minute.", "2026-10-03"),
});
const mine = "2026-10-04-webhook-skpersonal999-priya.md";
writeFileSync(join(s.personal, mine), learning("Webhook skpersonal999 retries", "internal/ocr/client.go", "## Decided\nThree retries with jitter.", "2026-10-04"));
writeFileSync(join(s.d, "internal", "ocr", "client.go"), "package ocr\n\nconst retries = 5\n");
const check = s.cli(["check", s.d, "--base", "HEAD", "--json"]);
const r = JSON.parse(check.stdout);
const sources = r.findings.map((f: any) => f.source.path ?? "");
assert.ok(sources.some((p: string) => p.endsWith(mine)), "the personal learning was checked against");
assert.ok(sources.some((p: string) => p.endsWith(name)), "and so was the committed one");
const queued = outboxText(s.trailHome);
assert.ok(!queued.includes("skpersonal999"), "queued its name");
const e = JSON.parse(queued.trim());
assert.equal(e.kind, "check");
assert.deepEqual(e.shown_paths, [name]);
await inHome(s.trailHome, async () => {
await syncRepo(s.d, s.cloud, { fetch: false, fetchImpl: s.fetchImpl });
assert.equal(await flushActivity(s.cloud, s.fetchImpl), 1);
});
for (const x of s.sent) assert.ok(!x.raw.includes("skpersonal999"), `sent its name to ${x.path}`);
});
test("only names the repo's last upload had go up, with that upload's authors; an older trail's lines and a repo never synced included", async () => {
const s = scratch("unit", { [`.trail/learnings/${COMMITTED}`]: committedBbox });
const other = "github.com/acme/billing";
s.cloud.repos.push(other);
const at = new Date().toISOString();
const line = (repo: string, kind: string, paths: string[], authors: string[]) =>
JSON.stringify({ repo, kind, asker: "Kumar", session: "s1", file_count: 1, shown_paths: paths, shown_authors: authors, at });
await inHome(s.trailHome, async () => {
await syncRepo(s.d, s.cloud, { fetch: false, fetchImpl: s.fetchImpl });
writeFileSync(
join(s.trailHome, "outbox.jsonl"),
[
line(KEY, "search", [COMMITTED, "2026-10-09-globexdraft-kumar.md"], ["Someone Else", "Kumar"]),
// An older trail's check: names and authors each deduped, not in step.
line(KEY, "check", ["2026-10-09-globexdraft-kumar.md", COMMITTED], ["Kumar"]),
line(other, "search", ["2026-10-01-billing-globexdraft-kumar.md"], ["Kumar"]),
].join("\n") + "\n",
);
assert.equal(await flushActivity(s.cloud, s.fetchImpl), 3);
});
const req = s.sent.find((x) => x.path === "/api/cli/activity")!;
assert.ok(!req.raw.includes("globexdraft"));
assert.deepEqual(
req.body.events.map((e: any) => [e.repo, e.kind, e.shown_paths, e.shown_authors]),
[
[KEY, "search", [COMMITTED], ["Priya"]],
[KEY, "check", [COMMITTED], ["Priya"]],
[other, "search", [], []],
],
);
});
test("connecting again forgets what an earlier connection was sent: its names vouch for nothing", async () => {
const s = scratch("reconnect", { [`.trail/learnings/${COMMITTED}`]: committedBbox });
await inHome(s.trailHome, async () => {
await syncRepo(s.d, s.cloud, { fetch: false, fetchImpl: s.fetchImpl });
dropActivity();
writeFileSync(
join(s.trailHome, "outbox.jsonl"),
`${JSON.stringify({ repo: KEY, kind: "search", asker: "Kumar", session: "s1", file_count: 1, shown_paths: [COMMITTED], shown_authors: ["Priya"], at: new Date().toISOString() })}\n`,
);
assert.equal(await flushActivity(s.cloud, s.fetchImpl), 1);
});
const req = s.sent.find((x) => x.path === "/api/cli/activity")!;
assert.deepEqual(req.body.events[0].shown_paths, []);
});
test("a learning holding a secret never goes up, committed or on a pushed branch, and no use names it", async () => {
// Synthetic, assembled at run time.
const key = ["s", "k-proj-", "Ab3dE5fG7hJ9kL1mN3pQ5rS7tU9vW1xY3z"].join("");
const leaky = (title: string, date: string) =>
learning(title, "internal/ocr/bbox.go", `## Decided\nThe staging OCR account answers to ${key} for now.`, date);
const atHead = "2026-10-08-staging-leakyhead-account-priya.md";
const onBranch = "2026-10-09-staging-leakybranch-account-kumar.md";
const branchOk = "2026-10-09-ocr-retry-jitter-kumar.md";
const s = scratch("secret", { [`.trail/learnings/${COMMITTED}`]: committedBbox, [`.trail/learnings/${atHead}`]: leaky("Staging leakyhead OCR account", "2026-10-08") });
mkdirSync(cacheDir(s.d), { recursive: true });
writeFileSync(
join(cacheDir(s.d), "trail-branches.json"),
JSON.stringify({
fetchedAt: Date.now(),
base: "origin/main",
branches: [
{
ref: "origin/kumar/staging",
author: "Kumar",
at: Date.now(),
files: [],
learnings: [
{ name: onBranch, text: leaky("Staging leakybranch OCR account", "2026-10-09") },
{ name: branchOk, text: learning("OCR retries need jitter", "internal/ocr/client.go", "## Decided\nJitter each retry.", "2026-10-09") },
],
},
],
}),
);
await inHome(s.trailHome, async () => {
const res = await syncRepo(s.d, s.cloud, { fetch: false, fetchImpl: s.fetchImpl });
assert.ok(!isError(res), JSON.stringify(res));
writeFileSync(
join(s.trailHome, "outbox.jsonl"),
`${JSON.stringify({ repo: KEY, kind: "search", asker: "Kumar", session: "s1", file_count: 1, shown_paths: [COMMITTED, atHead, onBranch, branchOk], shown_authors: ["Priya", "Priya", "Kumar", "Kumar"], at: new Date().toISOString() })}\n`,
);
assert.equal(await flushActivity(s.cloud, s.fetchImpl), 1);
});
const up = s.sent.find((x) => x.path === "/api/cli/learnings")!;
assert.deepEqual(up.body.learnings.map((l: any) => l.path).sort(), [`.trail/learnings/${COMMITTED}`, `.trail/learnings/${branchOk}`].sort());
for (const x of s.sent) {
assert.ok(!x.raw.includes(key), `sent the key to ${x.path}`);
assert.doesNotMatch(x.raw, /leaky(head|branch)/, `sent a refused learning's name to ${x.path}`);
}
const req = s.sent.find((x) => x.path === "/api/cli/activity")!;
assert.deepEqual(req.body.events[0].shown_paths, [COMMITTED, branchOk]);
// Each named learning's author as uploaded (both files say Priya), never the use's own list.
assert.deepEqual(req.body.events[0].shown_authors, ["Priya", "Priya"]);
});
test("only live learnings go up: a retired, held or replaced one never does, and no use names it", async () => {
const s = scratch("live", {
[`.trail/learnings/${COMMITTED}`]: committedBbox,
".trail/learnings/2026-10-07-old-retry-retired-priya.md": `---\ntitle: Old retry rule\nauthor: Priya\ndate: 2026-10-07\nstatus: retired\n---\n## Decided\nx\n`,
".trail/learnings/2026-10-07-retry-held-priya.md": `---\ntitle: Held retry rule\nauthor: Priya\ndate: 2026-10-07\nstatus: held\n---\n## Decided\nx\n`,
".trail/learnings/2026-10-07-keep-four-priya.md": `---\ntitle: Keep four retries\nauthor: Priya\ndate: 2026-10-07\nid: l-0a0a0a0a\n---\n## Decided\n4\n`,
".trail/learnings/2026-10-08-raise-to-six-priya.md": `---\ntitle: Raise to six retries\nauthor: Priya\ndate: 2026-10-08\nid: l-0b0b0b0b\nreplaces: l-0a0a0a0a\n---\n## Decided\n6\n`,
});
mkdirSync(cacheDir(s.d), { recursive: true });
// A replacement on a teammate's unmerged branch goes up as itself, and hides nothing yet.
const onBranch = "2026-10-09-retry-bbox-kumar.md";
writeFileSync(
join(cacheDir(s.d), "trail-branches.json"),
JSON.stringify({
fetchedAt: Date.now(),
base: "origin/main",
branches: [{ ref: "origin/kumar/bbox", author: "Kumar", at: Date.now(), files: [], learnings: [{ name: onBranch, text: `---\ntitle: Bbox redo\nauthor: Kumar\ndate: 2026-10-09\nid: l-0c0c0c0c\nreplaces: ${"l-"}${"0".repeat(8)}\n---\n## Decided\ny\n` }] }],
}),
);
await inHome(s.trailHome, async () => {
const res = await syncRepo(s.d, s.cloud, { fetch: false, fetchImpl: s.fetchImpl });
assert.ok(!isError(res), JSON.stringify(res));
writeFileSync(
join(s.trailHome, "outbox.jsonl"),
`${JSON.stringify({ repo: KEY, kind: "search", asker: "Kumar", session: "s1", file_count: 1, shown_paths: [COMMITTED, "2026-10-07-old-retry-retired-priya.md", "2026-10-07-keep-four-priya.md"], shown_authors: ["Priya", "Priya", "Priya"], at: new Date().toISOString() })}\n`,
);
assert.equal(await flushActivity(s.cloud, s.fetchImpl), 1);
});
const up = s.sent.find((x) => x.path === "/api/cli/learnings")!;
assert.deepEqual(
up.body.learnings.map((l: any) => l.path).sort(),
[COMMITTED, "2026-10-08-raise-to-six-priya.md", onBranch].map((n) => `.trail/learnings/${n}`).sort(),
);
const req = s.sent.find((x) => x.path === "/api/cli/activity")!;
assert.deepEqual(req.body.events[0].shown_paths, [COMMITTED], "a use never names a learning that didn't go up");
});
test("trail workspace names a learning left out for a secret, and why, instead of leaving it silently missing", async () => {
const key = ["s", "k-proj-", "Ab3dE5fG7hJ9kL1mN3pQ5rS7tU9vW1xY3z"].join("");
const leaky = "2026-10-08-staging-ocr-account-priya.md";
const s = scratch("left-out", {
[`.trail/learnings/${COMMITTED}`]: committedBbox,
[`.trail/learnings/${leaky}`]: learning("Staging OCR account", "internal/ocr/bbox.go", `## Decided\nThe staging OCR account answers to ${key} for now.`, "2026-10-08"),
});
const { createServer } = await import("node:http");
const server = createServer((req, res) => {
res.setHeader("content-type", "application/json");
if (req.url === "/api/cli/me")
res.end(JSON.stringify({ user: s.cloud.user, workspace: s.cloud.workspace, repos: [{ key: KEY, name: "acme/extract", learnings: 1, added_by: "Priya" }] }));
else {
res.statusCode = 404;
res.end("{}");
}
});
await new Promise<void>((done) => server.listen(0, "127.0.0.1", done));
const port = (server.address() as { port: number }).port;
writeCloud({ ...s.cloud, url: `http://127.0.0.1:${port}` }, { ...process.env, TRAIL_HOME: s.trailHome });
const { spawn } = await import("node:child_process");
const home = dirname(s.trailHome);
const env = { ...process.env, HOME: home, USERPROFILE: home, TRAIL_HOME: s.trailHome, DO_NOT_TRACK: "1", TRAIL_NO_FETCH: "1", CLAUDECODE: undefined, TRAIL_INVOKED_AS: undefined };
const out = await new Promise<{ code: number | null; out: string; err: string }>((done) => {
const child = spawn(process.execPath, ["--import", "tsx", join(process.cwd(), "src", "bin", "trail.ts"), "workspace", s.d], { env });
let o = "";
let e = "";
child.stdout.on("data", (b) => (o += b));
child.stderr.on("data", (b) => (e += b));
child.on("close", (code) => done({ code, out: o, err: e }));
});
server.close();
assert.equal(out.code, 0, out.err);
assert.match(out.out, new RegExp(`left out: ${escapeRe(leaky)}: looks like it holds a secret \\(an API key\\)`), out.out + out.err);
assert.doesNotMatch(out.out, new RegExp(escapeRe(COMMITTED)), "only what was left out is named");
assert.ok(!out.out.includes(key), "the secret itself is never printed");
});