@webappwiz/arbor 0.0.28 → 0.0.30

package/escalate.test.ts

@@ -0,0 +1,76 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { join } from "node:path";
+import { add } from "./add";
+import { escalate, REVIEW_SUBJECT } from "./escalate";
+import { PLAN_FILE, questions } from "./plan";
+import { Testing } from "./testing";
+
+describe("escalate", () => {
+	let deps: Testing;
+
+	beforeEach(async () => {
+		deps = await Testing.open();
+	});
+
+	afterEach(() => deps.disposeAsync());
+
+	it("records the reason, drops the lease, and leaves the tree alone", async () => {
+		await add(deps, "alpha");
+		const worktree = (await deps.service.find("alpha")).path;
+		await deps.fs.write(join(worktree, "half-done.txt"), "work in progress\n");
+
+		await escalate(deps, "both sides restructured the router", worktree);
+
+		const state = (await deps.service.find("alpha")).state;
+		expect(state).toMatchObject({ status: "escalated", lease: null });
+		expect(state?.escalations).toHaveLength(1);
+		expect(await deps.fs.exists(join(worktree, "half-done.txt"))).toBe(true);
+
+		await escalate(deps, "second thoughts", worktree);
+		expect((await deps.service.find("alpha")).state?.escalations).toHaveLength(
+			2,
+		);
+	});
+
+	it("requires an explicit task when run outside a worktree", async () => {
+		await add(deps, "alpha");
+
+		await expect(escalate(deps, "needs a human", deps.root)).toBail("usage", {
+			message: "--task",
+		});
+
+		await escalate(deps, "needs a human", deps.root, { task: "alpha" });
+		expect((await deps.service.find("alpha")).state?.status).toBe("escalated");
+	});
+
+	it("asks for approval with a question of its own, once nothing else is open", async () => {
+		await add(deps, "alpha");
+		const worktree = (await deps.service.find("alpha")).path;
+		const plan = join(worktree, PLAN_FILE);
+		await deps.fs.write(plan, "# alpha\n\n## Blocked\n\n- [ ] 1. Keep it?\n");
+
+		await expect(
+			escalate(deps, "check the header", worktree, { review: true }),
+		).toBail("blocked", { data: { task: "alpha", blocked: ["1"] } });
+
+		await deps.fs.write(
+			plan,
+			"# alpha\n\n## Blocked\n\n- [x] 1. Keep it? → yes\n",
+		);
+		await escalate(deps, "check the header at 390px", worktree, {
+			review: true,
+		});
+
+		expect(questions(await deps.fs.read(plan)).at(-1)).toMatchObject({
+			number: "2",
+			text: REVIEW_SUBJECT,
+			body: "check the header at 390px",
+		});
+		expect(
+			(await deps.service.find("alpha")).state?.escalations?.at(-1),
+		).toMatchObject({ reason: "check the header at 390px", review: "2" });
+		expect(deps.out()).toContain(
+			"review:   question 2 asks to approve merging",
+		);
+	});
+});

package/escalate.ts

