@nanonets/graft 0.21.0 → 0.22.0

package/dist/notes/notes.d.ts

@@ -0,0 +1,178 @@
+export interface NoteCost {
+    minutes?: number;
+    tokens?: number;
+}
+export interface Note {
+    /** Where the note is: an absolute path on this machine. */
+    path: string;
+    title: string;
+    author: string;
+    /** YYYY-MM-DD. */
+    date: string;
+    branch?: string;
+    cost?: NoteCost;
+    /** `file` or `file#Symbol`, relative to the top of the checkout (or to the folder `listNotes` was asked about). */
+    touches: string[];
+    body: string;
+    /** Written by someone other than whoever is asking. */
+    teammate?: boolean;
+    /** `repo`: in the repo's `.trail/learnings/`, for everyone. `personal`: in ~/.trail, this machine only. */
+    scope?: "repo" | "personal";
+    /** A rule or preference for every session here, not knowledge about one
+     * task: what the user kept having to tell Claude. The session-start hook
+     * lists these up front, since no single task would bring them up. */
+    standing?: boolean;
+    /** Found on a teammate's pushed branch (`origin/kumar/jitter`) rather than in
+     * this checkout. `path` is then `<ref>:.trail/learnings/<name>`, readable
+     * with `git show`, and the whole body travels with the note. */
+    ref?: string;
+}
+/** Which kind of learning to write: for the repo (the default) or for this person only. */
+export type LearningScope = "repo" | "personal";
+/** The three sections a note is written under. Notes may have others; these are the ones `ask` quotes. */
+export declare const SECTIONS: readonly [{
+    readonly key: "decided";
+    readonly heading: "Decided";
+    readonly label: "decided";
+}, {
+    readonly key: "ruledOut";
+    readonly heading: "Tried and ruled out";
+    readonly label: "ruled out";
+}, {
+    readonly key: "watchOut";
+    readonly heading: "Watch out";
+    readonly label: "watch out";
+}];
+export declare function renderNote(n: Omit<Note, "path">): string;
+/** A note file, or null when it isn't one (no title in its frontmatter). */
+export declare function parseNote(text: string, path: string): Note | null;
+/** The file name a note is known by, wherever it sits: one learning on a branch and in the tree is one learning. */
+export declare function noteName(n: Note): string;
+/**
+ * Every learning that bears on the folder `dir`, newest first: the repo's
+ * committed ones in `.trail/learnings/`, this person's own in ~/.trail, and
+ * the ones on teammates' pushed branches that haven't merged yet (from the
+ * branch cache, so nothing here runs git). For a folder that holds several
+ * repos, its own and each repo's. Touches come back relative to `dir`, so
+ * they line up with a query run there. `children: false` leaves a folder's
+ * repos out. One file name is one learning: the working tree's copy wins,
+ * then this machine's, then a branch's. Unreadable files are skipped.
+ */
+export declare function listNotes(dir: string, opts?: {
+    children?: boolean;
+    branches?: boolean;
+}): Note[];
+/** The first line of a section's text, or null when the note has no such section. */
+export declare function sectionLead(body: string, heading: string): string | null;
+/** `Bbox coordinates are off on rotated PDFs` → `bbox-coordinates-are-off-on-rotated`. */
+export declare function slug(s: string, words?: number): string;
+export interface WriteNoteInput {
+    title: string;
+    body: string;
+    author: string;
+    date: string;
+    branch?: string;
+    cost?: NoteCost;
+    touches?: string[];
+    standing?: boolean;
+}
+/**
+ * Write a new learning for the repo `dir` is in, and return it: into the
+ * repo's `.trail/learnings/` (made if needed), or with `scope: "personal"`,
+ * or outside git, into ~/.trail. Never overwrites: a second one with the same
+ * name on the same day gets `-2`, `-3`.
+ */
+export declare function writeNote(dir: string, input: WriteNoteInput, scope?: LearningScope): Note;
+/**
+ * The standing learnings for `dir`: the team's in the checkout and the
+ * person's own, never ones on a teammate's unmerged branch, which nobody has
+ * reviewed yet.
+ */
+export declare function standingLearnings(dir: string): Note[];
+/** Where a learning is, as the agent and the person read it: `.trail/learnings/x.md`, `~/.trail/…`, or `origin/b:.trail/…`. */
+export declare function notePlace(n: Note): string;
+export interface NoteTarget {
+    /** A folder in the repo the note goes to. */
+    dir: string;
+    /** What the session touched there, relative to the top of that checkout. */
+    touches: string[];
+}
+/**
+ * Which repos a session's note belongs in, and what it touched in each.
+ *
+ * The repo the note was saved from gets the files it has uncommitted or
+ * committed since `since`. Every other repo the session edited (`edited`:
+ * absolute paths, from the agent's transcript) gets the note too, with its
+ * own files, so a session that changed a backend and the library it calls
+ * leaves a note in both. Saved from a folder that holds several repos, the
+ * note goes to each repo the session changed, or stays with the folder when
+ * it changed none. Two worktrees of one repo are one repo.
+ */
+export declare function noteTargets(dir: string, edited?: string[], since?: number): NoteTarget[];
+/**
+ * Files of the checkout at `dir` that a note's text names by path. A session
+ * that only read code edits nothing, so without these its note would touch no
+ * file, and nothing that looks a note up by file (`trail check`, the ranked
+ * search) would ever find it.
+ */
+export declare function mentionedFiles(dir: string, body: string): string[];
+export interface NoteHit {
+    note: Note;
+    score: number;
+    /** Files the note touches that this query's results also point into. */
+    shared: string[];
+}
+/**
+ * The notes worth showing next to a query's results: ones whose title or body
+ * share the query's words, or that touch a file the results point into. At
+ * most `limit`, best first. A note has to clear a bar — two of the query's
+ * words, or one in its title, or a shared file — so an unrelated note never
+ * rides along just because it exists.
+ */
+export declare function findNotes(notes: Note[], query: string, files?: string[], limit?: number): NoteHit[];
+/** `2026-10-07` → `Oct 7`; anything else as it came. */
+export declare function shortDate(date: string): string;
+/** `~9.6k tokens`, `~600 tokens`. */
+export declare function tokensLabel(n: number): string;
+/** `took 12 min and ~9.6k tokens to work out`, or null when the note has no cost. */
+export declare function costLabel(cost?: NoteCost): string | null;
+/** What reading a note costs an agent, in tokens: its text at ~4 characters a token. */
+export declare function readingTokens(n: Note): number;
+/**
+ * What reusing a learning saves: what it took to work out, less what reading
+ * it costs. 0 when it carries no token cost, or reading it costs as much.
+ */
+export declare function savedByNote(n: Note): number;
+/** `Anirudh's learning`, `a learning`, `Kumar's learning on kumar/jitter`. */
+export declare function whoseLearning(n: Note): string;
+/**
+ * The block `ask` prints above its results: whose learning each is, when,
+ * what it was about and what it cost, then the first line of each section and
+ * where to read the rest. A learning on a teammate's unmerged branch says so,
+ * with the `git show` that prints it, since there's no file here to open. An agent
+ * relays the cost when it says what the turn saved, which is how the saving
+ * becomes countable.
+ */
+export declare function formatNoteHits(hits: NoteHit[]): string[];
+/** The line an agent closes its reply with after saving a learning just for the user. */
+export declare const PERSONAL_SAVED_LINE = "\uD83D\uDCDD Saved just for you \u00B7 stays on this machine, out of the repo";
+/** `Anay`, `Anay and Rushil`, `Anay, Rushil and 3 others`. */
+export declare function namesLabel(names: string[]): string;
+/**
+ * The lines that close a reply after a team learning is saved, one for each
+ * way the turn can end, since only the agent knows whether it committed the
+ * learning by then. Uncommitted, it makes the case for committing: who else
+ * works on the same files, and the head start their agents would get, which
+ * is what the learning took to work out.
+ */
+export declare function commitLines(note: Pick<Note, "cost">, teammates: string[], where?: "files" | "repo"): {
+    committed: string;
+    uncommitted: string;
+};
+/**
+ * The line that credits reused learnings, for the savings accumulator and the
+ * agent's closing line: what they took to work out, less what reading them
+ * here costs. Null when no shown learning carries a token cost.
+ */
+export declare function learningSavingsLine(hits: NoteHit[]): string | null;
+//# sourceMappingURL=notes.d.ts.map

