@webappwiz/arbor 0.0.28 → 0.0.30

package/progress.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "bun:test";
+import { progress } from "./progress";
+
+const plan = (...lines: string[]): string => `${lines.join("\n")}\n`;
+
+describe("progress", () => {
+	it("counts the ticked boxes against every box in Done and Next", () => {
+		expect(
+			progress(
+				plan(
+					"# alpha",
+					"",
+					"## Done",
+					"- [x] one",
+					"- [x] two",
+					"",
+					"## Next",
+					"- [ ] three",
+					"- [ ] four",
+				),
+			),
+		).toEqual({ done: 2, total: 4 });
+	});
+
+	it("ignores a checklist outside the sections that hold the work", () => {
+		expect(
+			progress(
+				plan(
+					"# alpha",
+					"",
+					"## Next",
+					"- [ ] the rest",
+					"",
+					"## Notes",
+					"- [ ] a stray box here must not count",
+				),
+			),
+		).toEqual({ done: 0, total: 1 });
+	});
+
+	it("reports nothing to count when the file has no checklist", () => {
+		expect(progress(plan("# alpha", "", "## Goal", "land it"))).toBeNull();
+	});
+
+	it("reports nothing to count when neither section is there at all", () => {
+		expect(progress(plan("- [x] a box under no heading"))).toBeNull();
+	});
+
+	it("counts an upper-case X as ticked, the way the CLI does", () => {
+		expect(
+			progress(plan("## Done", "- [X] one", "", "## Next", "- [ ] two")),
+		).toEqual({ done: 1, total: 2 });
+	});
+});

package/progress.ts

@@ -0,0 +1,31 @@
+import { Markdown } from "webappwiz/md";
+
+const BOX = /^[ \t]*- \[([ xX])\]/gm;
+
+/** The sections that hold the work, so a checklist under Notes cannot skew it. */
+const WORK = ["Done", "Next"];
+
+export interface Progress {
+	done: number;
+	total: number;
+}
+
+/**
+ * How far along a task is, counted off its `ARBOR.md` checkboxes rather than
+ * anything arbor records: the agent moving an item to `## Done` is the only
+ * signal there is that a step finished. Null when there is nothing to count,
+ * which is a task whose file has no checklist yet.
+ */
+export function progress(plan: string): Progress | null {
+	const md = Markdown.parse(plan);
+	const boxes = WORK.flatMap((name) =>
+		md.has(name) ? [...md.section(name).body.matchAll(BOX)] : [],
+	);
+	if (boxes.length === 0) {
+		return null;
+	}
+	return {
+		done: boxes.filter((box) => box[1] !== " ").length,
+		total: boxes.length,
+	};
+}

package/remove.test.ts

@@ -0,0 +1,68 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { add } from "./add";
+import { remove } from "./remove";
+import { LIVE_PID, Testing } from "./testing";
+
+describe("remove", () => {
+	let deps: Testing;
+
+	beforeEach(async () => {
+		deps = await Testing.open();
+	});
+
+	afterEach(() => deps.disposeAsync());
+
+	it("removes everything and says what was thrown away", async () => {
+		await add(deps, "alpha");
+		const worktree = (await deps.service.find("alpha")).path;
+		await deps.commit(worktree, "alpha.txt", "alpha\n", "unlanded work");
+
+		await remove(deps, "alpha");
+
+		expect(deps.out()).toContain("discarded 1 commit(s)");
+		expect(await deps.fs.exists(worktree)).toBe(false);
+		expect(await deps.fs.exists(deps.service.recordPath("alpha"))).toBe(false);
+		expect(await deps.gitCli(deps.root, "branch", "--list", "task/alpha")).toBe(
+			"",
+		);
+	});
+
+	it("tells 'already removed' apart from 'never existed'", async () => {
+		await add(deps, "alpha");
+		await remove(deps, "alpha");
+
+		await expect(remove(deps, "alpha")).toBail("already_removed");
+		await expect(remove(deps, "never")).toBail("not_found");
+	});
+
+	it("cleans up leftovers when the worktree directory is already gone", async () => {
+		await add(deps, "alpha");
+		const worktree = (await deps.service.find("alpha")).path;
+		await deps.fs.rm(worktree, { recursive: true, force: true });
+
+		await remove(deps, "alpha");
+
+		expect(deps.out()).toContain("already gone");
+		expect(await deps.gitCli(deps.root, "branch", "--list", "task/alpha")).toBe(
+			"",
+		);
+	});
+
+	it("refuses a tree another agent is driving, unless forced", async () => {
+		await add(deps, "alpha");
+		const worktree = await (await deps.service.find("alpha")).save({
+			lease: {
+				pid: LIVE_PID,
+				hostname: deps.ps.hostname,
+				heartbeatAt: new Date().toISOString(),
+			},
+		});
+
+		await expect(remove(deps, "alpha")).toBail("lease_held", {
+			message: "--force",
+		});
+
+		await remove(deps, "alpha", { force: true });
+		expect(await deps.fs.exists(worktree.path)).toBe(false);
+	});
+});

