Skip to content

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

20.9 KB
Raw Blame
/**
 * Where a repo's personal learnings and takeaways live: on this machine, under
 * `~/.trail/repos/<key>/`. (Learnings about the code itself go in the repo's
 * committed `.trail/`, see repo-trail.ts.) Nothing here shows up in
 * `git status` or in anyone's pull request, and nothing leaves the machine
 * unless its owner shares it.
 *
 * The key names the repo, not the folder it happens to be checked out in, so
 * every checkout of one repo reads and writes the same notes:
 *
 * - a linked worktree reads its main checkout's git config, so it gets the
 *   same key;
 * - a checkout with a remote is keyed by it (`github.com/nanonets/assign`),
 *   so a second clone somewhere else finds the same notes;
 * - a submodule, or any repo nested in another, is its own repo with its own
 *   key: the walk up stops at the nearest `.git`;
 * - a subfolder of a monorepo is part of its repo;
 * - a repo with no remote, and a folder outside git, are keyed by path.
 *
 * A folder outside git that holds repos (a workspace) has its own key for
 * notes written there, and reads its child repos' notes too.
 *
 * A key can change under a repo: a remote renamed, or added for the first
 * time. The first write under a new key looks for a folder already holding
 * notes for a repo with the same first commit, and points the new key at it
 * in `repos/index.json`, so the notes carry over instead of starting empty.
 *
 * Finding the key spawns no git, because hooks and the statusline call it on
 * every turn: it reads `.git` and the repo's config file directly. Only that
 * first write runs git, once, for the first commit.
 */
import { execFileSync } from "node:child_process";
import { randomUUID } from "node:crypto";
import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import { readJson, writeJsonAtomic } from "../util/state.js";
import { readBranchCache } from "./branches.js";
import { hasRepoTrail, learningFiles, learningsDir } from "./repo-trail.js";
import { liveLearnings, readLearningFields, type LearningFields } from "./learning-fields.js";
import { matter } from "../util/front-matter.js";
import { trailHome } from "./trail-home.js";

export { trailHome };

/** A path as people read it: `~/.trail/…` under the home folder, absolute otherwise. */
export function shownPath(p: string): string {
  if (!isAbsolute(p)) return p;
  const home = homedir();
  const rel = relative(home, p);
  return rel && !rel.startsWith("..") && !isAbsolute(rel) ? `~/${rel.split(sep).join("/")}` : p.split(sep).join("/");
}

/* -------------------------------------------------------------------------- */
/* reading git without git                                                    */
/* -------------------------------------------------------------------------- */

/** The nearest folder at or above `start` holding a `.git` (folder or file), or null outside git. */
export function checkoutRoot(start: string): string | null {
  let dir = resolve(start);
  for (;;) {
    if (existsSync(join(dir, ".git"))) return dir;
    const up = dirname(dir);
    if (up === dir) return null;
    dir = up;
  }
}

interface GitDirs {
  /** This checkout's own git dir. */
  gitDir: string;
  /** The one its config lives in: the main `.git` for a linked worktree, the same dir otherwise. */
  commonDir: string;
}

const GITDIR_KEY = "gitdir:";

/**
 * A checkout's git dirs, from its `.git`. A folder: a main checkout. A file
 * pointing at `<main>/.git/worktrees/<name>`: a linked worktree, whose
 * `commondir` leads back to the main `.git`. A file pointing anywhere else
 * (`<super>/.git/modules/<name>`): a submodule, which is a repo of its own.
 */
function gitDirs(checkout: string): GitDirs | null {
  const dot = join(checkout, ".git");
  try {
    if (statSync(dot).isDirectory()) return { gitDir: dot, commonDir: dot };
    // split/startsWith, not a regex: see mainWorktreeRoot in graph/seed.ts.
    const line = readFileSync(dot, "utf8").split("\n").find((l) => l.startsWith(GITDIR_KEY));
    const target = line?.slice(GITDIR_KEY.length).trim();
    if (!target) return null;
    const gitDir = isAbsolute(target) ? target : resolve(checkout, target);
    let commonDir = gitDir;
    try {
      const rel = readFileSync(join(gitDir, "commondir"), "utf8").trim();
      if (rel) commonDir = isAbsolute(rel) ? rel : resolve(gitDir, rel);
    } catch {
      /* no commondir: a submodule, its own git dir */
    }
    return { gitDir, commonDir };
  } catch {
    return null;
  }
}

