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

package/dist/src/review/start.js

@@ -0,0 +1,140 @@
+// `bottleship review <pr>`: a box with the PR's head and base, the review server running, and an agent building a guided tour of the PR.
+import { ROOT } from "../paths.js";
+import { BsError } from "../config.js";
+import { createBox, putFiles, putTar, runIn, startAgent } from "../boxes.js";
+import { dotenvFiles, parseRepoEnv, readEnvFiles, tarFiles } from "../repo.js";
+import { fetchPr, prEnvFiles } from "./pr.js";
+import { reviewPrompt } from "./prompt.js";
+import { localChanges } from "./local.js";
+import { shq } from "../util.js";
+import { templateFiles, templatePackage } from "./template.js";
+// the review server's port in the box, and ports for instances besides the app's own, e.g. base; all published
+export const REVIEW_PORT = Number(process.env.BOTTLESHIP_REVIEW_PORT ?? 7777);
+export const INSTANCE_PORTS = [7781, 7782, 7783, 7784];
+// containers publish what listens on all interfaces; the provider decides who can reach it (docker: this machine only)
+const REVIEW_HOST = process.env.BOTTLESHIP_REVIEW_HOST ?? "0.0.0.0";
+// a headless browser the agent drives to see and check the UI; require("playwright") resolves through NODE_PATH
+const PLAYWRIGHT = "1.64.1";
+const BROWSER = `USER root
+ENV PLAYWRIGHT_BROWSERS_PATH=/opt/ms-playwright NODE_PATH=/opt/playwright/lib/node_modules
+RUN npm install -g --prefix /opt/playwright playwright@${PLAYWRIGHT} && /opt/playwright/bin/playwright install --with-deps chromium && rm -rf /var/lib/apt/lists/* /root/.npm
+USER box
+`;
+// the review app's dependencies, installed once into the image; a review links them into its copy of the template
+const REVIEW_APP = () => `USER root
+RUN mkdir -p /opt/review-app && echo ${Buffer.from(templatePackage()).toString("base64")} | base64 -d > /opt/review-app/package.json \\
+ && cd /opt/review-app && npm install --no-audit --no-fund && rm -rf /root/.npm && chown -R box:box /opt/review-app
+USER box
+`;
+// what the box needs to run the review server, and the package.json that marks it as ES modules
+const SERVER_FILES = ["package.json", "dist/src/review/server.js", "dist/src/review/contract.js", "dist/src/review/serve.js", "dist/src/review/github.js", "dist/src/review/comments.js", "dist/src/review/setting-up.js", "dist/src/util.js"];
+// onPhase: what is happening now, for a person watching in a terminal
+// local: the user's checkout of the same repo, for its .env files and its .bottleship/ when the PR has none
+export async function startReview(cfg, opts) {
+    const phase = opts.onPhase ?? (() => { });
+    const src = opts.source;
+    const localEnv = opts.local ? readEnvFiles(opts.local) : undefined;
+    const dotenv = opts.local ? dotenvFiles(opts.local) : {};
+    let subject;
+    let workspace, pr, prEnv, baseTree, baseSha;
+    if ("pr" in src) {
+        phase(`Reading ${src.pr.repo.label}#${src.pr.number} from GitHub`);
+        const p = await fetchPr(src.pr.repo, src.pr.number);
+        prEnv = await prEnvFiles(src.pr.repo, p.headRefOid);
+        subject = { raw: p.raw, title: p.title, url: p.url, diff: p.diff, reviewComments: p.reviewComments, base: p.baseRefName, label: String(src.pr.number), prompt: { repo: src.pr.repo.label, number: p.number, title: p.title, base: p.baseRefName } };
+        workspace = { clone: { url: src.pr.repo.clone, label: src.pr.repo.label } };
+        pr = { number: src.pr.number, base: p.baseRefName };
+    }
+    else {
+        phase("Reading the local changes");
+        const c = await localChanges(src.changes.root, { ...src.changes, exclude: Object.keys(dotenv) });
+        const base = c.raw.baseRefName;
+        subject = { raw: c.raw, title: c.branch, url: c.branch, diff: c.diff, reviewComments: [], base, label: "local", prompt: { repo: c.raw.repo, title: c.branch, base, changes: { branch: c.branch, note: src.changes.note } } };
+        workspace = { tar: c.head };
+        baseTree = c.baseTree;
+        baseSha = c.base;
+    }
+    const env = prEnv ? "pr" : localEnv ? "local" : "none";
+    const repoEnv = parseRepoEnv((prEnv ?? localEnv)?.Dockerfile);
+    const reviewUrl = `http://127.0.0.1:${REVIEW_PORT}`;
+    phase(`Creating the box for "${subject.title}" (the first box builds the image, which takes minutes)`);
+    const box = await createBox(cfg, {
+        provider: opts.provider,
+        label: `review-${subject.label}`,
+        agent: opts.agent,
+        workspace,
+        pr,
+        repoEnv,
+        dotenv,
+        env: { BOTTLESHIP_REVIEW_URL: reviewUrl },
+        dockerfile: `${BROWSER}${REVIEW_APP()}EXPOSE ${REVIEW_PORT} ${INSTANCE_PORTS.join(" ")}\n`,
+    });
+    try {
+        phase("Copying the changes and the review app into the box");
+        if (baseTree) {
+            // local changes: base from git, head from the working tree, each its own repo so the agent can diff its hooks;
+            // .env files stay out of both
+            await putTar(box, "base", baseTree);
+            const exclude = Object.keys(dotenv).map((n) => `/${n}`).join("\n");
+            const id = "-c user.name=bottleship -c user.email=review@bottleship.local";
+            const repos = await runIn(box, `set -e
+cd "$HOME/base" && git init -q && printf '%s\\n' ${shq(exclude)} >> .git/info/exclude && git add -A && git ${id} commit -qm base
+cp -R "$HOME/base/.git" "$HOME/workspace/.git" && cd "$HOME/workspace" && git add -A && git ${id} commit -qm ${shq(`local changes on ${subject.title}`)} --allow-empty
+[ -d "$HOME/.bottleship/dotenv" ] && cp -R "$HOME/.bottleship/dotenv/." "$HOME/base/" || true`);
+            if (repos.code !== 0)
+                throw new BsError("setup_failed", `could not set up the checkouts in ${box.id}`, "see stderr", { stderr: repos.stderr.slice(-2000) });
+        }
+        // the review app: the template, the changes in src/data, and the dependencies from the image
+        await putTar(box, ".bottleship/review-template", await tarFiles(ROOT, templateFiles()));
+        const shas = await runIn(box, 'git -C "$HOME/base" rev-parse HEAD && git -C "$HOME/workspace" rev-parse HEAD');
+        const [base, head] = baseSha ? [baseSha, "working tree"] : shas.stdout.trim().split("\n");
+        const files = {
+            "review/app/src/data/pr.json": JSON.stringify(subject.raw, null, 2),
+            "review/app/src/data/review-comments.json": JSON.stringify(subject.reviewComments, null, 2),
+            "review/app/src/data/pr.diff": subject.diff,
+            "review/app/src/data/box.json": JSON.stringify({ base, head }),
+        };
+        // the reviewer's local, uncommitted environment, when the change itself has none
+        if (env === "local")
+            for (const [name, content] of Object.entries(localEnv))
+                for (const dir of ["workspace", "base"])
+                    files[`${dir}/.bottleship/${name}`] = content;
+        const app = await runIn(box, `set -e
+mkdir -p "$HOME/review/steps" "$HOME/review/shots"
+cp -R "$HOME/.bottleship/review-template/review-app/." "$HOME/review/app"
+rm -f "$HOME/review/app/src/data/"*
+ln -sfn /opt/review-app/node_modules "$HOME/review/app/node_modules"`);
+        if (app.code !== 0)
+            throw new BsError("review_app_failed", `could not set up the review app in ${box.id}`, "see stderr", { stderr: app.stderr.slice(-2000) });
+        await putFiles(box, files);
+        await putTar(box, ".bottleship/review-server", await tarFiles(ROOT, SERVER_FILES));
+        // where this machine reaches each port the box publishes, for the review UI's links and frames
+        const urls = {};
+        if (box.provider.url)
+            for (const port of [REVIEW_PORT, ...INSTANCE_PORTS, ...repoEnv.ports]) {
+                try {
+                    urls[port] = await box.provider.url(box.box, port);
+                }
+                catch { }
+            }
+        await putFiles(box, { ".bottleship/urls.json": JSON.stringify(urls) });
+        phase("Starting the review server");
+        // with the box's env, so posting a review uses its GH_TOKEN
+        const server = `. "$HOME/.bottleship/env.sh"
+S="$HOME/.bottleship/review-server/dist/src/review/serve.js"
+nohup node "$S" --dir "$HOME/review" --port ${REVIEW_PORT} --host ${shq(REVIEW_HOST)} --urls "$HOME/.bottleship/urls.json" --ask "$HOME/.bottleship/ask.sh" --state "$HOME/.bottleship/agent-state.sh" > "$HOME/.bottleship/review-server.log" 2>&1 < /dev/null &
+echo $! > "$HOME/.bottleship/review-server.pid"
+for i in $(seq 1 50); do curl -s -o /dev/null ${shq(`${reviewUrl}/api/status`)} && exit 0; sleep 0.2; done
+cat "$HOME/.bottleship/review-server.log" >&2; exit 1`;
+        const r = await runIn(box, server);
+        if (r.code !== 0)
+            throw new BsError("review_server_failed", `the review server did not start in ${box.id}`, "see stderr", { stderr: r.stderr.slice(-2000) });
+        phase("Starting the agent");
+        await startAgent(box, reviewPrompt({ ...subject.prompt, reviewUrl, instancePorts: INSTANCE_PORTS, appPorts: repoEnv.ports, envSource: env }));
+        return { box, url: urls[REVIEW_PORT] ?? reviewUrl, pr: subject.url, title: subject.title, env };
+    }
+    catch (e) {
+        await box.provider.destroy(box.box).catch(() => { });
+        throw e;
+    }
+}

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