@@ -0,0 +1,112 @@
+import { color, type Logger } from "webappwiz/log";
+import type { Fs, Lock } from "webappwiz/system";
+import { fail } from "./exit";
+import type { Git } from "./git";
+import { PLAN_FILE, questions, withQuestion } from "./plan";
+import type { WorktreeService } from "./worktree-service";
+
+export interface EscalateOptions {
+	/** Task to escalate. Defaults to the one `cwd` is a worktree for. */
+	task?: string;
+	/**
+	 * Ask a person to approve merging, rather than to answer questions: adds
+	 * the question that asks it to the plan, with the reason as its detail.
+	 * Refused while another question is unchecked.
+	 */
+	review?: boolean;
+}
+
+/** The question a review asks. */
+export const REVIEW_SUBJECT = "Ready to merge?";
+
+/**
+ * The way out that is not "resolve the conflict badly to finish the task".
+ * When both sides restructured the same logic there is no correct merge, only
+ * a decision, and that belongs to a human.
+ */
+export async function escalate(
+	{
+		service,
+		git,
+		lock,
+		log,
+		fs,
+	}: {
+		service: WorktreeService;
+		git: Git;
+		lock: Lock;
+		log: Logger;
+		fs: Fs;
+	},
+	reason: string,
+	cwd: string,
+	{ task, review = false }: EscalateOptions = {},
+): Promise<void> {
+	const branch = await git.currentBranch(cwd).catch(() => "");
+	const name = task || service.taskFor(branch);
+	if (!name) {
+		fail(
+			"usage",
+			"not in a task worktree: pass --task <name> to escalate from elsewhere",
+		);
+	}
+	const found = await service.find(name);
+	if (!found.state) {
+		fail("not_found", `no state file for '${name}'`, { task: name });
+	}
+
+	let asked: string | undefined;
+	if (review) {
+		const path = `${found.path}/${PLAN_FILE}`;
+		const plan = await fs.read(path).catch(() => "");
+		const unchecked = questions(plan)
+			.filter((question) => !question.done)
+			.map((question) => question.number);
+		// A review is the one thing left: approve it and the task lands.
+		if (unchecked.length > 0) {
+			fail(
+				"blocked",
+				`'${name}' has questions ${unchecked.join(", ")} unchecked under ## Blocked: settle those first, or escalate without --review to ask them`,
+				{ task: name, blocked: unchecked },
+			);
+		}
+		const added = withQuestion(plan, REVIEW_SUBJECT, reason);
+		await fs.write(path, added.plan);
+		asked = added.number;
+	}
+	const escalations = [
+		...(found.state.escalations ?? []),
+		{
+			reason,
+			at: new Date().toISOString(),
+			...(asked === undefined ? {} : { review: asked }),
+		},
+	];
+	// The worktree is left exactly as it is: a human needs to see what the
+	// agent saw, conflict markers and all.
+	const worktree = await found.save({
+		status: "escalated",
+		lease: null,
+		escalations,
+	});
+	await lock.releaseIfOurs();
+
+	log.info(
+		[
+			`${color.yellow("escalated")} ${worktree.task}`,
+			`  worktree: ${worktree.path}`,
+			`  branch:   ${worktree.branch}`,
+			`  reason:   ${reason}`,
+			asked === undefined
+				? ""
+				: `  review:   question ${asked} asks to approve merging`,
+			escalations.length > 1
+				? `  (${escalations.length} escalations recorded)`
+				: "",
+			"",
+			"Left untouched for a human. Stop working on this task.",
+		]
+			.filter(Boolean)
+			.join("\n"),
+	);
+}

package/exit.test.ts

@@ -0,0 +1,71 @@
+import { beforeEach, describe, expect, it } from "bun:test";
+import { MemoryLogger } from "webappwiz/log";
+import { NodePs } from "webappwiz/system";
+import { FakeProcess } from "webappwiz/system/testing";
+import { EXIT, exits, fail } from "./exit";
+
+it("keeps the exit codes stable", () => {
+	// pinned: these codes are arbor's API and an agent branches on them, so a
+	// renumbering has to be deliberate, and README.md's table has one source
+	expect(EXIT).toEqual({
+		usage: 1,
+		conflict: 2,
+		tests_failed: 3,
+		lease_lost: 4,
+		budget_exhausted: 5,
+		lease_held: 6,
+		dirty: 7,
+		not_found: 8,
+		hook_failed: 9,
+		exists: 10,
+		orphaned: 11,
+		merge_failed: 12,
+		already_removed: 13,
+		timeout: 14,
+		blocked: 16,
+	});
+});
+
+describe("exit", () => {
+	let process: FakeProcess;
+	let log: MemoryLogger;
+	let ps: NodePs;
+	let middleware: ReturnType<typeof exits>;
+
+	beforeEach(() => {
+		process = new FakeProcess();
+		log = new MemoryLogger();
+		ps = new NodePs({ proc: process });
+		middleware = exits();
+	});
+
+	it("turns a refusal into JSON, an explanation and a status code", async () => {
+		await middleware({ log, ps }, async () => {
+			fail("conflict", "rebase conflicted", { task: "alpha" });
+		});
+
+		expect(process.lastExit()).toBe(EXIT.conflict);
+		const [json, human] = log.entries;
+		expect(JSON.parse(String(json?.message))).toEqual({
+			reason: "conflict",
+			task: "alpha",
+		});
+		expect(String(human?.message)).toContain("rebase conflicted");
+	});
+
+	it("lets anything that is not a refusal through", async () => {
+		const boom = middleware({ log, ps }, async () => {
+			throw new Error("boom");
+		});
+
+		expect(boom).rejects.toThrow("boom");
+		expect(process.lastExit()).toBeUndefined();
+	});
+
+	it("leaves a command that succeeded alone", async () => {
+		await middleware({ log, ps }, async () => {});
+
+		expect(process.lastExit()).toBeUndefined();
+		expect(log.entries).toEqual([]);
+	});
+});

