@webappwiz/arbor 0.0.30 → 0.0.31

package/wait.test.ts

@@ -1,61 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from "bun:test";
-import { Duration, sleep } from "webappwiz/time";
-import { add } from "./add";
-import { remove } from "./remove";
-import { Testing } from "./testing";
-import { wait } from "./wait";
-
-/** Long enough that a test only reaches it when waiting is genuinely stuck. */
-const PATIENT = { timeout: Duration.secs(5), poll: Duration.ms(5) };
-
-describe("wait", () => {
-	let deps: Testing;
-
-	beforeEach(async () => {
-		deps = await Testing.open();
-	});
-
-	afterEach(() => deps.disposeAsync());
-
-	it("returns with the reason once a task escalates while it waits", async () => {
-		await add(deps, "alpha");
-		deps.log.clear();
-
-		const waiting = wait(deps, "alpha", PATIENT);
-		await sleep(Duration.ms(20));
-		await (await deps.service.find("alpha")).save({
-			status: "escalated",
-			escalations: [{ reason: "needs a human", at: new Date().toISOString() }],
-		});
-		await waiting;
-
-		expect(deps.out()).toContain("escalated");
-		expect(deps.out()).toContain("needs a human");
-	});
-
-	it("returns once nothing is left of the task", async () => {
-		await add(deps, "alpha");
-		await remove(deps, "alpha");
-		deps.log.clear();
-
-		await wait(deps, "alpha", PATIENT);
-
-		expect(deps.out()).toContain("removed");
-		expect(deps.out()).toContain("arbor log");
-	});
-
-	it("gives up on a task that keeps working", async () => {
-		await add(deps, "alpha");
-
-		await expect(
-			wait(deps, "alpha", { timeout: Duration.ms(20), poll: Duration.ms(5) }),
-		).toBail("timeout", {
-			message: "still working",
-			data: { task: "alpha", status: "working" },
-		});
-	});
-
-	it("refuses a name nothing remembers", async () => {
-		await expect(wait(deps, "nope", PATIENT)).toBail("not_found");
-	});
-});

package/wait.ts

@@ -1,77 +0,0 @@
-import { color, type Logger } from "webappwiz/log";
-import { Duration, sleep } from "webappwiz/time";
-import { fail } from "./exit";
-import type { Worktree, WorktreeStatus } from "./worktree";
-import type { WorktreeService } from "./worktree-service";
-
-/** How long `wait` gives a task before handing the wait back to its caller. */
-export const DEFAULT_TIMEOUT = Duration.mins(15);
-
-/** How often the task's record is re-read. Cheap: a file and two git refs. */
-const POLL = Duration.secs(2);
-
-/** The only two statuses a task moves on from by itself. */
-const RUNNING: WorktreeStatus[] = ["working", "merging"];
-
-export interface WaitOptions {
-	/** How long to wait before giving up. */
-	timeout?: Duration;
-	/** How long between reads of the record; the default suits a human's patience. */
-	poll?: Duration;
-}
-
-/**
- * Blocks until a task stops moving: merged or removed (both leave the name
- * `removed`), escalated to a human, or broken. Waiting is for the agent whose
- * own work overlaps this one's and would rather rebase onto the result than
- * against it, which is why the timeout is short enough to come back and think
- * again rather than block a session for an afternoon.
- */
-export async function wait(
-	{ service, log }: { service: WorktreeService; log: Logger },
-	task: string,
-	{ timeout = DEFAULT_TIMEOUT, poll = POLL }: WaitOptions = {},
-): Promise<void> {
-	const deadline = Date.now() + timeout.ms;
-	for (;;) {
-		const worktree = await service.find(task);
-		// `removed` is a task that landed or was discarded, and is what waiting
-		// for one usually ends in. `absent` is a name nothing remembers, which
-		// is a typo, not an ending.
-		if (worktree.status === "absent") {
-			fail(
-				"not_found",
-				`no task '${task}': run \`arbor list\` to see what there is`,
-				{ task },
-			);
-		}
-		if (!RUNNING.includes(worktree.status)) {
-			log.info(report(worktree));
-			return;
-		}
-		const left = deadline - Date.now();
-		if (left <= 0) {
-			fail(
-				"timeout",
-				`'${task}' is still ${worktree.status} after ${timeout.secs}s: wait again, work alongside it and accept the rebase, or ask the human`,
-				{ task, status: worktree.status },
-			);
-		}
-		await sleep(Duration.min(poll, Duration.ms(left)));
-	}
-}
-
-function report(worktree: Worktree): string {
-	const lines = [`${color.bold(worktree.task)} ${worktree.status}`];
-	const escalation = worktree.state?.escalations?.at(-1)?.reason;
-	if (escalation) {
-		lines.push(`  ${color.yellow(`escalated: ${escalation}`)}`);
-	}
-	if (worktree.status === "removed") {
-		lines.push(
-			"",
-			`Nothing left of it here: \`arbor log\` says whether it landed.`,
-		);
-	}
-	return lines.join("\n");
-}

