projectkeeper 0.0.0-stage → 1.0.0

package/src/util/git.ts

@@ -0,0 +1,411 @@
+/**
+ * Read-only git access. Every call disables optional locks and pagers, so observing a
+ * repository never changes its state (Spec §1.1: the Keeper's own work does not change
+ * version-control state).
+ */
+import { execFile, execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { canonicalPath } from './paths.ts';
+
+export interface GitResult {
+  readonly ok: boolean;
+  readonly out: string;
+  readonly err: string;
+}
+
+/**
+ * Given to every git call ProjectKeeper makes. Without it Git for Windows stops at any path of 260 characters or more,
+ * its own files included: `<repository>\.git\objects\…` is that long once the repository's own path passes about
+ * 200. Then `status` fails, a tracked file deep in the tree reads as deleted, and nothing there can be hashed or added.
+ * (What no setting helps, a repository whose own path is too long, is util/paths.ts `gitPathLimit`.)
+ */
+export const LONG_PATHS: readonly string[] = ['-c', 'core.longpaths=true'];
+
+function env(): NodeJS.ProcessEnv {
+  const copy: NodeJS.ProcessEnv = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (!['GIT_PAGER', 'PAGER', 'GIT_EXTERNAL_DIFF', 'GIT_OPTIONAL_LOCKS'].includes(key.toUpperCase())) copy[key] = value;
+  }
+  copy.GIT_OPTIONAL_LOCKS = '0';
+  return copy;
+}
+
+export function git(cwd: string, args: readonly string[], timeoutMs = 8000, maxBuffer = 16_000_000): GitResult {
+  try {
+    const out = execFileSync('git', ['--no-pager', '-c', 'core.fsmonitor=false', ...LONG_PATHS, '-C', cwd, ...args], {
+      encoding: 'utf8', env: env(), timeout: timeoutMs, maxBuffer, windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return { ok: true, out, err: '' };
+  } catch (error) {
+    const e = error as { status?: number; stdout?: string; stderr?: string; message?: string };
+    return { ok: false, out: e.stdout ?? '', err: (e.stderr || e.message || String(error)).trim() };
+  }
+}
+
+// The paths git reports are put in the file system's own spelling (canonicalPath), the one every location is kept in:
+// git usually prints that spelling already, but not for a repository reached through a mapped drive, and a worktree
+// is listed as it was spelled when it was registered.
+
+export function gitToplevel(dir: string): string | null {
+  const r = git(dir, ['rev-parse', '--show-toplevel']);
+  return r.ok && r.out.trim() ? canonicalPath(resolve(r.out.trim())) : null;
+}
+
+export function gitCommonDir(dir: string): string | null {
+  const r = git(dir, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  return r.ok && r.out.trim() ? canonicalPath(r.out.trim()) : null;
+}
+
+export function gitDir(dir: string): string | null {
+  const r = git(dir, ['rev-parse', '--path-format=absolute', '--git-dir']);
+  return r.ok && r.out.trim() ? canonicalPath(r.out.trim()) : null;
+}
+
+export interface WorktreeInfo {
+  readonly path: string;
+  readonly head: string | null;
+  readonly branch: string | null;
+  readonly detached: boolean;
+  readonly bare: boolean;
+}
+
+export function gitWorktrees(dir: string): WorktreeInfo[] {
+  const r = git(dir, ['worktree', 'list', '--porcelain']);
+  if (!r.ok) return [];
+  const out: WorktreeInfo[] = [];
+  let current: { path?: string; head?: string; branch?: string; detached?: boolean; bare?: boolean } = {};
+  const flush = () => {
+    if (current.path) {
+      out.push({
+        path: canonicalPath(current.path), head: current.head ?? null, branch: current.branch ?? null,
+        detached: current.detached === true, bare: current.bare === true,
+      });
+    }
+    current = {};
+  };
+  for (const line of r.out.split(/\r?\n/)) {
+    if (line.startsWith('worktree ')) { flush(); current.path = line.slice(9); }
+    else if (line.startsWith('HEAD ')) current.head = line.slice(5);
+    else if (line.startsWith('branch ')) current.branch = line.slice(7).replace(/^refs\/heads\//, '');
+    else if (line === 'detached') current.detached = true;
+    else if (line === 'bare') current.bare = true;
+    else if (line === '') flush();
+  }
+  flush();
+  return out;
+}
+
+export function gitHead(dir: string): string | null {
+  const r = git(dir, ['rev-parse', 'HEAD']);
+  return r.ok && /^[0-9a-f]{40}/.test(r.out.trim()) ? r.out.trim() : null;
+}
+
+export function gitBranch(dir: string): string | null {
+  const r = git(dir, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  return r.ok && r.out.trim() && r.out.trim() !== 'HEAD' ? r.out.trim() : null;
+}
+
+/** First commit(s) of the history; two repositories sharing one are a copy or a fork of each other. */
+export function gitRootCommits(dir: string): string[] {
+  const r = git(dir, ['rev-list', '--max-parents=0', 'HEAD']);
+  return r.ok ? r.out.split(/\s+/).filter((h) => /^[0-9a-f]{40}$/.test(h)).sort() : [];
+}
+
+export function gitRemotes(dir: string): string[] {
+  const r = git(dir, ['remote', '-v']);
+  return r.ok ? r.out.split(/\r?\n/).filter((l) => l.trim()) : [];
+}
+
+export interface GitStatus {
+  readonly branch: string | null;
+  readonly head: string | null;
+  readonly dirty: readonly string[];
+}
+
+/** The same read-only git call without blocking the event loop (used where the workbench must keep answering). */
+export function gitAsync(cwd: string, args: readonly string[], timeoutMs = 8000): Promise<GitResult> {
+  return new Promise((resolve) => {
+    execFile('git', ['--no-pager', '-c', 'core.fsmonitor=false', ...LONG_PATHS, '-C', cwd, ...args], {
+      encoding: 'utf8', env: env(), timeout: timeoutMs, maxBuffer: 16_000_000, windowsHide: true,
+    }, (error, stdout, stderr) => {
+      if (error) resolve({ ok: false, out: String(stdout ?? ''), err: String(stderr || error.message) });
+      else resolve({ ok: true, out: String(stdout), err: '' });
+    });
+  });
+}
+
+export async function gitStatusAsync(dir: string): Promise<GitStatus | null> {
+  const [status, head, branch] = await Promise.all([
+    gitAsync(dir, ['status', '--porcelain', '--untracked-files=normal']),
+    gitAsync(dir, ['rev-parse', 'HEAD']),
+    gitAsync(dir, ['rev-parse', '--abbrev-ref', 'HEAD']),
+  ]);
+  if (!status.ok) return null;
+  const h = head.out.trim();
+  const b = branch.out.trim();
+  return { branch: branch.ok && b && b !== 'HEAD' ? b : null, head: head.ok && /^[0-9a-f]{40}/.test(h) ? h : null, dirty: status.out.split(/\r?\n/).filter((l) => l.trim()) };
+}
+
+export function gitStatus(dir: string): GitStatus | null {
+  const r = git(dir, ['status', '--porcelain', '--untracked-files=normal']);
+  if (!r.ok) return null;
+  return { branch: gitBranch(dir), head: gitHead(dir), dirty: r.out.split(/\r?\n/).filter((l) => l.trim()) };
+}
+
+export interface CommitInfo {
+  readonly hash: string;
+  readonly at: string;
+  readonly author: string;
+  readonly subject: string;
+  readonly files: readonly string[];
+}
+
+/**
+ * The commits reachable from HEAD — all of them unless `limit` asks for fewer (D77: the history is read in full, no
+ * recent-N cap), since `since` when given; `notFrom` excludes what another ref already reaches (a worktree's commits
+ * beyond its main repository).
+ */
+export function gitRecentCommits(dir: string, since: string | null, limit: number | null = null, notFrom: string | null = null): CommitInfo[] {
+  const args = ['log', ...(limit !== null ? [`-n${Math.max(1, Math.floor(limit))}`] : []), '--date=iso-strict', '--name-only', '--format=%x1e%H%x1f%aI%x1f%an%x1f%s'];
+  if (since) args.push(`--since=${since}`);
+  if (notFrom) args.push('HEAD', `^${notFrom}`);
+  // A whole history takes longer and prints more than the recent part did.
+  const r = git(dir, args, limit === null ? 180_000 : 20000, limit === null ? 512_000_000 : 16_000_000);
+  if (!r.ok) return [];
+  const out: CommitInfo[] = [];
+  for (const block of r.out.split('\x1e')) {
+    const trimmed = block.trim();
+    if (!trimmed) continue;
+    const [header, ...rest] = trimmed.split(/\r?\n/);
+    const [hash, at, author, subject] = (header ?? '').split('\x1f');
+    if (!hash) continue;
+    out.push({ hash, at: at ?? '', author: author ?? '', subject: subject ?? '', files: rest.map((l) => l.trim()).filter(Boolean) });
+  }
+  return out;
+}
+
+/** Content of a path at a commit; null when it does not exist there. */
+export function gitShow(dir: string, commit: string, path: string): string | null {
+  const r = git(dir, ['show', `${commit}:${path.split('\\').join('/')}`], 20000);
+  return r.ok ? r.out : null;
+}
+
+// ───────────────────────── reading version history (Spec §1.2 `History only`, §3.1; CKC-03 AC-24) ─────────────────────────
+//
+// Everything below is a read: log, show, ls-tree, cat-file, rev-parse, diff --name-only and hash-object without -w. Paths
+// come raw (core.quotePath=false), so names in any script read as they are. A user-given ref only ever reaches
+// rev-parse, after `--end-of-options`; every later call uses the full hash it resolved to.
+
+/** The same read-only call with room for a long history: a larger buffer and time limit, raw path names. */
+export function gitRead(cwd: string, args: readonly string[], options: { readonly timeoutMs?: number; readonly maxBuffer?: number } = {}): GitResult {
+  try {
+    const out = execFileSync('git', ['--no-pager', '-c', 'core.fsmonitor=false', '-c', 'core.quotePath=false', ...LONG_PATHS, '-C', cwd, ...args], {
+      encoding: 'utf8', env: env(), timeout: options.timeoutMs ?? 30_000, maxBuffer: options.maxBuffer ?? 64_000_000, windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return { ok: true, out, err: '' };
+  } catch (error) {
+    const e = error as { stdout?: string; stderr?: string; message?: string };
+    return { ok: false, out: e.stdout ?? '', err: (e.stderr || e.message || String(error)).trim() };
+  }
+}
+
+/** A ref the history tools accept — a hash, a branch or tag, HEAD, with `~`, `^` or `@{…}` after it — and never an option. */
+export function isSafeRef(ref: string): boolean {
+  return ref.length > 0 && ref.length <= 200 && !ref.startsWith('-') && !ref.includes('..') && /^[A-Za-z0-9._/@{}~^+-]+$/.test(ref);
+}
+
+/** The full hash of the commit a ref names, or null when it names none. */
+export function gitResolveCommit(dir: string, ref: string): string | null {
+  if (!isSafeRef(ref)) return null;
+  const r = gitRead(dir, ['rev-parse', '--verify', '--quiet', '--end-of-options', `${ref}^{commit}`], { timeoutMs: 8000 });
+  const hash = r.out.trim();
+  return r.ok && /^[0-9a-f]{40}$/.test(hash) ? hash : null;
+}
+
+export interface CommitMeta {
+  readonly hash: string;
+  readonly parents: readonly string[];
+  readonly at: string;
+  readonly author: string;
+  readonly subject: string;
+}
+const META_FORMAT = '--format=%x1e%H%x1f%P%x1f%aI%x1f%an%x1f%s';
+function metaOf(header: string): CommitMeta | null {
+  const [hash, parents, at, author, subject] = header.split('\x1f');
+  if (!hash || !/^[0-9a-f]{40}$/.test(hash)) return null;
+  return { hash, parents: (parents ?? '').split(' ').filter(Boolean), at: at ?? '', author: author ?? '', subject: subject ?? '' };
+}
+
+/** Author, time, subject and parents of one commit. */
+export function gitCommitMeta(dir: string, hash: string): CommitMeta | null {
+  const r = gitRead(dir, ['log', '-1', META_FORMAT, hash, '--'], { timeoutMs: 8000 });
+  return r.ok ? metaOf(r.out.replace(/^\x1e/, '').trim()) : null;
+}
+
+/** A path git printed in C quotes (only control characters, quotes and backslashes are quoted once quotePath is off). */
+function unquote(path: string): string {
+  if (!(path.startsWith('"') && path.endsWith('"'))) return path;
+  const body = path.slice(1, -1);
+  const bytes: number[] = [];
+  for (let i = 0; i < body.length; i++) {
+    const c = body[i]!;
+    if (c !== '\\') { bytes.push(...Buffer.from(c, 'utf8')); continue; }
+    const n = body[++i] ?? '';
+    if (/[0-7]/.test(n)) { const oct = body.slice(i, i + 3); bytes.push(parseInt(oct, 8)); i += 2; continue; }
+    bytes.push(({ n: 10, t: 9, r: 13, '"': 34, '\\': 92, a: 7, b: 8, f: 12, v: 11 } as Record<string, number>)[n] ?? n.charCodeAt(0));
+  }
+  return Buffer.from(bytes).toString('utf8');
+}
+
+export interface PathChange {
+  /** A added, M modified, D deleted, R renamed, C copied, T type changed. */
+  readonly status: 'A' | 'M' | 'D' | 'R' | 'C' | 'T';
+  readonly path: string;
+  /** The other side of a rename or copy: where it came from (`path` is where it went). */
+  readonly from: string | null;
+}
+export interface PathCommit extends CommitMeta {
+  /** The changes of this commit that touch the path (a file's own line, or every file under a directory). */
+  readonly changes: readonly PathChange[];
+}
+
+const under = (path: string, target: string): boolean => path === target || path.startsWith(`${target}/`);
+
+/**
+ * Every commit reachable from `ref` that touched a path, newest first — including the one that deleted it, and a rename
+ * away from it with where it went. `--full-diff` lets rename detection see both sides of a move out of the path. A page
+ * of `limit` commits after the first `skip`; paging reaches the whole history.
+ */
+export function gitPathHistory(dir: string, relPath: string, limit = 100, ref = 'HEAD', skip = 0): PathCommit[] | null {
+  const target = relPath.replace(/\/+$/, '');
+  const r = gitRead(dir, ['log', '-M', '--full-diff', '--name-status', META_FORMAT, `-n${Math.max(1, limit)}`, ...(skip > 0 ? [`--skip=${Math.floor(skip)}`] : []), ref, '--', target], { timeoutMs: 120_000, maxBuffer: 256_000_000 });
+  if (!r.ok) return null;
+  const out: PathCommit[] = [];
+  for (const block of r.out.split('\x1e')) {
+    const lines = block.split(/\r?\n/);
+    const meta = metaOf(lines[0] ?? '');
+    if (!meta) continue;
+    const changes: PathChange[] = [];
+    for (const line of lines.slice(1)) {
+      if (!line.trim()) continue;
+      const [code, a, b] = line.split('\t');
+      const status = (code ?? '').charAt(0) as PathChange['status'];
+      if (!'AMDRCT'.includes(status) || !a) continue;
+      const first = unquote(a);
+      const second = b !== undefined ? unquote(b) : null;
+      if ((status === 'R' || status === 'C') && second !== null) {
+        if (under(first, target) || under(second, target)) changes.push({ status, path: second, from: first });
+      } else if (under(first, target)) changes.push({ status, path: first, from: null });
+    }
+    if (changes.length) out.push({ ...meta, changes });
+  }
+  return out;
+}
+
+export interface TreeEntry {
+  readonly type: 'blob' | 'tree' | 'commit';
+  readonly id: string;
+  readonly size: number | null;
+}
+/** What a path is at a commit — a file (blob), a directory (tree) or a submodule — or null when it is not there. */
+export function gitTreeEntry(dir: string, commit: string, relPath: string): TreeEntry | null {
+  const r = gitRead(dir, ['ls-tree', '-l', '-z', commit, '--', relPath.replace(/\/+$/, '')], { timeoutMs: 8000 });
+  if (!r.ok) return null;
+  const wanted = relPath.replace(/\/+$/, '');
+  for (const entry of r.out.split('\0')) {
+    const tab = entry.indexOf('\t');
+    if (tab < 0 || entry.slice(tab + 1) !== wanted) continue;
+    const [, type, id, size] = entry.slice(0, tab).trim().split(/\s+/);
+    if (type !== 'blob' && type !== 'tree' && type !== 'commit') return null;
+    return { type, id: id ?? '', size: size && /^\d+$/.test(size) ? Number(size) : null };
+  }
+  return null;
+}
+
+/** The blob id a working-tree file would have if it were added now (filters applied, nothing written). */
+export function gitHashWorkingFile(dir: string, absPath: string, relPath: string): string | null {
+  const r = gitRead(dir, ['hash-object', `--path=${relPath}`, '--', absPath], { timeoutMs: 8000 });
+  const id = r.out.trim();
+  return r.ok && /^[0-9a-f]{40}$/.test(id) ? id : null;
+}
+
+/** Every file path in a commit's tree, optionally under a path. */
+export function gitTrackedPaths(dir: string, ref = 'HEAD', relPath: string | null = null): Set<string> | null {
+  const r = gitRead(dir, ['ls-tree', '-r', '--name-only', '-z', ref, ...(relPath ? ['--', relPath] : [])]);
+  return r.ok ? new Set(r.out.split('\0').filter(Boolean)) : null;
+}
+
+export interface DeletedPath {
+  readonly path: string;
+  /** The commit that deleted it last — the newest deletion when it was deleted, added back and deleted again. */
+  readonly deletedIn: CommitMeta;
+}
+/** Files deleted in the history reachable from `ref`, newest deletion first; a rename is not a deletion. */
+export function gitDeletedPaths(dir: string, ref = 'HEAD', relPath: string | null = null): DeletedPath[] | null {
+  const r = gitRead(dir, ['log', '-M', '--diff-filter=D', '--name-only', META_FORMAT, ref, ...(relPath ? ['--', relPath] : [])], { timeoutMs: 120_000, maxBuffer: 256_000_000 });
+  if (!r.ok) return null;
+  const seen = new Set<string>();
+  const out: DeletedPath[] = [];
+  for (const block of r.out.split('\x1e')) {
+    const lines = block.split(/\r?\n/);
+    const meta = metaOf(lines[0] ?? '');
+    if (!meta) continue;
+    for (const line of lines.slice(1)) {
+      const path = unquote(line.trim());
+      if (!path || seen.has(path)) continue;
+      seen.add(path);
+      out.push({ path, deletedIn: meta });
+    }
+  }
+  return out;
+}
+
+/** Files HEAD has that the working tree no longer has: deletions not committed yet. */
+export function gitUncommittedDeletions(dir: string): string[] {
+  const r = gitRead(dir, ['diff', '--name-only', '-z', '--diff-filter=D', 'HEAD', '--'], { timeoutMs: 20_000 });
+  return r.ok ? r.out.split('\0').filter(Boolean) : [];
+}
+
+export type PathFate =
+  | { readonly kind: 'deleted'; readonly commit: CommitMeta }
+  | { readonly kind: 'moved'; readonly to: string; readonly commit: CommitMeta };
+/**
+ * What became of paths HEAD no longer has: the commit that deleted each, or the one that moved it away and where to.
+ * Null for a path HEAD still has (a change in the working tree, not committed yet) or whose last commit says neither.
+ * A few calls per hundred paths, however many there are: a deleted directory is one question, not one per file.
+ */
+export function gitPathFates(dir: string, relPaths: readonly string[]): Map<string, PathFate | null> {
+  const out = new Map<string, PathFate | null>();
+  const wanted = [...new Set(relPaths)];
+  for (let i = 0; i < wanted.length; i += 100) {
+    const chunk = wanted.slice(i, i + 100);
+    for (const p of chunk) out.set(p, null);
+    const present = gitRead(dir, ['ls-tree', '-r', '--name-only', '-z', 'HEAD', '--', ...chunk]);
+    const inHead = new Set(present.ok ? present.out.split('\0').filter(Boolean) : chunk);
+    const open = new Set(chunk.filter((p) => !inHead.has(p)));
+    if (open.size === 0) continue;
+    const r = gitRead(dir, ['log', '-M', '--full-diff', '--name-status', META_FORMAT, 'HEAD', '--', ...open], { timeoutMs: 60_000 });
+    if (!r.ok) continue;
+    // Newest first: the first time a path shows up is what last happened to it.
+    for (const block of r.out.split('\x1e')) {
+      if (open.size === 0) break;
+      const lines = block.split(/\r?\n/);
+      const meta = metaOf(lines[0] ?? '');
+      if (!meta) continue;
+      for (const line of lines.slice(1)) {
+        const [code, a, b] = line.split('\t');
+        if (!a) continue;
+        const status = (code ?? '').charAt(0);
+        const first = unquote(a);
+        if (!open.has(first)) continue;
+        if (status === 'R' && b !== undefined) out.set(first, { kind: 'moved', to: unquote(b), commit: meta });
+        else if (status === 'D') out.set(first, { kind: 'deleted', commit: meta });
+        else if (status === 'C') continue;   // copied from it: the path itself is still there after this commit
+        open.delete(first);
+      }
+    }
+  }
+  return out;
+}

package/src/util/own-ts.ts

@@ -0,0 +1,15 @@
+/**
+ * What a new Node thread or process needs to load ProjectKeeper's own TypeScript sources.
+ *
+ * In a clone: nothing — Node strips the types itself. Installed as a package the sources sit under node_modules, where
+ * Node refuses to; bin/strip-types.mjs does it instead, and has to be loaded again in every worker thread and child
+ * process that runs one of these sources (the file scan's and the ledger rebuild's workers, the code engine's child).
+ */
+const underNodeModules = import.meta.url.includes('/node_modules/');
+const preload = ['--import', new URL('../../bin/strip-types.mjs', import.meta.url).href];
+
+/** For a child process: flags to put before the script. */
+export const OWN_TS_NODE_ARGS: readonly string[] = underNodeModules ? preload : [];
+
+/** For `new Worker(…)`: options to spread in. Nothing in a clone, so a worker there starts exactly as it always did. */
+export const OWN_TS_WORKER_OPTIONS: { readonly execArgv?: string[] } = underNodeModules ? { execArgv: [...preload] } : {};

package/src/util/paths.ts

@@ -0,0 +1,225 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, normalize, parse, relative, resolve, sep } from 'node:path';
+
+const WIN = process.platform === 'win32';
+const MAC = process.platform === 'darwin';
+
+/** Absolute, normalised, without a trailing separator. Display form keeps the original case. */
+export function normalizePath(path: string): string {
+  const abs = normalize(isAbsolute(path) ? path : resolve(path));
+  const root = parse(abs).root;
+  let out = abs;
+  while (out.length > root.length && /[\\/]$/.test(out)) out = out.slice(0, -1);
+  return out;
+}
+
+/**
+ * The one spelling of a path, as the file system itself gives it: absolute, with links and junctions resolved and, on
+ * Windows, 8.3 short names expanded (`C:\Users\RUNNER~1` → `C:\Users\runneradmin`), a `subst` drive followed and
+ * every name in the case it has on disk. git reports paths this way (`rev-parse --show-toplevel`, `worktree list`),
+ * so a path that enters ProjectKeeper — a project's location, the home, a directory a configuration file names — is
+ * put in this spelling before it is kept or compared; two spellings of one directory compared as text are two
+ * directories, and a repository then looks like it is not one. What does not exist yet keeps its missing tail on top
+ * of the real spelling of the part that exists. A mapped network drive keeps its drive letter (its real spelling is
+ * a `\\server\share` path, which not every program can work in).
+ */
+export function canonicalPath(path: string): string {
+  const abs = normalizePath(path);
+  const tail: string[] = [];
+  for (let head = abs; ;) {
+    let real: string | null = null;
+    try { real = realpathSync.native(head); } catch {
+      // Some volumes (a RAM disk, some network file systems) do not answer the native call; the links are still resolved.
+      try { real = realpathSync(head); } catch { real = null; }
+    }
+    if (real !== null) {
+      if (WIN && real.startsWith('\\\\') && !abs.startsWith('\\\\')) return abs;
+      return normalizePath(tail.length ? join(real, ...tail.reverse()) : real);
+    }
+    const parent = dirname(head);
+    if (parent === head) return abs;   // nothing of it exists, not even its root
+    tail.push(basename(head));
+    head = parent;
+  }
+}
+
+/**
+ * A normalised path folded into the key two spellings of one file share on a system:
+ *
+ * - Windows: case folded. Its file systems take another case for the same name.
+ * - macOS: case folded and the Unicode form composed (NFC). The usual Mac volume takes another case for the same name,
+ *   and a name in either Unicode form: Finder and Cocoa applications write `é` and Korean and Japanese syllables
+ *   decomposed (NFD), a shell tool writes them as typed, and git reports them composed. A Mac volume formatted
+ *   case-sensitive is treated the same way, as a directory made case-sensitive is on Windows: two names there that
+ *   differ only in case are one name to ProjectKeeper.
+ * - anywhere else: as it is.
+ *
+ * Only keys are folded. A path that is opened, shown or handed to git keeps its spelling (`canonicalPath` does not
+ * fold, and must not: the name Claude Code gives a project's session folder is made from the directory's own
+ * characters), and the shell guard's keys (keeper/bounds/paths.ts `canonicalKey`) are not folded on macOS because the
+ * guard also opens them.
+ */
+export function foldForSystem(normalised: string, platform: NodeJS.Platform = process.platform): string {
+  if (platform === 'win32') return normalised.toLowerCase();
+  if (platform === 'darwin') return normalised.normalize('NFC').toLowerCase();
+  return normalised;
+}
+
+/** Comparison key: folded as the system's file system folds names (`foldForSystem`). Never shown to the user, never opened. */
+export function pathKey(path: string): string {
+  return foldForSystem(normalizePath(path));
+}
+
+export function samePath(a: string, b: string): boolean {
+  return pathKey(a) === pathKey(b);
+}
+
+/** A path that says where it is in full, drive included on Windows; any other would be completed from wherever this process runs. */
+const FULL_PATH = WIN ? /^(?:[A-Za-z]:[\\/]|[\\/]{2})/ : /^\//;
+
+/**
+ * Comparison key of the directory a path names: `pathKey` of its `canonicalPath`, so two spellings of one directory
+ * give one key. For a path somebody else wrote down — the working directory in an agent's session log — which is in
+ * whatever spelling that program ran under. A directory that no longer exists has no real spelling to ask for: its
+ * missing part is compared as text, on top of the real spelling of the part that exists. So a session recorded through
+ * a junction or a `subst` drive that is gone since is not recognised.
+ */
+export function directoryKey(path: string): string {
+  return pathKey(FULL_PATH.test(path) ? canonicalPath(path) : path);
+}
+
+/** Two paths name one directory: the same text, or two spellings of it by the file system's own judgement. */
+export function sameDirectory(a: string, b: string): boolean {
+  return samePath(a, b) || directoryKey(a) === directoryKey(b);
+}
+
+/** `path` is `root` or lives under it. */
+export function isWithin(root: string, path: string): boolean {
+  const r = pathKey(root);
+  const p = pathKey(path);
+  return p === r || p.startsWith(r + sep);
+}
+
+/**
+ * A name, or a path below a project's location, in the one Unicode form ProjectKeeper keeps such names in on a system.
+ *
+ * On macOS that is the composed form (NFC), which is the form git reports names in there. The file system lists a
+ * name in the form it was written in — decomposed (NFD) when Finder or a Cocoa application wrote it — and takes either
+ * form for the same file; git, with `core.precomposeunicode` (which `git init` and `git clone` set on a Mac), composes
+ * every name it lists and every name it is given. A document found by the file walk and the same document in the
+ * history then had two names, and what joined them by name — the ledger's text and versions of a file, the ignore
+ * rules, a material rule, a removal — missed. So a name is composed where it enters from outside git: a directory
+ * listing, a change the watcher reports, a path a person or the model wrote (which may be copied from a listing), and
+ * every path made relative to a location. This is what git itself does at the same two places. What git says is kept
+ * as git says it, so what is said back to git is in its own words. (A repository whose history holds decomposed
+ * names — made by a git without that setting — is not covered: there git and the walk still differ.)
+ *
+ * Elsewhere a name is the characters it was written with, and stays so.
+ */
+export function nameForm(text: string, platform: NodeJS.Platform = process.platform): string {
+  return platform === 'darwin' ? text.normalize('NFC') : text;
+}
+
+/** The path of `path` below `root` (or from it, with `..`), written with `/` and in the form names are kept in (`nameForm`). */
+export function relativeDisplay(root: string, path: string): string {
+  const from = normalizePath(root);
+  const to = normalizePath(path);
+  // On macOS `relative` compares names exactly while `isWithin` folds them, as the file system does: a path under the
+  // root in another case or Unicode form would come back as `../../…`. (On Windows `relative` folds case itself.)
+  if (MAC) {
+    const under = partUnder(from, to, sep, foldForSystem);
+    if (under !== null) return nameForm(under);
+  }
+  return nameForm(relative(from, to).split(sep).join('/'));
+}
+
+/**
+ * The part of `path` below `root`, its names as `path` spells them and joined with `/` — `''` when they are the same
+ * place, null when `path` is not under `root`. Names are compared through `fold`, one by one.
+ */
+export function partUnder(root: string, path: string, separator: string, fold: (name: string) => string): string | null {
+  const above = root.split(separator);
+  while (above.length > 1 && above[above.length - 1] === '') above.pop();   // a root directory ends in its separator
+  const names = path.split(separator);
+  if (names.length < above.length) return null;
+  for (let i = 0; i < above.length; i += 1) if (fold(above[i]!) !== fold(names[i]!)) return null;
+  return names.slice(above.length).filter((name) => name !== '').join('/');
+}
+
+/**
+ * Whether `path` ends with the names `tail` gives — a repository named by the last part of its path, say — whichever
+ * separator either is written with, and whatever the case. (A path of this system has the system's separator: looking
+ * for `/name` at the end of it as text finds nothing on Windows.)
+ */
+export function endsWithPath(path: string, tail: string): boolean {
+  const names = (p: string) => p.split(/[\\/]+/).filter((name) => name !== '').map((name) => name.toLowerCase());
+  const all = names(path);
+  const last = names(tail);
+  return last.length > 0 && last.length <= all.length && last.every((name, i) => name === all[all.length - last.length + i]);
+}
+
+/**
+ * Where a file lies among these directories: the innermost one that holds it, as a key, and the file's path below it
+ * written with `/` — or, when none holds it, no directory and the file's own key.
+ */
+export function placeUnder(roots: readonly string[], file: string): { repo: string | null; path: string } {
+  const root = roots.filter((r) => isWithin(r, file) && !samePath(r, file)).sort((a, b) => pathKey(b).length - pathKey(a).length)[0];
+  return root !== undefined ? { repo: pathKey(root), path: relativeDisplay(root, file) } : { repo: null, path: pathKey(file) };
+}
+
+/**
+ * A path as its owner typed it into the workbench: `~` and `~/…` are the home directory. A shell makes that of them
+ * before a program sees the path; a field of a web page is no shell, and the path would be taken for a directory named
+ * `~` under wherever ProjectKeeper was started. `~name` (another account's home) is left as it is.
+ */
+export function expandHome(path: string): string {
+  if (path === '~') return homedir();
+  if (path.startsWith('~/') || (WIN && path.startsWith('~\\'))) return join(homedir(), path.slice(2));
+  return path;
+}
+
+/**
+ * Claude Code stores a project's sessions under `~/.claude/projects/<encoded cwd>/`, where
+ * every character outside `[A-Za-z0-9-]` becomes `-`. Observed on Windows:
+ * `D:\orchard` → `D--orchard`, `D:\my_app` → `D--my-app`,
+ * `D:\orchard\.worktrees\w9` → `D--orchard--worktrees-w9`.
+ */
+export function claudeProjectDirName(cwd: string): string {
+  return normalizePath(cwd).replace(/[^A-Za-z0-9-]/g, '-');
+}
+
+// ───────────────────────── Windows: how long a project's own path can be ─────────────────────────
+//
+// Files deep inside a project are no trouble: Node opens them at any length, and every git call is given
+// `core.longpaths` (util/git.ts `LONG_PATHS`). The length of the project's own path is another matter, and no setting
+// helps there, neither git's nor Windows' own for long paths. Both limits were measured (Git for Windows 2.53, pi
+// 0.87.1, Windows 11 with long paths enabled).
+
+/**
+ * The longest path of a repository Git for Windows can open. Before it reads any setting it looks for
+ * `<repository>\.git\objects`, which has to stay under 260 characters: one character more and it answers "not a git
+ * repository"; from 259 on it cannot enter the directory at all.
+ */
+export const GIT_ROOT_MAX = 246;
+
+/**
+ * The longest path of a directory the Keeper can work in. pi keeps a job's session in a folder named after the working
+ * directory, with two dashes before and after, and a folder's name is at most 255 characters. A few characters
+ * further, at 259, Windows starts no process in the directory, so no shell command could run there either.
+ */
+export const KEEPER_CWD_MAX = 251;
+
+/** What to say of a repository at `dir` that git cannot open because its path is too long; null when that is not the case. */
+export function gitPathLimit(dir: string): string | null {
+  const path = normalizePath(dir);
+  if (!WIN || path.length <= GIT_ROOT_MAX || !existsSync(join(path, '.git'))) return null;
+  return `This directory holds a git repository, but its path is ${path.length} characters long, and git on Windows cannot open a repository whose path is longer than ${GIT_ROOT_MAX} characters: its history, worktrees and ignore rules are not read. Move the project to a shorter path.`;
+}
+
+/** What to say of a directory the Keeper cannot work in because its path is too long; null when it can. */
+export function keeperPathLimit(dir: string): string | null {
+  const path = normalizePath(dir);
+  if (!WIN || path.length <= KEEPER_CWD_MAX) return null;
+  return `The Keeper cannot work in this project's directory: its path is ${path.length} characters long, and on Windows the Keeper can only work in a directory whose path is at most ${KEEPER_CWD_MAX} characters. Move the project to a shorter path.`;
+}