@webappwiz/arbor 0.0.28 → 0.0.30

package/show.ts

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

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

package/snapshot.ts

@@ -0,0 +1,84 @@
+import { basename } from "node:path";
+import type { Fs } from "webappwiz/system";
+import { type Details, TaskDetails } from "./show";
+import type { TodoState, Todos } from "./todo";
+import type { WorktreeService } from "./worktree-service";
+
+/**
+ * Everything one page shows: `todo list`, and `list` and `show` for each
+ * task.
+ */
+export interface Snapshot {
+	/** The repository's directory name, so a page among many says whose it is. */
+	repo: string;
+	/** Where the repository sits, with the home directory as `~`. */
+	path: string;
+	/** Past this age a todo is offered for removal rather than recommended. */
+	todoStalenessMs: number;
+	todos: TodoState[];
+	tasks: Details[];
+}
+
+/**
+ * Reads the whole repo the way the CLI's read commands do. Takes no lease, so
+ * the page can sit open on a live tree without disturbing the agent in it.
+ */
+export async function snapshot({
+	service,
+	todos,
+	fs,
+	home,
+}: {
+	service: WorktreeService;
+	todos: Todos;
+	fs: Fs;
+	/** The home directory to show as `~`, when there is one. */
+	home?: string;
+}): Promise<Snapshot> {
+	const details = new TaskDetails({ fs });
+	const tasks: Details[] = [];
+	for (const worktree of await service.list()) {
+		tasks.push(await details.get(worktree));
+	}
+	return {
+		repo: basename(service.git.root),
+		path: tilde(service.git.root, home),
+		todoStalenessMs: service.config.todoStalenessMs,
+		todos: (await todos.all()).map((todo) => todo.state),
+		tasks,
+	};
+}
+
+/**
+ * What the page is actually showing, minus the fields that move on their own.
+ * `age` ticks every minute, and hashing it would push to every open page for
+ * nothing.
+ */
+export function fingerprint({ todos, tasks }: Snapshot): string {
+	return JSON.stringify([
+		todos,
+		tasks.map((task) => [
+			task.task,
+			task.status,
+			task.lease,
+			task.ahead,
+			task.added,
+			task.removed,
+			task.escalation,
+			task.review,
+			task.plan,
+			task.planProblems,
+		]),
+	]);
+}
+
+/** `root` with a leading `home` written as `~`, the way a shell prompt shows it. */
+function tilde(root: string, home: string | undefined): string {
+	if (!home) {
+		return root;
+	}
+	if (root === home) {
+		return "~";
+	}
+	return root.startsWith(`${home}/`) ? `~${root.slice(home.length)}` : root;
+}

package/table.ts

@@ -0,0 +1,20 @@
+import { color } from "webappwiz/log";
+
+/**
+ * Columns padded to their widest cell. Padding goes by visible width, not
+ * string length: cells carry color codes.
+ */
+export function table(header: string[], rows: string[][]): string {
+	const width = (cell: string): number => color.strip(cell).length;
+	const widths = header.map((heading, i) =>
+		Math.max(heading.length, ...rows.map((row) => width(row[i] ?? ""))),
+	);
+	const line = (cells: string[]): string =>
+		cells
+			.map((cell, i) =>
+				cell.padEnd((widths[i] ?? 0) + cell.length - width(cell)),
+			)
+			.join("  ")
+			.trimEnd();
+	return [color.dim(line(header)), ...rows.map(line)].join("\n");
+}

package/testing.ts

