@webappwiz/arbor 0.0.28 → 0.0.30

package/claim.test.ts

@@ -0,0 +1,89 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { add } from "./add";
+import { claim } from "./claim";
+import { LIVE_PID, Testing } from "./testing";
+
+describe("claim", () => {
+	let deps: Testing;
+
+	beforeEach(async () => {
+		deps = await Testing.open();
+	});
+
+	afterEach(() => deps.disposeAsync());
+
+	it("refuses a live lease and takes a cold one", async () => {
+		await add(deps, "alpha");
+		await (await deps.service.find("alpha")).save({
+			lease: {
+				pid: LIVE_PID,
+				hostname: deps.ps.hostname,
+				heartbeatAt: new Date().toISOString(),
+			},
+		});
+
+		await expect(claim(deps, "alpha")).toBail("lease_held");
+
+		// The same lease, gone cold because the heartbeat aged out.
+		await (await deps.service.find("alpha")).save({
+			lease: {
+				pid: LIVE_PID,
+				hostname: deps.ps.hostname,
+				heartbeatAt: new Date(Date.now() - 120_000).toISOString(),
+			},
+		});
+		await claim(deps, "alpha");
+
+		expect((await deps.service.find("alpha")).state?.lease?.pid).toBe(
+			deps.ps.pid,
+		);
+		expect(deps.out()).toContain("claimed alpha");
+	});
+
+	it("rebuilds a missing record and reports an interrupted rebase", async () => {
+		await add(deps, "alpha");
+		const worktree = (await deps.service.find("alpha")).path;
+
+		await deps.commit(deps.root, "README.md", "trunk side\n", "trunk");
+		await deps.commit(worktree, "README.md", "task side\n", "task");
+		await deps.ps.spawnCapture(["git", "-C", worktree, "rebase", "main"]);
+		await deps.fs.rm(deps.service.recordPath("alpha"));
+
+		await claim(deps, "alpha");
+
+		expect(deps.out()).toContain("state file rebuilt from disk");
+		expect(deps.out()).toContain("rebase in progress");
+		expect((await deps.service.find("alpha")).state).toMatchObject({
+			branch: "task/alpha",
+		});
+	});
+
+	it("reports a record whose worktree is gone as orphaned", async () => {
+		await add(deps, "alpha");
+		const worktree = (await deps.service.find("alpha")).path;
+		await deps.fs.rm(worktree, { recursive: true, force: true });
+
+		await expect(claim(deps, "alpha")).toBail("orphaned", {
+			message: "arbor remove alpha",
+		});
+	});
+
+	it("puts an escalated task back to working, keeping its budget", async () => {
+		await add(deps, "alpha");
+		await (await deps.service.find("alpha")).save({
+			status: "escalated",
+			lease: null,
+			mergeAttempts: 1,
+			escalations: [{ reason: "needs a look", at: new Date().toISOString() }],
+		});
+
+		await claim(deps, "alpha");
+
+		expect((await deps.service.find("alpha")).state).toMatchObject({
+			status: "working",
+			mergeAttempts: 1,
+			escalations: [{ reason: "needs a look" }],
+		});
+		expect(deps.out()).toContain("status:   working (was escalated)");
+	});
+});

package/claim.ts