/** The main checkout behind a linked worktree; the checkout itself otherwise. */
function mainCheckout(checkout: string, dirs: GitDirs | null): string {
  if (!dirs || dirs.gitDir === dirs.commonDir) return checkout;
  if (basename(dirname(dirs.gitDir)) !== "worktrees" || basename(dirs.commonDir) !== ".git") return checkout;
  return dirname(dirs.commonDir);
}

/** origin's url from a git config file's text, else the first remote's, else null. */
export function remoteUrl(config: string): string | null {
  let section = "";
  let first: string | null = null;
  for (const raw of config.split("\n")) {
    const line = raw.trim();
    if (line.startsWith("[")) {
      section = line;
      continue;
    }
    if (!section.startsWith('[remote "')) continue;
    const eq = line.indexOf("=");
    if (eq === -1 || line.slice(0, eq).trim().toLowerCase() !== "url") continue;
    const url = line.slice(eq + 1).trim();
    if (!url) continue;
    if (section === '[remote "origin"]') return url;
    first ??= url;
  }
  return first;
}

/** One path segment of a key: lowercase, safe as a folder name, never `.` or `..`. */
function segment(s: string): string {
  const dashed = s.toLowerCase().replace(/[^a-z0-9._-]+/g, "-");
  // Trim the dashes by hand: `/-+$/` rescans every run of dashes, quadratic on a long one.
  let a = 0;
  let b = dashed.length;
  while (a < b && dashed[a] === "-") a++;
  while (b > a && dashed[b - 1] === "-") b--;
  const out = dashed.slice(a, b);
  return /^\.+$/.test(out) ? "" : out;
}

/**
 * `[email protected]:NanoNets/Graft.git`, `https://user:[email protected]/NanoNets/Graft`
 * and `ssh://[email protected]:22/NanoNets/Graft.git` all → `github.com/nanonets/graft`.
 * Null for a remote that is a path on this machine: those are keyed by path.
 */
export function keyFromRemote(url: string): string | null {
  const s = url.trim();
  let host: string;
  let path: string;
  const scheme = s.indexOf("://");
  if (scheme !== -1) {
    if (s.slice(0, scheme).toLowerCase() === "file") return null;
    const rest = s.slice(scheme + 3);
    const slash = rest.indexOf("/");
    if (slash === -1) return null;
    host = rest.slice(0, slash);
    path = rest.slice(slash + 1);
  } else {
    const colon = s.indexOf(":");
    // No colon, or a Windows drive letter: a local path.
    if (colon <= 1 || s.slice(0, colon).includes("/")) return null;
    host = s.slice(0, colon);
    path = s.slice(colon + 1);
  }
  host = segment(host.slice(host.lastIndexOf("@") + 1).replace(/:\d*$/, ""));
  const parts = path
    .replace(/\.git\/?$/i, "")
    .split("/")
    .map(segment)
    .filter(Boolean);
  if (!host || parts.length === 0) return null;
  return [host, ...parts].join("/");
}

/**
 * The checkout at or above `start` and its remote's key (`github.com/nanonets/assign`),
 * as written in its git config, before any `insteadOf`: a clone whose fetches go
 * somewhere else still names the same repo. Null outside git or without a remote.
 * Reads only; spawns nothing.
 */
export function remoteKey(start: string): { checkout: string; key: string } | null {
  const top = checkoutRoot(start);
  const dirs = top ? gitDirs(top) : null;
  if (!top || !dirs) return null;
  try {
    const url = remoteUrl(readFileSync(join(dirs.commonDir, "config"), "utf8"));
    const key = url ? keyFromRemote(url) : null;
    return key ? { checkout: top, key } : null;
  } catch {
    return null;
  }
}

/** `local/Users-priya-src-extract`: the key for a repo with no remote, or a folder outside git. */
function pathKey(dir: string): string {
  return `local/${segment(resolve(dir)) || "root"}`;
}

/* -------------------------------------------------------------------------- */
/* the place                                                                  */
/* -------------------------------------------------------------------------- */

