local-review 0.0.1 → 0.2.0

package/dist/server/commits.js

@@ -0,0 +1,393 @@
+import fs from 'node:fs';
+import { EMPTY_TREE, git, gitBuffer, gitWithInput, safeRef, sha40 } from './git.js';
+// ---- caches keyed by immutable data (commit shas) ----
+const summaryCache = new Map(); // repo\0sha
+const patchIdCache = new Map();
+const filesCache = new Map();
+const SEP = '\x1f';
+async function resolveBase(cfg) {
+    const candidates = cfg.base ? [cfg.base] : ['origin/HEAD', 'main', 'master'];
+    for (const c of candidates) {
+        try {
+            await git(cfg.path, ['rev-parse', '--verify', '--quiet', '--end-of-options', `${safeRef(c)}^{commit}`]);
+            return c;
+        }
+        catch {
+            /* try next */
+        }
+    }
+    throw new Error(cfg.base ? `base ref '${cfg.base}' not found` : `no base found (tried origin/HEAD, main, master)`);
+}
+export const rangeEnd = (cfg) => cfg.to ?? cfg.branch ?? '';
+/** The sha the range ends at (branch head or `to`), or null if it doesn't resolve. */
+export async function headOf(cfg) {
+    try {
+        return (await git(cfg.path, ['rev-parse', '--verify', '--quiet', '--end-of-options', `${safeRef(rangeEnd(cfg))}^{commit}`])).trim();
+    }
+    catch {
+        return null;
+    }
+}
+async function revParse(repo, ref) {
+    try {
+        return (await git(repo, ['rev-parse', '--verify', '--quiet', '--end-of-options', `${safeRef(ref)}^{commit}`])).trim();
+    }
+    catch {
+        return null;
+    }
+}
+export async function summarize(repo, sha) {
+    const key = repo + '\0' + sha;
+    const hit = summaryCache.get(key);
+    if (hit)
+        return hit;
+    const meta = await git(repo, ['show', '-s', `--format=%P${SEP}%s${SEP}%an${SEP}%ae${SEP}%aI${SEP}%(trailers:key=Change-Id,valueonly,separator=%x2C)`, sha40(sha)]);
+    const [parents, subject, author, authorEmail, date, changeIds] = meta.trim().split(SEP);
+    const parent = parents.split(' ').filter(Boolean)[0] ?? null;
+    const files = await changedFiles(repo, sha, parent);
+    const s = {
+        parent,
+        subject,
+        author,
+        authorEmail,
+        date,
+        changeId: changeIds?.split(',')[0]?.trim() || null,
+        additions: files.reduce((a, f) => a + f.additions, 0),
+        deletions: files.reduce((a, f) => a + f.deletions, 0),
+        filesChanged: files.length,
+    };
+    summaryCache.set(key, s);
+    return s;
+}
+/**
+ * The repo's live range. With `optional` (the repo has landed PRs), a missing `branch`/`to`, or one that no longer
+ * resolves (deleted after the merge), is no range at all rather than an error, and other range problems are a
+ * `warning`; only a missing repo is still an error.
+ */
+export async function loadRepo(cfg, opts = {}) {
+    const end = rangeEnd(cfg);
+    const info = { name: cfg.name, path: cfg.path, branch: cfg.branch ?? null, end, base: cfg.base ?? null, from: cfg.from ?? null, head: null, mergeBase: null, commits: [] };
+    if (!fs.existsSync(cfg.path)) {
+        info.error = `repo not found: ${cfg.path}`;
+        return info;
+    }
+    try {
+        if (!end) {
+            if (opts.optional)
+                return info;
+            throw new Error('no `branch` or `to` given');
+        }
+        info.head = await headOf(cfg);
+        if (!info.head && opts.optional)
+            return info;
+        if (!info.head)
+            throw new Error(cfg.to ? `'to' ref '${cfg.to}' not found` : `branch '${end}' not found`);
+        let range;
+        if (cfg.from) {
+            const first = await revParse(cfg.path, cfg.from);
+            if (!first)
+                throw new Error(`'from' commit '${cfg.from}' not found`);
+            try {
+                await git(cfg.path, ['merge-base', '--is-ancestor', '--end-of-options', sha40(first), sha40(info.head)]);
+            }
+            catch {
+                throw new Error(`'from' commit '${cfg.from}' is not an ancestor of ${end}`);
+            }
+            const parent = (await summarize(cfg.path, first)).parent;
+            info.mergeBase = parent;
+            range = parent ? `${sha40(parent)}..${sha40(info.head)}` : sha40(info.head);
+        }
+        else {
+            const base = await resolveBase(cfg);
+            info.base = base;
+            const mb = (await git(cfg.path, ['merge-base', '--end-of-options', safeRef(base), info.head])).trim();
+            info.mergeBase = mb;
+            range = `${sha40(mb)}..${sha40(info.head)}`;
+        }
+        const shas = (await git(cfg.path, ['rev-list', '--reverse', '--end-of-options', range])).split('\n').filter(Boolean);
+        info.commits = await Promise.all(shas.map(async (sha) => ({ sha, short: sha.slice(0, 8), ...(await summarize(cfg.path, sha)) })));
+    }
+    catch (e) {
+        if (opts.optional) {
+            info.warning = `live range: ${e.message}`;
+            info.commits = [];
+        }
+        else
+            info.error = e.message;
+    }
+    return info;
+}
+/** The repo's base ref as a sha (`base`, else origin/HEAD, main, master), or null. */
+export async function baseSha(cfg) {
+    try {
+        return await revParse(cfg.path, await resolveBase(cfg));
+    }
+    catch {
+        return null;
+    }
+}
+const isFull = (s) => typeof s === 'string' && /^[0-9a-f]{40}$/.test(s);
+/** A full sha from a YAML file, if the repo has it as a commit; returned as git itself prints it. */
+const present = (repo, s) => (isFull(s) ? revParse(repo, s) : Promise.resolve(null));
+async function mergeBaseOf(repo, a, b) {
+    try {
+        return (await git(repo, ['merge-base', '--end-of-options', sha40(a), sha40(b)])).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+const landedCache = new Map(); // only complete (merge-base) results: objects don't vanish
+/**
+ * A landed PR as a range entry: `sha` is its prs file's key, and its diff is merge-base(base, head)...head (GitHub's
+ * view of a stacked PR once it's retargeted and rebased onto the base). If the head or base object isn't in the repo
+ * (a deleted branch, never fetched), it falls back to the merge commit's first-parent diff, else no diff at all.
+ * Subject: the prs file's stored `subject:`, else the head's (or the key commit's), else the PR title.
+ */
+export async function landedSummary(repo, key, l, stored = {}) {
+    sha40(key);
+    const ck = [repo, key, l.head, l.base, l.commit, l.method, l.at, stored.subject, stored.title].join('\0');
+    const hit = landedCache.get(ck);
+    if (hit)
+        return hit;
+    const [head, base, merge, keyObj] = await Promise.all([present(repo, l.head), present(repo, l.base), present(repo, l.commit), present(repo, key)]);
+    let from = null;
+    let to = null;
+    let diff = 'none';
+    if (head && base) {
+        const mb = await mergeBaseOf(repo, base, head);
+        if (mb)
+            [from, to, diff] = [mb, head, 'merge-base'];
+    }
+    if (!to && merge) {
+        from = (await summarize(repo, merge)).parent;
+        [to, diff] = [merge, 'merge-commit'];
+    }
+    const metaSha = head ?? keyObj; // whose author, date and subject stand for the PR (not the merge commit's)
+    const meta = metaSha ? await summarize(repo, metaSha) : merge ? await summarize(repo, merge) : null;
+    const files = to ? await changedFiles(repo, to, from) : [];
+    const s = {
+        sha: key,
+        short: key.slice(0, 8),
+        parent: from,
+        subject: stored.subject?.trim() || (metaSha && meta?.subject) || stored.title || meta?.subject || '',
+        author: meta?.author ?? '',
+        authorEmail: meta?.authorEmail ?? '',
+        date: (metaSha && meta?.date) || l.at || meta?.date || '',
+        changeId: null,
+        additions: files.reduce((a, f) => a + f.additions, 0),
+        deletions: files.reduce((a, f) => a + f.deletions, 0),
+        filesChanged: files.length,
+        tip: to,
+        landed: { ...l, diff },
+    };
+    if (diff === 'merge-base') {
+        if (landedCache.size > 2000)
+            landedCache.clear();
+        landedCache.set(ck, s);
+    }
+    return s;
+}
+/** The files a range entry changes: its first-parent diff, or a landed PR's diff (none if it has none). */
+export function filesOf(repo, c) {
+    if (c.tip === null)
+        return Promise.resolve([]);
+    return changedFiles(repo, c.tip ?? c.sha, c.parent);
+}
+function parseStatus(code) {
+    switch (code[0]) {
+        case 'A': return 'added';
+        case 'D': return 'deleted';
+        case 'R': return 'renamed';
+        case 'C': return 'copied';
+        case 'T': return 'type-changed';
+        default: return 'modified';
+    }
+}
+/** Files changed by `sha` relative to its first parent (or the empty tree), with -M rename detection. */
+export async function changedFiles(repo, sha, parent) {
+    const key = repo + '\0' + sha + '\0' + (parent ?? '');
+    const hit = filesCache.get(key);
+    if (hit)
+        return hit;
+    const from = parent ? sha40(parent) : EMPTY_TREE;
+    sha40(sha);
+    const [rawOut, numOut] = await Promise.all([
+        git(repo, ['diff', '-M', '--no-ext-diff', '--no-textconv', '--raw', '-z', from, sha, '--']),
+        git(repo, ['diff', '-M', '--no-ext-diff', '--no-textconv', '--numstat', '-z', from, sha, '--']),
+    ]);
+    // --raw -z: ":old new oldsha newsha STATUS\0path\0[newpath\0]"
+    const raw = rawOut.split('\0');
+    const files = [];
+    for (let i = 0; i < raw.length;) {
+        const head = raw[i++];
+        if (!head || !head.startsWith(':'))
+            continue;
+        const statusCode = head.split(' ')[4] ?? 'M';
+        const status = parseStatus(statusCode);
+        if (status === 'renamed' || status === 'copied') {
+            const oldPath = raw[i++];
+            const newPath = raw[i++];
+            files.push({ path: newPath, oldPath, status, similarity: Number(statusCode.slice(1)) || undefined, additions: 0, deletions: 0, binary: false });
+        }
+        else {
+            const p = raw[i++];
+            files.push({ path: p, oldPath: status === 'added' ? null : p, status, additions: 0, deletions: 0, binary: false });
+        }
+    }
+    // --numstat -z: "add\tdel\tpath\0" or for renames "add\tdel\t\0old\0new\0"
+    const num = numOut.split('\0');
+    const stats = new Map();
+    for (let i = 0; i < num.length;) {
+        const rec = num[i++];
+        if (!rec)
+            continue;
+        const [a, d, p] = rec.split('\t');
+        let pathKey = p;
+        if (p === '' || p === undefined) {
+            i++; // old path
+            pathKey = num[i++];
+        }
+        stats.set(pathKey, { a: a === '-' ? 0 : Number(a), d: d === '-' ? 0 : Number(d), bin: a === '-' });
+    }
+    for (const f of files) {
+        const s = stats.get(f.path);
+        if (s) {
+            f.additions = s.a;
+            f.deletions = s.d;
+            f.binary = s.bin;
+        }
+    }
+    filesCache.set(key, files);
+    return files;
+}
+const MAX_BLOB = 2 * 1024 * 1024;
+async function readBlob(repo, rev, p) {
+    const spec = `${sha40(rev)}:${p}`;
+    const size = Number((await git(repo, ['cat-file', '-s', spec])).trim());
+    if (size > MAX_BLOB)
+        return { text: null, tooLarge: true, binary: false };
+    const buf = await gitBuffer(repo, ['cat-file', 'blob', spec]);
+    if (buf.subarray(0, 8000).includes(0))
+        return { text: null, tooLarge: false, binary: true };
+    return { text: buf.toString('utf8'), tooLarge: false, binary: false };
+}
+// commit details are immutable per sha; keep the last few (file contents can be large)
+const detailCache = new Map();
+const DETAIL_CACHE_SIZE = 12;
+export function commitDetail(repo, sha) {
+    return cachedDetail(repo + '\0' + sha, () => loadCommitDetail(repo, sha));
+}
+/** A range entry's detail: a commit's, or a landed PR's (its own diff, the head's message; see landedSummary). */
+export function detailOf(repo, c) {
+    if (!c.landed)
+        return commitDetail(repo, c.sha);
+    return cachedDetail(`${repo}\0landed\0${c.sha}\0${c.parent}\0${c.tip}\0${c.subject}`, () => loadLandedDetail(repo, c));
+}
+function cachedDetail(key, load) {
+    let p = detailCache.get(key);
+    if (p) {
+        detailCache.delete(key); // refresh LRU position
+    }
+    else {
+        p = load();
+        p.catch(() => detailCache.delete(key));
+    }
+    detailCache.set(key, p);
+    while (detailCache.size > DETAIL_CACHE_SIZE)
+        detailCache.delete(detailCache.keys().next().value);
+    return p;
+}
+const messageBody = (message) => message.replace(/^[^\n]*\n?/, '').replace(/^\n+/, '').trimEnd();
+/** A commit's message body (everything after the subject line), without loading its files. */
+export async function commitBody(repo, sha) {
+    return messageBody(await git(repo, ['show', '-s', '--format=%B', sha40(sha)]));
+}
+async function loadCommitDetail(repo, sha) {
+    const s = await summarize(repo, sha);
+    const meta = await git(repo, ['show', '-s', `--format=%B${SEP}%cn${SEP}%cI`, sha40(sha)]);
+    const [message, committer, committerDate] = meta.split(SEP);
+    const body = messageBody(message);
+    const files = await withContents(repo, await changedFiles(repo, sha, s.parent), s.parent, sha);
+    return { sha, short: sha.slice(0, 8), ...s, body, committer, committerDate, files };
+}
+async function loadLandedDetail(repo, c) {
+    // the message of the head (or the key commit), if the repo has it; a merge commit's message isn't the PR's
+    const msgSha = (await present(repo, c.landed?.head)) ?? (await present(repo, c.sha));
+    let body = '';
+    let committer = '';
+    let committerDate = '';
+    if (msgSha) {
+        const [message, cn, cd] = (await git(repo, ['show', '-s', `--format=%B${SEP}%cn${SEP}%cI`, sha40(msgSha)])).split(SEP);
+        [body, committer, committerDate] = [messageBody(message), cn, cd.trim()];
+    }
+    const files = c.tip ? await withContents(repo, await changedFiles(repo, c.tip, c.parent), c.parent, c.tip) : [];
+    return { ...c, body, committer, committerDate, files };
+}
+/** Old and new contents for each changed file, `from` (null: the empty tree) .. `to`. */
+async function withContents(repo, files, from, to) {
+    const s = { parent: from };
+    const sha = to;
+    return Promise.all(files.map(async (f) => {
+        const out = { ...f, oldContent: null, newContent: null };
+        if (f.binary)
+            return out;
+        try {
+            if (f.status !== 'added' && f.oldPath && s.parent) {
+                const r = await readBlob(repo, s.parent, f.oldPath);
+                out.oldContent = r.text;
+                out.tooLarge ||= r.tooLarge;
+                out.binary ||= r.binary;
+            }
+            if (f.status !== 'deleted') {
+                const r = await readBlob(repo, sha, f.path);
+                out.newContent = r.text;
+                out.tooLarge ||= r.tooLarge;
+                out.binary ||= r.binary;
+            }
+        }
+        catch {
+            // e.g. submodule entries: leave contents empty
+            out.binary = true;
+        }
+        return out;
+    }));
+}
+const ancestorCache = new Map(); // repo\0sha\0head
+/** Is `sha` an ancestor of (or equal to) `head`? False if either is unknown to the repo. */
+export async function isAncestor(repo, sha, head) {
+    const key = `${repo}\0${sha}\0${head}`;
+    const hit = ancestorCache.get(key);
+    if (hit !== undefined)
+        return hit;
+    let yes = false;
+    try {
+        await git(repo, ['merge-base', '--is-ancestor', '--end-of-options', sha40(sha), sha40(head)]);
+        yes = true;
+    }
+    catch {
+        yes = false;
+    }
+    if (ancestorCache.size > 5000)
+        ancestorCache.clear();
+    ancestorCache.set(key, yes);
+    return yes;
+}
+/** `git patch-id --stable` of a commit's diff against its first parent. */
+export async function patchId(repo, sha) {
+    const key = repo + '\0' + sha;
+    if (patchIdCache.has(key))
+        return patchIdCache.get(key);
+    let id = null;
+    try {
+        const s = await summarize(repo, sha);
+        const diff = await git(repo, ['diff', '-M', '--no-ext-diff', '--no-textconv', s.parent ? sha40(s.parent) : EMPTY_TREE, sha40(sha), '--']);
+        const out = await gitWithInput(repo, ['patch-id', '--stable'], diff);
+        id = out.trim().split(/\s+/)[0] || null;
+    }
+    catch {
+        id = null;
+    }
+    patchIdCache.set(key, id);
+    return id;
+}

package/dist/server/config.js

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * The package root: the directory holding Local Review's own package.json. This file runs from server/ (from
+ * source, via tsx: dev and tests) or from dist/server/ (the compiled, installed package), so walk up to it rather
+ * than assume a depth.
+ */
+export function packageRoot(from = path.dirname(fileURLToPath(import.meta.url))) {
+    for (let dir = from;; dir = path.dirname(dir)) {
+        try {
+            if (JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')).name === 'local-review')
+                return dir;
+        }
+        catch {
+            /* no package.json here (or not ours): keep going */
+        }
+        if (path.dirname(dir) === dir)
+            throw new Error(`can't find Local Review's package.json above ${from}`);
+    }
+}
+export const ROOT = packageRoot();
+/** The built UI (`npm run build`), the bundled fonts and the files `local-review init` / `guide` use. */
+export const WEB_DIST = path.join(ROOT, 'dist', 'web');
+export const FONT_DIR = path.join(ROOT, 'server', 'fonts');
+export const EXAMPLE_PROJECT = path.join(ROOT, 'examples', 'project.example.yaml');
+export const AGENT_GUIDE = path.join(ROOT, 'AGENT-GUIDE.md');
+export function expandHome(p) {
+    if (p === '~')
+        return os.homedir();
+    if (p.startsWith('~/'))
+        return path.join(os.homedir(), p.slice(2));
+    return p;
+}
+/**
+ * User data lives outside the app repo, in ~/.local-review (or $LOCAL_REVIEW_HOME):
+ *   projects/<slug>/{project.yaml, prs/, reviews/, assets/}   (assets/: images, server/assets.ts)
+ *   backups/<ISO timestamp>/   automatic snapshots of projects/ (server/backups.ts)
+ */
+export const HOME = path.resolve(expandHome(process.env.LOCAL_REVIEW_HOME || path.join(os.homedir(), '.local-review')));
+/**
+ * LOCAL_REVIEW_PROJECTS_DIR points just the projects at another directory (the tests use it). It's not a data
+ * home, so automatic snapshots are off unless LOCAL_REVIEW_HOME is set too (then they go to $LOCAL_REVIEW_HOME/backups).
+ */
+const projectsOverride = process.env.LOCAL_REVIEW_PROJECTS_DIR;
+export const PROJECTS_DIR = projectsOverride ? path.resolve(expandHome(projectsOverride)) : path.join(HOME, 'projects');
+export const BACKUPS_DIR = !projectsOverride || process.env.LOCAL_REVIEW_HOME ? path.join(HOME, 'backups') : null;
+/** The default port. The one place it's set: the CLI's help, the startup line and `npm run dev` all derive from it. */
+export { DEFAULT_PORT } from './port.js';
+/** A port number from the command line or $PORT: an integer 0–65535 (0 picks any free port), else null. */
+export function parsePort(v) {
+    return /^[0-9]{1,5}$/.test(v) && Number(v) <= 65535 ? Number(v) : null;
+}
+/** A name we use as a directory and a URL segment: [A-Za-z0-9._-], no leading dot. */
+export const SAFE_NAME = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;
+export function safeName(s, fallback) {
+    return s.replace(/[^A-Za-z0-9._-]/g, '-').replace(/^\.+/, '_') || fallback;
+}

package/dist/server/context.js

@@ -0,0 +1,68 @@
+import { commitDetail, detailOf, isAncestor, patchId, rangeEnd, summarize } from './commits.js';
+export function liveCommits(cfg, info) {
+    // landed PRs are in the list (so nothing takes their files) but frozen (so they take nothing)
+    return info.commits.map((c) => ({ sha: c.sha, subject: c.subject, changeId: c.changeId, getPatchId: () => patchId(cfg.path, c.sha), ...(c.landed ? { frozen: true } : {}) }));
+}
+/**
+ * Look up the sha of an orphaned review / PR file in the reviewed repo (read-only): is it still an ancestor of
+ * the range end (it only left the range), and its subject, Change-Id and patch-id for files that lack them.
+ */
+export function inspectOrphan(cfg, info) {
+    return async (sha) => {
+        if (!/^[0-9a-f]{40}$/.test(sha))
+            return null;
+        let s;
+        try {
+            s = await summarize(cfg.path, sha);
+        }
+        catch {
+            return { exists: false, reachable: false }; // not in this repo (or gc'd)
+        }
+        return {
+            exists: true,
+            reachable: info.head ? await isAncestor(cfg.path, sha, info.head) : false,
+            subject: s.subject,
+            changeId: s.changeId,
+            getPatchId: () => patchId(cfg.path, sha),
+        };
+    };
+}
+/** Everything the review store needs to know about one commit of a loaded repo range. */
+export function contextFor(dir, cfg, info, commit) {
+    return {
+        repo: cfg.name,
+        dir,
+        repoPath: cfg.path,
+        branch: rangeEnd(cfg),
+        sha: commit.sha,
+        subject: commit.subject,
+        changeId: commit.changeId,
+        getPatchId: () => patchId(cfg.path, commit.sha),
+        liveCommits: liveCommits(cfg, info),
+        inspectOrphan: inspectOrphan(cfg, info),
+        // sha is either a range commit or an old sha taken from a review file name (40 hex), never user input
+        getFiles: async (sha) => {
+            if (!/^[0-9a-f]{40}$/.test(sha))
+                return null;
+            try {
+                // a landed PR's own diff (merge-base(base, head)...head), not its key commit's
+                return (await (sha === commit.sha ? detailOf(cfg.path, commit) : commitDetail(cfg.path, sha))).files;
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+export function prContextFor(dir, cfg, info, commit) {
+    return {
+        repo: cfg.name,
+        dir,
+        sha: commit.sha,
+        subject: commit.subject,
+        changeId: commit.changeId,
+        getPatchId: () => patchId(cfg.path, commit.sha),
+        liveCommits: liveCommits(cfg, info),
+        inspectOrphan: inspectOrphan(cfg, info),
+    };
+}

package/dist/server/events.js

@@ -0,0 +1,87 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { watch } from 'chokidar';
+import { BACKUPS_DIR, PROJECTS_DIR } from './config.js';
+import { startSnapshots } from './backups.js';
+import { headOf } from './commits.js';
+import { listProjectSlugs, loadProjectConfig } from './projects.js';
+const listeners = new Set();
+export function subscribe(l) {
+    listeners.add(l);
+    return () => listeners.delete(l);
+}
+export function emit(e) {
+    for (const l of listeners) {
+        try {
+            l(e);
+        }
+        catch {
+            /* ignore broken listener */
+        }
+    }
+}
+// debounce per key so a burst of fs events becomes one push
+const timers = new Map();
+function emitSoon(key, e, ms = 150) {
+    clearTimeout(timers.get(key));
+    timers.set(key, setTimeout(() => { timers.delete(key); emit(e); }, ms));
+}
+/** Map a changed path under projects/ to the event the browser needs. */
+export function eventFor(rel) {
+    const [project, kind, repo, name] = rel;
+    if (!project)
+        return null;
+    if (rel.length === 1)
+        return { type: 'projects', reason: 'dir' };
+    if (rel.length === 2)
+        return kind === 'project.yaml' ? { type: 'project', project, reason: 'config' } : null;
+    if (rel.length !== 4 || (kind !== 'reviews' && kind !== 'prs'))
+        return null;
+    const m = /^([0-9a-f]{40})\.yaml$/.exec(name);
+    if (m)
+        return { type: kind === 'reviews' ? 'review' : 'pr', project, repo, sha: m[1] };
+    // renamed/backup files can still affect rebase re-matching
+    if (name.endsWith('.yaml') || name.endsWith('.bak'))
+        return { type: 'project', project, reason: kind, repo };
+    return null;
+}
+/** Watch projects/ and the branch heads, and take automatic snapshots (backups.ts). Called once on server start. */
+export function startWatchers() {
+    fs.mkdirSync(PROJECTS_DIR, { recursive: true });
+    startSnapshots(PROJECTS_DIR, BACKUPS_DIR);
+    const onPath = (p) => {
+        const rel = path.relative(PROJECTS_DIR, p).split(path.sep);
+        if (rel[0] === '' || rel[0] === '..')
+            return;
+        const e = eventFor(rel);
+        if (!e)
+            return;
+        const key = e.type === 'review' || e.type === 'pr' ? `${e.type}:${e.project}:${e.repo}:${e.sha}` : e.type === 'project' ? `project:${e.project}` : 'projects';
+        emitSoon(key, e);
+        if (e.type === 'project' && e.reason === 'config')
+            emitSoon('projects', { type: 'projects', reason: 'config' });
+    };
+    watch(PROJECTS_DIR, { ignoreInitial: true, depth: 3, awaitWriteFinish: false, ignored: (p) => path.basename(p).endsWith('.tmp') })
+        .on('add', onPath)
+        .on('change', onPath)
+        .on('unlink', onPath)
+        .on('addDir', onPath)
+        .on('unlinkDir', onPath)
+        .on('error', (err) => console.error('[watch projects]', err));
+    // poll range ends (branch heads) so new / amended / rebased commits show up
+    const heads = new Map();
+    const poll = async () => {
+        for (const slug of listProjectSlugs()) {
+            const cfg = loadProjectConfig(slug);
+            for (const r of cfg?.repos ?? []) {
+                const key = `${slug}\0${r.name}\0${r.path}\0${r.to ?? r.branch}`;
+                const h = await headOf(r);
+                if (heads.has(key) && heads.get(key) !== h)
+                    emit({ type: 'project', project: slug, reason: 'head', repo: r.name });
+                heads.set(key, h);
+            }
+        }
+    };
+    poll().catch(() => { });
+    setInterval(() => poll().catch(() => { }), 3000).unref();
+}