package/worktree-service.test.ts

@@ -1,158 +0,0 @@
-// scry-ignore-file one-class-per-file: the same two fakes are local to this suite
-import { beforeEach, describe, expect, it } from "bun:test";
-import type { Fs, MkdirOptions, RmOptions, StatResult } from "webappwiz/system";
-import { FakeFs, FakePs } from "webappwiz/system/testing";
-import type { Config } from "./config";
-import { Git } from "./git";
-import { WorktreeService } from "./worktree-service";
-
-/** Records every filesystem call so the write path can be asserted on. */
-class RecordingFs implements Fs {
-	readonly ops: string[] = [];
-
-	constructor(private readonly inner: Fs) {}
-
-	exists(path: string): Promise<boolean> {
-		return this.inner.exists(path);
-	}
-	mkdir(path: string, opts?: MkdirOptions): Promise<void> {
-		return this.inner.mkdir(path, opts);
-	}
-	read(path: string): Promise<string> {
-		return this.inner.read(path);
-	}
-	write(path: string, data: string): Promise<void> {
-		this.ops.push(`write ${path}`);
-		return this.inner.write(path, data);
-	}
-	readBytes(path: string): Promise<Uint8Array> {
-		return this.inner.readBytes(path);
-	}
-	writeBytes(path: string, data: Uint8Array): Promise<void> {
-		this.ops.push(`writeBytes ${path}`);
-		return this.inner.writeBytes(path, data);
-	}
-	rename(from: string, to: string): Promise<void> {
-		this.ops.push(`rename ${from} -> ${to}`);
-		return this.inner.rename(from, to);
-	}
-	readdir(path: string): Promise<string[]> {
-		return this.inner.readdir(path);
-	}
-	stat(path: string): Promise<StatResult> {
-		return this.inner.stat(path);
-	}
-	rm(path: string, opts?: RmOptions): Promise<void> {
-		return this.inner.rm(path, opts);
-	}
-}
-
-/** Dies halfway through a write, leaving a truncated file behind. */
-class CrashingFs extends FakeFs {
-	crash = false;
-
-	override async write(path: string, data: string): Promise<void> {
-		if (!this.crash) {
-			return super.write(path, data);
-		}
-		await super.write(path, data.slice(0, data.length / 2));
-		throw new Error("boom");
-	}
-}
-
-describe("WorktreeService", () => {
-	const ARBOR_DIR = "/repo/.git/arbor";
-	let ps: FakePs;
-	let config: Config;
-
-	beforeEach(() => {
-		ps = new FakePs();
-		config = {
-			trunk: "main",
-			worktreeRoot: "/repo-arbor",
-			postCheckout: null,
-			postRewrite: null,
-			preMerge: "true",
-			postMerge: null,
-			leaseStalenessMs: 90_000,
-			mergeRetryCount: 2,
-			removedCapacity: 50,
-			logCapacity: 200,
-			todoStalenessMs: 30 * 24 * 60 * 60 * 1000,
-		};
-	});
-
-	const git = (fs: Fs) => new Git("/repo", { ps: ps, fs: fs });
-
-	it("lands a record by rename, never by writing in place", async () => {
-		const fs = new RecordingFs(new FakeFs());
-		const worktrees = new WorktreeService(git(fs), config, ARBOR_DIR, {
-			fs: fs,
-			ps: ps,
-		});
-
-		await (await worktrees.find("alpha")).save();
-
-		const path = worktrees.recordPath("alpha");
-		expect(fs.ops).toEqual([
-			`write ${path}.4242.tmp`,
-			`rename ${path}.4242.tmp -> ${path}`,
-		]);
-		expect((await worktrees.find("alpha")).state).toMatchObject({
-			task: "alpha",
-		});
-	});
-
-	it("leaves the previous record readable when a write dies partway", async () => {
-		const fs = new CrashingFs();
-		const worktrees = new WorktreeService(git(fs), config, ARBOR_DIR, {
-			fs: fs,
-			ps: ps,
-		});
-		const saved = await (await worktrees.find("alpha")).save({
-			mergeAttempts: 1,
-		});
-
-		fs.crash = true;
-		await expect(saved.save({ mergeAttempts: 2 })).rejects.toThrow("boom");
-
-		// The truncated bytes went to the temp path; the record itself never moved.
-		expect((await worktrees.find("alpha")).state).toMatchObject({
-			mergeAttempts: 1,
-		});
-	});
-
-	it("reports unknown, not absent, when a record will not parse", async () => {
-		const fs = new FakeFs();
-		ps.exit(1); // every spawn now fails, so git reports no such branch
-		const worktrees = new WorktreeService(git(fs), config, ARBOR_DIR, {
-			fs: fs,
-			ps: ps,
-		});
-		await fs.write(worktrees.recordPath("alpha"), "{not json");
-
-		expect((await worktrees.find("alpha")).status).toBe("unknown");
-		expect((await worktrees.find("missing")).status).toBe("absent");
-	});
-
-	it("drops the oldest removed names when the memory is full", async () => {
-		const fs = new FakeFs();
-		config.removedCapacity = 2;
-		const worktrees = new WorktreeService(git(fs), config, ARBOR_DIR, {
-			fs: fs,
-			ps: ps,
-		});
-		const removed = `${ARBOR_DIR}/removed`;
-		await worktrees.init();
-
-		// Seeded with distinct timestamps, since four discards in the same
-		// millisecond would have nothing to order them by.
-		await fs.write(`${removed}/oldest`, "2026-01-01T00:00:00.000Z\n");
-		await fs.write(`${removed}/middle`, "2026-02-01T00:00:00.000Z\n");
-		await fs.write(`${removed}/newest`, "2026-03-01T00:00:00.000Z\n");
-
-		await worktrees.discard(await worktrees.find("alpha"));
-
-		expect((await fs.readdir(removed)).sort()).toEqual(["alpha", "newest"]);
-	});
-});