export interface RepoPlace {
  /** The top of the checkout the folder is in (a worktree's own top), or the folder itself outside git. */
  checkout: string;
  /** Inside a git checkout. */
  git: boolean;
  /** `github.com/nanonets/assign`, or `local/…`. */
  key: string;
  /** `<trail home>/repos/<key>`: where this repo's notes and takeaways are. */
  dir: string;
}

interface Index {
  /** A key that changed, to the one whose folder has the notes. */
  aliases: Record<string, string>;
  /** A repo's first commit, to the key whose folder has its notes. */
  roots: Record<string, string>;
}

function indexPath(home: string): string {
  return join(home, "repos", "index.json");
}

function readIndex(home: string): Index {
  const raw = readJson<Partial<Index>>(indexPath(home));
  return { aliases: raw?.aliases ?? {}, roots: raw?.roots ?? {} };
}

function keyDir(home: string, key: string): string {
  return join(home, "repos", ...key.split("/"));
}

/** Where the notes for the folder `start` live. Reads only; spawns nothing. */
export function repoPlace(start: string, env: NodeJS.ProcessEnv = process.env): RepoPlace {
  const home = trailHome(env);
  const top = checkoutRoot(start);
  const dirs = top ? gitDirs(top) : null;
  let url: string | null = null;
  if (dirs) {
    try {
      url = remoteUrl(readFileSync(join(dirs.commonDir, "config"), "utf8"));
    } catch {
      /* no config: keyed by path */
    }
  }
  const checkout = top ?? resolve(start);
  const fresh = (url && keyFromRemote(url)) || pathKey(top ? mainCheckout(top, dirs) : checkout);
  const key = existsSync(keyDir(home, fresh)) ? fresh : (readIndex(home).aliases[fresh] ?? fresh);
  return { checkout, git: top !== null, key, dir: keyDir(home, key) };
}

/** A repo's first commits (more than one after merging unrelated histories), sorted; [] without git or commits. */
function rootCommits(checkout: string): string[] {
  try {
    const out = execFileSync("git", ["rev-list", "--max-parents=0", "HEAD"], {
      cwd: checkout,
      encoding: "utf8",
      stdio: ["ignore", "pipe", "ignore"],
      timeout: 5000,
    });
    return out.split("\n").map((l) => l.trim()).filter(Boolean).sort();
  } catch {
    return [];
  }
}

/**
 * When `place`'s key has no folder yet but a repo with the same first commit
 * does (its remote was renamed, or added after its first notes), point the
 * key at that folder and return the place there. Runs git once, and only on a
 * machine that already keeps notes for some repo; otherwise `place` as it was.
 */
function followMovedRepo(home: string, place: RepoPlace, index: Index, roots: string[]): RepoPlace {
  if (existsSync(place.dir)) return place;
  const known = roots.map((r) => index.roots[r]).find((k): k is string => !!k && k !== place.key && existsSync(keyDir(home, k)));
  if (!known) return place;
  index.aliases[place.key] = known;
  return { ...place, key: known, dir: keyDir(home, known) };
}

/**
 * Where the notes for `start` are, following a repo whose key changed since
 * they were written. For reads that can afford one git call (`ask`, not the
 * statusline); a machine with no notes anywhere never spawns it.
 */
export function findRepoPlace(start: string, env: NodeJS.ProcessEnv = process.env): RepoPlace {
  const place = repoPlace(start, env);
  if (existsSync(place.dir) || !place.git) return place;
  const home = trailHome(env);
  const index = readIndex(home);
  if (Object.keys(index.roots).length === 0) return place;
  const moved = followMovedRepo(home, place, index, rootCommits(place.checkout));
  if (moved !== place) writeJsonAtomic(indexPath(home), index);
  return moved;
}

export const HOME_README = `# ~/.trail

What Trail keeps on this machine. Learnings about the code are in each
repo's own .trail/learnings/, committed with the code; this folder holds
the rest, and none of it leaves this machine unless you share it.

- repos/<repo>/notes/    personal learnings: about your setup or habits,
                         not the code
- repos/<repo>/skills/   corrections you taught your agent, per skill
- repos/known.json       the repos Trail has run in, which is the list a
                         workspace's repo picker shows
- cloud.json             your Trail workspace, once you've connected one

<repo> is the repo's remote (github.com/owner/name), so every clone and
worktree of one repo shares its learnings. Repos without a remote are under
local/, by path.
`;