@@ -0,0 +1,73 @@
+import { color, type Logger } from "webappwiz/log";
+import { fail } from "./exit";
+import type { WorktreeService } from "./worktree-service";
+
+/**
+ * The resume entry point: a fresh agent thread picking up existing work. An
+ * escalated task goes back to `working`, since someone is on it again; its
+ * merge budget stays as it was, which only `retry` refills.
+ */
+export async function claim(
+	{ service, log }: { service: WorktreeService; log: Logger },
+	task: string,
+): Promise<void> {
+	const found = await service.find(task);
+
+	if (found.gone) {
+		fail("not_found", `no task '${task}': run \`arbor add ${task}\``, {
+			task,
+		});
+	}
+	if (found.status === "orphaned") {
+		fail(
+			"orphaned",
+			`state file for '${task}' has no worktree at ${found.path}: run \`arbor remove ${task}\``,
+			{ task, worktree: found.path },
+		);
+	}
+	if (found.status === "stray") {
+		fail(
+			"orphaned",
+			`branch ${found.branch} exists but has no worktree: run \`arbor remove ${task}\` and start over`,
+			{ task, branch: found.branch },
+		);
+	}
+	if (found.leaseHeldByOther) {
+		fail(
+			"lease_held",
+			`'${task}' is held by pid ${found.lease?.pid} on ${found.lease?.hostname} (heartbeat ${found.lease?.heartbeatAt}): another agent is driving this tree`,
+			{ task, lease: found.lease },
+		);
+	}
+
+	// A worktree with no readable record is still work: `save` writes a fresh
+	// one rather than refusing the resume.
+	const rebuilt = found.state === null;
+	const escalated = found.status === "escalated";
+	const worktree = await found.take(escalated ? { status: "working" } : {});
+
+	const interrupted = await worktree.interruptedOps();
+	const changes = await worktree.uncommitted();
+	const lines = [
+		`${color.green("claimed")} ${worktree.task}`,
+		`  worktree: ${worktree.path}`,
+		`  branch:   ${worktree.branch}`,
+		`  status:   ${worktree.status}${escalated ? " (was escalated)" : ""}`,
+		`  attempts: ${worktree.mergeAttempts}`,
+	];
+	if (rebuilt) {
+		lines.push(`  ${color.yellow("note: state file rebuilt from disk")}`);
+	}
+	if (interrupted.length > 0) {
+		lines.push(
+			`  ${color.red(`interrupted git operation: ${interrupted.join(", ")}`)}`,
+			"  resolve it before merging: you are standing in a half-finished operation",
+		);
+	}
+	lines.push(
+		changes.length === 0
+			? "  uncommitted: none"
+			: `  uncommitted (${changes.length}):\n${changes.map((change) => `    ${change}`).join("\n")}`,
+	);
+	log.info(lines.join("\n"));
+}

package/components.json

@@ -0,0 +1,21 @@
+{
+	"$schema": "https://ui.shadcn.com/schema.json",
+	"style": "base-nova",
+	"rsc": false,
+	"tsx": true,
+	"tailwind": {
+		"config": "",
+		"css": "dev/styles.css",
+		"baseColor": "neutral",
+		"cssVariables": true,
+		"prefix": ""
+	},
+	"iconLibrary": "lucide",
+	"aliases": {
+		"components": "#dev/components",
+		"utils": "#dev/lib/utils.ts",
+		"ui": "#dev/components/ui",
+		"lib": "#dev/lib",
+		"hooks": "#dev/hooks"
+	}
+}

package/config.ts

@@ -0,0 +1,58 @@
+export interface Config {
+	/**
+	 * The integration branch name. `merge` rebases a task onto this branch and
+	 * then fast-forwards it to the result; new worktrees start from it.
+	 */
+	trunk: string;
+	/** Directory holding one worktree per task, a sibling of the repo. */
+	worktreeRoot: string;
+	/** Command run by `add` in the new worktree, via `sh -c`. */
+	postCheckout: string | null;
+	/**
+	 * Command run by `merge` after the rebase, before `preMerge`, via `sh -c`.
+	 * A rebase can bring in a dependency the worktree has never installed, and
+	 * whatever `preMerge` runs needs it.
+	 */
+	postRewrite: string | null;
+	/**
+	 * Command run by `merge` after the rebase, via `sh -c`. The last gate before
+	 * the branch lands: a nonzero exit rolls the branch back and leaves the base
+	 * untouched. Tests are the obvious thing to put here, but arbor has no
+	 * opinion; a repo with nothing to run leaves it null and merges on a green
+	 * rebase alone.
+	 */
+	preMerge: string | null;
+	/**
+	 * Command run by `merge` in the main tree after the base fast-forwards, via
+	 * `sh -c`. The branch has already landed and the worktree is gone: a nonzero
+	 * exit reports the failure but rolls nothing back.
+	 */
+	postMerge: string | null;
+	/** How long since its last heartbeat before a task's lease is up for grabs. */
+	leaseStalenessMs: number;
+	/** Failed `merge` attempts a task gets before it must escalate or be removed. */
+	mergeRetryCount: number;
+	/**
+	 * How many removed task names to keep, so `remove` can say "already removed"
+	 * rather than "never existed". A flat cap with no age policy: losing the
+	 * oldest costs a nicer message and nothing else.
+	 */
+	removedCapacity: number;
+	/** How many entries `arbor log` keeps before the oldest fall off. */
+	logCapacity: number;
+	/**
+	 * How long a todo can wait before `merge` stops recommending it and offers
+	 * it for removal instead: work deferred that long has usually been done
+	 * some other way, or stopped mattering.
+	 */
+	todoStalenessMs: number;
+}
+
+/**
+ * Identity, for the types. `export default defineConfig({ ... })` in
+ * `arbor.config.ts` gets the key names and their types checked, and completion
+ * while writing it; a bare object literal gets neither.
+ */
+export function defineConfig(config: Partial<Config>): Partial<Config> {
+	return config;
+}

