local-review 0.0.1 → 0.2.0

package/dist/server/backups.js

@@ -0,0 +1,212 @@
+// Automatic snapshots of the projects directory: a plain recursive copy into backups/<timestamp>/, so restoring
+// is just copying files back. Taken on server start and then hourly, each only if something changed since the
+// newest snapshot. Pruning keeps the newest KEEP_RECENT snapshots plus the first snapshot of each (UTC) day for
+// KEEP_DAYS days, and can only ever remove directories directly inside the backups dir whose names are
+// snapshot timestamps (see assertPrunable).
+// Image assets (projects/<slug>/assets/<hash>.<ext>) are hard-linked into a snapshot rather than copied: they're
+// named by their content and never rewritten in place (safefs writes a new file and renames it), so every
+// snapshot can share the one copy on disk. Where linking fails (another file system), they're copied.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { ASSET_NAME } from '../shared/assets.js';
+export const KEEP_RECENT = 50;
+export const KEEP_DAYS = 30;
+export const INTERVAL_MS = 60 * 60 * 1000;
+/** `2026-10-09T08-45-12Z` (ISO 8601 UTC, ':' -> '-' so it's a valid file name everywhere), maybe `-2`, `-3`… */
+export const SNAPSHOT_NAME = /^(\d{4}-\d{2}-\d{2})T\d{2}-\d{2}-\d{2}Z(?:-\d{1,3})?$/;
+export function snapshotName(d) {
+    return d.toISOString().replace(/\.\d{3}Z$/, 'Z').replace(/:/g, '-');
+}
+/** Our own atomic-write temp files: never worth backing up. */
+const isTemp = (name) => name.startsWith('.') && name.endsWith('.tmp');
+/** An image asset: `<slug>/assets/<content hash>.<ext>` relative to the projects dir (see server/assets.ts). */
+const isAsset = (rel) => {
+    const parts = rel.split('/');
+    return parts.length === 3 && parts[1] === 'assets' && ASSET_NAME.test(parts[2]);
+};
+/** A hash of every file's relative path and contents (symlinks are skipped, as cpSync would copy them as links). */
+export function fingerprint(dir) {
+    const h = crypto.createHash('sha256');
+    let files = 0;
+    const walk = (d, rel) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const e of entries) {
+            if (isTemp(e.name))
+                continue;
+            const p = path.join(d, e.name);
+            const r = rel ? `${rel}/${e.name}` : e.name;
+            if (e.isDirectory())
+                walk(p, r);
+            else if (e.isFile()) {
+                files++;
+                // an asset's name is its content hash, so its name and size stand for its bytes (no need to read MBs hourly)
+                if (isAsset(r))
+                    h.update(`${r}\0${fs.statSync(p).size}\0`);
+                else
+                    h.update(`${r}\0`).update(fs.readFileSync(p)).update('\0');
+            }
+        }
+    };
+    walk(dir, '');
+    return files ? h.digest('hex') : null;
+}
+/** Snapshot directory names in `backupsDir`, oldest first (the names sort chronologically). */
+export function listSnapshots(backupsDir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(backupsDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isDirectory() && SNAPSHOT_NAME.test(e.name))
+        .map((e) => e.name)
+        .sort(compareNames);
+}
+function compareNames(a, b) {
+    const [ta, na] = splitName(a);
+    const [tb, nb] = splitName(b);
+    return ta < tb ? -1 : ta > tb ? 1 : na - nb;
+}
+const splitName = (n) => {
+    const m = /^(.*Z)(?:-(\d+))?$/.exec(n);
+    return [m[1], m[2] ? Number(m[2]) : 1];
+};
+/**
+ * Copy `projectsDir` to `backupsDir/<timestamp>/` unless it's empty or identical to the newest snapshot.
+ * The copy is made under a dot-name and renamed into place, so a snapshot directory is always complete.
+ * Returns the new snapshot's name, or null if none was needed.
+ */
+export function takeSnapshot(projectsDir, backupsDir, now = new Date()) {
+    const fp = fingerprint(projectsDir);
+    if (!fp)
+        return null; // nothing to back up
+    const existing = listSnapshots(backupsDir);
+    const newest = existing[existing.length - 1];
+    if (newest && fingerprint(path.join(backupsDir, newest)) === fp)
+        return null;
+    fs.mkdirSync(backupsDir, { recursive: true });
+    const base = snapshotName(now);
+    let name = base;
+    for (let n = 2; fs.existsSync(path.join(backupsDir, name)); n++)
+        name = `${base}-${n}`;
+    const partial = path.join(backupsDir, `.partial-${name}-${process.pid}`);
+    fs.cpSync(projectsDir, partial, {
+        recursive: true,
+        preserveTimestamps: true,
+        errorOnExist: true,
+        force: false,
+        filter: (src, dst) => !isTemp(path.basename(src)) && !(isAsset(path.relative(projectsDir, src).split(path.sep).join('/')) && linked(src, dst)),
+    });
+    const dest = path.join(backupsDir, name);
+    if (fs.existsSync(dest))
+        throw new Error(`${dest} appeared while snapshotting; leaving the copy at ${partial}`);
+    fs.renameSync(partial, dest); // fs-guard: a fresh dot-dir onto a name we just checked is free
+    return name;
+}
+/** Hard-link an asset into the snapshot being made; false (so it's copied instead) if that isn't possible. */
+function linked(src, dst) {
+    try {
+        if (!fs.lstatSync(src).isFile())
+            return false;
+        fs.mkdirSync(path.dirname(dst), { recursive: true });
+        fs.linkSync(src, dst); // fails rather than replace anything (the snapshot dir is brand new anyway)
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Which snapshots to keep: the newest KEEP_RECENT, plus the first of each UTC day in the last KEEP_DAYS days. */
+export function snapshotsToKeep(names, now = new Date()) {
+    const sorted = [...names].sort(compareNames);
+    const keep = new Set(sorted.slice(-KEEP_RECENT));
+    const cutoff = new Date(now.getTime() - KEEP_DAYS * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
+    const seenDays = new Set();
+    for (const n of sorted) {
+        const day = SNAPSHOT_NAME.exec(n)[1];
+        if (seenDays.has(day))
+            continue;
+        seenDays.add(day);
+        if (day >= cutoff)
+            keep.add(n);
+    }
+    return keep;
+}
+/**
+ * Throws unless `backupsDir/name` is something pruning may remove: `name` is a bare snapshot timestamp, the
+ * target is a real directory (not a symlink) directly inside `backupsDir`, and `backupsDir` is a directory
+ * called `backups` that is neither inside nor containing the projects directory.
+ */
+export function assertPrunable(backupsDir, name, projectsDir) {
+    if (typeof name !== 'string' || !SNAPSHOT_NAME.test(name) || name !== path.basename(name) || name.includes('/') || name.includes('\\')) {
+        throw new Error(`refusing to prune ${JSON.stringify(name)}: not a snapshot name`);
+    }
+    const root = path.resolve(backupsDir);
+    if (path.basename(root) !== 'backups')
+        throw new Error(`refusing to prune in ${root}: not a backups/ directory`);
+    const projects = path.resolve(projectsDir);
+    const inside = (a, b) => a === b || a.startsWith(b + path.sep);
+    if (inside(root, projects) || inside(projects, root))
+        throw new Error(`refusing to prune in ${root}: overlaps ${projects}`);
+    const target = path.join(root, name);
+    if (path.dirname(target) !== root)
+        throw new Error(`refusing to prune ${target}: not directly inside ${root}`);
+    const st = fs.lstatSync(target);
+    if (!st.isDirectory() || st.isSymbolicLink())
+        throw new Error(`refusing to prune ${target}: not a directory`);
+    // the real path too, in case backupsDir itself is reached through a symlink into the projects
+    const realRoot = fs.realpathSync(root);
+    if (path.dirname(fs.realpathSync(target)) !== realRoot)
+        throw new Error(`refusing to prune ${target}: resolves outside ${realRoot}`);
+    if (fs.existsSync(projects) && inside(realRoot, fs.realpathSync(projects)))
+        throw new Error(`refusing to prune in ${realRoot}: inside the projects`);
+    return target;
+}
+/** Remove snapshots that `snapshotsToKeep` doesn't keep. Never removes the newest. Returns the removed names. */
+export function pruneSnapshots(backupsDir, projectsDir, now = new Date()) {
+    const names = listSnapshots(backupsDir);
+    const keep = snapshotsToKeep(names, now);
+    const newest = names[names.length - 1];
+    const removed = [];
+    for (const n of names) {
+        if (keep.has(n) || n === newest)
+            continue;
+        const target = assertPrunable(backupsDir, n, projectsDir);
+        fs.rmSync(target, { recursive: true }); // fs-guard: backup pruning (assertPrunable checked the path)
+        removed.push(n);
+    }
+    return removed;
+}
+/** Snapshot (if changed) and prune. Never throws: a failed snapshot must not take the server down. */
+export function snapshotNow(projectsDir, backupsDir, now = new Date()) {
+    try {
+        const name = takeSnapshot(projectsDir, backupsDir, now);
+        if (name)
+            console.log(`[backups] snapshot ${path.join(backupsDir, name)}`);
+        const removed = pruneSnapshots(backupsDir, projectsDir, now);
+        if (removed.length)
+            console.log(`[backups] pruned ${removed.length} old snapshot(s)`);
+        return name;
+    }
+    catch (e) {
+        console.error('[backups] snapshot failed:', e);
+        return null;
+    }
+}
+/** On start, and then hourly while running. */
+export function startSnapshots(projectsDir, backupsDir) {
+    if (!backupsDir)
+        return;
+    snapshotNow(projectsDir, backupsDir);
+    setInterval(() => snapshotNow(projectsDir, backupsDir), INTERVAL_MS).unref();
+}

package/dist/server/branches.js

@@ -0,0 +1,113 @@
+// Branch tagging: which git branch stands for each candidate PR (commit). Local Review has no naming scheme: the
+// agent that writes the code creates plain branches (`git branch <name> <sha>`) and records the name in
+// prs/<repo>/<sha>.yaml (`branch:`, or `github.branch` once the PR exists). Here we read the repo's branches
+// (read-only, one `git for-each-ref` per range) and reconcile the recorded name with what git says.
+import { git, isSha } from './git.js';
+const SEP = '\x1f';
+export function emptyRefIndex() {
+    return { refs: [], byRef: new Map(), bySha: new Map(), remotes: [], symrefs: new Map() };
+}
+export function parseRefs(out) {
+    const idx = emptyRefIndex();
+    const remotes = new Set();
+    for (const line of out.split('\n')) {
+        if (!line)
+            continue;
+        const [sha, ref, symref] = line.split(SEP);
+        if (!ref)
+            continue;
+        const remote = ref.startsWith('refs/remotes/');
+        const name = ref.replace(/^refs\/(heads|remotes)\//, '');
+        if (remote)
+            remotes.add(name.split('/')[0]);
+        if (symref) {
+            // origin/HEAD: not a branch of its own, just remember where it points
+            idx.symrefs.set(name, symref.replace(/^refs\/(heads|remotes)\//, ''));
+            continue;
+        }
+        if (!isSha(sha))
+            continue; // a ref to something that isn't a 40-hex object name
+        const e = { ref, name, sha, remote };
+        idx.refs.push(e);
+        idx.byRef.set(ref, e);
+        const list = idx.bySha.get(sha) ?? [];
+        list.push(e);
+        idx.bySha.set(sha, list);
+    }
+    idx.remotes = [...remotes].sort();
+    return idx;
+}
+/**
+ * All local and remote-tracking branches of a repo, in one read-only call. (`--points-at` takes a single
+ * object, so for a whole range one listing of every branch is the batched form.) Never throws.
+ */
+export async function loadRefs(repo) {
+    try {
+        const out = await git(repo, ['for-each-ref', `--format=%(objectname)${SEP}%(refname)${SEP}%(symref)`, '--end-of-options', 'refs/heads', 'refs/remotes']);
+        return parseRefs(out);
+    }
+    catch {
+        return emptyRefIndex();
+    }
+}
+/** Find a recorded branch name: local `refs/heads/<n>` first, then `refs/remotes/<n>`, then `<remote>/<n>`. */
+export function lookupBranch(idx, name) {
+    const local = idx.byRef.get(`refs/heads/${name}`);
+    if (local)
+        return local;
+    const asRemote = idx.byRef.get(`refs/remotes/${name}`);
+    if (asRemote)
+        return asRemote;
+    for (const r of idx.remotes) {
+        const e = idx.byRef.get(`refs/remotes/${r}/${name}`);
+        if (e)
+            return e;
+    }
+    return null;
+}
+/** `origin/main` -> `main` (any remote that has refs here), `refs/heads/main` -> `main`; else unchanged. */
+export function stripRemote(idx, ref) {
+    let r = ref.replace(/^refs\/heads\//, '').replace(/^refs\/remotes\//, '');
+    r = idx.symrefs.get(r) ?? r; // origin/HEAD -> origin/main
+    for (const remote of idx.remotes)
+        if (r.startsWith(remote + '/'))
+            return r.slice(remote.length + 1);
+    return r;
+}
+/** Is this ref the range's own tip branch (e.g. me/my-feature, or origin/me/my-feature)? */
+function isTip(idx, e, tip) {
+    if (!tip)
+        return false;
+    const t = tip.replace(/^refs\/heads\//, '');
+    if (!e.remote)
+        return e.name === t;
+    return e.name === t || stripRemote(idx, e.name) === t;
+}
+/** Branches pointing at `sha`, best first: local non-tip, remote non-tip, then the tip branch (local, remote). */
+export function discoveredFor(idx, sha, tip) {
+    const list = idx.bySha.get(sha) ?? [];
+    const rank = (e) => (isTip(idx, e, tip) ? 2 : 0) + (e.remote ? 1 : 0);
+    return [...list].sort((a, b) => rank(a) - rank(b) || a.name.localeCompare(b.name)).map((e) => e.name);
+}
+/**
+ * Reconcile what prs/<sha>.yaml records with git. Recorded name: `github.branch`, else `branch`. Then:
+ * ok (exists, points here), moved (exists, points elsewhere: `points_at`), missing (not in git). With nothing
+ * recorded: the best discovered branch (a local non-tip one first), status `discovered`; else null. A landed PR's
+ * recorded branch is `merged`, whatever git says (never a warning).
+ */
+export function reconcileBranch(idx, sha, override, tip) {
+    const recorded = override?.github?.branch ?? override?.branch;
+    // a landed PR's branch is history: it may be deleted or reused by now, and that's no problem
+    if (override?.landed)
+        return recorded ? { name: recorded, status: 'merged', discovered: [] } : null;
+    const discovered = discoveredFor(idx, sha, tip);
+    if (recorded) {
+        const e = lookupBranch(idx, recorded);
+        if (!e)
+            return { name: recorded, status: 'missing', discovered };
+        if (e.sha === sha)
+            return { name: recorded, status: 'ok', discovered };
+        return { name: recorded, status: 'moved', points_at: e.sha, discovered };
+    }
+    return discovered.length ? { name: discovered[0], status: 'discovered', discovered } : null;
+}

package/dist/server/cli.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+// `local-review [command] …`: the command-line entry point (the package's bin; `npm run lr -- …` from a checkout).
+// With no command it serves the UI. `plan` and `guide` are read-only: they never write a file and never run gh (or
+// anything but read-only git, via server/git.ts). `init` only ever creates a new project.yaml, never replaces one.
+// `asset add` only ever creates a new, content-named image file; `asset url` writes only the asset's own <name>.yaml.
+import fs from 'node:fs';
+import path from 'node:path';
+import { AGENT_GUIDE, DEFAULT_PORT, EXAMPLE_PROJECT, PROJECTS_DIR, ROOT, SAFE_NAME, parsePort } from './config.js';
+import { loadProject } from './projects.js';
+import { buildPlan, planMarkdown, planYaml } from './plan.js';
+import { ExistsError, atomicWrite } from './safefs.js';
+import { AssetError, addAsset, setPublishedUrl } from './assets.js';
+import { MAX_ASSET_BYTES, typeOfName } from '../shared/assets.js';
+const USAGE = `Usage: local-review [serve] [--port <n>]
+       local-review plan <project> [--repo <name>] [--stack <n>] [--include-follow-on] [--format md|json|yaml]
+       local-review init <project>
+       local-review asset add <project> <file> [--alt <text>]
+       local-review asset url <project> <name> <url>
+       local-review guide
+       local-review --version | --help
+
+  serve   (the default) Serve the review UI and API on http://localhost:<port> (127.0.0.1 only).
+          --port <n>       the port (default ${DEFAULT_PORT}, or $PORT)
+  plan    For each PR in scope, in order: commit, status (draft / ready / published), branch (with its
+          status), base, title and the exact full body (project intro, stack note, ---, PR description), plus
+          any recorded github: info. Warns about stacks with draft PRs, GitHub bases that differ from the
+          plan's, and published PRs that landed upstream without being frozen. Landed (merged) PRs are
+          never planned. Read-only.
+          --repo <name>    one repo of the project
+          --stack <n>      one declared stack (1-based, as in project.yaml); needs --repo if several repos have it.
+                           Naming a follow-on stack plans it (with a note).
+          --include-follow-on
+                           also plan follow-on stacks (follow_on: true, parked work); left out by default
+          --format <f>     md (default), json or yaml
+  init    Create a project to review: <projects>/<project>/project.yaml, a commented example to edit.
+          Never replaces an existing one.
+  asset add
+          Copy an image (PNG, JPEG, GIF, WebP or SVG, up to 5 MB) into the project's assets folder, named by its
+          content, and print the markdown that shows it, e.g. ![alt](assets/3f2a9c1e0b7d4a65.png), for a PR
+          description, stack note or project intro. Adding the same image again is a no-op.
+          --alt <text>     the alt text (default: the file name)
+  asset url
+          Record where an asset is published (a URL GitHub's readers can reach), so \`plan\` puts that URL in
+          the bodies instead of the local assets/<name> reference.
+  guide   Print the guide for agents using Local Review to get their work reviewed (AGENT-GUIDE.md).
+
+Data: $LOCAL_REVIEW_HOME/projects (default ~/.local-review/projects). Agents: run \`local-review guide\`.`;
+/** Bad usage: exit 2, with the usage. Anything else thrown exits 1. */
+class UsageError extends Error {
+}
+const VALUE_FLAGS = ['repo', 'stack', 'format', 'port', 'alt'];
+function parseArgs(argv) {
+    const pos = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '-h' || a === '--help')
+            flags.help = '1';
+        else if (a === '-v' || a === '--version')
+            flags.version = '1';
+        else if (a === '--include-follow-on')
+            flags['include-follow-on'] = '1';
+        else if (a.startsWith('--')) {
+            const eq = a.indexOf('=');
+            const [k, v] = eq > 0 ? [a.slice(2, eq), a.slice(eq + 1)] : [a.slice(2), argv[++i]];
+            if (!VALUE_FLAGS.includes(k))
+                throw new UsageError(`unknown option --${k}`);
+            if (v === undefined)
+                throw new UsageError(`--${k} needs a value`);
+            flags[k] = v;
+        }
+        else if (a.startsWith('-') && a.length > 1)
+            throw new UsageError(`unknown option ${a}`);
+        else
+            pos.push(a);
+    }
+    return { pos, flags };
+}
+/** Each command takes its own options and at most `max` arguments. */
+function check(cmd, flags, allowed, args, max) {
+    const bad = Object.keys(flags).find((k) => !allowed.includes(k));
+    if (bad)
+        throw new UsageError(`${cmd} doesn't take --${bad}`);
+    if (args.length > max)
+        throw new UsageError(`unexpected argument '${args[max]}'`);
+}
+async function plan(slug, flags) {
+    if (!slug)
+        throw new UsageError('plan needs a project');
+    if (!SAFE_NAME.test(slug))
+        throw new UsageError(`bad project name '${slug}'`);
+    const format = flags.format ?? 'md';
+    if (!['md', 'json', 'yaml'].includes(format))
+        throw new UsageError(`--format must be md, json or yaml`);
+    let stack;
+    if (flags.stack !== undefined) {
+        if (!/^[1-9][0-9]{0,3}$/.test(flags.stack))
+            throw new UsageError(`--stack must be a stack number (1, 2, …)`);
+        stack = Number(flags.stack);
+    }
+    const project = await loadProject(slug);
+    if (!project)
+        throw new Error(`no project '${slug}' (looked for ${path.join(PROJECTS_DIR, slug, 'project.yaml')}; \`local-review init ${slug}\` creates one)`);
+    const p = await buildPlan(project, { repo: flags.repo, stack, includeFollowOn: !!flags['include-follow-on'] });
+    process.stdout.write(format === 'json' ? JSON.stringify(p, null, 2) + '\n' : format === 'yaml' ? planYaml(p) : planMarkdown(p));
+}
+function init(slug) {
+    if (!slug)
+        throw new UsageError('init needs a project name, e.g. `local-review init my-feature`');
+    if (!SAFE_NAME.test(slug))
+        throw new UsageError(`bad project name '${slug}': use letters, digits, '.', '_' and '-', not starting with '.'`);
+    const file = path.join(PROJECTS_DIR, slug, 'project.yaml');
+    const text = fs.readFileSync(EXAMPLE_PROJECT, 'utf8').replace(/^title: .*$/m, `title: ${slug}`);
+    try {
+        atomicWrite(file, text, { createOnly: true });
+    }
+    catch (e) {
+        if (e instanceof ExistsError)
+            throw new Error(`${file} already exists; not replacing it`);
+        throw e;
+    }
+    const port = (process.env.PORT && parsePort(process.env.PORT)) || DEFAULT_PORT;
+    process.stdout.write(`Created ${file}\n\n` +
+        `Next: edit it (each repo's path and branch), then run \`local-review\` and open http://localhost:${port}/${slug}\n` +
+        `Edits to project.yaml are picked up live.\n`);
+}
+function projectDirFor(cmd, slug) {
+    if (!slug)
+        throw new UsageError(`${cmd} needs a project`);
+    if (!SAFE_NAME.test(slug))
+        throw new UsageError(`bad project name '${slug}'`);
+    const dir = path.join(PROJECTS_DIR, slug);
+    if (!fs.existsSync(path.join(dir, 'project.yaml')))
+        throw new Error(`no project '${slug}' (looked for ${path.join(dir, 'project.yaml')}; \`local-review init ${slug}\` creates one)`);
+    return dir;
+}
+function asset(args, flags) {
+    const [sub, slug, a, b] = args;
+    if (sub === 'add') {
+        if (args.length > 3)
+            throw new UsageError(`unexpected argument '${args[3]}'`);
+        const dir = projectDirFor('asset add', slug);
+        if (!a)
+            throw new UsageError('asset add needs an image file');
+        let st;
+        try {
+            st = fs.statSync(a);
+        }
+        catch {
+            throw new Error(`can't read ${a}`);
+        }
+        if (!st.isFile())
+            throw new Error(`${a} isn't a file`);
+        if (st.size > MAX_ASSET_BYTES)
+            throw new Error(`${a} is ${(st.size / 1024 / 1024).toFixed(1)} MB; the limit is ${MAX_ASSET_BYTES / 1024 / 1024} MB`);
+        const alt = flags.alt ?? path.basename(a).replace(/\.[^.]*$/, '');
+        try {
+            const r = addAsset(dir, fs.readFileSync(a), typeOfName(a), alt);
+            process.stderr.write(`${r.created ? 'Added' : 'Already there:'} ${r.file}\n`);
+            process.stdout.write(r.markdown + '\n');
+        }
+        catch (e) {
+            if (e instanceof AssetError)
+                throw new Error(`${a}: ${e.message}`);
+            throw e;
+        }
+        return;
+    }
+    if (sub === 'url') {
+        if (flags.alt !== undefined)
+            throw new UsageError("asset url doesn't take --alt");
+        if (args.length > 4)
+            throw new UsageError(`unexpected argument '${args[4]}'`);
+        const dir = projectDirFor('asset url', slug);
+        if (!a || !b)
+            throw new UsageError('asset url needs an asset name and a URL, e.g. `local-review asset url my-feature 3f2a9c1e0b7d4a65.png https://…`');
+        const name = a.replace(/^(?:\.\/)?assets\//, ''); // accept the reference as written in markdown
+        try {
+            process.stderr.write(`Recorded in ${setPublishedUrl(dir, name, b)}\n`);
+        }
+        catch (e) {
+            if (e instanceof AssetError)
+                throw e.status === 400 ? new UsageError(e.message) : new Error(e.message);
+            throw e;
+        }
+        return;
+    }
+    throw new UsageError(sub ? `unknown asset command '${sub}' (add or url)` : 'asset needs a command: add or url');
+}
+async function serve(flags) {
+    const given = flags.port ?? process.env.PORT;
+    // `npm run dev`: the API sits next to Vite's UI port (see vite.config.ts)
+    const port = given === undefined || given === '' ? DEFAULT_PORT + (process.env.LOCAL_REVIEW_DEV ? 1 : 0) : parsePort(given);
+    if (port === null)
+        throw new UsageError(`${flags.port !== undefined ? '--port' : 'PORT'} must be a port number (0-65535), not '${given}'`);
+    const { startServer } = await import('./index.js');
+    try {
+        await startServer(port);
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 'EADDRINUSE')
+            throw new Error(`port ${port} is already in use; pick another with --port <n>`);
+        if (code === 'EACCES')
+            throw new Error(`not allowed to listen on port ${port}; pick another with --port <n>`);
+        throw e;
+    }
+}
+/** Resolves with the exit code, or undefined while the server runs. */
+async function main(argv) {
+    const { pos, flags } = parseArgs(argv);
+    if (flags.help) {
+        process.stdout.write(USAGE + '\n');
+        return 0;
+    }
+    if (flags.version) {
+        process.stdout.write(JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version + '\n');
+        return 0;
+    }
+    const [cmd = 'serve', ...args] = pos;
+    switch (cmd) {
+        case 'serve':
+            check(cmd, flags, ['port'], args, 0);
+            await serve(flags);
+            return undefined;
+        case 'plan':
+            check(cmd, flags, ['repo', 'stack', 'format', 'include-follow-on'], args, 1);
+            await plan(args[0], flags);
+            return 0;
+        case 'init':
+            check(cmd, flags, [], args, 1);
+            init(args[0]);
+            return 0;
+        case 'asset':
+            check(cmd, flags, ['alt'], args, 4);
+            asset(args, flags);
+            return 0;
+        case 'guide':
+            check(cmd, flags, [], args, 0);
+            process.stdout.write(fs.readFileSync(AGENT_GUIDE, 'utf8'));
+            return 0;
+        default:
+            throw new UsageError(`unknown command '${cmd}'`);
+    }
+}
+// exitCode, not exit(): exiting could cut off output still being written to a pipe
+main(process.argv.slice(2)).then((code) => {
+    if (code !== undefined)
+        process.exitCode = code;
+}, (e) => {
+    process.stderr.write(`local-review: ${e.message}\n`);
+    if (e instanceof UsageError)
+        process.stderr.write(`\n${USAGE}\n`);
+    process.exitCode = e instanceof UsageError ? 2 : 1;
+});