/**
 * Make the folder for `start`'s repo, and return where it is. A repo seen for
 * the first time under this key, whose first commit already has a folder (a
 * renamed remote, a remote added later), is pointed at that folder.
 */
export function ensureRepoHome(start: string, env: NodeJS.ProcessEnv = process.env): { place: RepoPlace; created: boolean } {
  const home = trailHome(env);
  const index = readIndex(home);
  const before = JSON.stringify(index);
  const fresh = repoPlace(start, env);
  const roots = fresh.git ? rootCommits(fresh.checkout) : [];
  const place = followMovedRepo(home, fresh, index, roots);
  for (const r of roots) index.roots[r] ??= place.key;
  const created = !existsSync(place.dir);
  mkdirSync(join(place.dir, "notes"), { recursive: true });
  const readme = join(home, "README.md");
  if (!existsSync(readme)) writeFileSync(readme, HOME_README);
  if (JSON.stringify(index) !== before) writeJsonAtomic(indexPath(home), index);
  rememberRepo(start, env);
  return { place, created };
}

/**
 * This machine's uploader id: random, made once, kept in `~/.trail/id`. Trail
 * keys each person's uploaded notes by it, so one person's upload replaces
 * their own notes and never a teammate's. It names no one.
 */
export function uploaderId(env: NodeJS.ProcessEnv = process.env): string {
  const file = join(trailHome(env), "id");
  try {
    const id = readFileSync(file, "utf8").trim();
    if (id) return id;
  } catch {
    /* first time */
  }
  const id = randomUUID();
  mkdirSync(trailHome(env), { recursive: true });
  writeFileSync(file, `${id}\n`);
  return id;
}

/* -------------------------------------------------------------------------- */
/* a folder, and the repos under it                                           */
/* -------------------------------------------------------------------------- */

/** Most repos a workspace folder reads notes from. */
const MAX_CHILDREN = 64;

/** The git checkouts directly inside a folder that isn't one: a workspace's repos. */
export function childCheckouts(dir: string): string[] {
  let names: string[];
  try {
    names = readdirSync(dir, { withFileTypes: true })
      .filter((e) => e.isDirectory() && !e.name.startsWith("."))
      .map((e) => e.name)
      .sort();
  } catch {
    return [];
  }
  return names
    .map((n) => join(dir, n))
    .filter((d) => existsSync(join(d, ".git")))
    .slice(0, MAX_CHILDREN);
}

/**
 * Every place whose notes bear on the folder `dir`: its repo's, or, for a
 * folder outside git, its own and each child repo's. One per key, so two
 * worktrees of one repo side by side don't list its notes twice.
 */
export function notePlaces(dir: string, env: NodeJS.ProcessEnv = process.env): RepoPlace[] {
  const here = repoPlace(dir, env);
  const places = [here, ...(here.git ? [] : childCheckouts(here.checkout).map((c) => repoPlace(c, env)))];
  const seen = new Set<string>();
  return places.filter((p) => !seen.has(p.key) && seen.add(p.key));
}

/** This repo keeps learnings: it has a committed `.trail/`, or `trail init` or a first learning made its folder in ~/.trail. */
export function keepsNotes(dir: string, env: NodeJS.ProcessEnv = process.env): boolean {
  return notePlaces(dir, env).some((p) => existsSync(p.dir) || (p.git && hasRepoTrail(p.checkout)));
}

/** What `liveLearnings` needs of one learning file, read quietly, or null when it isn't a learning (no title, unreadable). */
type Counted = Pick<LearningFields, "id" | "status" | "replaces" | "scope"> & { date: string; path: string; ref?: string };

function counted(text: string, name: string, scope: "repo" | "personal", ref?: string): Counted | null {
  try {
    const parsed = matter(text);
    const d = parsed.data as Record<string, unknown>;
    if (parsed.refused || typeof d.title !== "string" || !d.title.trim()) return null;
    const date = d.date instanceof Date ? d.date.toISOString().slice(0, 10) : String(d.date ?? "");
    return { ...readLearningFields(d, name), scope, date, path: name, ...(ref ? { ref } : {}) };
  } catch {
    return null;
  }
}

function readText(path: string): string | null {
  try {
    return readFileSync(path, "utf8");
  } catch {
    return null;
  }
}

