@webappwiz/arbor 0.0.30 → 0.0.32

package/remove.test.ts

@@ -1,68 +0,0 @@
-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

@@ -1,88 +0,0 @@
-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

@@ -1,83 +0,0 @@
-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

@@ -1,43 +0,0 @@
-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

@@ -1,48 +0,0 @@
-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

@@ -1,44 +0,0 @@
-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

@@ -1,91 +0,0 @@
-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");
-	});
-});

package/show.ts

@@ -1,151 +0,0 @@
-import { color, type Logger } from "webappwiz/log";
-import { type Fs, NodeFs } from "webappwiz/system";
-import { age } from "./age";
-import { fail } from "./exit";
-import { checkPlan, PLAN_FILE } from "./plan";
-import type { Worktree } from "./worktree";
-import type { WorktreeService } from "./worktree-service";
-
-export interface Details {
-	task: string;
-	status: string;
-	branch: string;
-	base: string;
-	worktree: string;
-	lease: "held" | "stale" | "none";
-	ahead: number | null;
-	added: number | null;
-	removed: number | null;
-	age: string | null;
-	escalation: string | null;
-	/**
-	 * While escalated to be approved, the question that asks for it, `4`;
-	 * null otherwise.
-	 */
-	review: string | null;
-	plan: string | null;
-	/** How the `ARBOR.md` departs from the shape the skill prescribes. */
-	planProblems: string[];
-}
-
-export interface ShowOptions {
-	/** Print the details as JSON instead of prose. */
-	json?: boolean;
-}
-
-/**
- * One task in full: what `list` shows for it, plus the `ARBOR.md` its agent
- * left at the worktree root. Reading a tree this way takes no lease, so it
- * cannot knock the agent driving it off its own work.
- */
-export async function show(
-	{ service, fs, log }: { service: WorktreeService; fs: Fs; log: Logger },
-	task: string,
-	opts: ShowOptions = {},
-): Promise<void> {
-	const worktree = await service.find(task);
-	if (worktree.gone) {
-		fail(
-			"not_found",
-			`no task '${task}': run \`arbor list\` to see what there is`,
-			{ task },
-		);
-	}
-	const details = await new TaskDetails({ fs }).get(worktree);
-
-	if (opts.json ?? false) {
-		log.info(JSON.stringify(details, null, "\t"));
-		return;
-	}
-	log.info(report(details));
-}
-
-/** Configures how {@link TaskDetails} gathers a task's info. */
-export interface TaskDetailsOptions {
-	/** What the worktree is read through; the real filesystem by default. */
-	fs?: Fs;
-}
-
-/**
- * Everything there is to say about one task. Split out so `dev` can render the
- * same fields this prints, rather than assembling its own and drifting.
- */
-export class TaskDetails {
-	private readonly fs: Fs;
-
-	constructor(opts: TaskDetailsOptions = {}) {
-		this.fs = opts.fs ?? new NodeFs();
-	}
-
-	async get(worktree: Worktree): Promise<Details> {
-		const { state } = worktree;
-		// A record whose worktree or branch is gone is still worth showing: the
-		// status names what is wrong, and asking git about a branch that is not
-		// there would only fill the fields with nulls.
-		const stat = worktree.hasBranch ? await worktree.diffStat() : null;
-		const plan = worktree.exists
-			? await this.fs.read(`${worktree.path}/${PLAN_FILE}`).catch(() => null)
-			: null;
-		return {
-			task: worktree.task,
-			status: worktree.status,
-			branch: worktree.branch,
-			base: worktree.base,
-			worktree: worktree.path,
-			lease: worktree.leaseStatus,
-			ahead: worktree.hasBranch ? await worktree.commitsAhead() : null,
-			added: stat?.added ?? null,
-			removed: stat?.removed ?? null,
-			age: state ? age(state.createdAt) : null,
-			escalation: state?.escalations?.at(-1)?.reason ?? null,
-			review:
-				state?.status === "escalated"
-					? (state.escalations?.at(-1)?.review ?? null)
-					: null,
-			plan,
-			planProblems:
-				plan === null
-					? []
-					: checkPlan(plan, {
-							task: worktree.task,
-							escalated: worktree.status === "escalated",
-						}),
-		};
-	}
-}
-
-function report(details: Details): string {
-	const lines = [
-		`${color.bold(details.task)} ${details.status}`,
-		`  branch:    ${details.branch}`,
-		`  base:      ${details.base}`,
-		`  worktree:  ${details.worktree}`,
-		`  lease:     ${details.lease}`,
-		`  ahead:     ${details.ahead === null ? "?" : details.ahead}  ${diff(details)}`,
-		`  age:       ${details.age ?? "?"}`,
-	];
-	if (details.escalation !== null) {
-		lines.push(`  ${color.yellow(`escalated: ${details.escalation}`)}`);
-	}
-	if (details.plan !== null) {
-		lines.push("", color.bold(PLAN_FILE), details.plan.trimEnd());
-		for (const problem of details.planProblems) {
-			lines.push(color.yellow(`  ${problem}`));
-		}
-	} else if (details.status !== "orphaned") {
-		lines.push(
-			"",
-			color.yellow(
-				`no ${PLAN_FILE}: whoever picks this up starts from the diff`,
-			),
-		);
-	}
-	return lines.join("\n");
-}
-
-function diff(details: Details): string {
-	if (details.added === null || details.removed === null) {
-		return "?";
-	}
-	return `${color.green(`+${details.added}`)} ${color.red(`-${details.removed}`)}`;
-}

package/snapshot.test.ts

@@ -1,33 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from "bun:test";
-import { basename, dirname } from "node:path";
-import { snapshot } from "./snapshot";
-import { Testing } from "./testing";
-
-describe("snapshot", () => {
-	let deps: Testing;
-
-	beforeEach(async () => {
-		deps = await Testing.open();
-	});
-
-	afterEach(() => deps.disposeAsync());
-
-	it("writes a repo under home with ~", async () => {
-		const { path } = await snapshot({ ...deps, home: dirname(deps.root) });
-
-		expect(path).toBe(`~/${basename(deps.root)}`);
-	});
-
-	it("writes home itself as ~", async () => {
-		const { path } = await snapshot({ ...deps, home: deps.root });
-
-		expect(path).toBe("~");
-	});
-
-	it("leaves a repo outside home, or one only sharing its prefix, whole", async () => {
-		const { path } = await snapshot({ ...deps, home: deps.root.slice(0, -1) });
-
-		expect(path).toBe(deps.root);
-		expect((await snapshot(deps)).path).toBe(deps.root);
-	});
-});