package/dist/notes/notes.d.ts.map

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

package/dist/notes/notes.js

@@ -0,0 +1,498 @@
+/**
+ * Learnings: one short note per coding session that took real digging.
+ *
+ * A learning is what a session worked out that the code itself doesn't say:
+ * what was decided, what was tried and ruled out, and what to watch out for,
+ * plus what it cost to figure out. The next session on the same code reads it
+ * before exploring, so nobody pays for it twice.
+ *
+ * Most learnings are about the code, so they go in the repo's `.trail/learnings/`
+ * and are committed with the change (repo-trail.ts): every teammate's agent
+ * starts from them, and teammates' pushed branches bring theirs before they
+ * merge (branches.ts). A personal one, about one person's setup or habits,
+ * stays on their machine in `~/.trail/repos/<repo>/notes/` (home.ts).
+ *
+ * One file per session and never edited after it's written. A summary only,
+ * never a transcript: the agent writes the body, and nothing here reads
+ * source files or prompts into it.
+ */
+import { readdirSync, readFileSync, existsSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { matter } from "../util/front-matter.js";
+import { readBranchCache } from "./branches.js";
+import { changedFiles, ownPath } from "./git-facts.js";
+import { checkoutRoot, childCheckouts, ensureRepoHome, notePlaces, repoPlace, shownPath } from "./home.js";
+import { ensureRepoTrail, LEARNINGS_DIR, learningsDir } from "./repo-trail.js";
+/** The three sections a note is written under. Notes may have others; these are the ones `ask` quotes. */
+export const SECTIONS = [
+    { key: "decided", heading: "Decided", label: "decided" },
+    { key: "ruledOut", heading: "Tried and ruled out", label: "ruled out" },
+    { key: "watchOut", heading: "Watch out", label: "watch out" },
+];
+/* -------------------------------------------------------------------------- */
+/* reading and writing one note                                               */
+/* -------------------------------------------------------------------------- */
+/** A YAML scalar that round-trips: plain when it can be, double-quoted otherwise. */
+function scalar(s) {
+    return /^[A-Za-z0-9][^:#\n"'{}[\],&*!|>%@`]*$/.test(s) && s.trim() === s ? s : JSON.stringify(s);
+}
+export function renderNote(n) {
+    const fm = ["---", `title: ${scalar(n.title)}`, `author: ${scalar(n.author)}`, `date: ${n.date}`];
+    if (n.branch)
+        fm.push(`branch: ${scalar(n.branch)}`);
+    const cost = [];
+    if (n.cost?.minutes !== undefined)
+        cost.push(`minutes: ${n.cost.minutes}`);
+    if (n.cost?.tokens !== undefined)
+        cost.push(`tokens: ${n.cost.tokens}`);
+    if (cost.length)
+        fm.push(`cost: { ${cost.join(", ")} }`);
+    if (n.standing)
+        fm.push("standing: true");
+    if (n.touches.length)
+        fm.push("touches:", ...n.touches.map((t) => `  - ${scalar(t)}`));
+    fm.push("---", "");
+    return `${fm.join("\n")}\n${n.body.trim()}\n`;
+}
+function num(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+/** A note file, or null when it isn't one (no title in its frontmatter). */
+export function parseNote(text, path) {
+    let parsed;
+    try {
+        parsed = matter(text);
+    }
+    catch {
+        return null;
+    }
+    const d = parsed.data;
+    if (typeof d.title !== "string" || !d.title.trim())
+        return null;
+    const date = d.date instanceof Date ? d.date.toISOString().slice(0, 10) : String(d.date ?? "");
+    const cost = (d.cost ?? {});
+    const minutes = num(cost.minutes);
+    const tokens = num(cost.tokens);
+    return {
+        path,
+        title: d.title.trim(),
+        author: typeof d.author === "string" ? d.author : "",
+        date,
+        branch: typeof d.branch === "string" ? d.branch : undefined,
+        cost: minutes !== undefined || tokens !== undefined ? { minutes, tokens } : undefined,
+        touches: Array.isArray(d.touches) ? d.touches.map(String) : [],
+        body: parsed.content.trim(),
+        ...(d.standing === true ? { standing: true } : {}),
+    };
+}
+/** A touch saved relative to `checkout`, as a path relative to `here`. */
+function rebaseTouch(t, checkout, here) {
+    if (checkout === here)
+        return t;
+    const [file, ...sym] = t.split("#");
+    const rel = relative(here, join(checkout, file)).split(sep).join("/");
+    return [rel, ...sym].join("#");
+}
+/** Every `.md` in `notesDir` that parses as a note, with touches rebased onto `here`. */
+function readNotesIn(notesDir, checkout, here, scope) {
+    let files;
+    try {
+        files = readdirSync(notesDir).filter((f) => f.endsWith(".md"));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of files) {
+        try {
+            const n = parseNote(readFileSync(join(notesDir, f), "utf8"), join(notesDir, f));
+            if (n)
+                out.push({ ...n, scope, touches: n.touches.map((t) => rebaseTouch(t, checkout, here)) });
+        }
+        catch {
+            /* unreadable: skip */
+        }
+    }
+    return out;
+}
+/** The file name a note is known by, wherever it sits: one learning on a branch and in the tree is one learning. */
+export function noteName(n) {
+    return n.path.slice(Math.max(n.path.lastIndexOf("/"), n.path.lastIndexOf(":")) + 1);
+}
+/**
+ * Every learning that bears on the folder `dir`, newest first: the repo's
+ * committed ones in `.trail/learnings/`, this person's own in ~/.trail, and
+ * the ones on teammates' pushed branches that haven't merged yet (from the
+ * branch cache, so nothing here runs git). For a folder that holds several
+ * repos, its own and each repo's. Touches come back relative to `dir`, so
+ * they line up with a query run there. `children: false` leaves a folder's
+ * repos out. One file name is one learning: the working tree's copy wins,
+ * then this machine's, then a branch's. Unreadable files are skipped.
+ */
+export function listNotes(dir, opts = {}) {
+    const here = resolve(dir);
+    const out = [];
+    const seen = new Set();
+    const add = (notes) => {
+        for (const n of notes) {
+            const name = noteName(n);
+            if (seen.has(name))
+                continue;
+            seen.add(name);
+            out.push(n);
+        }
+    };
+    const places = notePlaces(here);
+    for (const place of opts.children === false ? places.slice(0, 1) : places) {
+        if (place.git)
+            add(readNotesIn(learningsDir(place.checkout), place.checkout, here, "repo"));
+        add(readNotesIn(join(place.dir, "notes"), place.checkout, here, "personal"));
+        if (place.git && opts.branches !== false)
+            add(branchNotes(place.checkout, here));
+    }
+    return out.sort((a, b) => (a.date === b.date ? b.path.localeCompare(a.path) : b.date.localeCompare(a.date)));
+}
+/** The learnings on teammates' pushed branches, from the branch cache. */
+function branchNotes(checkout, here) {
+    const cache = readBranchCache(checkout);
+    if (!cache)
+        return [];
+    const out = [];
+    for (const b of cache.branches) {
+        for (const l of b.learnings) {
+            const n = parseNote(l.text, `${b.ref}:${LEARNINGS_DIR}/${l.name}`);
+            if (n)
+                out.push({ ...n, scope: "repo", ref: b.ref, touches: n.touches.map((t) => rebaseTouch(t, checkout, here)) });
+        }
+    }
+    return out;
+}
+/** The first line of a section's text, or null when the note has no such section. */
+export function sectionLead(body, heading) {
+    const lines = body.split(/\r?\n/);
+    const at = lines.findIndex((l) => l.trim().toLowerCase() === `## ${heading.toLowerCase()}`);
+    if (at === -1)
+        return null;
+    for (let i = at + 1; i < lines.length; i++) {
+        const l = lines[i].trim();
+        if (l.startsWith("## "))
+            break;
+        if (l)
+            return l.replace(/^[-*]\s+/, "");
+    }
+    return null;
+}
+/** `Bbox coordinates are off on rotated PDFs` → `bbox-coordinates-are-off-on-rotated`. */
+export function slug(s, words = 6) {
+    return s
+        .toLowerCase()
+        .normalize("NFKD")
+        .replace(/[^a-z0-9\s-]/g, " ")
+        .split(/[\s-]+/)
+        .filter(Boolean)
+        .slice(0, words)
+        .join("-");
+}
+/**
+ * Write a new learning for the repo `dir` is in, and return it: into the
+ * repo's `.trail/learnings/` (made if needed), or with `scope: "personal"`,
+ * or outside git, into ~/.trail. Never overwrites: a second one with the same
+ * name on the same day gets `-2`, `-3`.
+ */
+export function writeNote(dir, input, scope = "repo") {
+    const { place } = ensureRepoHome(dir);
+    const inRepo = scope === "repo" && place.git;
+    let notes;
+    if (inRepo) {
+        ensureRepoTrail(place.checkout);
+        notes = learningsDir(place.checkout);
+    }
+    else {
+        notes = join(place.dir, "notes");
+    }
+    const base = [input.date, slug(input.title) || "note", slug(input.author, 1)].filter(Boolean).join("-");
+    let name = `${base}.md`;
+    for (let i = 2; existsSync(join(notes, name)); i++)
+        name = `${base}-${i}.md`;
+    const note = {
+        title: input.title.trim(),
+        author: input.author,
+        date: input.date,
+        branch: input.branch,
+        cost: input.cost,
+        touches: input.touches ?? [],
+        body: input.body,
+        scope: inRepo ? "repo" : "personal",
+        ...(input.standing ? { standing: true } : {}),
+    };
+    writeFileSync(join(notes, name), renderNote(note));
+    return { ...note, path: join(notes, name) };
+}
+/**
+ * The standing learnings for `dir`: the team's in the checkout and the
+ * person's own, never ones on a teammate's unmerged branch, which nobody has
+ * reviewed yet.
+ */
+export function standingLearnings(dir) {
+    return listNotes(dir, { branches: false }).filter((n) => n.standing && !n.ref);
+}
+/** Where a learning is, as the agent and the person read it: `.trail/learnings/x.md`, `~/.trail/…`, or `origin/b:.trail/…`. */
+export function notePlace(n) {
+    if (n.ref)
+        return n.path;
+    // Windows paths come with backslashes; the place is shown with `/` either way.
+    const path = n.path.replace(/\\/g, "/");
+    const at = path.lastIndexOf(`/${LEARNINGS_DIR}/`);
+    return at === -1 ? shownPath(n.path) : path.slice(at + 1);
+}
+/** Most files one note lists per repo. */
+const TOUCH_LIMIT = 10;
+/**
+ * Which repos a session's note belongs in, and what it touched in each.
+ *
+ * The repo the note was saved from gets the files it has uncommitted or
+ * committed since `since`. Every other repo the session edited (`edited`:
+ * absolute paths, from the agent's transcript) gets the note too, with its
+ * own files, so a session that changed a backend and the library it calls
+ * leaves a note in both. Saved from a folder that holds several repos, the
+ * note goes to each repo the session changed, or stays with the folder when
+ * it changed none. Two worktrees of one repo are one repo.
+ */
+export function noteTargets(dir, edited = [], since) {
+    const here = repoPlace(dir);
+    const byKey = new Map();
+    const add = (checkout, files) => {
+        const key = repoPlace(checkout).key;
+        const entry = byKey.get(key) ?? { dir: checkout, files: [] };
+        for (const f of files)
+            if (f && !ownPath(f) && !entry.files.includes(f))
+                entry.files.push(f);
+        byKey.set(key, entry);
+    };
+    if (here.git)
+        add(here.checkout, changedFiles(here.checkout, since));
+    else if (edited.length === 0)
+        for (const c of childCheckouts(here.checkout))
+            add(c, changedFiles(c, since));
+    // The agent's own files (memory, plans, scratch under ~/.claude) aren't what a note is about.
+    const agentFiles = join(homedir(), ".claude") + sep;
+    for (const f of edited) {
+        if (f.startsWith(agentFiles))
+            continue;
+        const top = checkoutRoot(dirname(f));
+        if (top)
+            add(top, [relative(top, f).split(sep).join("/")]);
+        else if (!here.git && !relative(here.checkout, f).startsWith(".."))
+            add(here.checkout, [relative(here.checkout, f).split(sep).join("/")]);
+    }
+    const out = [...byKey.entries()]
+        .filter(([key, e]) => e.files.length > 0 || key === here.key)
+        .map(([, e]) => ({ dir: e.dir, touches: e.files.slice(0, TOUCH_LIMIT) }));
+    // The repo it was saved from first; a folder of repos only when nothing else was touched.
+    out.sort((a, b) => Number(repoPlace(b.dir).key === here.key) - Number(repoPlace(a.dir).key === here.key));
+    const touched = out.filter((t) => t.touches.length > 0);
+    if (!here.git && touched.length > 0)
+        return touched;
+    return out.length ? out : [{ dir: here.checkout, touches: [] }];
+}
+/** A path-shaped word in a note: `client.go`, `src/a/b.ts:12-30`, `x.go#Fn`. */
+const MENTION = /(?:^|[\s(`'"\[])((?:[\w.-]+\/)*[\w-][\w.-]*\.[A-Za-z][A-Za-z0-9]{0,5})(?=$|[\s:#)`'",.;\]])/gm;
+/**
+ * Files of the checkout at `dir` that a note's text names by path. A session
+ * that only read code edits nothing, so without these its note would touch no
+ * file, and nothing that looks a note up by file (`trail check`, the ranked
+ * search) would ever find it.
+ */
+export function mentionedFiles(dir, body) {
+    const out = [];
+    for (const m of body.matchAll(MENTION)) {
+        const f = m[1].replace(/^\.\//, "");
+        if (out.includes(f) || ownPath(f) || f.startsWith(".."))
+            continue;
+        if (existsSync(join(dir, f)))
+            out.push(f);
+        if (out.length >= TOUCH_LIMIT)
+            break;
+    }
+    return out;
+}
+/* -------------------------------------------------------------------------- */
+/* finding the notes that matter for a query                                  */
+/* -------------------------------------------------------------------------- */
+const STOP = new Set("the and for with from that this what when where which into does how why are was were not but you your our out its it's can should would could about after before over under use using used fix find make".split(" "));
+function terms(s) {
+    return [...new Set(s.toLowerCase().split(/[^a-z0-9_]+/).filter((t) => t.length >= 3 && !STOP.has(t)))];
+}
+/** The file part of a `file#Symbol` touch. */
+function touchFile(t) {
+    return t.split("#")[0];
+}
+/**
+ * The notes worth showing next to a query's results: ones whose title or body
+ * share the query's words, or that touch a file the results point into. At
+ * most `limit`, best first. A note has to clear a bar — two of the query's
+ * words, or one in its title, or a shared file — so an unrelated note never
+ * rides along just because it exists.
+ */
+export function findNotes(notes, query, files = [], limit = 2) {
+    const q = terms(query);
+    const hitFiles = new Set(files);
+    const out = [];
+    for (const note of notes) {
+        const title = new Set(terms(note.title));
+        const text = new Set(terms(`${note.body} ${note.touches.join(" ")}`));
+        let score = 0;
+        let matched = 0;
+        for (const t of q) {
+            if (title.has(t)) {
+                score += 3;
+                matched++;
+            }
+            else if (text.has(t)) {
+                score += 1;
+                matched++;
+            }
+        }
+        const shared = [...new Set(note.touches.map(touchFile))].filter((f) => hitFiles.has(f));
+        score += shared.length * 4;
+        const clears = shared.length > 0 || matched >= 2 || [...title].some((t) => q.includes(t));
+        if (clears && score >= 3)
+            out.push({ note, score, shared });
+    }
+    return out.sort((a, b) => b.score - a.score || b.note.date.localeCompare(a.note.date)).slice(0, limit);
+}
+/* -------------------------------------------------------------------------- */
+/* how a note reads inside a query's output                                   */
+/* -------------------------------------------------------------------------- */
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+/** `2026-10-07` → `Oct 7`; anything else as it came. */
+export function shortDate(date) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date);
+    if (!m)
+        return date;
+    return `${MONTHS[Number(m[2]) - 1] ?? m[2]} ${Number(m[3])}`;
+}
+/** `~9.6k tokens`, `~600 tokens`. */
+export function tokensLabel(n) {
+    if (n >= 1000)
+        return `~${(n / 1000).toFixed(n >= 10_000 ? 0 : 1).replace(/\.0$/, "")}k tokens`;
+    return `~${n} tokens`;
+}
+/** `took 12 min and ~9.6k tokens to work out`, or null when the note has no cost. */
+export function costLabel(cost) {
+    if (!cost)
+        return null;
+    const parts = [];
+    if (cost.minutes !== undefined)
+        parts.push(`${cost.minutes} min`);
+    if (cost.tokens !== undefined)
+        parts.push(tokensLabel(cost.tokens));
+    return parts.length ? `took ${parts.join(" and ")} to work out` : null;
+}
+/** `'a b'`, with any single quote inside closed, escaped and reopened: safe to paste into a shell. */
+function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function clip(s, n = 88) {
+    return s.length > n ? `${s.slice(0, n - 1).trimEnd()}…` : s;
+}
+/** What reading a note costs an agent, in tokens: its text at ~4 characters a token. */
+export function readingTokens(n) {
+    return Math.ceil(renderNote(n).length / 4);
+}
+/**
+ * What reusing a learning saves: what it took to work out, less what reading
+ * it costs. 0 when it carries no token cost, or reading it costs as much.
+ */
+export function savedByNote(n) {
+    const took = n.cost?.tokens ?? 0;
+    return Math.max(0, took - readingTokens(n));
+}
+/** `Anirudh's learning`, `a learning`, `Kumar's learning on kumar/jitter`. */
+export function whoseLearning(n) {
+    const who = n.author ? `${n.author}'s learning` : "a learning";
+    return n.ref ? `${who} on ${n.ref.replace(/^origin\//, "")}` : who;
+}
+/**
+ * The block `ask` prints above its results: whose learning each is, when,
+ * what it was about and what it cost, then the first line of each section and
+ * where to read the rest. A learning on a teammate's unmerged branch says so,
+ * with the `git show` that prints it, since there's no file here to open. An agent
+ * relays the cost when it says what the turn saved, which is how the saving
+ * becomes countable.
+ */
+export function formatNoteHits(hits) {
+    const lines = [];
+    for (const { note } of hits) {
+        const who = `${note.author ? `${note.author}'s learning` : "a learning"}${note.teammate ? ", a teammate's" : ""}`;
+        lines.push(`from ${who} · ${shortDate(note.date)} · ${note.title}`);
+        const cost = costLabel(note.cost);
+        for (const s of SECTIONS) {
+            const lead = sectionLead(note.body, s.heading);
+            if (lead)
+                lines.push(`  ${s.label.padEnd(11)} ${clip(lead)}`);
+        }
+        if (note.ref) {
+            // On a teammate's branch, not reviewed yet: where to read the rest, and that it's unmerged.
+            lines.push(`  on ${note.ref.replace(/^origin\//, "")}, pushed and not merged yet · git show ${shellQuote(note.path)}${cost ? ` · ${cost}` : ""}`);
+            lines.push("");
+            continue;
+        }
+        lines.push(`  ${notePlace(note)}${cost ? ` · ${cost}` : ""}`);
+        lines.push("");
+    }
+    return lines;
+}
+/** The line an agent closes its reply with after saving a learning just for the user. */
+export const PERSONAL_SAVED_LINE = "📝 Saved just for you · stays on this machine, out of the repo";
+/** `Anay`, `Anay and Rushil`, `Anay, Rushil and 3 others`. */
+export function namesLabel(names) {
+    if (names.length <= 2)
+        return names.join(" and ");
+    if (names.length === 3)
+        return `${names[0]}, ${names[1]} and ${names[2]}`;
+    return `${names[0]}, ${names[1]} and ${names.length - 2} others`;
+}
+/** `48k`, `3.8k`, `600`. */
+function tokensShort(n) {
+    return tokensLabel(n).replace(/^~/, "").replace(" tokens", "");
+}
+/**
+ * The lines that close a reply after a team learning is saved, one for each
+ * way the turn can end, since only the agent knows whether it committed the
+ * learning by then. Uncommitted, it makes the case for committing: who else
+ * works on the same files, and the head start their agents would get, which
+ * is what the learning took to work out.
+ */
+export function commitLines(note, teammates, where = "files") {
+    const start = note.cost?.tokens ? `a ${tokensShort(note.cost.tokens)}-token head start` : "a head start";
+    const place = where === "files" ? "this part of the codebase" : "this repo";
+    if (!teammates.length) {
+        return {
+            committed: `📝 Committed · your teammates' agents now get ${start}`,
+            uncommitted: `🌱 Commit what you learned and give your teammates' agents ${start}`,
+        };
+    }
+    const who = namesLabel(teammates);
+    const work = teammates.length === 1 ? "works" : "work";
+    return {
+        committed: `📝 Committed · ${who} ${work} in ${place}, and their agents now get ${start}`,
+        uncommitted: `🌱 ${who} ${work} in ${place}. Commit what you learned and give their agents ${start}`,
+    };
+}
+/**
+ * The line that credits reused learnings, for the savings accumulator and the
+ * agent's closing line: what they took to work out, less what reading them
+ * here costs. Null when no shown learning carries a token cost.
+ */
+export function learningSavingsLine(hits) {
+    const saved = hits.reduce((sum, h) => sum + savedByNote(h.note), 0);
+    if (saved <= 0)
+        return null;
+    const read = hits.reduce((sum, h) => sum + readingTokens(h.note), 0);
+    const minutes = hits.reduce((sum, h) => sum + (h.note.cost?.minutes ?? 0), 0);
+    const time = minutes > 0 ? ` and ~${minutes} min` : "";
+    return `[trail] learnings saved ≈ ${saved.toLocaleString("en-US")} tokens${time} (estimate): what they took to work out, less the ~${read.toLocaleString("en-US")} tokens to read them here.`;
+}
+//# sourceMappingURL=notes.js.map