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
/**
* Which repo a folder belongs to, for notes kept in ~/.trail/repos/<key>/:
* one key per repo however it's checked out (clones, worktrees, subfolders),
* its own key for a repo inside another (submodules, nested repos), a key
* that survives a renamed remote, and a folder of repos that reads them all.
*/
import { test } from "node:test";
import assert from "node:assert/strict";
import { spawnSync } from "node:child_process";
import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
import { homedir, tmpdir } from "node:os";
import { join } from "node:path";
import {
childCheckouts,
ensureRepoHome,
findRepoPlace,
keepsNotes,
keyFromRemote,
noteCount,
notePlaces,
remoteUrl,
repoPlace,
shownPath,
} from "../src/notes/home.js";
import { listNotes, noteTargets, writeNote } from "../src/notes/notes.js";
import { tmpRepo } from "./helpers.js";
/** A fresh ~/.trail per test, so keys and aliases never leak between them. */
function home(): NodeJS.ProcessEnv {
const env = { ...process.env, TRAIL_HOME: mkdtempSync(join(tmpdir(), "trail-home-")) };
process.env.TRAIL_HOME = env.TRAIL_HOME;
return env;
}
function git(cwd: string, ...args: string[]): string {
const r = spawnSync("git", ["-c", "commit.gpgsign=false", "-c", "init.defaultBranch=main", ...args], { cwd, encoding: "utf8" });
assert.equal(r.status, 0, `git ${args.join(" ")}: ${r.stderr}`);
return r.stdout.trim();
}
/** A repo with one commit, and `origin` when given. */
function repo(tag: string, origin?: string, files: Record<string, string> = { "main.go": "package main\n" }): string {
const d = tmpRepo(tag);
for (const [f, text] of Object.entries(files)) {
mkdirSync(join(d, f, ".."), { recursive: true });
writeFileSync(join(d, f), text);
}
git(d, "init", "-q");
git(d, "config", "user.name", "Priya Raman");
git(d, "config", "user.email", "[email protected]");
git(d, "add", "-A");
git(d, "commit", "-qm", "init");
if (origin) git(d, "remote", "add", "origin", origin);
return d;
}
const BODY = "## Decided\nRotate each box by its page's /Rotate.";
// --- a remote, as a key ---
test("a remote becomes host/owner/name, however it's spelled", () => {
for (const url of [
"[email protected]:NanoNets/Graft.git",
"https://github.com/NanoNets/Graft",
"https://github.com/nanonets/graft.git/",
"https://x-access-token:[email protected]/NanoNets/Graft.git",
"ssh://[email protected]:22/NanoNets/Graft.git",
])
assert.equal(keyFromRemote(url), "github.com/nanonets/graft", url);
assert.equal(keyFromRemote("[email protected]:acme/platform/extract.git"), "gitlab.com/acme/platform/extract", "subgroups stay");
assert.equal(keyFromRemote("https://github.com/acme/../../etc"), "github.com/acme/etc", "never climbs out of ~/.trail");
});
test("a remote that's a path on this machine isn't a key: those repos go by path", () => {
for (const url of ["/srv/git/extract.git", "../extract", "file:///srv/git/extract.git", "C:\\repos\\extract"]) assert.equal(keyFromRemote(url), null, url);
});
test("origin wins; a repo with other remotes uses the first; none, none", () => {
const cfg = '[core]\n\tbare = false\n[remote "upstream"]\n\turl = [email protected]:acme/up.git\n[remote "origin"]\n\turl = [email protected]:priya/fork.git\n';
assert.equal(remoteUrl(cfg), "[email protected]:priya/fork.git");
assert.equal(remoteUrl('[remote "upstream"]\n url = [email protected]:acme/up.git\n'), "[email protected]:acme/up.git");
assert.equal(remoteUrl("[core]\n\tbare = false\n"), null);
});
// --- one repo, however it's checked out ---
test("two clones, a subfolder and a worktree of one repo share one folder", () => {
const env = home();
const a = repo("clone-a", "[email protected]:acme/extract.git", { "internal/ocr/bbox.go": "package ocr\n" });
const b = repo("clone-b", "https://github.com/acme/extract.git");
const wt = join(tmpRepo("wt-parent"), "extract-wt");
git(a, "worktree", "add", "-q", "-b", "fix/bbox", wt);
const want = join(env.TRAIL_HOME!, "repos", "github.com", "acme", "extract");
for (const dir of [a, b, join(a, "internal", "ocr"), wt]) assert.equal(repoPlace(dir).dir, want, dir);
assert.equal(repoPlace(join(a, "internal")).checkout, a, "the checkout is the top of the repo");
assert.equal(repoPlace(wt).checkout, wt, "a worktree reads touches against its own top");
});
test("a worktree of a repo with no remote shares its main checkout's folder", () => {
home();
const main = repo("local-main");
const wt = join(tmpRepo("wt-local"), "wt");
git(main, "worktree", "add", "-q", "-b", "side", wt);
assert.match(repoPlace(main).key, /^local\//);
assert.equal(repoPlace(wt).key, repoPlace(main).key);
});
test("a repo inside another is its own repo: a nested clone, and a submodule's .git file", () => {
home();
const outer = repo("outer", "[email protected]:acme/app.git");
// A clone sitting inside another repo's tree.
const nested = join(outer, "vendor", "ocr-lib");
mkdirSync(nested, { recursive: true });
git(nested, "init", "-q");
git(nested, "remote", "add", "origin", "[email protected]:acme/ocr-lib.git");
assert.equal(repoPlace(join(nested)).key, "github.com/acme/ocr-lib");
// A submodule: `.git` is a file pointing into the superproject's .git/modules.
const mod = join(outer, "libs", "pdf");
mkdirSync(mod, { recursive: true });
const modGit = join(outer, ".git", "modules", "libs", "pdf");
mkdirSync(modGit, { recursive: true });
writeFileSync(join(modGit, "config"), '[remote "origin"]\n\turl = https://github.com/acme/pdf.git\n');
writeFileSync(join(mod, ".git"), "gitdir: ../../.git/modules/libs/pdf\n");
assert.equal(repoPlace(mod).key, "github.com/acme/pdf");
assert.equal(repoPlace(join(outer, "libs")).key, "github.com/acme/app", "the folder around it is still the outer repo");
});
test("a folder outside git is keyed by its path", () => {
home();
const d = tmpRepo("plain");
const p = repoPlace(d);
assert.equal(p.git, false);
assert.match(p.key, /^local\/[a-z0-9._-]+$/);
assert.equal(p.checkout, d);
});
// --- a key that changes ---
test("a renamed remote finds its notes again, through the repo's first commit", () => {
home();
const d = repo("renamed", "[email protected]:nanonets/graft.git");
writeNote(d, { title: "Bbox rotation", body: BODY, author: "Priya", date: "2026-10-07" }, "personal");
git(d, "remote", "set-url", "origin", "[email protected]:trailhq/trail.git");
assert.equal(repoPlace(d).key, "github.com/trailhq/trail", "reads alone don't run git");
assert.equal(findRepoPlace(d).key, "github.com/nanonets/graft", "ask's lookup follows the first commit");
assert.equal(repoPlace(d).key, "github.com/nanonets/graft", "and remembers it for everything after");
assert.equal(listNotes(d).length, 1);
// A fresh clone under the new name, somewhere else, lands on the same notes.
const clone = tmpRepo("renamed-clone");
git(clone, "clone", "-q", d, "trail");
git(join(clone, "trail"), "remote", "set-url", "origin", "https://github.com/trailhq/trail");
assert.equal(listNotes(join(clone, "trail")).length, 1);
});
test("notes from before a repo had a remote carry over once it gets one", () => {
home();
const d = repo("no-remote-yet");
writeNote(d, { title: "First note", body: BODY, author: "Priya", date: "2026-10-07" }, "personal");
git(d, "remote", "add", "origin", "[email protected]:acme/extract.git");
assert.equal(ensureRepoHome(d).place.key, repoPlace(d).key);
assert.match(repoPlace(d).key, /^local\//, "the new key points at the old folder");
assert.equal(listNotes(d).length, 1);
});
test("a different repo never inherits notes: no shared first commit, no alias", () => {
const env = home();
const a = repo("first-a", "[email protected]:acme/a.git", { "a.go": "package a\n" });
writeNote(a, { title: "A's note", body: BODY, author: "Priya", date: "2026-10-07" }, "personal");
const b = repo("first-b", "[email protected]:acme/b.git", { "b.go": "package b\n" });
assert.equal(findRepoPlace(b).key, "github.com/acme/b");
assert.equal(listNotes(b).length, 0);
assert.equal(keepsNotes(b), false);
assert.ok(!repoPlace(b).dir.startsWith(join(env.TRAIL_HOME!, "repos", "github.com", "acme", "a")));
});
test("a machine with no notes anywhere never runs git to look for moved ones", () => {
home();
const d = repo("no-notes", "[email protected]:acme/none.git");
// No index.json: findRepoPlace returns the plain place without spawning.
assert.equal(findRepoPlace(d).key, "github.com/acme/none");
});
// --- a folder of repos ---
test("a folder holding several repos reads each one's notes, with touches under the repo's folder", () => {
home();
const ws = tmpRepo("workspace");
for (const [name, remote] of [["api", "[email protected]:acme/api.git"], ["web", "[email protected]:acme/web.git"]]) {
const d = join(ws, name!);
mkdirSync(d);
git(d, "init", "-q");
git(d, "remote", "add", "origin", remote!);
}
mkdirSync(join(ws, "notes-scratch"));
assert.deepEqual(childCheckouts(ws).map((c) => c.slice(ws.length + 1)), ["api", "web"]);
writeNote(join(ws, "api"), { title: "Retry budget", body: BODY, author: "Priya", date: "2026-10-06", touches: ["internal/retry.go"] });
writeNote(join(ws, "web"), { title: "Bbox overlay", body: BODY, author: "Sam", date: "2026-10-07", touches: ["src/Overlay.tsx#Overlay"] });
assert.equal(noteCount(ws), 2);
assert.equal(keepsNotes(ws), true);
const notes = listNotes(ws);
assert.deepEqual(
notes.map((n) => n.touches),
[["web/src/Overlay.tsx#Overlay"], ["api/internal/retry.go"]],
);
assert.equal(notePlaces(ws).length, 3, "the folder itself, then each repo");
// From inside one repo, only that repo's notes.
assert.deepEqual(listNotes(join(ws, "api")).map((n) => n.title), ["Retry budget"]);
});
test("touches read relative to the folder asked about, so they line up with a code map built in a subfolder", () => {
home();
const d = repo("mono", "[email protected]:acme/mono.git", { "backend/ocr/bbox.go": "package ocr\n", "web/a.ts": "" });
writeNote(d, { title: "Bbox", body: BODY, author: "Priya", date: "2026-10-07", touches: ["backend/ocr/bbox.go#NormalizeBox", "web/a.ts"] });
assert.deepEqual(listNotes(join(d, "backend"))[0]?.touches, ["ocr/bbox.go#NormalizeBox", "../web/a.ts"]);
assert.deepEqual(listNotes(d)[0]?.touches, ["backend/ocr/bbox.go#NormalizeBox", "web/a.ts"]);
});
// --- which repos a note goes to ---
test("a session that edited two repos leaves its note in both, each with its own files", () => {
home();
const api = repo("edit-api", "[email protected]:acme/api.git", { "internal/retry.go": "package internal\n" });
const lib = repo("edit-lib", "[email protected]:acme/lib.git", { "retry/backoff.go": "package retry\n" });
writeFileSync(join(api, "internal", "retry.go"), "package internal\n// changed\n");
const targets = noteTargets(api, [join(lib, "retry", "backoff.go"), join(api, "internal", "retry.go"), join(homedir(), ".claude", "plans", "x.md")]);
assert.deepEqual(targets, [
{ dir: api, touches: ["internal/retry.go"] },
{ dir: lib, touches: ["retry/backoff.go"] },
]);
});
test("saved from a folder of repos, a note goes to the repos the session changed, or to the folder", () => {
home();
const ws = tmpRepo("ws-note");
const api = join(ws, "api");
const web = join(ws, "web");
for (const d of [api, web]) {
mkdirSync(d);
git(d, "init", "-q");
}
writeFileSync(join(web, "app.ts"), "x\n");
assert.deepEqual(noteTargets(ws, [join(web, "app.ts")]), [{ dir: web, touches: ["app.ts"] }]);
// No transcript: each repo's own uncommitted changes say what was touched.
assert.deepEqual(noteTargets(ws), [{ dir: web, touches: ["app.ts"] }]);
// Nothing changed anywhere: the note stays with the folder.
const quiet = tmpRepo("ws-quiet");
assert.deepEqual(noteTargets(quiet), [{ dir: quiet, touches: [] }]);
});
test("with the session's transcript, a note lists what the session touched, not what was lying around", () => {
home();
const d = repo("touch-session", "[email protected]:acme/t.git", { "src/a.ts": "a\n", "src/b.ts": "b\n" });
writeFileSync(join(d, "AGENTS.md"), "stray, untracked before the session\n");
writeFileSync(join(d, "src", "a.ts"), "a changed\n");
const [t] = noteTargets(d, [join(d, "src", "a.ts")], undefined, { read: [join(d, "src", "b.ts"), join(d, "src", "a.ts"), join(homedir(), ".claude", "x.md")] });
assert.deepEqual(t, { dir: d, touches: ["src/a.ts"], read: ["src/b.ts"] });
// A session that only read still says what it read.
assert.deepEqual(noteTargets(d, [], undefined, { read: [join(d, "src", "b.ts")] }), [{ dir: d, touches: [], read: ["src/b.ts"] }]);
// Without a transcript, the working tree is still the best guess.
assert.deepEqual(noteTargets(d)[0]!.touches.sort(), ["AGENTS.md", "src/a.ts"]);
});
test("a session that edited a repo through both its checkout and a worktree leaves one note", () => {
home();
const main = repo("both-main", "[email protected]:acme/both.git", { "a.go": "package a\n", "b.go": "package b\n" });
const wt = join(tmpRepo("both-wt"), "wt");
git(main, "worktree", "add", "-q", "-b", "side", wt);
const targets = noteTargets(main, [join(main, "a.go"), join(wt, "b.go")]);
assert.equal(targets.length, 1);
assert.deepEqual(targets[0]!.touches.sort(), ["a.go", "b.go"]);
});
test("paths under the home folder read as ~/", () => {
assert.equal(shownPath(join(homedir(), ".trail", "repos", "x")), "~/.trail/repos/x");
assert.equal(shownPath("/srv/elsewhere"), "/srv/elsewhere");
assert.equal(shownPath("notes/a.md"), "notes/a.md");
});
test("noteCount counts only live learnings: not retired, held or replaced ones", () => {
const env = home();
const d = repo("count-live", "[email protected]:acme/api.git");
const dir = join(d, ".trail", "learnings");
mkdirSync(dir, { recursive: true });
const file = (name: string, extra = "", date = "2026-10-08") => writeFileSync(join(dir, name), `---\ntitle: "${name}"\nauthor: Priya\ndate: ${date}\n${extra}---\n\n${BODY}\n`);
file("2026-10-08-active-priya.md");
file("2026-10-08-retired-priya.md", "status: retired\n");
file("2026-10-08-held-priya.md", "status: held\n");
file("2026-10-08-old-priya.md", "id: l-0a0a0a0a\n");
file("2026-10-09-new-priya.md", "id: l-0b0b0b0b\nreplaces: l-0a0a0a0a\n", "2026-10-09");
writeFileSync(join(dir, "README.md"), "not a learning\n");
assert.equal(noteCount(d, env), 2, "the active one and the one that replaced the old one");
writeNote(d, { title: "Mine", body: BODY, author: "Priya", date: "2026-10-10" }, "personal");
assert.equal(noteCount(d, env), 3);
});