@nanonets/graft 0.21.0 → 0.22.0

package/dist/notes/branches.js

@@ -0,0 +1,238 @@
+/**
+ * Teammates' pushed branches: which files each one changes, and the learnings
+ * it carries that the default branch doesn't have yet.
+ *
+ * This is how two people find out they're on the same thing before review,
+ * with no server: once work is pushed, `git fetch` brings it to every clone.
+ * Learnings committed on a branch reach everyone the same way, hours or days
+ * before the branch merges.
+ *
+ * Reading branches takes git, and hooks and `ask` must not wait on it, so a
+ * detached `_trail-branches` child fetches and writes what it found to a
+ * cache, at most every REFRESH_MS. Everything that reads it reads the cache.
+ */
+import { execFileSync, spawn } from "node:child_process";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { graftCliPath } from "../claude/paths.js";
+import { cacheDir, readJson, writeJsonAtomic } from "../util/state.js";
+import { LEARNINGS_DIR } from "./repo-trail.js";
+/** How old the cache may get before the next command refreshes it in the
+ * background: about what editors that fetch on their own wait between fetches. */
+export const REFRESH_MS = 3 * 60 * 1000;
+/** At the start of a session, a cache older than this is refreshed. */
+export const SESSION_REFRESH_MS = 60 * 1000;
+/** A refresh that started this long ago without finishing is presumed dead. */
+const STALE_RUN_MS = 2 * 60 * 1000;
+/** Branches older than this are finished or abandoned work, not overlap. */
+export const BRANCH_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
+/** Most branches read per refresh, newest first. */
+const MAX_BRANCHES = 30;
+/** Most changed files kept per branch. */
+const MAX_FILES = 200;
+/** A learning file name as `trail note` writes it: no folders, no shell characters. */
+export const SAFE_LEARNING_NAME = /^[A-Za-z0-9._-]+\.md$/;
+/** Most learnings read per branch, and the most bytes per learning. */
+const MAX_LEARNINGS = 20;
+const MAX_LEARNING_BYTES = 64 * 1024;
+function cachePath(repo) {
+    return join(cacheDir(repo), "trail-branches.json");
+}
+export function readBranchCache(repo) {
+    return readJson(cachePath(repo));
+}
+function git(repo, args, timeout = 15_000) {
+    try {
+        // Never a credential prompt: this runs detached, where nobody could answer it.
+        return execFileSync("git", args, {
+            cwd: repo,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout,
+            maxBuffer: 16 * 1024 * 1024,
+            env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/** First word of a name, capitalised, the way a learning's author is written. Letters only, at most 40. */
+function firstName(name) {
+    const first = (name.trim().split(/\s+/)[0] ?? "").replace(/[^\p{L}\p{N}._-]/gu, "").slice(0, 40);
+    return first ? first[0].toUpperCase() + first.slice(1) : "";
+}
+/**
+ * A branch name as it may appear in what the agent reads: the characters git
+ * branch names are usually made of, at most 80. Branch names and authors come
+ * from whoever pushed, so nothing else of theirs reaches an instruction.
+ */
+export function safeRef(ref) {
+    return ref.replace(/[^A-Za-z0-9._/-]/g, "").slice(0, 80);
+}
+/** The remote branch everything is compared with: what origin/HEAD points at, else a usual name. */
+function defaultRef(repo) {
+    const head = git(repo, ["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"])?.trim();
+    if (head)
+        return head;
+    for (const name of ["origin/main", "origin/master", "origin/trunk", "origin/dev"]) {
+        if (git(repo, ["rev-parse", "--verify", "--quiet", name]) !== null)
+            return name;
+    }
+    return null;
+}
+/**
+ * Fetch, then read every recently pushed branch: the files it changes and the
+ * learnings it adds. Writes the cache and returns it. `fetch: false` reads
+ * the refs already on this machine, for tests and for a repo that's offline.
+ */
+export function refreshBranches(repo, opts = {}) {
+    const now = opts.now ?? Date.now();
+    // TRAIL_NO_FETCH: tests, and anyone who'd rather fetch themselves.
+    if (opts.fetch !== false && !process.env.TRAIL_NO_FETCH)
+        git(repo, ["fetch", "--quiet", "--prune", "origin"], opts.fetchTimeoutMs ?? 30_000);
+    const base = defaultRef(repo);
+    const branches = [];
+    if (base) {
+        const listed = git(repo, ["for-each-ref", "--sort=-committerdate", "--format=%(refname:short)%09%(committerdate:unix)%09%(authorname)", "refs/remotes/origin"]) ?? "";
+        for (const line of listed.split("\n")) {
+            if (branches.length >= MAX_BRANCHES)
+                break;
+            const [ref, unix, author] = line.split("\t");
+            if (!ref || ref === base || ref === "origin/HEAD" || ref === "origin")
+                continue;
+            // A name made only of what branch names are usually made of, or the branch is skipped:
+            // it reaches what the agent reads, and a cleaned-up copy would name a different branch.
+            if (safeRef(ref) !== ref)
+                continue;
+            const at = Number(unix) * 1000;
+            if (!Number.isFinite(at) || now - at > BRANCH_WINDOW_MS)
+                continue;
+            const changed = (git(repo, ["diff", "--name-only", `${base}...${ref}`]) ?? "").split("\n").map((f) => f.trim()).filter(Boolean);
+            if (changed.length === 0)
+                continue;
+            const learnings = [];
+            // Only names trail itself would write: the name reaches a command the agent may run.
+            const named = changed.filter((f) => f.startsWith(`${LEARNINGS_DIR}/`) && SAFE_LEARNING_NAME.test(f.slice(LEARNINGS_DIR.length + 1)));
+            for (const path of named.slice(0, MAX_LEARNINGS)) {
+                const text = git(repo, ["show", `${ref}:${path}`]);
+                if (text && text.length <= MAX_LEARNING_BYTES)
+                    learnings.push({ name: path.slice(LEARNINGS_DIR.length + 1), text });
+            }
+            branches.push({ ref, author: firstName(author ?? ""), at, files: changed.slice(0, MAX_FILES), learnings });
+        }
+    }
+    const cache = { fetchedAt: Date.now(), stamp: refsStamp(repo), base, branches };
+    writeJsonAtomic(cachePath(repo), cache, true);
+    return cache;
+}
+/** The checkout's shared git dir: `.git`, or for a linked worktree the main one's. Read, never spawned. */
+function commonGitDir(repo) {
+    const dot = join(repo, ".git");
+    try {
+        if (statSync(dot).isDirectory())
+            return dot;
+        const line = readFileSync(dot, "utf8").split("\n").find((l) => l.startsWith("gitdir:"));
+        const gitDir = line?.slice("gitdir:".length).trim();
+        if (!gitDir)
+            return null;
+        try {
+            return join(gitDir, readFileSync(join(gitDir, "commondir"), "utf8").trim());
+        }
+        catch {
+            return gitDir;
+        }
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * When this clone's idea of the remote last changed: the newest mtime under
+ * `refs/remotes/`, `packed-refs` and `FETCH_HEAD`. A push updates the
+ * remote-tracking ref it pushed, and a fetch rewrites FETCH_HEAD, so either
+ * shows here without running git.
+ */
+export function refsStamp(repo) {
+    const dir = commonGitDir(repo);
+    if (!dir)
+        return "";
+    let newest = 0;
+    const walk = (p, depth) => {
+        try {
+            const st = statSync(p);
+            newest = Math.max(newest, st.mtimeMs);
+            if (st.isDirectory() && depth < 6)
+                for (const e of readdirSync(p))
+                    walk(join(p, e), depth + 1);
+        }
+        catch {
+            /* gone, or never there */
+        }
+    };
+    walk(join(dir, "refs", "remotes"), 0);
+    for (const f of ["packed-refs", "FETCH_HEAD"])
+        walk(join(dir, f), 6);
+    return String(Math.round(newest));
+}
+/** Whether the cache is older than `maxAgeMs`, or the clone's remote refs moved since it was written. */
+export function branchesStale(repo, now = Date.now(), maxAgeMs = REFRESH_MS) {
+    const cache = readBranchCache(repo);
+    return !cache || now - cache.fetchedAt >= maxAgeMs || cache.stamp !== refsStamp(repo);
+}
+/**
+ * Refresh in a detached child when the cache is older than `maxAgeMs`, or
+ * the clone's remote refs moved since (a push, a fetch), and no refresh is
+ * already running. Never waits, never throws. A checkout with no origin gets
+ * an empty cache.
+ */
+export function maybeRefreshBranches(repo, now = Date.now(), maxAgeMs = REFRESH_MS) {
+    try {
+        const cache = readBranchCache(repo);
+        if (!branchesStale(repo, now, maxAgeMs))
+            return false;
+        if (cache?.runningSince && now - cache.runningSince < STALE_RUN_MS)
+            return false;
+        writeJsonAtomic(cachePath(repo), { ...(cache ?? { fetchedAt: 0, base: null, branches: [] }), runningSince: now }, true);
+        const child = spawn(process.execPath, [graftCliPath(), "_trail-branches", repo], { detached: true, stdio: "ignore", windowsHide: true });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Teammates' pushed branches that change any of `files`: work going on in the
+ * same place, from someone other than `me`, newest first.
+ */
+export function overlapsWith(repo, files, me, cache = readBranchCache(repo)) {
+    if (!cache || files.length === 0)
+        return [];
+    const mine = new Set(files.filter((f) => !f.startsWith(".trail/")));
+    const out = [];
+    for (const b of cache.branches) {
+        if (!b.author || b.author === me)
+            continue;
+        const shared = b.files.filter((f) => mine.has(f));
+        if (shared.length)
+            out.push({ ref: b.ref, author: b.author, at: b.at, shared });
+    }
+    return out.sort((a, b) => b.at - a.at);
+}
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+/** `today 14:20`, `Oct 7`: when a branch was pushed, short. */
+export function pushedWhen(at, now = Date.now()) {
+    const d = new Date(at);
+    const n = new Date(now);
+    if (d.toDateString() === n.toDateString())
+        return `today ${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+    return `${MONTHS[d.getMonth()]} ${d.getDate()}`;
+}
+/** `● overlap · Kumar's branch kumar/jitter also changes client.go (pushed today 14:20)`. */
+export function formatOverlap(o, now = Date.now()) {
+    const branch = o.ref.replace(/^origin\//, "");
+    const files = o.shared.length <= 2 ? o.shared.join(" and ") : `${o.shared.slice(0, 2).join(", ")} and ${o.shared.length - 2} more`;
+    return `● overlap · ${o.author}'s branch ${branch} also changes ${files} (pushed ${pushedWhen(o.at, now)})`;
+}
+//# sourceMappingURL=branches.js.map

package/dist/notes/branches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branches.js","sourceRoot":"","sources":["../../src/notes/branches.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD;kFACkF;AAClF,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AACxC,uEAAuE;AACvE,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,GAAG,IAAI,CAAC;AAC5C,+EAA+E;AAC/E,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AACnC,4EAA4E;AAC5E,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AACzD,oDAAoD;AACpD,MAAM,YAAY,GAAG,EAAE,CAAC;AACxB,0CAA0C;AAC1C,MAAM,SAAS,GAAG,GAAG,CAAC;AACtB,uFAAuF;AACvF,MAAM,CAAC,MAAM,kBAAkB,GAAG,uBAAuB,CAAC;AAC1D,uEAAuE;AACvE,MAAM,aAAa,GAAG,EAAE,CAAC;AACzB,MAAM,kBAAkB,GAAG,EAAE,GAAG,IAAI,CAAC;AA2BrC,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,qBAAqB,CAAC,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,QAAQ,CAAc,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,GAAG,CAAC,IAAY,EAAE,IAAc,EAAE,OAAO,GAAG,MAAM;IACzD,IAAI,CAAC;QACH,+EAA+E;QAC/E,OAAO,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE;YAC/B,GAAG,EAAE,IAAI;YACT,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;YACnC,OAAO;YACP,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;YAC3B,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,mBAAmB,EAAE,GAAG,EAAE;SAClD,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,2GAA2G;AAC3G,SAAS,SAAS,CAAC,IAAY;IAC7B,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,oBAAoB,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACjG,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC/D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,GAAW;IACjC,OAAO,GAAG,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC3D,CAAC;AAED,oGAAoG;AACpG,SAAS,UAAU,CAAC,IAAY;IAC9B,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,cAAc,EAAE,SAAS,EAAE,SAAS,EAAE,0BAA0B,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;IACnG,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IACtB,KAAK,MAAM,IAAI,IAAI,CAAC,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,CAAC,EAAE,CAAC;QAClF,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;IAClF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,OAAmE,EAAE;IACjH,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;IACnC,mEAAmE;IACnE,IAAI,IAAI,CAAC,KAAK,KAAK,KAAK,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc;QAAE,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE,IAAI,CAAC,cAAc,IAAI,MAAM,CAAC,CAAC;IAC7I,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,QAAQ,GAAmB,EAAE,CAAC;IACpC,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,cAAc,EAAE,uBAAuB,EAAE,mEAAmE,EAAE,qBAAqB,CAAC,CAAC,IAAI,EAAE,CAAC;QACtK,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACtC,IAAI,QAAQ,CAAC,MAAM,IAAI,YAAY;gBAAE,MAAM;YAC3C,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC7C,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,aAAa,IAAI,GAAG,KAAK,QAAQ;gBAAE,SAAS;YAChF,uFAAuF;YACvF,wFAAwF;YACxF,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,GAAG;gBAAE,SAAS;YACnC,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;YAC/B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,GAAG,GAAG,EAAE,GAAG,gBAAgB;gBAAE,SAAS;YAClE,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,IAAI,MAAM,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAChI,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YACnC,MAAM,SAAS,GAA8B,EAAE,CAAC;YAChD,qFAAqF;YACrF,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,aAAa,GAAG,CAAC,IAAI,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YACrI,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,aAAa,CAAC,EAAE,CAAC;gBACjD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;gBACnD,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,IAAI,kBAAkB;oBAAE,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;YACtH,CAAC;YACD,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC;QAC7G,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAgB,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAC7F,eAAe,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IAC9C,OAAO,KAAK,CAAC;AACf,CAAC;AAED,2GAA2G;AAC3G,SAAS,YAAY,CAAC,IAAY;IAChC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC/B,IAAI,CAAC;QACH,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE;YAAE,OAAO,GAAG,CAAC;QAC5C,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;QACxF,MAAM,MAAM,GAAG,IAAI,EAAE,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QACpD,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QACzB,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9E,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC;IACpB,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,MAAM,IAAI,GAAG,CAAC,CAAS,EAAE,KAAa,EAAE,EAAE;QACxC,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;YACvB,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC;YACtC,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,KAAK,GAAG,CAAC;gBAAE,KAAK,MAAM,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC;oBAAE,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QACjG,CAAC;QAAC,MAAM,CAAC;YACP,0BAA0B;QAC5B,CAAC;IACH,CAAC,CAAC;IACF,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC;IACtC,KAAK,MAAM,CAAC,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC;QAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACrE,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;AACpC,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,QAAQ,GAAG,UAAU;IACjF,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,CAAC,KAAK,IAAI,GAAG,GAAG,KAAK,CAAC,SAAS,IAAI,QAAQ,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,IAAI,CAAC,CAAC;AACxF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,QAAQ,GAAG,UAAU;IACxF,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,GAAG,EAAE,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAC;QACtD,IAAI,KAAK,EAAE,YAAY,IAAI,GAAG,GAAG,KAAK,CAAC,YAAY,GAAG,YAAY;YAAE,OAAO,KAAK,CAAC;QACjF,eAAe,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC,KAAK,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,EAAE,YAAY,EAAE,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC;QACxH,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,YAAY,EAAE,EAAE,iBAAiB,EAAE,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;QACzI,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAUD;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,KAAe,EAAE,EAAU,EAAE,QAA4B,eAAe,CAAC,IAAI,CAAC;IACvH,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC5C,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IACpE,MAAM,GAAG,GAAc,EAAE,CAAC;IAC1B,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,EAAE;YAAE,SAAS;QAC3C,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAClD,IAAI,MAAM,CAAC,MAAM;YAAE,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IAClF,CAAC;IACD,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,MAAM,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAEpG,+DAA+D;AAC/D,MAAM,UAAU,UAAU,CAAC,EAAU,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IACrD,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC;IACvB,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;IACxB,IAAI,CAAC,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC,YAAY,EAAE;QAAE,OAAO,SAAS,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;IAC9I,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;AAClD,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,aAAa,CAAC,CAAU,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IACxD,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAC9C,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,OAAO,CAAC;IACnI,OAAO,eAAe,CAAC,CAAC,MAAM,aAAa,MAAM,iBAAiB,KAAK,YAAY,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,GAAG,CAAC;AAC9G,CAAC"}

package/dist/notes/cold-start.d.ts

@@ -0,0 +1,127 @@
+import { type Note } from "./notes.js";
+/** One message the person wrote, with the end of what Claude said just before it. */
+export interface PastPrompt {
+    text: string;
+    /** The tail of Claude's last reply before this message, so "no, use a worktree" reads on its own. */
+    before?: string;
+}
+export interface PastSession {
+    id: string;
+    /** ISO time of the first message. */
+    at: string;
+    branch?: string;
+    prompts: PastPrompt[];
+}
+export interface Finding {
+    title: string;
+    /** `team`: about the code or how the team works here. `you`: this person's own habits or machine. */
+    for: "team" | "you";
+    /** Markdown under `## Decided` and maybe `## Watch out`, secrets scrubbed. */
+    body: string;
+    /** Sessions the cited quotes were found in, newest first. */
+    sessions: string[];
+    /** YYYY-MM-DD of the newest of them. */
+    last: string;
+    quotes: string[];
+}
+export interface FindResult {
+    /** Past sessions with at least one message of the person's. */
+    sessions: number;
+    /** How many of them, newest first, Claude read. */
+    read: number;
+    findings: Finding[];
+    model: string;
+    durationMs: number;
+    costUsd?: number;
+    /** Why nothing came back, when nothing did. */
+    reason?: "no_sessions" | "no_claude" | "failed" | "none_found";
+}
+/** Sonnet: on assign's history it merged related corrections into fewer, stronger findings than Haiku. */
+export declare const COLD_START_MODEL = "claude-sonnet-5-5";
+/**
+ * The checkout `repo` belongs to and every worktree of it git still lists:
+ * sessions run in any of them, or in a folder under one, are this repo's.
+ * Worktrees git has forgotten were usually under the main checkout
+ * (`.claude/worktrees/…`), so their sessions are still found under it.
+ */
+export declare function repoRoots(repo: string): string[];
+/**
+ * Transcript files for sessions run inside `roots`. Claude Code names a
+ * project's folder after its path with every other character as `-`, so a
+ * folder under a root starts with the root's name; but so does a sibling like
+ * `assign-old`, so each file's own `cwd` decides.
+ */
+export declare function sessionFiles(roots: string[], home?: string): string[];
+/** The person's message with what isn't theirs taken out, or null when nothing of theirs is left. */
+export declare function ownWords(raw: string): string | null;
+/**
+ * One transcript's messages from the person, oldest first. Headless runs
+ * (`claude -p`, scripts) are skipped whole: their prompts were written once
+ * and replayed, so a repeat there isn't the person repeating themselves.
+ */
+export declare function readSession(path: string): PastSession | null;
+/** Every past session of the repo with something the person wrote, newest first. */
+export declare function pastSessions(repo: string, home?: string): PastSession[];
+/**
+ * The sessions as one text for Claude, newest first, cut at `maxChars`. Each
+ * session is headed by a short id that the findings cite back.
+ */
+export declare function digest(sessions: PastSession[], maxChars?: number): {
+    text: string;
+    ids: Map<string, string>;
+};
+interface RawFinding {
+    title?: string;
+    for?: string;
+    body?: string;
+    evidence?: {
+        session?: string;
+        quote?: string;
+    }[];
+}
+/** Whether `claude` (Claude Code) is on PATH. */
+export declare function hasClaude(): boolean;
+/**
+ * The findings whose quotes are really in the person's messages, in two or
+ * more sessions, best first. A quote filed under the wrong session still
+ * counts for the session it's in.
+ */
+export declare function verify(raw: RawFinding[], sessions: PastSession[], ids: Map<string, string>): Finding[];
+/** Anything that looks like a credential, a key or an email address, replaced. Learnings get committed. */
+export declare function scrub(text: string): string;
+/**
+ * What the person kept telling Claude in this repo, checked against their
+ * messages. Never throws: no sessions, no Claude Code, or a failed call come
+ * back as an empty list with the reason.
+ */
+export declare function findLearnings(repo: string, opts?: {
+    model?: string;
+    timeoutMs?: number;
+    home?: string;
+    limit?: number;
+    sessions?: PastSession[];
+}): Promise<FindResult>;
+export interface PastRead {
+    sessions: number;
+    started: number;
+    result: Promise<FindResult>;
+    done: boolean;
+}
+/**
+ * Start reading the repo's past Claude sessions, once per repo per machine,
+ * for `trail init` to collect at its end; null when there's nothing to read,
+ * it was read before, or TRAIL_NO_FETCH is set.
+ */
+export declare function beginPastRead(repo: string, env?: NodeJS.ProcessEnv): PastRead | null;
+/**
+ * Each finding as a standing learning: the team's in `.trail/learnings/`,
+ * the person's own in ~/.trail. The body says where it came from.
+ */
+export declare function saveFindings(repo: string, findings: Finding[], author?: string, date?: string): Note[];
+/** Wait for the read, save what it found, and remember the repo was read. */
+export declare function finishPastRead(repo: string, read: PastRead): Promise<{
+    result: FindResult;
+    saved: Note[];
+}>;
+export {};
+//# sourceMappingURL=cold-start.d.ts.map

package/dist/notes/cold-start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cold-start.d.ts","sourceRoot":"","sources":["../../src/notes/cold-start.ts"],"names":[],"mappings":"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"}