/**
 * How many live learnings bear on `dir`: the repo's `.trail/learnings/`, this
 * machine's own, and the ones on teammates' pushed branches, one per file
 * name, leaving out what is retired, held or replaced (`liveLearnings`).
 * Spawns nothing and prints nothing: the statusline calls it.
 */
export function noteCount(dir: string, env: NodeJS.ProcessEnv = process.env): number {
  const c = noteCounts(dir, env);
  return c.repo + c.personal;
}

/** The live learnings bearing on `dir` by where they live: the repo's (`.trail/learnings/`, teammates' branches) and the person's own in the Trail home. */
export interface NoteCounts { repo: number; personal: number }

/** `noteCount`, split by place, so the session start names each where it is. */
export function noteCounts(dir: string, env: NodeJS.ProcessEnv = process.env): NoteCounts {
  const all: Counted[] = [];
  const seen = new Set<string>();
  const add = (name: string, text: string | null, scope: "repo" | "personal", ref?: string) => {
    if (seen.has(name) || text === null) return;
    const c = counted(text, name, scope, ref);
    if (!c) return;
    seen.add(name);
    all.push(c);
  };
  for (const p of notePlaces(dir, env)) {
    if (p.git) for (const f of learningFiles(p.checkout)) add(f, readText(join(learningsDir(p.checkout), f)), "repo");
    try {
      for (const f of readdirSync(join(p.dir, "notes"))) if (f.endsWith(".md")) add(f, readText(join(p.dir, "notes", f)), "personal");
    } catch {
      /* none */
    }
    if (p.git) for (const b of readBranchCache(p.checkout)?.branches ?? []) for (const l of b.learnings) add(l.name, l.text, "repo", b.ref);
  }
  const live = liveLearnings(all);
  const personal = live.filter((c) => c.scope === "personal").length;
  return { repo: live.length - personal, personal };
}

/* -------------------------------------------------------------------------- */
/* the repos Trail has run in                                                 */
/* -------------------------------------------------------------------------- */

export interface KnownRepo {
  /** `github.com/hashicorp/go-retryablehttp`: the key notes are kept under. */
  key: string;
  /** `hashicorp/go-retryablehttp`: how people name it. */
  name: string;
  /** The checkout it was last seen in, on this machine. */
  path: string;
  /** When, epoch ms. */
  seenAt: number;
}

function knownPath(home: string): string {
  return join(home, "repos", "known.json");
}

/** `github.com/hashicorp/go-retryablehttp` → `hashicorp/go-retryablehttp`; a local key → its folder's name. */
export function repoName(key: string, checkout?: string): string {
  if (key.startsWith("local/")) return basename(checkout ?? key);
  const parts = key.split("/");
  return parts.length > 2 ? parts.slice(1).join("/") : key;
}

/**
 * Every repo Trail has run in on this machine, most recent first. This is the
 * list a workspace's repo picker shows: Trail never searches the disk for repos.
 */
export function knownRepos(env: NodeJS.ProcessEnv = process.env): KnownRepo[] {
  const raw = readJson<Record<string, Omit<KnownRepo, "key">>>(knownPath(trailHome(env))) ?? {};
  return Object.entries(raw)
    .map(([key, r]) => ({ key, name: r.name, path: r.path, seenAt: r.seenAt }))
    .sort((a, b) => b.seenAt - a.seenAt);
}

/** How long a sighting stays fresh before `rememberRepo` writes again. */
const SEEN_TTL_MS = 24 * 60 * 60 * 1000;

/**
 * Note that Trail ran in the repo at `dir`. Cheap enough for every command:
 * it writes only for a repo that's new, moved, or not seen for a day.
 */
export function rememberRepo(dir: string, env: NodeJS.ProcessEnv = process.env, now = Date.now()): void {
  try {
    const place = repoPlace(dir, env);
    if (!place.git) return;
    const file = knownPath(trailHome(env));
    const all = readJson<Record<string, Omit<KnownRepo, "key">>>(file) ?? {};
    const prior = all[place.key];
    if (prior && prior.path === place.checkout && now - prior.seenAt < SEEN_TTL_MS) return;
    all[place.key] = { name: repoName(place.key, place.checkout), path: place.checkout, seenAt: now };
    writeJsonAtomic(file, all);
  } catch {
    /* a missed sighting only shortens the picker's list */
  }
}