package/remove.ts

@@ -0,0 +1,88 @@
+import { color, type Logger } from "webappwiz/log";
+import { fail } from "./exit";
+import type { Todos } from "./todo";
+import type { WorktreeService } from "./worktree-service";
+
+export interface RemoveOptions {
+	/** Discard the tree even when another agent holds its lease. */
+	force?: boolean;
+}
+
+/**
+ * Discards a whole task: `git worktree remove` plus the branch and the
+ * record.
+ *
+ * Throwing a task away and redoing it against current trunk is usually cheaper
+ * than a hard rebase, so this is meant to be used freely.
+ */
+export async function remove(
+	{
+		service,
+		log,
+		todos,
+	}: { service: WorktreeService; log: Logger; todos: Todos },
+	task: string,
+	{ force = false }: RemoveOptions = {},
+): Promise<void> {
+	const worktree = await service.find(task);
+
+	if (worktree.gone) {
+		const removed = worktree.status === "removed";
+		fail(
+			removed ? "already_removed" : "not_found",
+			removed
+				? `'${task}' was already removed (${worktree.removedAt}), nothing left to remove`
+				: `no worktree, branch or state file named '${task}', so it never existed here`,
+			{ task },
+		);
+	}
+
+	if (worktree.leaseHeldByOther) {
+		if (!force) {
+			fail(
+				"lease_held",
+				`'${task}' is held by pid ${worktree.lease?.pid} on ${worktree.lease?.hostname}: pass --force to discard it anyway`,
+				{ task, lease: worktree.lease },
+			);
+		}
+		log.error(
+			color.yellow(
+				`arbor: --force discarding a tree held by pid ${worktree.lease?.pid}`,
+			),
+		);
+	}
+
+	// Counted before the branch goes, so the report can say what was lost.
+	const unlanded = worktree.hasBranch ? await worktree.commitsAhead() : 0;
+
+	const discarded = await worktree.discard();
+	if (discarded.code !== 0) {
+		fail("usage", `discarding '${task}' failed: ${discarded.stderr}`, {
+			task,
+		});
+	}
+
+	// The work was thrown away, not done, so what it took up is open again.
+	const released = await todos.takenBy(task);
+	for (const todo of released) {
+		await todo.release();
+	}
+
+	const lines = [
+		`${color.green("removed")} ${task}`,
+		`  worktree: ${worktree.exists ? worktree.path : "already gone"}`,
+		`  branch:   ${worktree.hasBranch ? worktree.branch : "already gone"}`,
+		`  state:    ${worktree.state ? "removed" : "already gone"}`,
+	];
+	if (unlanded) {
+		lines.push(
+			color.yellow(
+				`  discarded ${unlanded} commit(s) that were never on ${worktree.base}`,
+			),
+		);
+	}
+	for (const todo of released) {
+		lines.push(`  todo ${todo.id} is open again: ${todo.subject}`);
+	}
+	log.info(lines.join("\n"));
+}

package/repository.ts

