local-review 0.0.1 → 0.3.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/demo/lib/gitworld.js

@@ -0,0 +1,224 @@
+// A tiny deterministic git history builder for the demo test bed. Commits are built in memory (each one a full
+// snapshot of the tree) and written with one `git fast-import` per repo, with fixed authors and dates and git's
+// config isolated from the machine's, so every run on every machine produces the same shas.
+import { execFile, execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+/** The environment every git command here runs with: nothing from the machine's git config, no signing, no hooks. */
+export function gitEnv() {
+    const env = {};
+    for (const [k, v] of Object.entries(process.env))
+        if (!k.startsWith('GIT_'))
+            env[k] = v;
+    return { ...env, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0', LC_ALL: 'C', TZ: 'UTC' };
+}
+export function git(cwd, args, input) {
+    return execFileSync('git', args, { cwd, env: gitEnv(), input, encoding: 'utf8', maxBuffer: 64 << 20, stdio: ['pipe', 'pipe', 'pipe'] });
+}
+/** `git` without blocking: the app builds the example projects with this while it keeps serving. */
+export function gitAsync(cwd, args, input) {
+    return new Promise((resolve, reject) => {
+        const child = execFile('git', args, { cwd, env: gitEnv(), encoding: 'utf8', maxBuffer: 64 << 20 }, (err, stdout, stderr) => err ? reject(new Error(`git ${args[0]} failed in ${cwd}: ${stderr || err.message}`)) : resolve(stdout));
+        // commands that don't read stdin may exit before it's written (EPIPE): their exit status is what counts
+        child.stdin?.on('error', () => { });
+        child.stdin?.end(input ?? '');
+    });
+}
+/** Replace exactly one occurrence of `from` (fails loudly if it isn't there, so content edits can't silently drift). */
+export const replace = (from, to) => (old) => {
+    const i = old.indexOf(from);
+    if (i < 0)
+        throw new Error(`replace: text not found:\n${from}`);
+    if (old.indexOf(from, i + 1) >= 0)
+        throw new Error(`replace: text found more than once:\n${from}`);
+    return old.slice(0, i) + to + old.slice(i + from.length);
+};
+/** Several `replace`s in order. */
+export const edits = (...pairs) => (old) => pairs.reduce((s, [a, b]) => replace(a, b)(s), old);
+/** Insert `text` right after the (unique) `anchor`. */
+export const after = (anchor, text) => replace(anchor, anchor + text);
+/** Strip the common indentation of a template literal and its leading newline, keep one trailing newline. */
+export function code(strings, ...vals) {
+    let s = strings.reduce((a, str, i) => a + str + (i < vals.length ? String(vals[i]) : ''), '');
+    s = s.replace(/^\n/, '').replace(/[ \t]+$/, '');
+    const lines = s.split('\n');
+    const indent = Math.min(...lines.filter((l) => l.trim()).map((l) => /^ */.exec(l)[0].length));
+    return lines.map((l) => l.slice(indent)).join('\n').replace(/\n*$/, '\n');
+}
+/** Go files and Makefiles are indented with tabs on disk; the content scripts write them with 4 spaces. */
+export function onDisk(file, content) {
+    if (!/\.go$|(^|\/)Makefile$/.test(file))
+        return content;
+    return content.replace(/^((?: {4})+)/gm, (m) => '\t'.repeat(m.length / 4));
+}
+const unix = (iso) => Math.floor(new Date(iso).getTime() / 1000);
+export class RepoBuilder {
+    name;
+    remoteUrl;
+    nextMark = 1;
+    commits = [];
+    byKey = new Map();
+    refs = new Map();
+    constructor(name, remoteUrl) {
+        this.name = name;
+        this.remoteUrl = remoteUrl;
+    }
+    /** A commit on `parent` (null: a root commit). `key` defaults to the subject. */
+    commit(parent, message, changes, o) {
+        const files = new Map(parent?.files ?? []);
+        if (o.merge)
+            for (const [p, c] of o.merge.files)
+                if (!files.has(p))
+                    files.set(p, c);
+        for (const [p, ch] of Object.entries(changes)) {
+            if (ch === null) {
+                if (!files.delete(p))
+                    throw new Error(`${this.name}: delete of missing file ${p}`);
+            }
+            else if (typeof ch === 'function') {
+                const old = files.get(p);
+                if (old === undefined)
+                    throw new Error(`${this.name}: edit of missing file ${p} in "${message.split('\n')[0]}"`);
+                files.set(p, ch(old));
+            }
+            else
+                files.set(p, ch);
+        }
+        const subject = message.split('\n')[0];
+        const key = o.key ?? subject;
+        if (this.byKey.has(key))
+            throw new Error(`${this.name}: duplicate commit key ${key}`);
+        const c = {
+            mark: this.nextMark++,
+            key,
+            message: message.replace(/\n*$/, '\n'),
+            subject,
+            author: o.author,
+            authorAt: o.at,
+            committer: o.committer ?? o.author,
+            committedAt: o.committedAt ?? o.at,
+            parent,
+            merge: o.merge ?? null,
+            changes,
+            files,
+        };
+        this.commits.push(c);
+        this.byKey.set(key, c);
+        return c;
+    }
+    /**
+     * Replay commits onto `onto`, as `git rebase` would: same message, author and author date, a new committer
+     * date. Each copy takes over its original's key; the original stays reachable as `<key>@<tag>`.
+     */
+    replay(list, onto, o) {
+        let base = onto;
+        return list.map((c) => {
+            const key = c.key;
+            this.rekey(c, `${key}@${o.tag}`);
+            // `override`: the copy's changes, when the rebase had to adapt the commit (a fixup squashed into it)
+            base = this.commit(base, c.message, o.override?.[key] ?? c.changes, { author: c.author, at: c.authorAt, committer: o.committer ?? c.committer, committedAt: o.at, key });
+            return base;
+        });
+    }
+    rekey(c, key) {
+        if (this.byKey.has(key))
+            throw new Error(`${this.name}: duplicate commit key ${key}`);
+        this.byKey.delete(c.key);
+        c.key = key;
+        this.byKey.set(key, c);
+    }
+    get(key) {
+        const c = this.byKey.get(key);
+        if (!c)
+            throw new Error(`${this.name}: no commit ${key}`);
+        return c;
+    }
+    sha(key) {
+        const s = this.get(key).sha;
+        if (!s)
+            throw new Error(`${this.name}: not built yet`);
+        return s;
+    }
+    /** A file at a commit, as it is on disk. */
+    file(key, file) {
+        const s = this.get(key).files.get(file);
+        if (s === undefined)
+            throw new Error(`${this.name}: no ${file} at ${key}`);
+        return onDisk(file, s);
+    }
+    ref(name, c) {
+        this.refs.set(name.startsWith('refs/') ? name : `refs/heads/${name}`, c);
+    }
+    /** `git init`, one fast-import, then check out `checkout` (the work tree a developer would have). */
+    build(dir, checkout) {
+        const { steps, marks } = this.plan(dir, checkout);
+        for (const [args, input] of steps)
+            git(dir, args, input);
+        this.readMarks(marks);
+    }
+    /** The same as `build`, without blocking the event loop. */
+    async buildAsync(dir, checkout) {
+        const { steps, marks } = this.plan(dir, checkout);
+        for (const [args, input] of steps)
+            await gitAsync(dir, args, input);
+        this.readMarks(marks);
+    }
+    /** Create `dir` (it mustn't exist: never builds over anything) and list the git commands that fill it. */
+    plan(dir, checkout) {
+        if (fs.existsSync(dir))
+            throw new Error(`${dir} already exists`);
+        fs.mkdirSync(dir, { recursive: true });
+        const chunks = [];
+        const w = (s) => chunks.push(Buffer.from(s, 'utf8'));
+        const data = (s) => {
+            w(`data ${Buffer.byteLength(s, 'utf8')}\n`);
+            w(s);
+            w('\n');
+        };
+        for (const c of this.commits) {
+            // every commit goes through one scratch ref, reset first so its parent is exactly what it says (none for a root)
+            w(`reset refs/lr-demo/build\ncommit refs/lr-demo/build\nmark :${c.mark}\n`);
+            w(`author ${c.author.name} <${c.author.email}> ${unix(c.authorAt)} +0000\n`);
+            w(`committer ${c.committer.name} <${c.committer.email}> ${unix(c.committedAt)} +0000\n`);
+            data(c.message);
+            if (c.parent)
+                w(`from :${c.parent.mark}\n`);
+            if (c.merge)
+                w(`merge :${c.merge.mark}\n`);
+            w('deleteall\n');
+            for (const p of [...c.files.keys()].sort()) {
+                w(`M 100644 inline ${p}\n`);
+                data(onDisk(p, c.files.get(p)));
+            }
+            w('\n');
+        }
+        for (const [name, c] of [...this.refs].sort(([a], [b]) => a.localeCompare(b)))
+            w(`reset ${name}\nfrom :${c.mark}\n\n`);
+        const marks = path.join(dir, '.git', 'lr-demo-marks');
+        return {
+            marks,
+            steps: [
+                [['init', '-q', '-b', 'main']],
+                [['config', 'core.hooksPath', '/dev/null']],
+                [['config', 'commit.gpgSign', 'false']],
+                [['config', 'gc.auto', '0']], // keep rewritten-away commits (anchors and moved branches point at them)
+                [['config', 'rebase.updateRefs', 'true']], // AGENTS.md "Branch tagging"
+                [['remote', 'add', 'origin', this.remoteUrl]],
+                [['fast-import', '--quiet', '--date-format=raw', `--export-marks=${marks}`], Buffer.concat(chunks).toString('utf8')],
+                [['update-ref', '-d', 'refs/lr-demo/build']],
+                [['checkout', '-q', '-f', checkout]],
+            ],
+        };
+    }
+    /** Every commit's sha, from fast-import's marks. The file stays in .git: nothing reads it, and this code never
+     * deletes a file (the app runs it to create the example projects, so test/fsguard.test.ts scans it like the server). */
+    readMarks(marks) {
+        const markShas = new Map();
+        for (const line of fs.readFileSync(marks, 'utf8').split('\n').filter(Boolean)) {
+            const [m, sha] = line.split(' ');
+            markShas.set(Number(m.slice(1)), sha);
+        }
+        for (const c of this.commits)
+            c.sha = markShas.get(c.mark);
+    }
+}