@@ -0,0 +1,20 @@
+export interface GhRepo {
+    host: string;
+    owner: string;
+    name: string;
+}
+export interface PrRepo {
+    label: string;
+    api: string;
+    hostname?: string;
+    clone: string;
+}
+export declare function parseRemote(s: string): GhRepo | undefined;
+export declare function parseRepoArg(s: string): GhRepo;
+export declare function parsePrRef(s: string): {
+    number: number;
+    repo?: GhRepo;
+};
+export declare const sameRepo: (a: GhRepo, b: GhRepo) => boolean;
+export declare function prRepo(r: GhRepo): PrRepo;
+export declare function prRepoFromRemote(remote: string): PrRepo;

package/dist/src/review/target.js

@@ -0,0 +1,66 @@
+// Which PR to review: a number, a shorthand, or a link, on github.com or a GitHub Enterprise host.
+import { BsError } from "../config.js";
+const FORMS = "17, #17, owner/name#17, host/owner/name#17, or a PR link like https://github.com/owner/name/pull/17";
+const bad = (what) => new BsError("bad_request", `"${what}" is not a PR`, `use ${FORMS}`);
+const strip = (n) => n.replace(/\.git$/, "");
+const SEG = "[A-Za-z0-9_.-]+";
+// a git remote or repo link: https://host/owner/name(.git), git@host:owner/name(.git), ssh://git@host[:port]/owner/name(.git)
+export function parseRemote(s) {
+    const scp = s.match(new RegExp(`^[\\w.-]+@([^:/]+):(${SEG})/(${SEG})/?$`));
+    if (scp)
+        return { host: scp[1].toLowerCase(), owner: scp[2], name: strip(scp[3]) };
+    let u;
+    try {
+        u = new URL(s);
+    }
+    catch {
+        return undefined;
+    }
+    if (!["https:", "http:", "ssh:", "git:"].includes(u.protocol))
+        return undefined;
+    const parts = u.pathname.replace(/^\/+|\/+$/g, "").split("/");
+    if (parts.length !== 2 || !parts.every((p) => new RegExp(`^${SEG}$`).test(p)))
+        return undefined;
+    return { host: u.hostname.toLowerCase(), owner: parts[0], name: strip(parts[1]) };
+}
+// --repo: owner/name (github.com), host/owner/name, or a link or remote
+export function parseRepoArg(s) {
+    const short = s.match(new RegExp(`^(?:(${SEG}\\.${SEG})/)?(${SEG})/(${SEG})$`));
+    if (short)
+        return { host: (short[1] ?? "github.com").toLowerCase(), owner: short[2], name: strip(short[3]) };
+    const r = parseRemote(s);
+    if (!r)
+        throw new BsError("bad_request", `"${s}" is not a repo`, "use owner/name, host/owner/name for GitHub Enterprise, or the repo's URL");
+    return r;
+}
+export function parsePrRef(s) {
+    const arg = s.trim();
+    const n = arg.match(/^#?(\d+)$/);
+    if (n)
+        return { number: Number(n[1]) };
+    const short = arg.match(new RegExp(`^(?:(${SEG}\\.${SEG})/)?(${SEG})/(${SEG})#(\\d+)$`));
+    if (short)
+        return { number: Number(short[4]), repo: { host: (short[1] ?? "github.com").toLowerCase(), owner: short[2], name: strip(short[3]) } };
+    // a link to the PR or any page under it: /files, /commits, #comment anchors, query strings
+    let u;
+    try {
+        u = new URL(/^[a-z]+:\/\//i.test(arg) ? arg : `https://${arg}`);
+    }
+    catch {
+        throw bad(s);
+    }
+    const p = u.pathname.split("/").filter(Boolean);
+    if (!u.hostname.includes(".") || p.length < 4 || p[2] !== "pull" || !/^\d+$/.test(p[3]))
+        throw bad(s);
+    return { number: Number(p[3]), repo: { host: u.hostname.toLowerCase(), owner: p[0], name: strip(p[1]) } };
+}
+export const sameRepo = (a, b) => a.host === b.host && a.owner.toLowerCase() === b.owner.toLowerCase() && a.name.toLowerCase() === b.name.toLowerCase();
+export function prRepo(r) {
+    const github = r.host === "github.com";
+    return { label: github ? `${r.owner}/${r.name}` : `${r.host}/${r.owner}/${r.name}`, api: `repos/${r.owner}/${r.name}`, ...(!github && { hostname: r.host }), clone: `https://${r.host}/${r.owner}/${r.name}.git` };
+}
+// a remote that is no GitHub repo link, e.g. a path, goes to gh and git as it is
+export function prRepoFromRemote(remote) {
+    const r = parseRemote(remote);
+    return r ? prRepo(r) : { label: remote, api: `repos/${remote}`, clone: remote };
+}

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

@@ -0,0 +1,3 @@
+export declare const TEMPLATE: string;
+export declare function templateFiles(dir?: string): string[];
+export declare const templatePackage: () => string;

package/dist/src/review/template.js

@@ -0,0 +1,13 @@
+// The review app template: a Vite and React project with the review kit, which the box agent fills in for each PR.
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { ROOT } from "../paths.js";
+export const TEMPLATE = join(ROOT, "review-app");
+// the playground is for working on the kit, not part of a review
+const SKIP = new Set(["node_modules", "dist", ".DS_Store", "playground"]);
+// every template file, relative to the package root
+export function templateFiles(dir = TEMPLATE) {
+    return readdirSync(dir, { withFileTypes: true }).flatMap((e) => SKIP.has(e.name) ? [] : e.isDirectory() ? templateFiles(join(dir, e.name)) : [relative(ROOT, join(dir, e.name))]);
+}
+// the template's package.json, installed once into the box image so a review builds without a network
+export const templatePackage = () => readFileSync(join(TEMPLATE, "package.json"), "utf8");

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

@@ -0,0 +1,4 @@
+import { startReview } from "./start.ts";
+import { type UI } from "../ui.ts";
+import type { Config } from "../types.ts";
+export declare function reviewInTerminal(ui: UI, cfg: Config, opts: Parameters<typeof startReview>[1]): Promise<void>;

package/dist/src/review/terminal.js

@@ -0,0 +1,91 @@
+// `bottleship review` for a person in a terminal: each phase as it happens, the review UI opened in the browser,
+// then the box watched until the agent is done or the person stops watching. The review keeps going either way.
+import { spawn } from "node:child_process";
+import { agentState } from "../boxes.js";
+import { startReview } from "./start.js";
+import { c } from "../ui.js";
+const ENV = {
+    pr: "the PR's own .bottleship/",
+    local: "your local .bottleship/",
+    none: "nothing: neither the PR nor your checkout has a .bottleship/, so the agent works out how to run the app",
+};
+function openInBrowser(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "linux" ? "xdg-open" : undefined;
+    if (!cmd)
+        return false;
+    try {
+        spawn(cmd, [url], { stdio: "ignore", detached: true }).on("error", () => { }).unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const elapsed = (since) => {
+    const s = Math.round((Date.now() - since) / 1000);
+    return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${s % 60}s`;
+};
+export async function reviewInTerminal(ui, cfg, opts) {
+    const pr = "pr" in opts.source ? opts.source.pr : undefined;
+    ui.intro("review");
+    const setup = ui.spin(pr ? `Reading ${pr.repo.label}#${pr.number} from GitHub` : "Reading the local changes");
+    let r;
+    try {
+        r = await startReview(cfg, { ...opts, onPhase: (t) => setup.message(t) });
+    }
+    catch (e) {
+        setup.stop("Could not start the review", true);
+        throw e;
+    }
+    setup.stop(pr ? `${c.bold(`#${pr.number}`)} ${r.title}` : `${c.bold("Local changes")} on ${r.title}`);
+    const opened = openInBrowser(r.url);
+    ui.note("Review", `${r.url}${opened ? "  (opened in your browser)" : ""}\n\nIt shows the tour as soon as the agent has built it. Box ${r.box.id}, environment from ${ENV[r.env]}.`);
+    // watch until the agent is done; Ctrl-C only stops watching
+    const started = Date.now();
+    let watch = ui.spin("Setting up the environment");
+    let stopped = false;
+    const stop = () => (stopped = true);
+    process.once("SIGINT", stop);
+    let envSeen = "";
+    let built = false;
+    let last = { agent: "running", log: "" };
+    try {
+        while (!stopped) {
+            last = await agentState(r.box, 12);
+            if (last.env && last.env !== envSeen && ["ready", "failed"].includes(last.env)) {
+                envSeen = last.env;
+                watch.stop(last.env === "ready" ? "The app's environment is up" : "The app's environment failed to set up; the agent will work around it", last.env === "failed");
+                if (last.env === "failed")
+                    ui.say(c.dim(`    see it: bottleship agent exec ${r.box.id} -- tail -40 ~/.bottleship/setup.log ~/.bottleship/app.log`));
+                watch = ui.spin("Agent is building the tour");
+            }
+            if (!built) {
+                built = await fetch(`${r.url}/api/status`).then((x) => x.json()).then((s) => !!s.app, () => false);
+                if (built) {
+                    watch.stop("The tour is built and open in the review; the agent is checking it");
+                    watch = ui.spin("Agent is checking the tour");
+                }
+            }
+            if (last.agent !== "running")
+                break;
+            watch.message(`${built ? "Agent is checking the tour" : envSeen ? "Agent is building the tour" : "Setting up the environment"}  ${c.dim(elapsed(started))}`);
+            await new Promise((res) => setTimeout(res, 2000));
+        }
+    }
+    finally {
+        process.off("SIGINT", stop);
+    }
+    if (stopped) {
+        watch.stop("Stopped watching; the review keeps going in the box");
+        ui.say("    The tour shows how far it got.");
+    }
+    else {
+        const failed = last.agent !== "exited" || ("exitCode" in last && last.exitCode !== 0);
+        watch.stop(failed ? `The agent stopped after ${elapsed(started)}` : `The agent is done after ${elapsed(started)}`, failed);
+        const summary = last.log.trim().split("\n").slice(-3).join("\n");
+        if (summary)
+            ui.note(failed ? "Last output" : "Agent's summary", summary);
+    }
+    ui.say(`    ${c.dim(`bottleship box rm ${r.box.id}`)}  when the review is over`);
+    ui.close(built ? `Review at ${r.url}` : "Done");
+}

package/dist/src/secrets.d.ts

@@ -3,3 +3,4 @@ export declare function describe(source: SecretSource): string;
 export declare function readSecret(source: SecretSource): string;
 export declare function storeSecret(name: string, value: string): string;
 export declare function hasSecret(source: SecretSource): boolean;
+export declare function forgetSecret(name: string): void;

package/dist/src/secrets.js

@@ -1,6 +1,6 @@
 // Reads and stores secret values on this machine. Sources are described in types.ts (SecretSource).
 import { execFileSync } from "node:child_process";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { HOME } from "./paths.js";
 const SERVICE = "bottleship";
@@ -56,3 +56,13 @@ export function hasSecret(source) {
         return false;
     }
 }
+export function forgetSecret(name) {
+    if (useKeychain()) {
+        try {
+            sh("security", ["delete-generic-password", "-s", SERVICE, "-a", name]);
+        }
+        catch { }
+    }
+    else
+        rmSync(join(FILE_DIR, name), { force: true });
+}

package/dist/src/types.d.ts

@@ -13,33 +13,12 @@ export interface AgentSpec {
     resume: string;
     env?: EnvMap;
     unset?: string[];
-    login?: AgentLogin;
-}
-export type LoginRoute = "token" | "device" | "none";
-export interface AgentLogin {
-    routes: LoginRoute[];
-    use: LoginRoute;
-    token?: {
+    login?: {
         env: string;
         store: string;
         command?: string;
         hint?: string;
     };
-    tokens?: {
-        env: string;
-        store: string;
-        hint?: string;
-    }[];
-    device?: {
-        command: string;
-        status: string;
-        setup?: string;
-        timeout?: number;
-    };
-}
-export interface ProviderSpec {
-    module: string;
-    [option: string]: unknown;
 }
 export interface Config {
     provider: string;
@@ -49,12 +28,7 @@ export interface Config {
         email: string;
     };
     env: EnvMap;
-    providers: Record<string, ProviderSpec>;
     agents: Record<string, AgentSpec>;
-    templates: Record<string, {
-        name: string;
-        ref: string;
-    }>;
 }
 export interface ExecResult {
     code: number | null;
@@ -68,50 +42,6 @@ export interface BoxStream {
     close(): void;
     onClose(cb: (code?: number | null) => void): void;
 }
-export type BoxStatus = "running" | "gone";
-export interface TemplateSpec {
-    name: string;
-    dockerfile: string;
-}
-export interface Provider {
-    template?(spec: TemplateSpec): Promise<string>;
-    create(opts: {
-        id: string;
-        source?: string;
-        template?: string;
-    }): Promise<{
-        id: string;
-    }>;
-    exec(id: string, script: string, opts?: {
-        stdin?: string | Buffer;
-    }): Promise<ExecResult>;
-    destroy(id: string): Promise<unknown>;
-    openStream?(id: string, script: string): BoxStream | Promise<BoxStream>;
-    status?(id: string): Promise<BoxStatus>;
-}
-export interface LoadedProvider extends Provider {
-    name: string;
-}
-export interface RunOptions {
-    stdin?: string | Buffer;
-    check?: boolean;
-    env?: Record<string, string>;
-}
-export interface ProviderKit {
-    run(cmd: string, args: string[], opts?: RunOptions): Promise<ExecResult>;
-    shq(s: unknown): string;
-    fill(template: string, values: Record<string, unknown>): string;
-    spawnStream(cmd: string, args: string[]): BoxStream;
-    wsStream(url: string, headers?: Record<string, string>): BoxStream;
-}
-export interface ProviderCtx {
-    name: string;
-    options: Record<string, any>;
-    secret(source: SecretSource): string;
-    log(...args: unknown[]): void;
-    kit: ProviderKit;
-}
-export type ProviderFactory = (ctx: ProviderCtx) => Provider | Promise<Provider>;
 export interface BsErrorJSON {
     error: string;
     message: string;

package/dist/src/ui.d.ts

@@ -9,8 +9,12 @@ export declare const c: {
     white: (s: string) => string;
 };
 export declare function header(): string;
+export interface Spinner {
+    message(text: string): void;
+    stop(text: string, failed?: boolean): void;
+}
 export interface UI {
-    intro(): void;
+    intro(title?: string): void;
     say(line?: string): void;
     section(title: string): void;
     ok(label: string, detail?: string): void;
@@ -25,6 +29,7 @@ export interface UI {
     confirm(question: string): Promise<boolean>;
     handOver(command: string): Promise<number | null>;
     step<T>(label: string, fn: () => Promise<T>): Promise<T>;
+    spin(label: string): Spinner;
     fail(message: string, fix?: string): void;
     close(message?: string): void;
 }

package/dist/src/ui.js

@@ -13,35 +13,29 @@ export const c = {
     blue: sgr("34"),
     white: sgr("97"),
 };
-// a ship in a bottle, with a color mask per line: c glass, y cork and stars, w sails, r hull and flags, b sea
+// the sail on two waves, as on the review's pages, with a mask per line: w the sail and the near wave, d the far one
 const ART = [
-    "            .-----------------------------------------------.",
-    "            ccccccccccccccccccccccccccccccccccccccccccccccccc",
-    "           /                                                 \\",
-    "           c                                                 c",
-    " _________/     *             |>          |>                  \\",
-    " cccccccccc     y             wr          wr                  c",
-    "[####|                       /|\\         /|\\          .        |",
-    "yyyyyc                       www         www          y        c",
-    "[####|             .        / | \\       / | \\                  |",
-    "yyyyyc             y        w w w       w w w                  c",
-    "[####|____                 /__|__\\     /__|__\\      *          |",
-    "yyyyyccccc                 wwwwwww     wwwwwww      y          c",
-    "          \\         ~~~~~~\\__o___o___o___o___o__/~~~~~~       /",
-    "          c         bbbbbbrrryrrryrrryrrryrrryrrrbbbbbb       c",
-    "           \\   ~     ~     ~     ~     ~     ~     ~     ~   /",
-    "           c   b     b     b     b     b     b     b     b   c",
-    "            '-----------------------------------------------'",
-    "            ccccccccccccccccccccccccccccccccccccccccccccccccc",
+    "      │╲",
+    "      ww",
+    "      │ ╲",
+    "      w ww",
+    "      │  ╲",
+    "      w  w",
+    "      │___╲",
+    "      wwwww",
+    "  ∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿",
+    "  ddddddddddddddd",
+    " ∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿",
+    " wwwwwwwwwwwwwwwww",
 ];
-const paint = { c: c.cyan, y: c.yellow, w: c.white, r: c.red, b: c.blue };
+const paint = { w: c.white, d: c.dim };
 export function header() {
     const rows = [];
     for (let i = 0; i < ART.length; i += 2) {
         const [text, mask] = [ART[i], ART[i + 1]];
         rows.push([...text].map((ch, j) => (paint[mask[j]] ?? String)(ch)).join(""));
     }
-    return `\n${rows.join("\n")}\n\n   ${c.bold("bottleship")}  ${c.dim("coding agents in little boxes, run by your agent")}\n`;
+    return `\n${rows.join("\n")}\n\n  ${c.bold("bottleship")}\n`;
 }
 // soft-wraps each line to width, keeping a list item's hanging indent
 function wrap(text, width) {
@@ -71,9 +65,9 @@ function answered(v) {
 export function terminalUI() {
     let closed = false;
     return {
-        intro() {
+        intro(title = "setup") {
             process.stdout.write(header() + "\n");
-            p.intro(c.bold(" setup "));
+            p.intro(c.bold(` ${title} `));
         },
         say: (line = "") => p.log.message(line.replace(/^ +/gm, "")),
         section: (title) => p.log.step(c.bold(title)),
@@ -112,6 +106,11 @@ export function terminalUI() {
                 throw e;
             }
         },
+        spin(label) {
+            const s = p.spinner();
+            s.start(label);
+            return { message: (t) => s.message(t), stop: (t, failed) => s.stop(failed ? c.red(t) : t, failed ? 1 : 0) };
+        },
         fail(message, fix) {
             p.log.error(`${message}${fix ? "\n" + c.dim(fix) : ""}`);
             p.outro(c.red("Setup did not finish."));

package/dist/src/util.d.ts

@@ -0,0 +1,11 @@
+import type { BoxStream, ExecResult } from "./types.ts";
+export interface RunOptions {
+    stdin?: string | Buffer;
+    check?: boolean;
+    env?: Record<string, string>;
+    cwd?: string;
+}
+export declare function run(cmd: string, args: string[], opts?: RunOptions): Promise<ExecResult>;
+export declare function spawnStream(cmd: string, args: string[]): BoxStream;
+export declare const shq: (s: unknown) => string;
+export declare function fill(template: string, values: Record<string, unknown>): string;

package/dist/src/util.js

@@ -0,0 +1,40 @@
+// Process helpers: run a command to completion, or keep one open as a stream.
+import { spawn } from "node:child_process";
+function spawnPiped(cmd, args, { env, cwd } = {}) {
+    return spawn(cmd, args, { stdio: ["pipe", "pipe", "pipe"], cwd, env: env ? { ...process.env, ...env } : process.env });
+}
+// resolves { code, stdout, stderr }; with check (default true) a non-zero exit rejects
+export function run(cmd, args, opts = {}) {
+    const { stdin, check = true } = opts;
+    return new Promise((resolve, reject) => {
+        const child = spawnPiped(cmd, args, opts);
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (d) => (stdout += d));
+        child.stderr.on("data", (d) => (stderr += d));
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (check && code !== 0)
+                reject(new Error(`${cmd} ${args.slice(0, 3).join(" ")}... exited ${code}: ${stderr.trim().slice(-500)}`));
+            else
+                resolve({ code, stdout, stderr });
+        });
+        child.stdin.on("error", () => { });
+        child.stdin.end(stdin ?? "");
+    });
+}
+// a long-lived child process as a BoxStream
+export function spawnStream(cmd, args) {
+    const child = spawnPiped(cmd, args);
+    child.stdin.on("error", () => { });
+    return { stdin: child.stdin, stdout: child.stdout, stderr: child.stderr, close: () => child.kill(), onClose: (cb) => child.on("close", (code) => cb(code)) };
+}
+// single-quote for sh
+export const shq = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+// fills {name} with the shell-quoted value, missing values with ""
+export function fill(template, values) {
+    return template.replace(/\{(\w+)\}/g, (_, k) => {
+        const v = values[k];
+        return v === undefined || v === null ? "" : shq(v);
+    });
+}