@@ -0,0 +1,83 @@
+import { dirname } from "node:path";
+import type { Deps, Middleware } from "webappwiz/cmd";
+import { FileLock, type Fs, type Lock } from "webappwiz/system";
+import type { Config } from "./config";
+import { Git } from "./git";
+import { Journal } from "./journal";
+import { loadConfig } from "./load-config";
+import { Shell } from "./shell";
+import { Todos } from "./todo";
+import { WorktreeService } from "./worktree-service";
+
+/** What a command gets to work with, once there is a repository to work in. */
+export interface Repository {
+	config: Config;
+	git: Git;
+	service: WorktreeService;
+	lock: Lock;
+	shell: Shell;
+	journal: Journal;
+	todos: Todos;
+}
+
+/**
+ * Runs the action against the repository `cwd` sits in, and refuses to run it
+ * at all when that is not a repository.
+ */
+export function repository<C extends Deps & { fs: Fs }>(
+	at?: string,
+): Middleware<C, C & Repository> {
+	// Nothing below here touches `Fs` or `Ps`: this is the only place they are
+	// spoken.
+	return async (ctx, next) => {
+		const { fs, ps, log } = ctx;
+		const cwd = at ?? ps.cwd();
+		const { exitCode, stdout } = await ps.spawnCapture([
+			"git",
+			"-C",
+			cwd,
+			"rev-parse",
+			"--path-format=absolute",
+			"--git-common-dir",
+		]);
+		if (exitCode !== 0) {
+			throw new Error(`not a git repository: ${cwd}`);
+		}
+		// Every worktree shares one `.git`, so state kept under it is visible to
+		// every agent and is inherently untracked.
+		const gitDir = stdout.trim();
+		const arborDir = `${gitDir}/arbor`;
+
+		const git = new Git(dirname(gitDir), { ps, fs });
+		const config = await loadConfig(dirname(gitDir), { fs, git });
+		const service = new WorktreeService(git, config, arborDir, { fs, ps });
+		await service.init();
+
+		await next({
+			...ctx,
+			config,
+			git,
+			service,
+			lock: new FileLock(`${arborDir}/merge.lock`, {
+				fs,
+				ps,
+				log,
+				stalenessMs: config.leaseStalenessMs,
+			}),
+			shell: new Shell({ ps }),
+			journal: new Journal(`${arborDir}/log.jsonl`, config.logCapacity, {
+				fs,
+			}),
+			todos: new Todos(
+				`${arborDir}/todos`,
+				new FileLock(`${arborDir}/todos.lock`, {
+					fs,
+					ps,
+					log,
+					stalenessMs: config.leaseStalenessMs,
+				}),
+				{ fs },
+			),
+		});
+	};
+}

package/retry.test.ts

@@ -0,0 +1,43 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { add } from "./add";
+import { retry } from "./retry";
+import { Testing } from "./testing";
+
+describe("retry", () => {
+	let deps: Testing;
+
+	beforeEach(async () => {
+		deps = await Testing.open();
+	});
+
+	afterEach(() => deps.disposeAsync());
+
+	it("puts an escalated task back to working with a fresh budget", async () => {
+		await add(deps, "alpha");
+		const spent = await deps.service.find("alpha");
+		await spent.save({
+			status: "escalated",
+			mergeAttempts: deps.config.mergeRetryCount,
+		});
+
+		await retry(deps, "alpha");
+
+		expect((await deps.service.find("alpha")).state).toMatchObject({
+			status: "working",
+			mergeAttempts: 0,
+		});
+	});
+
+	it("refuses a task nobody has escalated", async () => {
+		await add(deps, "alpha");
+
+		await expect(retry(deps, "alpha")).toBail("usage", {
+			message: "not escalated",
+		});
+		expect((await deps.service.find("alpha")).state?.status).toBe("working");
+	});
+
+	it("refuses a name with no task", async () => {
+		await expect(retry(deps, "nope")).toBail("not_found");
+	});
+});

package/retry.ts

@@ -0,0 +1,48 @@
+import { color, type Logger } from "webappwiz/log";
+import type { Config } from "./config";
+import { fail } from "./exit";
+import type { WorktreeService } from "./worktree-service";
+
+/**
+ * The way back from `budget_exhausted`. A task that has spent its merge
+ * attempts gets another `mergeRetryCount` of them, instead of `remove` and redo.
+ *
+ * Only from `escalated`, and deliberately: the budget's whole job is to make an
+ * agent stop and hand the task over. An agent that could grant itself more
+ * would be back to grinding against a moving trunk forever, so the price of a
+ * fresh budget is that a human has looked at the tree first.
+ */
+export async function retry(
+	{
+		service,
+		config,
+		log,
+	}: { service: WorktreeService; config: Config; log: Logger },
+	task: string,
+): Promise<void> {
+	const found = await service.find(task);
+	if (found.gone) {
+		fail("not_found", `no task '${task}'`, { task });
+	}
+	if (found.status !== "escalated") {
+		fail(
+			"usage",
+			`'${task}' is ${found.status}, not escalated: only a task handed to a human can be granted more merge attempts`,
+			{ task, status: found.status },
+		);
+	}
+
+	// The lease stays as escalate left it: whoever picks the task up takes it
+	// with `claim`, the same as any other resume.
+	const worktree = await found.save({ status: "working", mergeAttempts: 0 });
+
+	log.info(
+		[
+			`${color.green("retry")} ${worktree.task}`,
+			`  attempts: 0 of ${config.mergeRetryCount}`,
+			`  status:   working`,
+			"",
+			`Run \`arbor claim ${worktree.task}\` to pick it up.`,
+		].join("\n"),
+	);
+}

