local-review 0.0.1 → 0.2.0

package/README.md

@@ -1,3 +1,127 @@
-# local-review
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/edspencer/local-review/main/brand/lockup-dark.svg">
+    <img alt="Local Review" src="https://raw.githubusercontent.com/edspencer/local-review/main/brand/lockup-light.svg" width="380">
+  </picture>
+</p>
 
-Placeholder. See https://github.com/edspencer/local-review
+<p align="center"><strong>Review your PR stacks before you create them.</strong></p>
+
+<p align="center">
+  <a href="https://github.com/edspencer/local-review/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/edspencer/local-review/actions/workflows/ci.yml/badge.svg?branch=main"></a>
+  <a href="https://www.npmjs.com/package/local-review"><img alt="npm" src="https://img.shields.io/npm/v/local-review?color=4a1942"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
+  <a href="https://local-review.edspencer.net"><img alt="Docs" src="https://img.shields.io/badge/docs-local--review.edspencer.net-4a1942"></a>
+  <img alt="Node.js 22 or later" src="https://img.shields.io/badge/node-%E2%89%A522-339933">
+</p>
+
+<p align="center">
+  <img alt="Local Review showing a PR: the plum &quot;not on GitHub&quot; header, a sidebar of colour-coded PR stacks with readiness badges, and the PR's title, readiness toggle and Conversation tab" src="https://raw.githubusercontent.com/edspencer/local-review/main/docs/media/readme-hero.png" width="800">
+</p>
+
+Local Review is a GitHub-style pull-request UI for the **stack of commits on your machine**, before any of it is
+pushed. Every commit is shown as its own PR, grouped into the stacks you mean to open. You review them like PRs, your
+coding agent reads your comments and replies in the same place, and when a stack is right, the agent publishes it as
+GitHub stacked PRs.
+
+- **Every commit is a PR**, with a Conversation tab, a Files changed tab and a readiness badge, grouped into
+  colour-coded [PR stacks](https://local-review.edspencer.net/concepts/pr-stacks/), across one repo or several.
+- **Your agent answers in the review.** Comments are plain YAML files that any coding agent can read and reply to; the
+  replies show up in your browser live, and threads follow their code through amends and rebases.
+- **Publish when it's ready.** `local-review plan` prints each PR's branch, base, title and body, and your agent opens
+  the stack as [GitHub native stacked PRs](https://local-review.edspencer.net/agents/publishing-stacked-prs/). It
+  works in front of any [stacking tool](https://local-review.edspencer.net/concepts/stacking-tools/).
+- **Safe to point at your work.** It never modifies your repos, never talks to GitHub, never deletes your review, and
+  only listens on localhost.
+
+<p align="center">
+  <img alt="A review round trip: the reviewer comments on a range of lines, the agent's reply appears in the thread live, the reviewer resolves the thread and marks the PR ready, and the sidebar's stack tally goes from 1/3 to 2/3 ready" src="https://raw.githubusercontent.com/edspencer/local-review/main/docs/media/demo.gif" width="800">
+  <br><sub>One review round trip, on the fictional demo project the docs use.</sub>
+</p>
+
+## Quickstart
+
+Needs Node.js 22 or later and git, on macOS or Linux.
+
+```sh
+npx local-review init my-feature   # create ~/.local-review/projects/my-feature/project.yaml
+npx local-review                   # serve the UI on http://localhost:5622
+```
+
+Edit `project.yaml` to point at your repo, branch and stacks:
+
+```yaml
+title: My feature
+repos:
+  - path: ~/code/my-service
+    branch: me/my-feature        # the range ends at this branch's head
+    base: origin/main            # and starts at its merge-base with this
+    stacks:
+      - title: Groundwork
+      - title: The feature itself
+        starts_at: "Add the feature flag"   # the subject of the commit the stack starts at
+```
+
+Then open **http://localhost:5622**. Edits are picked up live. The full walk-through is the
+[Quickstart](https://local-review.edspencer.net/getting-started/quickstart/).
+
+> **Upgrading from before 0.2.0?** The default port was 5000; it's now 5622 (macOS uses 5000 for AirPlay). Update
+> bookmarks and agent prompts, or run `npx local-review --port 5000`.
+
+## For agents
+
+```sh
+npx local-review guide
+```
+
+prints the guide for coding agents driving Local Review from the repo they work on: the data model, how to answer
+review threads, fix a commit mid-stack, tag branches, publish stacked PRs and record merges. It's
+[AGENT-GUIDE.md](AGENT-GUIDE.md) in this repo, and [on the docs site](https://local-review.edspencer.net/agents/agent-guide/).
+To hand a reviewed project to your agent, paste the
+[hand-off prompt](https://local-review.edspencer.net/agents/hand-off-prompt/).
+
+## Documentation
+
+**https://local-review.edspencer.net**
+
+- **Getting started:** [Quickstart](https://local-review.edspencer.net/getting-started/quickstart/) ·
+  [Installation](https://local-review.edspencer.net/getting-started/installation/)
+- **Concepts:** [Projects & repos](https://local-review.edspencer.net/concepts/projects-and-repos/) ·
+  [PR stacks](https://local-review.edspencer.net/concepts/pr-stacks/) ·
+  [Readiness](https://local-review.edspencer.net/concepts/readiness/) ·
+  [Landed PRs](https://local-review.edspencer.net/concepts/landed-prs/) ·
+  [Following rebases](https://local-review.edspencer.net/concepts/following-rebases/)
+- **Using it:** [A tour of the UI](https://local-review.edspencer.net/using/ui-tour/) ·
+  [Reviewing & comments](https://local-review.edspencer.net/using/reviewing-and-comments/) ·
+  [Stack pictures](https://local-review.edspencer.net/using/stack-pictures/)
+- **Reference:** [CLI](https://local-review.edspencer.net/reference/cli/) ·
+  [project.yaml](https://local-review.edspencer.net/reference/project-yaml/) ·
+  [Comment files](https://local-review.edspencer.net/reference/comment-files/) ·
+  [HTTP API](https://local-review.edspencer.net/reference/http-api/) ·
+  [Where your data lives](https://local-review.edspencer.net/reference/data-directory/)
+
+## Guarantees
+
+- **Read-only:** it never fetches, checks out, commits or rebases; all git access goes through one read-only
+  allow-list. [Read-only guarantee](https://local-review.edspencer.net/guarantees/read-only/)
+- **Never deletes:** your review lives in `~/.local-review`, never in your repos; writes are atomic, nothing is
+  unlinked, and it's snapshotted hourly. [Never-delete guarantee](https://local-review.edspencer.net/guarantees/never-delete/)
+- **Localhost only:** it binds 127.0.0.1 and rejects non-localhost `Host` and `Origin` headers.
+  [Localhost security](https://local-review.edspencer.net/guarantees/localhost-security/)
+
+And so you can't mistake it for github.com, its header is deep plum with an amber underline and a "not on GitHub" pill.
+
+## Contributing
+
+Contributions are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md), and [AGENTS.md](AGENTS.md) for coding agents
+working on this repo. Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
+How AI was used to build it: [AI-DECLARATION.md](AI-DECLARATION.md).
+Releases: [RELEASING.md](RELEASING.md).
+
+## License
+
+MIT, see [LICENSE](LICENSE).
+
+The fonts bundled in `server/fonts/` for the stack picture are [Inter](https://github.com/rsms/inter) and
+[JetBrains Mono](https://github.com/JetBrains/JetBrainsMono), both under the SIL Open Font License 1.1
+(`server/fonts/*-OFL.txt`). npm dependencies keep their own licenses.

package/dist/server/anchors.js

@@ -0,0 +1,207 @@
+// Line anchors: how an inline thread follows its code across amends and rebases.
+//
+// When a thread is created the server stores an `anchor`: the commit it was made on, its location there, the
+// exact text of the commented line(s) and up to CONTEXT_LINES lines of context on each side. To place the
+// thread on another commit (or after its code changed) we look for that text on the same side of the same
+// file (following renames), score each match by how much surrounding context still fits, and break ties by
+// distance from the last known line. No match => the thread is "outdated". Pure functions, no I/O.
+// The rules are documented on the docs site: website/src/content/docs/concepts/following-rebases.md ("Line anchoring").
+export const CONTEXT_LINES = 3;
+/** True for a range whose start is on the other side from its end (start_side set and != side). */
+export const isMixed = (l) => !!l.start_line && !!l.start_side && l.start_side !== (l.side ?? 'right');
+/** Split file content into lines (1-based line n = result[n-1]); CRs and the final newline are dropped. */
+export function splitLines(content) {
+    const ls = content.split('\n').map((l) => (l.endsWith('\r') ? l.slice(0, -1) : l));
+    if (ls.length && ls[ls.length - 1] === '')
+        ls.pop();
+    return ls;
+}
+const toLines = (s) => (s === undefined ? [] : s.split('\n'));
+const loose = (s) => s.replace(/\s+/g, ' ').trim();
+export function sideContent(f, side) {
+    return side === 'left' ? f.oldContent : f.newContent;
+}
+/** Find the file for `path` in a commit's diff: by new path, then by pre-rename path (it was renamed here). */
+export function findFile(files, ...paths) {
+    for (const p of paths) {
+        if (!p)
+            continue;
+        const f = files.find((x) => x.path === p) ?? files.find((x) => x.oldPath === p);
+        if (f)
+            return f;
+    }
+    return undefined;
+}
+export function makeAnchor(files, commit, loc) {
+    const f = findFile(files, loc.path);
+    if (!f)
+        return null;
+    const content = sideContent(f, loc.side);
+    if (content == null)
+        return null;
+    const lines = splitLines(content);
+    if (isMixed(loc)) {
+        // anchor the end line as a single line, and remember the start line's text on its own side
+        const sc = sideContent(f, loc.start_side);
+        const sl = sc == null ? [] : splitLines(sc);
+        if (loc.line < 1 || loc.line > lines.length || loc.start_line < 1 || loc.start_line > sl.length)
+            return null;
+        const a = makeAnchor(files, commit, { path: loc.path, side: loc.side, line: loc.line });
+        if (!a)
+            return null;
+        return { ...a, start_side: loc.start_side, start_line: loc.start_line, start_text: sl[loc.start_line - 1] };
+    }
+    const start = loc.start_line ?? loc.line;
+    if (start < 1 || loc.line > lines.length || start > loc.line)
+        return null;
+    const a = { commit, path: f.path, side: loc.side, line: loc.line, text: lines.slice(start - 1, loc.line).join('\n') };
+    if (f.oldPath && f.oldPath !== f.path)
+        a.old_path = f.oldPath;
+    if (loc.start_line)
+        a.start_line = loc.start_line;
+    const before = lines.slice(Math.max(0, start - 1 - CONTEXT_LINES), start - 1);
+    const after = lines.slice(loc.line, loc.line + CONTEXT_LINES);
+    if (before.length)
+        a.before = before.join('\n');
+    if (after.length)
+        a.after = after.join('\n');
+    return a;
+}
+/**
+ * Find where `anchor`'s text is in `lines`. Exact matches are preferred; if there are none, matches that
+ * differ only in whitespace are used. Among matches: most context lines that still fit, then nearest to
+ * `hint` (1-based start line), then earliest. Returns the 1-based start line, or null.
+ */
+export function findAnchorText(lines, anchor, hint) {
+    return searchAnchor(lines, anchor, hint)?.line ?? null;
+}
+function searchAnchor(lines, anchor, hint) {
+    const text = toLines(anchor.text);
+    const before = toLines(anchor.before);
+    const after = toLines(anchor.after);
+    const k = text.length;
+    const matchesAt = (i, eq) => {
+        for (let j = 0; j < k; j++)
+            if (!eq(lines[i + j], text[j]))
+                return false;
+        return true;
+    };
+    const collect = (eq) => {
+        const out = [];
+        for (let i = 0; i + k <= lines.length; i++)
+            if (matchesAt(i, eq))
+                out.push(i);
+        return out;
+    };
+    let cands = collect((a, b) => a === b);
+    const exact = cands.length > 0;
+    if (!exact)
+        cands = collect((a, b) => loose(a) === loose(b));
+    if (!cands.length)
+        return null;
+    const score = (i) => {
+        let s = 0;
+        for (let j = 0; j < before.length; j++) {
+            const l = lines[i - before.length + j];
+            if (l !== undefined && loose(l) === loose(before[j]))
+                s++;
+        }
+        for (let j = 0; j < after.length; j++) {
+            const l = lines[i + k + j];
+            if (l !== undefined && loose(l) === loose(after[j]))
+                s++;
+        }
+        return s;
+    };
+    const blank = text.every((t) => !t.trim());
+    let best = null;
+    for (const i of cands) {
+        const s = score(i);
+        if (blank && s === 0)
+            continue; // a blank line matches everywhere; demand some context
+        const d = Math.abs(i + 1 - hint);
+        if (!best || s > best.s || (s === best.s && d < best.d))
+            best = { i, s, d };
+    }
+    return best ? { line: best.i + 1, score: best.s, exact } : null;
+}
+/**
+ * Where a thread goes on commit `sha` whose diff is `files`.
+ *  - Anchored on `sha` itself, or not anchored at all: its stored path/side/line, as is.
+ *  - Anchored on another commit: relocated by its anchor text (following renames).
+ *  - Outdated when its file isn't in the diff, the side has no content, or the text can't be found.
+ */
+export function placeThread(t, files, sha) {
+    if (!t.path || !t.line)
+        return { outdated: false };
+    const a = t.anchor;
+    const side = t.side ?? a?.side ?? 'right';
+    if (!a || a.commit === sha) {
+        const f = findFile(files, t.path);
+        const content = f && sideContent(f, side);
+        if (content == null || t.line > splitLines(content).length)
+            return { outdated: true };
+        const loc = { outdated: false, path: f.path, side, line: t.line };
+        if (t.start_line)
+            loc.start_line = t.start_line;
+        if (isMixed({ side, start_line: t.start_line, start_side: t.start_side })) {
+            const sc = sideContent(f, t.start_side);
+            // the start line must exist on its side; if not, keep the end line only
+            if (sc != null && t.start_line <= splitLines(sc).length)
+                loc.start_side = t.start_side;
+            else
+                delete loc.start_line;
+        }
+        return loc;
+    }
+    // hint = expected first line of anchor.text (just the end line for a mixed-side range)
+    const hint = isMixed(a) ? t.line : (t.start_line ?? t.line ?? a.start_line ?? a.line);
+    let f = findFile(files, t.path, a.path, a.old_path);
+    let hit = null;
+    if (f) {
+        const content = sideContent(f, a.side);
+        if (content != null)
+            hit = searchAnchor(splitLines(content), a, hint);
+    }
+    else {
+        // The file isn't in this diff under any known name. If it was added by this commit and then renamed by
+        // a fixup, git sees a plain add under the new name, so look in the other files, but only accept an
+        // exact match whose context mostly fits (strong evidence it's the same code).
+        const ctxLines = toLines(a.before).length + toLines(a.after).length;
+        const need = Math.min(ctxLines, 3);
+        if (a.text.trim() && need > 0) {
+            for (const g of files) {
+                const content = sideContent(g, a.side);
+                if (content == null)
+                    continue;
+                const h = searchAnchor(splitLines(content), a, hint);
+                if (h && h.exact && h.score >= need && (!hit || h.score > hit.score)) {
+                    hit = h;
+                    f = g;
+                }
+            }
+        }
+    }
+    if (!f || !hit)
+        return { outdated: true };
+    if (isMixed(a)) {
+        // end line found; look for the start line's text on its own side, near where the shift puts it
+        const loc = { outdated: false, path: f.path, side: a.side, line: hit.line };
+        const sc = sideContent(f, a.start_side);
+        if (sc != null && a.start_text !== undefined) {
+            const startHint = a.start_line + (hit.line - a.line);
+            const s = searchAnchor(splitLines(sc), { text: a.start_text }, startHint);
+            if (s && s.exact) {
+                loc.start_line = s.line;
+                loc.start_side = a.start_side;
+            }
+        }
+        return loc; // start not found: degrade to a single-line thread on the end line
+    }
+    const start = hit.line;
+    const span = a.start_line ? a.line - a.start_line : 0;
+    const loc = { outdated: false, path: f.path, side: a.side, line: start + span };
+    if (span > 0)
+        loc.start_line = start;
+    return loc;
+}

package/dist/server/assets.js

@@ -0,0 +1,147 @@
+// A project's images: projects/<slug>/assets/<sha256 prefix>.<ext>, added by `local-review asset add` or an upload
+// in the UI, and referred to from markdown as `assets/<name>` (shared/assets.ts). Files are named by their content,
+// so adding the same bytes twice is a no-op, and an asset file is never replaced or removed: it's written once,
+// create-only, through safefs. Beside one may sit `<name>.yaml` with a `url:` where the image is published, which
+// `plan` uses in place of the local reference (GitHub can't show a file on this machine).
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+import { ASSET_HASH_LENGTH, ASSET_NAME, MAX_ASSET_BYTES, assetMarkdown, assetRefs, rewriteAssetRefs } from '../shared/assets.js';
+import { ExistsError, atomicWrite } from './safefs.js';
+export class AssetError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+export const assetsDir = (projectDir) => path.join(projectDir, 'assets');
+const startsWith = (b, bytes, at = 0) => b.length >= at + bytes.length && bytes.every((x, i) => b[at + i] === x);
+const ascii = (s) => [...s].map((c) => c.charCodeAt(0));
+/** Whether `b` is an SVG document: UTF-8 text whose root element (after any prolog) is `<svg`. */
+function isSvg(b) {
+    let s;
+    try {
+        s = new TextDecoder('utf-8', { fatal: true }).decode(b);
+    }
+    catch {
+        return false;
+    }
+    if (s.includes('\0'))
+        return false;
+    s = s.replace(/^/, '');
+    // the prolog: an XML declaration, comments, processing instructions and a DOCTYPE without an internal subset
+    // (entity declarations have no business in an image)
+    const prolog = /^\s*(?:<\?xml\b[^>]*\?>|<!--[\s\S]*?-->|<\?[\s\S]*?\?>|<!DOCTYPE\s+svg\b[^[>]*>)/i;
+    for (let m = prolog.exec(s); m; m = prolog.exec(s))
+        s = s.slice(m[0].length);
+    return /^\s*<svg[\s>/]/.test(s) && /<\/svg\s*>\s*(?:<!--[\s\S]*?-->\s*)*$|^\s*<svg\b[^>]*\/>\s*$/.test(s);
+}
+/** The image type `bytes` actually are, by their magic numbers (SVG: by parsing the start), or null. */
+export function sniff(bytes) {
+    if (startsWith(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))
+        return 'png';
+    if (startsWith(bytes, [0xff, 0xd8, 0xff]))
+        return 'jpg';
+    if (startsWith(bytes, ascii('GIF87a')) || startsWith(bytes, ascii('GIF89a')))
+        return 'gif';
+    if (startsWith(bytes, ascii('RIFF')) && startsWith(bytes, ascii('WEBP'), 8))
+        return 'webp';
+    return isSvg(bytes) ? 'svg' : null;
+}
+/**
+ * Add an image to the project's assets folder, named by its content. `claimed` is the type the caller says it is
+ * (from a Content-Type or a file extension); the bytes must really be that type. Re-adding the same bytes is a
+ * no-op. Never replaces a file.
+ */
+export function addAsset(projectDir, bytes, claimed, alt) {
+    if (!claimed)
+        throw new AssetError(415, 'not an image type Local Review takes: PNG, JPEG, GIF, WebP or SVG');
+    if (bytes.length === 0)
+        throw new AssetError(400, 'the image is empty');
+    if (bytes.length > MAX_ASSET_BYTES)
+        throw new AssetError(413, `the image is ${mb(bytes.length)}; the limit is ${mb(MAX_ASSET_BYTES)}`);
+    const actual = sniff(bytes);
+    if (!actual)
+        throw new AssetError(415, `the file isn't a ${claimed.toUpperCase()} image (its contents don't match any image type Local Review takes)`);
+    if (actual !== claimed)
+        throw new AssetError(415, `the file says it's ${claimed.toUpperCase()} but its contents are ${actual.toUpperCase()}`);
+    const name = `${crypto.createHash('sha256').update(bytes).digest('hex').slice(0, ASSET_HASH_LENGTH)}.${actual}`;
+    const file = path.join(assetsDir(projectDir), name);
+    let created = true;
+    try {
+        atomicWrite(file, bytes, { createOnly: true });
+    }
+    catch (e) {
+        if (!(e instanceof ExistsError))
+            throw e;
+        // the same name: the same image, unless the file was changed by hand (then it's left alone, and we say so)
+        if (!Buffer.from(bytes).equals(fs.readFileSync(file)))
+            throw new AssetError(409, `${file} already exists with different contents; not replacing it`);
+        created = false;
+    }
+    return { name, file, markdown: assetMarkdown(name, alt), created };
+}
+const mb = (n) => `${(n / 1024 / 1024).toFixed(1).replace(/\.0$/, '')} MB`;
+/** An asset's file, if `name` is a valid asset name and it's a regular file (not a symlink) in the folder. */
+export function assetFile(projectDir, name) {
+    if (!ASSET_NAME.test(name))
+        return null;
+    const file = path.join(assetsDir(projectDir), name);
+    try {
+        const st = fs.lstatSync(file);
+        return st.isFile() ? file : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** `<name>.yaml` beside an asset: where it's published. Only `url:` is read; anything else in it is kept. */
+export const assetRecordPath = (projectDir, name) => path.join(assetsDir(projectDir), `${name}.yaml`);
+/** The published URL recorded for an asset, or null (no record, no url:, or a record that doesn't parse). */
+export function publishedUrl(projectDir, name) {
+    let doc;
+    try {
+        doc = YAML.parse(fs.readFileSync(assetRecordPath(projectDir, name), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    const url = doc && typeof doc === 'object' ? doc.url : null;
+    return typeof url === 'string' && isHttpUrl(url) ? url : null;
+}
+export const isHttpUrl = (u) => /^https?:\/\/[^\s]+$/.test(u) && u.length <= 2000;
+/**
+ * Record (or change) where an asset is published, in `<name>.yaml`, keeping anything else a person or agent wrote
+ * there. The asset must exist. A record that doesn't parse is never overwritten.
+ */
+export function setPublishedUrl(projectDir, name, url) {
+    if (!ASSET_NAME.test(name))
+        throw new AssetError(400, `bad asset name '${name}' (expected <16 hex digits>.<png|jpg|gif|webp|svg>)`);
+    if (!assetFile(projectDir, name))
+        throw new AssetError(404, `no asset ${name} in ${assetsDir(projectDir)}`);
+    if (!isHttpUrl(url))
+        throw new AssetError(400, `not an http(s) URL: ${url}`);
+    const file = assetRecordPath(projectDir, name);
+    let doc = new YAML.Document({});
+    if (fs.existsSync(file)) {
+        doc = YAML.parseDocument(fs.readFileSync(file, 'utf8'));
+        if (doc.errors.length || (doc.contents !== null && !YAML.isMap(doc.contents)))
+            throw new AssetError(409, `${file} doesn't parse as a YAML mapping; not overwriting it`);
+        if (doc.contents === null)
+            doc = new YAML.Document({});
+    }
+    doc.set('url', url);
+    atomicWrite(file, doc.toString({ lineWidth: 0 }));
+    return file;
+}
+/**
+ * For `plan`: the assets a body refers to, and the body with each reference that has a published URL rewritten
+ * to it. References without one are left as `assets/<name>` (the plan warns about them).
+ */
+export function resolveAssetRefs(projectDir, body) {
+    const assets = assetRefs(body).map((name) => ({ name, file: assetFile(projectDir, name), url: publishedUrl(projectDir, name) }));
+    const urls = new Map(assets.map((a) => [a.name, a.url]));
+    return { body: rewriteAssetRefs(body, (n) => urls.get(n) ?? null), assets };
+}