package/exit.ts

@@ -0,0 +1,74 @@
+import type { Deps, Middleware } from "webappwiz/cmd";
+
+/** Exit codes are the API: an agent branches on these, not on prose. */
+export const EXIT = {
+	// Stable by contract: keep them as they are, and keep README.md's table in
+	// sync.
+	usage: 1,
+	conflict: 2,
+	tests_failed: 3,
+	lease_lost: 4,
+	budget_exhausted: 5,
+	lease_held: 6,
+	dirty: 7,
+	not_found: 8,
+	hook_failed: 9,
+	exists: 10,
+	orphaned: 11,
+	merge_failed: 12,
+	already_removed: 13,
+	timeout: 14,
+	// 15 was `unread`, gone with the replies that waited to be read: never reuse it.
+	blocked: 16,
+	// 17 was `not_escalated`, gone with answering from the page: never reuse it.
+} as const;
+
+export type Reason = keyof typeof EXIT;
+
+/**
+ * A refusal, carrying the reason to branch on, a message to show, and any
+ * data worth reporting with it. `exits` turns one into output and a status
+ * code.
+ */
+export class Exit extends Error {
+	constructor(
+		readonly reason: Reason,
+		message: string,
+		readonly data: Record<string, unknown> = {},
+	) {
+		super(message);
+	}
+}
+
+/**
+ * How a command refuses. Every call site means "and go no further", which is
+ * what the `never` return buys: the code below a `fail` is unreachable, and
+ * TypeScript narrows accordingly.
+ */
+export function fail(
+	reason: Reason,
+	message: string,
+	data: Record<string, unknown> = {},
+): never {
+	throw new Exit(reason, message, data);
+}
+
+/**
+ * Decides what a refusal looks like (a machine-readable reason on stdout, a
+ * human explanation on stderr) and is the only place that ends the process.
+ * An agent branches on the first and reads the second.
+ */
+export function exits<C extends Deps>(): Middleware<C> {
+	return async (ctx, next) => {
+		try {
+			await next(ctx);
+		} catch (e) {
+			if (!(e instanceof Exit)) {
+				throw e;
+			}
+			ctx.log.info(JSON.stringify({ reason: e.reason, ...e.data }));
+			ctx.log.error(e.message);
+			ctx.ps.exit(EXIT[e.reason]);
+		}
+	};
+}

package/git.ts

