bottleship 0.1.0-prototype.0 → 0.1.0-prototype.2

package/dist/src/review/loop.js

@@ -0,0 +1,119 @@
+// A local review and the developer's agent that asked for it: the agent waits for the reviewer's comments, changes
+// the checkout, then updates the review, which copies the new state into the box and has the box agent refresh the tour.
+import { BsError } from "../config.js";
+import { ask, putFiles, putTar, runIn, waitAgent } from "../boxes.js";
+import { dotenvFiles } from "../repo.js";
+import { shq } from "../util.js";
+import { localChanges } from "./local.js";
+import { REVIEW_PORT } from "./start.js";
+const api = `http://127.0.0.1:${REVIEW_PORT}/api`;
+// the review server in the box, which only listens there
+async function call(b, path, body, seconds = 30) {
+    const r = await b.provider.exec(b.box, `curl -s --max-time ${seconds} -w '\\n%{http_code}' -X POST -H 'content-type: application/json' --data-binary @- ${shq(api + path)}`, JSON.stringify(body));
+    const out = r.stdout.trimEnd();
+    const code = Number(out.slice(out.lastIndexOf("\n") + 1));
+    const text = out.slice(0, out.lastIndexOf("\n"));
+    // nothing answered: the server is restarting or gone, which a wait rides out
+    if (!code)
+        throw new BsError("review_server_down", `the review server in ${b.id} did not answer ${path}`, `bottleship agent exec ${b.id} -- tail ~/.bottleship/review-server.log`);
+    if (r.code !== 0 || code >= 400) {
+        let errors = text;
+        try {
+            errors = JSON.parse(text).errors.join(", ");
+        }
+        catch { }
+        throw new BsError("review_server", `the review server in ${b.id} answered ${code || "nothing"} to ${path}: ${errors || r.stderr.trim()}`, `bottleship agent exec ${b.id} -- tail ~/.bottleship/review-server.log`);
+    }
+    return (text ? JSON.parse(text) : {});
+}
+// what the reviewer sent, as soon as they send it; nothing after seconds
+// how long a wait keeps asking a review server that does not answer, e.g. while it restarts
+const DOWN_FOR = 60_000;
+const RETRY = 2_000;
+export async function waitForComments(b, seconds, retry = RETRY) {
+    const until = seconds === undefined ? Infinity : Date.now() + seconds * 1000;
+    let down;
+    for (;;) {
+        const ms = Math.max(0, Math.min(25_000, until - Date.now()));
+        let w;
+        try {
+            w = await call(b, "/wait", { ms }, 40);
+        }
+        catch (e) {
+            if (!(e instanceof BsError && e.code === "review_server_down"))
+                throw e;
+            down ??= Date.now();
+            if (Date.now() - down > DOWN_FOR)
+                throw e;
+            await new Promise((r) => setTimeout(r, retry));
+            continue;
+        }
+        down = undefined;
+        if (w.comments.length || w.done || Date.now() >= until)
+            return w;
+    }
+}
+async function readJson(b, path) {
+    const r = await runIn(b, `cat "$HOME"/${shq(path)}`);
+    try {
+        return JSON.parse(r.stdout);
+    }
+    catch {
+        throw new BsError("not_a_review", `${b.id} has no review data at ~/${path}`, "pass the id bottleship agent review returned");
+    }
+}
+// the checkout as it is now becomes the box's head: a new commit on top of the last, with the box agent's review
+// hooks put back; then the tour notes the update, the comments get the agent's answers, and the box agent refreshes the tour
+export async function updateReview(b, root, o) {
+    const pr = await readJson(b, "review/app/src/data/pr.json");
+    if (pr.number)
+        throw new BsError("bad_request", `${b.id} is the review of PR #${pr.number}`, "update is for reviews of local changes; in a PR review the box agent pushes to the PR itself");
+    const box = await readJson(b, "review/app/src/data/box.json");
+    const dotenv = dotenvFiles(root);
+    const c = await localChanges(root, { base: box.base, exclude: Object.keys(dotenv) });
+    await runIn(b, 'rm -rf "$HOME/.bottleship/update-tree"');
+    await putTar(b, ".bottleship/update-tree", c.head);
+    const id = "-c user.name=bottleship -c user.email=review@bottleship.local";
+    const r = await runIn(b, `set -e
+U="$HOME/.bottleship/update-tree"; I="$HOME/.bottleship/update.index"
+cd "$HOME/workspace"
+hooks=none
+if [ -n "$(git status --porcelain)" ]; then git stash push -u -q -m "review hooks"; hooks=kept; fi
+rm -f "$I"
+GIT_INDEX_FILE="$I" GIT_WORK_TREE="$U" git add -A
+c=$(git ${id} commit-tree "$(GIT_INDEX_FILE="$I" git write-tree)" -p HEAD -m ${shq(`update: ${o.note}`)})
+git merge -q --ff-only "$c"
+if [ "$hooks" = kept ] && ! git stash pop -q >/dev/null 2>&1; then hooks=conflict; fi
+rm -rf "$U" "$I"
+echo "$hooks"`);
+    if (r.code !== 0)
+        throw new BsError("update_failed", `could not bring the changes into ${b.id}`, "see stderr", { stderr: r.stderr.slice(-2000) });
+    const hooks = r.stdout.trim().split("\n").pop();
+    await putFiles(b, {
+        "review/app/src/data/pr.diff": c.diff,
+        "review/app/src/data/pr.json": JSON.stringify({ ...pr, files: c.raw.files }, null, 2),
+    });
+    const u = await call(b, "/updates", { note: o.note, refreshed: false });
+    for (const [cid, body] of Object.entries(o.answers))
+        await call(b, `/comments/${cid}/answer`, { body });
+    // the box agent may still be refreshing the last update
+    await waitAgent(b, 900);
+    await ask(b, refreshPrompt(u.n, o.note, hooks));
+    return { update: u.n, hooks };
+}
+export function refreshPrompt(n, note, hooks) {
+    const kept = {
+        kept: "Your review hooks were stashed and put back.",
+        conflict: "Your review hooks were stashed but did not go back cleanly: resolve them (git status, git stash show -p), then git stash drop.",
+        none: "There were no review hooks to keep.",
+    }[hooks];
+    return `The developer's agent updated the changes after the reviewer's comments: ${note}
+bottleship committed the new state of their checkout on top of ~/workspace (git show --stat HEAD is what changed) and rewrote src/data/pr.diff and the files in pr.json. ~/base is unchanged. ${kept}
+Refresh the tour for this update; do not rebuild it:
+- restart head if the update needs it
+- fix the groups' line ranges and whatever in src/review.tsx the update makes wrong, and nothing else
+- rerun the steps the update affects and check they still show what their chapters say, then reset events
+- npm run check until it passes
+- then mark the update refreshed: curl -s -X POST -H 'content-type: application/json' -d '{}' ${api}/updates/${n}/refreshed
+End with one line on what you changed in the tour.`;
+}