@@ -0,0 +1,229 @@
+import { expect } from "bun:test";
+import { mkdtemp, realpath, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { CounterIdProvider } from "webappwiz/id";
+import { color, MemoryLogger } from "webappwiz/log";
+import { FileLock, NodeFs, NodePs } from "webappwiz/system";
+import { FakeProcess } from "webappwiz/system/testing";
+import type { Config } from "./config";
+import { assets } from "./dev/assets";
+import { Exit, type Reason } from "./exit";
+import { Git } from "./git";
+import { Journal } from "./journal";
+import { Shell } from "./shell";
+import { Todos } from "./todo";
+import { WorktreeService } from "./worktree-service";
+
+/**
+ * A throwaway git repo with one commit on `main`, holding every dependency an
+ * arbor command runs against, wired to it. A command takes the whole thing as
+ * its deps: `await add(deps, "alpha")`.
+ *
+ * It coordinates the dependencies and nothing else. What a test is about, the
+ * tasks, the commits, the config it needs to differ, the test does itself.
+ */
+export class Testing implements AsyncDisposable {
+	readonly root: string;
+	readonly arborDir: string;
+	readonly fs = new NodeFs();
+	/** Spawns for real; its exits and signals are the fake process's to keep. */
+	readonly proc = new FakeProcess();
+	readonly ps: NodePs;
+	readonly log = new MemoryLogger();
+	/** Stored file names count up from 0, so a test can name them. */
+	readonly ids = new CounterIdProvider();
+	// The real ones, which publish: `dev` is tested by serving a page and
+	// fetching it, and asserting on what comes back is the point.
+	readonly assets = assets;
+	/** Arbitrary but valid settings; a test changes what it cares about. */
+	readonly config: Config;
+	readonly git: Git;
+	readonly service: WorktreeService;
+	readonly shell: Shell;
+	readonly journal: Journal;
+	readonly lockPath: string;
+	readonly lock: FileLock;
+	readonly todos: Todos;
+
+	private constructor(private readonly base: string) {
+		this.root = join(base, "repo");
+		this.arborDir = join(this.root, ".git", "arbor");
+		this.ps = new NodePs({ proc: this.proc });
+		this.config = {
+			trunk: "main",
+			worktreeRoot: `${this.root}-arbor`,
+			postCheckout: null,
+			postRewrite: null,
+			// Keeps merge's gate green unless a test asks otherwise.
+			preMerge: "true",
+			postMerge: null,
+			leaseStalenessMs: 90_000,
+			removedCapacity: 50,
+			mergeRetryCount: 2,
+			logCapacity: 200,
+			todoStalenessMs: 30 * 24 * 60 * 60 * 1000,
+		};
+		this.git = new Git(this.root, { ps: this.ps, fs: this.fs });
+		this.service = new WorktreeService(this.git, this.config, this.arborDir, {
+			fs: this.fs,
+			ps: this.ps,
+		});
+		this.shell = new Shell({ ps: this.ps });
+		this.journal = new Journal(
+			join(this.arborDir, "log.jsonl"),
+			this.config.logCapacity,
+			{ fs: this.fs },
+		);
+		this.lockPath = join(this.arborDir, "merge.lock");
+		this.lock = new FileLock(this.lockPath, {
+			fs: this.fs,
+			ps: this.ps,
+			log: this.log,
+			stalenessMs: this.config.leaseStalenessMs,
+		});
+		this.todos = new Todos(
+			join(this.arborDir, "todos"),
+			new FileLock(join(this.arborDir, "todos.lock"), {
+				fs: this.fs,
+				ps: this.ps,
+				log: this.log,
+			}),
+			{ fs: this.fs, ids: this.ids },
+		);
+	}
+
+	/** A repo of its own, seeded and ready for a command. */
+	static async open(): Promise<Testing> {
+		const base = await realpath(await mkdtemp(join(tmpdir(), "arbor-")));
+		const testing = new Testing(base);
+		await testing.seed();
+		return testing;
+	}
+
+	/** Runs git in `cwd`, named apart from the `git` a command is handed. */
+	async gitCli(cwd: string, ...args: string[]): Promise<string> {
+		const { exitCode, stdout, stderr } = await this.ps.spawnCapture([
+			"git",
+			"-C",
+			cwd,
+			...args,
+		]);
+		if (exitCode !== 0) {
+			throw new Error(`git ${args.join(" ")}: ${stderr}`);
+		}
+		return stdout.trim();
+	}
+
+	/** Writes a file in `cwd` and commits it. */
+	async commit(
+		cwd: string,
+		file: string,
+		content: string,
+		message: string,
+	): Promise<void> {
+		await this.fs.write(join(cwd, file), content);
+		await this.gitCli(cwd, "add", file);
+		await this.gitCli(cwd, "commit", "-m", message);
+	}
+
+	/** Everything logged so far, one line each, without colour. */
+	out(): string {
+		return color.strip(
+			this.log.entries.map((entry) => String(entry.message)).join("\n"),
+		);
+	}
+
+	/** Deletes the repo, its worktrees and the temporary directory holding them. */
+	disposeAsync(): Promise<void> {
+		return rm(this.base, { recursive: true, force: true });
+	}
+
+	// so a concurrent test can own its repo with `await using`, instead of
+	// afterEach handing every test in the file the same one
+	[Symbol.asyncDispose](): Promise<void> {
+		return this.disposeAsync();
+	}
+
+	private async seed(): Promise<void> {
+		await this.fs.mkdir(this.root);
+		await this.gitCli(this.root, "init", "-b", "main");
+		await this.gitCli(this.root, "config", "user.email", "arbor@example.com");
+		await this.gitCli(this.root, "config", "user.name", "arbor");
+		await this.gitCli(this.root, "config", "commit.gpgsign", "false");
+		await this.commit(this.root, "README.md", "seed\n", "seed");
+		await this.service.init();
+	}
+}
+
+/** pid 1 always exists, so it stands in for another agent that is still running. */
+export const LIVE_PID = 1;
+
+/** What a refusal carries beyond its reason, when a test says. */
+export interface BailOptions {
+	/** A fragment of the message the person reading it gets, or every one. */
+	message?: string | string[];
+	/** Everything the refusal reports alongside the reason. */
+	data?: Record<string, unknown>;
+}
+
+declare module "bun:test" {
+	interface Matchers<T> {
+		/** Asserts the work refuses: `await expect(add(t, "x")).toBail("usage")`. */
+		toBail(reason: Reason, expected?: BailOptions): Promise<void>;
+	}
+}
+
+// Registered here because every test file that asserts a refusal already
+// imports `Testing`, and `expect.extend` has to have run before the first one.
+expect.extend({
+	async toBail(work, reason, expected = {}) {
+		const exit = await refusal(work);
+		if (exit === null) {
+			return {
+				pass: false,
+				message: () => `expected a ${reason} refusal, but it succeeded`,
+			};
+		}
+		if (exit.reason !== reason) {
+			return {
+				pass: false,
+				message: () =>
+					`expected a ${reason} refusal, got ${exit.reason}: ${exit.message}`,
+			};
+		}
+		const fragments = [expected.message ?? []].flat();
+		const missing = fragments.filter((text) => !exit.message.includes(text));
+		if (missing.length > 0) {
+			return {
+				pass: false,
+				message: () =>
+					`expected the ${reason} message to contain ${this.utils.printExpected(missing)}, got ${this.utils.printReceived(exit.message)}`,
+			};
+		}
+		if (expected.data !== undefined && !this.equals(exit.data, expected.data)) {
+			return {
+				pass: false,
+				message: () =>
+					`expected the ${reason} data to be ${this.utils.printExpected(expected.data)}, got ${this.utils.printReceived(exit.data)}`,
+			};
+		}
+		return { pass: true, message: () => `expected no ${reason} refusal` };
+	},
+});
+
+/**
+ * The `Exit` some work refused with, or null when it did not refuse. Anything
+ * else it threw is a real failure and is left to blow up the test as itself.
+ */
+async function refusal(work: unknown): Promise<Exit | null> {
+	try {
+		await work;
+		return null;
+	} catch (entry) {
+		if (entry instanceof Exit) {
+			return entry;
+		}
+		throw entry;
+	}
+}