package/shell.ts

@@ -0,0 +1,44 @@
+import {
+	NodePs,
+	type Ps,
+	type SpawnCaptureResult,
+	type SpawnOptions,
+	type SpawnResult,
+} from "webappwiz/system";
+
+/** What a `Shell` spawns through; the real process by default. */
+export interface ShellOptions {
+	ps?: Ps;
+}
+
+/**
+ * Runs the commands a repo configures (the lifecycle hooks) as shell strings
+ * rather than argv, since that is how a repo writes them.
+ */
+export class Shell {
+	private readonly ps: Ps;
+
+	// This is the whole of what `merge` and `add` are allowed to do to the
+	// process. Handing them a `Ps` instead would hand them `exit` and `cd` too.
+	constructor(opts: ShellOptions = {}) {
+		this.ps = opts.ps ?? new NodePs();
+	}
+
+	/** Captures output, for commands whose failure has to be reported back. */
+	run(
+		command: string,
+		cwd: string,
+		opts: SpawnOptions = {},
+	): Promise<SpawnCaptureResult> {
+		return this.ps.spawnCapture(["sh", "-c", command], { ...opts, cwd });
+	}
+
+	/** Inherits stdio, for commands the agent should watch as they run. */
+	stream(
+		command: string,
+		cwd: string,
+		opts: SpawnOptions = {},
+	): Promise<SpawnResult> {
+		return this.ps.spawn(["sh", "-c", command], { ...opts, cwd });
+	}
+}

package/show.test.ts

@@ -0,0 +1,91 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { add } from "./add";
+import { show } from "./show";
+import { Testing } from "./testing";
+
+describe("show", () => {
+	let deps: Testing;
+
+	beforeEach(async () => {
+		deps = await Testing.open();
+	});
+
+	afterEach(() => deps.disposeAsync());
+
+	it("reports a task and prints the ARBOR.md left in its worktree", async () => {
+		await add(deps, "alpha");
+		const alpha = (await deps.service.find("alpha")).path;
+		await deps.fs.write(
+			`${alpha}/ARBOR.md`,
+			"# alpha\n\n## Next\n- [ ] the rest\n",
+		);
+		deps.log.clear();
+
+		await show(deps, "alpha");
+
+		expect(deps.out()).toContain("task/alpha");
+		expect(deps.out()).toContain("working");
+		expect(deps.out()).toContain("- [ ] the rest");
+	});
+
+	it("says how an ARBOR.md departs from the shape the skill prescribes", async () => {
+		await add(deps, "alpha");
+		const alpha = (await deps.service.find("alpha")).path;
+		await deps.fs.write(
+			`${alpha}/ARBOR.md`,
+			"# something else\n\n## Goal\nland it\n",
+		);
+		deps.log.clear();
+
+		await show(deps, "alpha");
+
+		expect(deps.out()).toContain('should be "# alpha"');
+		expect(deps.out()).toContain("no ## Next section");
+	});
+
+	it("says the ARBOR.md is missing rather than staying silent", async () => {
+		await add(deps, "alpha");
+		const alpha = (await deps.service.find("alpha")).path;
+		await deps.fs.rm(`${alpha}/ARBOR.md`);
+		deps.log.clear();
+
+		await show(deps, "alpha");
+
+		expect(deps.out()).toContain("no ARBOR.md");
+	});
+
+	it("carries the task's fields and its ARBOR.md as JSON", async () => {
+		await add(deps, "alpha");
+		const alpha = (await deps.service.find("alpha")).path;
+		await deps.fs.write(`${alpha}/ARBOR.md`, "# alpha\n");
+		deps.log.clear();
+
+		await show(deps, "alpha", { json: true });
+
+		expect(JSON.parse(deps.out())).toMatchObject({
+			task: "alpha",
+			status: "working",
+			branch: "task/alpha",
+			ahead: 0,
+			plan: "# alpha\n",
+		});
+	});
+
+	it("refuses a task that was never created", async () => {
+		await expect(show(deps, "ghost")).toBail("not_found");
+	});
+
+	it("still describes a task whose worktree is gone", async () => {
+		await add(deps, "alpha");
+		await deps.fs.rm((await deps.service.find("alpha")).path, {
+			recursive: true,
+			force: true,
+		});
+		deps.log.clear();
+
+		await show(deps, "alpha");
+
+		expect(deps.out()).toContain("orphaned");
+		expect(deps.out()).not.toContain("no ARBOR.md");
+	});
+});