package/dist/src/review/pr.d.ts

@@ -0,0 +1,14 @@
+import type { PrRepo } from "./target.ts";
+export interface PullRequest {
+    number: number;
+    title: string;
+    url: string;
+    body: string;
+    headRefOid: string;
+    baseRefName: string;
+    raw: Record<string, unknown>;
+    diff: string;
+    reviewComments: unknown[];
+}
+export declare function fetchPr(repo: PrRepo, number: number): Promise<PullRequest>;
+export declare function prEnvFiles(repo: PrRepo, ref: string): Promise<Record<string, string> | undefined>;

package/dist/src/review/pr.js

@@ -0,0 +1,68 @@
+// A pull request, read with the gh CLI on this machine when a review starts.
+import { BsError } from "../config.js";
+import { run } from "../util.js";
+import { reviewThreads } from "./github.js";
+const FIELDS = "number,title,url,body,author,state,headRefName,headRefOid,baseRefName,baseRefOid,comments,reviews,files,labels";
+async function gh(args, stdin) {
+    try {
+        return await run("gh", args, { check: false, stdin });
+    }
+    catch {
+        throw new BsError("gh_missing", "the gh CLI is not installed on this machine", "install it from https://cli.github.com, then run `gh auth login`");
+    }
+}
+// gh api calls for an Enterprise host name it
+const api = (repo, path, ...rest) => gh(["api", ...(repo.hostname ? ["--hostname", repo.hostname] : []), `${repo.api}/${path}`, ...rest]);
+export async function fetchPr(repo, number) {
+    const view = await gh(["pr", "view", String(number), "--repo", repo.label, "--json", FIELDS]);
+    if (view.code !== 0)
+        throw new BsError("pr_not_found", `gh could not read PR #${number} in ${repo.label}: ${view.stderr.trim().slice(0, 300)}`, `check the PR number and repo, and that \`gh auth status${repo.hostname ? ` --hostname ${repo.hostname}` : ""}\` is logged in to an account that can read it`);
+    const raw = JSON.parse(view.stdout);
+    const diff = await gh(["pr", "diff", String(number), "--repo", repo.label]);
+    const comments = await api(repo, `pulls/${number}/comments`, "--paginate");
+    let reviewComments = [];
+    try {
+        if (comments.code === 0)
+            reviewComments = JSON.parse(comments.stdout);
+    }
+    catch { }
+    // REST has no resolved state; GraphQL has it per thread, keyed here by the thread's first comment
+    // a review still reads without it
+    const resolved = new Set((await reviewThreads({ owner: repo.label.split("/")[0], name: repo.label.split("/")[1], hostname: repo.hostname }, number).catch(() => [])).filter((t) => t.resolved).map((t) => t.root));
+    for (const c of reviewComments)
+        if (resolved.has(c.id))
+            c.resolved = true;
+    return {
+        number: raw.number,
+        title: raw.title,
+        url: raw.url,
+        body: raw.body ?? "",
+        headRefOid: raw.headRefOid,
+        baseRefName: raw.baseRefName,
+        raw,
+        diff: diff.code === 0 ? diff.stdout : "",
+        reviewComments,
+    };
+}
+// the PR's own box environment, if it has one: every file in .bottleship/ at the PR's head commit
+export async function prEnvFiles(repo, ref) {
+    const list = await api(repo, `contents/.bottleship?ref=${ref}`);
+    if (list.code !== 0)
+        return undefined;
+    let entries;
+    try {
+        entries = JSON.parse(list.stdout);
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(entries))
+        return undefined;
+    const files = {};
+    for (const e of entries.filter((x) => x.type === "file")) {
+        const r = await api(repo, `contents/${e.path}?ref=${ref}`, "-H", "Accept: application/vnd.github.raw");
+        if (r.code === 0)
+            files[e.name] = r.stdout;
+    }
+    return files;
+}