@@ -0,0 +1,294 @@
+import { type Fs, NodeFs, NodePs, type Ps } from "webappwiz/system";
+
+export interface GitResult {
+	code: number;
+	stdout: string;
+	stderr: string;
+}
+
+/**
+ * Every git call arbor makes, scoped to one repository. Agents are not allowed
+ * to run these themselves, since going through arbor is what makes concurrent
+ * work safe, so this is the only place git is spoken.
+ */
+/** What a `Git` works through; the real ones by default. */
+export interface GitOptions {
+	ps?: Ps;
+	fs?: Fs;
+}
+
+export class Git {
+	private readonly ps: Ps;
+	private readonly fs: Fs;
+
+	constructor(
+		/** The main worktree, where trunk lives. */
+		readonly root: string,
+		opts: GitOptions = {},
+	) {
+		this.ps = opts.ps ?? new NodePs();
+		this.fs = opts.fs ?? new NodeFs();
+	}
+
+	async run(cwd: string, ...args: string[]): Promise<GitResult> {
+		const { exitCode, stdout, stderr } = await this.ps.spawnCapture([
+			"git",
+			"-C",
+			cwd,
+			...args,
+		]);
+		return { code: exitCode, stdout: stdout.trim(), stderr: stderr.trim() };
+	}
+
+	async out(cwd: string, ...args: string[]): Promise<string> {
+		const result = await this.run(cwd, ...args);
+		if (result.code !== 0) {
+			throw new Error(
+				`git ${args.join(" ")}: ${result.stderr || result.stdout}`,
+			);
+		}
+		return result.stdout;
+	}
+
+	async branchExists(branch: string): Promise<boolean> {
+		const { code } = await this.run(
+			this.root,
+			"rev-parse",
+			"--verify",
+			"--quiet",
+			`refs/heads/${branch}`,
+		);
+		return code === 0;
+	}
+
+	/**
+	 * The branch `origin/HEAD` points at, or null when the repo has no such ref:
+	 * no remote, or a clone that never fetched it.
+	 */
+	async defaultBranch(): Promise<string | null> {
+		const { code, stdout } = await this.run(
+			this.root,
+			"symbolic-ref",
+			"--short",
+			"refs/remotes/origin/HEAD",
+		);
+		return code === 0 ? stdout.replace(/^origin\//, "") || null : null;
+	}
+
+	currentBranch(cwd: string): Promise<string> {
+		return this.out(cwd, "rev-parse", "--abbrev-ref", "HEAD");
+	}
+
+	head(cwd: string): Promise<string> {
+		return this.out(cwd, "rev-parse", "HEAD");
+	}
+
+	shortHead(cwd: string): Promise<string> {
+		return this.out(cwd, "rev-parse", "--short", "HEAD");
+	}
+
+	async porcelain(cwd: string): Promise<string[]> {
+		return lines(await this.out(cwd, "status", "--porcelain"));
+	}
+
+	async conflictedPaths(cwd: string): Promise<string[]> {
+		const out = await this.out(
+			cwd,
+			"diff",
+			"--name-only",
+			"--diff-filter=U",
+		).catch(() => "");
+		return lines(out);
+	}
+
+	async commitsAhead(trunk: string, branch: string): Promise<number | null> {
+		const result = await this.run(
+			this.root,
+			"rev-list",
+			"--count",
+			`${trunk}..${branch}`,
+		);
+		return result.code === 0 ? Number(result.stdout) : null;
+	}
+
+	/** Lines added and removed on `branch` since it left `trunk`. */
+	async diffStat(
+		trunk: string,
+		branch: string,
+	): Promise<{ added: number; removed: number } | null> {
+		const result = await this.run(
+			this.root,
+			"diff",
+			"--shortstat",
+			`${trunk}...${branch}`,
+		);
+		if (result.code !== 0) {
+			return null;
+		}
+		const count = (pattern: RegExp): number =>
+			Number(pattern.exec(result.stdout)?.[1] ?? 0);
+		return {
+			added: count(/(\d+) insertion/),
+			removed: count(/(\d+) deletion/),
+		};
+	}
+
+	/**
+	 * Every path `branch` touches since it left `trunk`, plus what is still
+	 * uncommitted in `worktree` when there is one: an agent mid-task has usually
+	 * committed nothing yet, and its edits are the overlap that matters most.
+	 */
+	async changedFiles(
+		trunk: string,
+		branch: string,
+		worktree: string | null,
+	): Promise<string[] | null> {
+		const committed = await this.run(
+			this.root,
+			"diff",
+			"--name-only",
+			`${trunk}...${branch}`,
+		);
+		if (committed.code !== 0) {
+			return null;
+		}
+		const paths = lines(committed.stdout);
+		if (worktree !== null) {
+			// Two calls rather than `status --porcelain`, whose leading status
+			// columns do not survive the trim every call here gets.
+			const edited = await this.run(worktree, "diff", "--name-only", "HEAD");
+			const added = await this.run(
+				worktree,
+				"ls-files",
+				"--others",
+				"--exclude-standard",
+			);
+			paths.push(...lines(edited.stdout), ...lines(added.stdout));
+		}
+		return [...new Set(paths)].sort();
+	}
+
+	/**
+	 * Every path a person might point an agent at in the tree at `cwd`: the
+	 * files git tracks, the new ones it does not ignore, and each directory
+	 * above them, which ends in `/`. Sorted, relative to the tree's root.
+	 */
+	async paths(cwd: string): Promise<string[]> {
+		const files = lines(
+			await this.out(
+				cwd,
+				"ls-files",
+				"--cached",
+				"--others",
+				"--exclude-standard",
+			),
+		);
+		const found = new Set(files);
+		for (const file of files) {
+			const parts = file.split("/");
+			for (let depth = 1; depth < parts.length; depth++) {
+				found.add(`${parts.slice(0, depth).join("/")}/`);
+			}
+		}
+		return [...found].sort();
+	}
+
+	rebase(cwd: string, onto: string): Promise<GitResult> {
+		return this.run(cwd, "rebase", onto);
+	}
+
+	resetHard(cwd: string, commit: string): Promise<GitResult> {
+		return this.run(cwd, "reset", "--hard", commit);
+	}
+
+	checkout(branch: string): Promise<GitResult> {
+		return this.run(this.root, "checkout", branch);
+	}
+
+	mergeFfOnly(cwd: string, branch: string): Promise<GitResult> {
+		return this.run(cwd, "merge", "--ff-only", branch);
+	}
+
+	/**
+	 * The worktree with `branch` checked out, or null when no worktree has it.
+	 * Git allows one worktree per branch and that is the only place the branch
+	 * can be advanced, so this is where a fast-forward has to happen.
+	 */
+	async worktreeFor(branch: string): Promise<string | null> {
+		const listing = await this.out(
+			this.root,
+			"worktree",
+			"list",
+			"--porcelain",
+		);
+		let path: string | null = null;
+		for (const line of listing.split("\n")) {
+			if (line.startsWith("worktree ")) {
+				path = line.slice("worktree ".length);
+			} else if (line === `branch refs/heads/${branch}`) {
+				return path;
+			}
+		}
+		return null;
+	}
+
+	addWorktree(branch: string, path: string, from: string): Promise<GitResult> {
+		return this.run(this.root, "worktree", "add", "-b", branch, path, from);
+	}
+
+	removeWorktree(path: string): Promise<GitResult> {
+		return this.run(this.root, "worktree", "remove", path, "--force");
+	}
+
+	/** Drops metadata for worktrees whose directories are gone. */
+	pruneWorktrees(): Promise<GitResult> {
+		return this.run(this.root, "worktree", "prune");
+	}
+
+	deleteBranch(branch: string): Promise<GitResult> {
+		return this.run(this.root, "branch", "-D", branch);
+	}
+
+	/** The one `.git` every worktree of this repo shares. */
+	commonDir(): Promise<string> {
+		return this.out(
+			this.root,
+			"rev-parse",
+			"--path-format=absolute",
+			"--git-common-dir",
+		);
+	}
+
+	/** The git directory belonging to a worktree, or null if it has none. */
+	async worktreeGitDir(worktree: string): Promise<string | null> {
+		// Guessing this from the worktree's basename would be wrong: git dedupes
+		// those names, so the directory is not always named after the worktree.
+		const raw = await this.fs.read(`${worktree}/.git`).catch(() => null);
+		return raw?.trim().replace(/^gitdir:\s*/, "") ?? null;
+	}
+
+	/** Half-finished merges and rebases a resuming agent is standing in. */
+	async interruptedOps(worktree: string): Promise<string[]> {
+		const dir = await this.worktreeGitDir(worktree);
+		if (dir === null) {
+			return [];
+		}
+		const checks: Array<[string, string]> = [
+			["rebase-merge", "rebase in progress"],
+			["rebase-apply", "rebase in progress"],
+			["MERGE_HEAD", "merge in progress"],
+			["CHERRY_PICK_HEAD", "cherry-pick in progress"],
+		];
+		const found: string[] = [];
+		for (const [entry, description] of checks) {
+			if (await this.fs.exists(`${dir}/${entry}`)) {
+				found.push(description);
+			}
+		}
+		return [...new Set(found)];
+	}
+}
+
+function lines(out: string): string[] {
+	return out === "" ? [] : out.split("\n");
+}

package/index.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env bun
+import { NodeFs } from "webappwiz/system";
+import { arbor } from "./arbor";
+import { assets } from "./dev/assets";
+
+await arbor.run({
+	fs: new NodeFs(),
+	assets,
+});