package/worktree-service.ts

@@ -1,193 +0,0 @@
-import { resolve } from "node:path";
-import { type Fs, NodeFs, NodePs, type Ps } from "webappwiz/system";
-import type { Config } from "./config";
-import type { Git, GitResult } from "./git";
-import { type TaskState, Worktree } from "./worktree";
-
-const BRANCH_PREFIX = "task/";
-
-export interface AddOptions {
-	/** Branch the new worktree starts from. Defaults to the trunk. */
-	base?: string;
-}
-
-/**
- * Where tasks live and everything persistent about them: the worktree
- * directories, the records under `.git/arbor/tasks`, and the names of tasks
- * already removed. One name, one lookup, whatever state it turns out to be in.
- */
-/** What a `WorktreeService` works through; the real ones by default. */
-export interface WorktreeServiceOptions {
-	fs?: Fs;
-	ps?: Ps;
-}
-
-export class WorktreeService {
-	private readonly tasksDir: string;
-	private readonly removedDir: string;
-	private readonly fs: Fs;
-	readonly ps: Ps;
-
-	// scry-ignore classes-over-function-exports: Git is the only way arbor speaks git and a second implementation is not coming, so there is no interface to write; tests run the real Git against a throwaway repo rather than faking twenty methods
-	constructor(
-		readonly git: Git,
-		readonly config: Config,
-		arborDir: string,
-		opts: WorktreeServiceOptions = {},
-	) {
-		this.fs = opts.fs ?? new NodeFs();
-		this.ps = opts.ps ?? new NodePs();
-		this.tasksDir = `${arborDir}/tasks`;
-		this.removedDir = `${arborDir}/removed`;
-	}
-
-	async init(): Promise<void> {
-		await this.fs.mkdir(this.tasksDir);
-		await this.fs.mkdir(this.removedDir);
-	}
-
-	get trunk(): string {
-		return this.config.trunk;
-	}
-
-	/** Where a task's worktree lives: a sibling of the repo, never inside it. */
-	pathFor(task: string): string {
-		return resolve(this.config.worktreeRoot, task);
-	}
-
-	branchFor(task: string): string {
-		return `${BRANCH_PREFIX}${task}`;
-	}
-
-	taskFor(branch: string): string | null {
-		return branch.startsWith(BRANCH_PREFIX)
-			? branch.slice(BRANCH_PREFIX.length)
-			: null;
-	}
-
-	recordPath(task: string): string {
-		return `${this.tasksDir}/${task}.json`;
-	}
-
-	/** Always answers; the returned worktree's status says what was found. */
-	async find(task: string): Promise<Worktree> {
-		let state: TaskState | null = null;
-		let corrupt = false;
-		try {
-			state = await this.readRecord(task);
-		} catch {
-			corrupt = true; // a record that will not parse is still a record
-		}
-		const path = state?.worktree ?? this.pathFor(task);
-		const exists = await this.fs.exists(path);
-		const hasBranch = await this.git.branchExists(this.branchFor(task));
-		return new Worktree(this, {
-			task,
-			branch: state?.branch ?? this.branchFor(task),
-			path,
-			state,
-			exists,
-			hasBranch,
-			corrupt,
-			// Only worth asking when there is nothing else left of the task.
-			removedAt:
-				state || exists || hasBranch || corrupt
-					? null
-					: await this.removedAt(task),
-		});
-	}
-
-	async list(): Promise<Worktree[]> {
-		const entries = await this.fs.readdir(this.tasksDir).catch(() => []);
-		const tasks = entries
-			.filter((entry) => entry.endsWith(".json"))
-			.map((entry) => entry.slice(0, -".json".length))
-			.sort();
-		const found: Worktree[] = [];
-		for (const task of tasks) {
-			found.push(await this.find(task));
-		}
-		return found;
-	}
-
-	/** Adds the branch and the working directory. The record comes after. */
-	async add(
-		task: string,
-		{ base = this.config.trunk }: AddOptions = {},
-	): Promise<GitResult> {
-		await this.fs.mkdir(this.config.worktreeRoot);
-		return this.git.addWorktree(this.branchFor(task), this.pathFor(task), base);
-	}
-
-	async discard(worktree: Worktree): Promise<GitResult> {
-		const removed = worktree.exists
-			? await this.git.removeWorktree(worktree.path)
-			: // Directory gone by other means: drop the metadata git still holds.
-				await this.git.pruneWorktrees();
-		if (removed.code !== 0) {
-			return removed;
-		}
-		if (worktree.hasBranch) {
-			const deleted = await this.git.deleteBranch(worktree.branch);
-			if (deleted.code !== 0) {
-				return deleted;
-			}
-		}
-		await this.fs.rm(this.recordPath(worktree.task), { force: true });
-		await this.rememberRemoved(worktree.task);
-		return removed;
-	}
-
-	/** Writes a task's record. A concurrent reader sees the old one or the new. */
-	async saveRecord(state: TaskState): Promise<void> {
-		// A half-written record read by a concurrent agent is a real failure mode,
-		// and rename is the only way to make the swap atomic.
-		const path = this.recordPath(state.task);
-		const tmp = `${path}.${this.ps.pid}.tmp`;
-		await this.fs.write(tmp, `${JSON.stringify(state, null, "\t")}\n`);
-		await this.fs.rename(tmp, path);
-	}
-
-	private async readRecord(task: string): Promise<TaskState | null> {
-		const raw = await this.fs.read(this.recordPath(task)).catch(() => null);
-		return raw === null ? null : (JSON.parse(raw) as TaskState);
-	}
-
-	private removedPath(task: string): string {
-		return `${this.removedDir}/${task}`;
-	}
-
-	private async removedAt(task: string): Promise<string | null> {
-		const raw = await this.fs.read(this.removedPath(task)).catch(() => null);
-		return raw?.trim() ?? null;
-	}
-
-	/**
-	 * Remembers a removed name so a second `remove` can say "already removed"
-	 * instead of "never existed", then drops the oldest so the list of
-	 * remembered names cannot grow without bound.
-	 */
-	private async rememberRemoved(
-		task: string,
-		at = new Date().toISOString(),
-	): Promise<void> {
-		const { removedCapacity } = this.config;
-		await this.fs.write(this.removedPath(task), `${at}\n`);
-		const names = await this.fs.readdir(this.removedDir).catch(() => []);
-		if (names.length <= removedCapacity) {
-			return;
-		}
-		// Each file holds the ISO timestamp it was written with, which sorts
-		// chronologically. An unreadable one sorts first and goes first.
-		const dated = await Promise.all(
-			names.map(async (name) => ({
-				name,
-				at: (await this.removedAt(name)) ?? "",
-			})),
-		);
-		dated.sort((left, right) => left.at.localeCompare(right.at));
-		for (const { name } of dated.slice(0, names.length - removedCapacity)) {
-			await this.fs.rm(this.removedPath(name), { force: true });
-		}
-	}
-}