package/dist/src/review/prompt.d.ts

@@ -0,0 +1,15 @@
+export interface ReviewPromptInput {
+    repo: string;
+    number?: number;
+    changes?: {
+        branch: string;
+        note?: string;
+    };
+    title: string;
+    base: string;
+    reviewUrl: string;
+    instancePorts: number[];
+    appPorts: number[];
+    envSource: "pr" | "local" | "none";
+}
+export declare function reviewPrompt(p: ReviewPromptInput): string;

package/dist/src/review/prompt.js

@@ -0,0 +1,48 @@
+// What the agent in a review box is asked to do: build a guided tour of one PR as a small React app, not review it.
+export function reviewPrompt(p) {
+    const local = p.changes;
+    const env = {
+        pr: "The PR's own .bottleship/ set up this box.",
+        local: local ? "The checkout's .bottleship/ set up this box; it is in ~/workspace/.bottleship and ~/base/.bottleship." : "The PR has no .bottleship/ yet, so this box uses the reviewer's local copy; it is in ~/workspace/.bottleship and ~/base/.bottleship, uncommitted.",
+        none: "Neither the PR nor the reviewer has a .bottleship/ for this repo, so nothing was set up for you: work out how to install and run the app yourself.",
+    }[p.envSource];
+    const subject = local ? `the local changes on ${local.branch} in ${p.repo}` : `PR #${p.number} in ${p.repo}, "${p.title}",`;
+    const where = local
+        ? `- ~/workspace: the changes as they are in the developer's checkout (commits, uncommitted and untracked files), as one commit on top of ~/base. ~/base: where ${local.branch} left ${p.base}. Each is its own git repo, so git diff in either shows only what you change there. Throughout, "the PR" means these changes: they have no PR, no comments and no reviews yet.${local.note ? `\n- The author's note: ${local.note}\n  It is the author's account of what they changed and why; check its claims like any other.` : ""}`
+        : `- ~/workspace: the PR's head, checked out. ~/base: the PR's base (${p.base}) where the PR branched off, a git worktree of the same clone. ${p.base} may have moved on since; compare head with ~/base, not with the tip of ${p.base}.`;
+    return `You are setting up the review of ${subject} for a human reviewer. You do not review it and you do not judge it. You build a guided tour of it: a small React app the reviewer opens in their browser, which first tells them what the PR is about, then walks them through what it does in the running app, then shows the code in the same order.
+
+Where things are:
+${where}
+- ~/review/app: the review app, Vite with React and TypeScript, dependencies installed.
+  - src/data: the PR from GitHub. pr.json has the description, comments, reviews and files; review-comments.json has the inline review comments, where review bots say most of what they say; pr.diff is the diff. The kit reads them; you read them to understand the PR.
+  - KIT.md: how a review is built and the rules that keep every review consistent. Read it first, all of it.
+  - WRITING.md: how to write every piece of text in the review, and your answers in the chat later. Read it before you write the tour.
+  - src/review.tsx: yours to write. It holds a starter now. examples/rply-16.tsx is a complete review to learn from.
+  - src/kit: the building blocks: Overview, Lead, BeforeAfter, Attention, Card, Chapter, Live, Outcome, Shot, Compare, Clip, Flow, Diff, Rows and Row. Use them first; write your own components next to review.tsx only when the PR needs something they do not do, with the kit's classes and tokens.
+  - src/App.tsx and the kit are the frame every review shares: the rail, the routes, the keys, the look. Leave them as they are unless this PR genuinely needs something else, and if you change them, say what and why in your summary.
+  - npm run check typechecks, builds, opens every page in Chromium as the reviewer will see it, and fails on script errors, failed requests and images that do not load. It saves a screenshot of every page to ~/review/checks. Look at them.
+- ${env} If ~/.bottleship/stage says ready, the head's setup.sh ran and its start.sh is running (log: ~/.bottleship/app.log; setup: ~/.bottleship/setup.log). Ports the app EXPOSEs: ${p.appPorts.join(", ") || "none"}.
+- A review server runs at ${p.reviewUrl} (env BOTTLESHIP_REVIEW_URL). The reviewer already has its link. It serves ~/review/app/dist as soon as you build it, and a page showing your progress until then: when you start a stage, report it with curl -s -X POST -H 'content-type: application/json' -d '{"stage":"<stage>"}' ${p.reviewUrl}/api/progress, stage one of read (step 1), instances (3), hooks (4), steps (5), shots (screenshots), tour (6), check (7); files under ~/review at files/<path>; events at /api/events; step scripts at /api/steps/<id>/run.
+- A headless Chromium with Playwright: \`const { chromium } = require("playwright")\` works in any CommonJS script. For screenshots, use node ~/review/app/scripts/shot.cjs (its options are at the top of the file): it saves ~/review/shots/<name>.png, which <Shot src="shots/<name>.png"> and <Compare base=... head=...> show. It can crop to an element, outline it, click and type first, and set the viewport, color scheme and locale. For a flow that takes several steps, moves or depends on timing, record a clip with node ~/review/app/scripts/clip.cjs instead: it records the page while it clicks, types and drags at a person's pace, and <Clip> plays base and head side by side (KIT.md, Clips, says when a clip beats a screenshot).
+- gh and git are logged in with the reviewer's GitHub token (GH_TOKEN). Read whatever helps you understand the change: CI results (gh pr checks), linked issues, earlier PRs. While you build the tour, do not comment, review, approve or push.
+${p.number ? "- Later, the reviewer may send you comments from the tour as a follow-up; it says how to handle them. Never comment, review or approve on GitHub unless the reviewer explicitly asks you to; the follow-up says how." : "- The reviewer's comments go to the developer's own agent, which changes their checkout. After it has, bottleship brings the new state into ~/workspace as a new commit and sends you a follow-up to refresh the tour for it; it says how."}
+
+What to do:
+1. Understand the change: the description, the diff, the code around it, the tests it adds. Note what the reviewer has to believe for the PR to be right.
+2. Decide how to show it. Prefer the running app and pictures of it over prose. When the change is about a difference in behaviour, run base and head side by side so both can be seen doing the same thing. When the PR changes what people see, the reviewer must see it without hunting: screenshots of the changed part in base and head, cropped and outlined, in the overview and in the chapter about it, next to the live app to try it, in every state the PR touches (hover, open, empty, error, narrow, dark, another language). When the behaviour is invisible (auth, caching, concurrency, background jobs, performance), use a flow: a small diagram of the parts involved that lights up as review hooks fire, and overlays that say what came out.
+3. Run the instances. Every instance must listen on a port the reviewer's browser can reach: the app's ports above (for head) or ${p.instancePorts.join(", ")} (for base and any others). Bind to 0.0.0.0. Start each with BOTTLESHIP_REVIEW_INSTANCE=<instance id> in its environment. List them in review.tsx's instances by their port in the box. Seed whatever state the tour needs (users, data, settings) so each chapter works from a fresh start.
+4. Add temporary review hooks to the box's copies of the code (both instances), at the points that decide the behaviour under review. A hook posts an event and never breaks the app: fire and forget, errors swallowed. In JavaScript:
+   fetch(process.env.BOTTLESHIP_REVIEW_URL + "/api/events", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ instance: process.env.BOTTLESHIP_REVIEW_INSTANCE, kind: "hook", at: "file.ts:47", text: "what happened", flow: { id: "flow-id", edge: ["from", "to"], node: "to", status: "ok", label: "short value" } }) }).catch(() => {})
+   In other languages do the same with their HTTP client. Every POST to the review server needs content-type: application/json. Keep hooks few, at most one per decision, and never commit them.
+5. Write the steps: ~/review/steps/<id>.sh, one per chapter that does something, each doing what a person would do (clicks through Playwright, HTTP calls, a script against the API, a CLI command) against every instance it applies to, then exiting. The reviewer presses Run; the server runs the script in ~/review and tags every event that arrives meanwhile with the step. A step script may post events itself: kind "request" for what it did, "ok" or "fail" with an overlay for what came out on each instance.
+6. Write src/review.tsx, the tour:
+   - The overview: one sentence on what the PR does for the people who use it (Lead); before and after in plain behaviour (BeforeAfter); where it happens, as a flow with the changed parts marked or the key before and after pictures; 2 to 4 things that deserve a close look, each linked to the chapter or code that shows it (Attention). Then go through the description and every comment and review in pr.json and review-comments.json that makes a claim about this code (from people and from bots) and check it in the box. A claim that does not fully hold goes into Attention with who said it, what they said and what you found, linked to the chapter that shows it; the claims that hold go into its held list. Leave out CI chatter and praise.
+   - 3 to 6 chapters, the core behaviour first, then edge cases, then that nothing else broke. Each says why it matters, what should happen on each instance before the reviewer runs it, and shows the evidence (KIT.md says which evidence fits which change).
+   - No chapter just to run the tests: CI does that. Run the PR's new or changed tests in the box against base as well as head. That they fail on base and pass on head is a claim that holds (or does not); what they actually check, if it is less than it looks, is a thing to look at closely. Make a chapter for tests only when the PR has no CI that runs them, or when their output is the evidence (a benchmark, a snapshot diff).
+   - groups: the diff split into the parts the tour talks about, in tour order, each with one sentence on why it exists and its new-file line ranges, linked to its chapter. Tests and glue last. Files no group covers are listed after them on their own.
+7. Check it: npm run check in ~/review/app until it passes, and look at the screenshots in ~/review/checks the way the reviewer will see the pages; fix what reads badly. Run every step with curl -s -X POST -H 'content-type: application/json' -d '{}' ${p.reviewUrl}/api/steps/<id>/run, wait for it, and read the events with curl -sN --max-time 3 ${p.reviewUrl}/api/events. Every step should finish and produce the events and overlays its chapter promises, for every instance. When everything works, reset with curl -s -X POST -H 'content-type: application/json' -d '{}' ${p.reviewUrl}/api/reset so the reviewer starts fresh.
+8. If part of the app cannot run in this box, say so in the overview and show what can be shown (tests, a script against one service, screenshots), rather than inventing results.
+
+End with three short lines: what the tour shows, anything that could not be set up and why, and anything you noticed that the reviewer should look at closely. Leave out URLs and ports (the reviewer already has the link, and ${p.reviewUrl} only works inside this box), and do not ask anyone to revert your hooks: they exist only in this box and go away with it.`;
+}