package/dev/api.ts

@@ -0,0 +1,120 @@
+/**
+ * The page's writes: the same core functions as `arbor todo add`, `update`
+ * and `remove`.
+ * A refusal comes back as the CLI's own reason and message, thrown so the
+ * caller can show it.
+ */
+
+export class ApiError extends Error {
+	constructor(
+		readonly reason: string,
+		message: string,
+	) {
+		super(message);
+	}
+}
+
+async function send(path: string, init: RequestInit): Promise<unknown> {
+	const response = await fetch(path, { method: "POST", ...init });
+	const body = (await response.json().catch(() => ({}))) as {
+		reason?: string;
+		message?: string;
+	};
+	if (!response.ok) {
+		throw new ApiError(
+			body.reason ?? "error",
+			body.message ?? `${path}: ${response.status}`,
+		);
+	}
+	return body;
+}
+
+/** A todo's files: new ones to add, and the stored ones to keep. */
+export interface FilesForm {
+	files: File[];
+	/** Paths of files already stored to keep; the rest are dropped. */
+	keep: string[];
+}
+
+/** What a todo says: a line, and whatever more there is to say. */
+export interface TodoForm {
+	subject: string;
+	text: string;
+	/** Where it goes in the list, 1 at the top; absent leaves it be. */
+	position?: number;
+	/** Its tags from now on; absent leaves them be. */
+	tags?: string[];
+}
+
+export async function addTodo(
+	{ subject, text, position }: TodoForm,
+	files: File[],
+): Promise<void> {
+	const form = filesForm({ files, keep: [] });
+	todoForm(form, { subject, text, position });
+	await send("/api/todos", { body: form });
+}
+
+export async function updateTodo(
+	id: number,
+	{ subject, text, position, tags, files, keep }: FilesForm & TodoForm,
+): Promise<void> {
+	const form = filesForm({ files, keep });
+	todoForm(form, { subject, text, position, tags });
+	await send(`/api/todos/${id}`, { method: "PATCH", body: form });
+}
+
+/** Puts a todo at `position`, 1 at the top, moving the rest around it. */
+export async function moveTodo(id: number, position: number): Promise<void> {
+	await send(`/api/todos/${id}/position`, {
+		method: "PUT",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({ position }),
+	});
+}
+
+export async function removeTodo(id: number): Promise<void> {
+	await send(`/api/todos/${id}`, { method: "DELETE" });
+}
+
+/** Where the page loads a file a todo holds. */
+export function fileUrl(path: string): string {
+	return `/api/file?${new URLSearchParams({ path })}`;
+}
+
+function todoForm(
+	form: FormData,
+	{ subject, text, position, tags }: TodoForm,
+): void {
+	form.set("subject", subject);
+	form.set("text", text);
+	if (position !== undefined) {
+		form.set("position", String(position));
+	}
+	if (tags !== undefined) {
+		form.set("tags", tags.join(","));
+	}
+}
+
+function filesForm({ files, keep }: FilesForm): FormData {
+	const form = new FormData();
+	for (const file of files) {
+		form.append("file", file, file.name);
+	}
+	for (const path of keep) {
+		form.append("keep", path);
+	}
+	return form;
+}
+
+/**
+ * The files and directories (ending in `/`) a task's tree holds, or the main
+ * tree's for none: what `@` offers.
+ */
+export async function paths(task = ""): Promise<string[]> {
+	const response = await fetch(`/api/paths?${new URLSearchParams({ task })}`);
+	if (!response.ok) {
+		throw new ApiError("error", `/api/paths: ${response.status}`);
+	}
+	return (await response.json()) as string[];
+}