package/dist/src/review/serve.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/review/serve.js

@@ -0,0 +1,8 @@
+// Runs the review server in a box: node serve.js --dir ~/review [--port N] [--host H] [--urls <file>] [--ask <script>] [--state <script>]
+import { parseArgs } from "node:util";
+import { startReviewServer } from "./server.js";
+const { values } = parseArgs({ options: { dir: { type: "string" }, port: { type: "string" }, host: { type: "string" }, urls: { type: "string" }, ask: { type: "string" }, state: { type: "string" } } });
+if (!values.dir)
+    throw new Error("usage: serve --dir <review dir> [--port N] [--host H] [--urls <file>]");
+const server = await startReviewServer({ dir: values.dir, port: Number(values.port ?? 7777), host: values.host ?? "127.0.0.1", urls: values.urls, ask: values.ask, state: values.state });
+console.log(`review server on ${server.url}`);

package/dist/src/review/server.d.ts

@@ -0,0 +1,14 @@
+export interface ReviewServer {
+    url: string;
+    close(): Promise<void>;
+}
+export interface ReviewServerOptions {
+    dir: string;
+    port?: number;
+    host?: string;
+    urls?: string;
+    ask?: string;
+    state?: string;
+    watchMs?: number;
+}
+export declare function startReviewServer({ dir: rawDir, port, host, urls, ask, state, watchMs }: ReviewServerOptions): Promise<ReviewServer>;