@webappwiz/arbor 0.0.30 → 0.0.31

package/journal.ts

@@ -1,89 +0,0 @@
-import { type Fs, NodeFs } from "webappwiz/system";
-import { Exit } from "./exit";
-
-/** One thing that was done to a task, and how it went. */
-export interface Entry {
-	at: string;
-	action: string;
-	/** The task it was about, or null when the command names none. */
-	task: string | null;
-	/** The refusal reason, or null when the command succeeded. */
-	reason: string | null;
-}
-
-/**
- * What has been done in this repo, oldest first. Entries outlive their tasks:
- * `merge` and `remove` take the record with them, so this is the only thing that
- * remembers a task existed at all.
- */
-/** What a `Journal` is stored through; the real filesystem by default. */
-export interface JournalOptions {
-	fs?: Fs;
-}
-
-export class Journal {
-	private readonly fs: Fs;
-
-	constructor(
-		private readonly path: string,
-		private readonly capacity: number,
-		opts: JournalOptions = {},
-	) {
-		this.fs = opts.fs ?? new NodeFs();
-	}
-
-	async record<T>(
-		action: string,
-		task: string | null,
-		run: () => Promise<T>,
-	): Promise<T> {
-		try {
-			const out = await run();
-			await this.append(action, task, null);
-			return out;
-		} catch (entry) {
-			await this.append(
-				action,
-				task,
-				entry instanceof Exit ? entry.reason : "error",
-			);
-			throw entry;
-		}
-	}
-
-	async tail(count: number): Promise<Entry[]> {
-		// slice(-0) is slice(0), which would hand back everything.
-		return count <= 0 ? [] : (await this.entries()).slice(-count);
-	}
-
-	private async append(
-		action: string,
-		task: string | null,
-		reason: string | null,
-	): Promise<void> {
-		// Rewriting the whole file is fine at a few hundred lines, and two agents
-		// finishing at the same instant lose an entry rather than corrupt one.
-		// Switch to an append + occasional compaction if `Fs` ever grows an append.
-		const entry: Entry = { at: new Date().toISOString(), action, task, reason };
-		const kept = [...(await this.entries()), entry].slice(-this.capacity);
-		await this.fs.write(
-			this.path,
-			kept.map((entry) => `${JSON.stringify(entry)}\n`).join(""),
-		);
-	}
-
-	private async entries(): Promise<Entry[]> {
-		const raw = await this.fs.read(this.path).catch(() => "");
-		return raw
-			.split("\n")
-			.filter(Boolean)
-			.flatMap((line) => {
-				try {
-					// A torn line loses one entry, not the whole log.
-					return [JSON.parse(line) as Entry];
-				} catch {
-					return [];
-				}
-			});
-	}
-}

package/list.test.ts

@@ -1,82 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from "bun:test";
-import { color } from "webappwiz/log";
-import { add } from "./add";
-import { list } from "./list";
-import { Testing } from "./testing";
-
-describe("list", () => {
-	let deps: Testing;
-
-	beforeEach(async () => {
-		deps = await Testing.open();
-	});
-
-	afterEach(() => deps.disposeAsync());
-
-	it("lists tasks, survives a corrupt record, and flags orphans", async () => {
-		await add(deps, "alpha");
-		await add(deps, "beta");
-		await deps.fs.write(deps.service.recordPath("broken"), "{not json");
-		const beta = (await deps.service.find("beta")).path;
-		await deps.fs.rm(beta, { recursive: true, force: true });
-
-		await list(deps);
-
-		expect(deps.out()).toContain("alpha");
-		expect(deps.out()).toContain("unknown"); // the corrupt row, not a crash
-		expect(deps.out()).toContain("orphaned");
-		expect(color.strip(deps.out())).toContain("+0 -0");
-
-		deps.log.clear();
-		await list(deps, { json: true });
-		const rows = JSON.parse(deps.out());
-		expect(rows.map((fixture: { task: string }) => fixture.task)).toEqual([
-			"alpha",
-			"beta",
-			"broken",
-		]);
-	});
-
-	it("names each task's changed and planned files with --files", async () => {
-		await add(deps, "alpha");
-		const worktree = (await deps.service.find("alpha")).path;
-		await deps.commit(worktree, "committed.txt", "a\n", "add committed");
-		await deps.fs.write(`${worktree}/untracked.txt`, "b\n");
-		await deps.fs.write(
-			`${worktree}/ARBOR.md`,
-			"# alpha\n\n## Files\n\n- `committed.txt`\n- planned.txt\n\nprose, not a path\n",
-		);
-
-		deps.log.clear();
-		await list(deps, { files: true });
-
-		const out = color.strip(deps.out());
-		expect(out).toContain("changed  committed.txt");
-		expect(out).toContain("changed  untracked.txt");
-		expect(out).toContain("planned  planned.txt");
-		expect(out).not.toContain("planned  committed.txt");
-		expect(out).not.toContain("ARBOR.md"); // excluded, so never a change
-
-		deps.log.clear();
-		await list(deps, { json: true, files: true });
-		const [row] = JSON.parse(deps.out());
-		expect(row.changed).toEqual(["committed.txt", "untracked.txt"]);
-		expect(row.planned).toEqual(["committed.txt", "planned.txt"]);
-	});
-
-	it("leaves files out unless asked", async () => {
-		await add(deps, "alpha");
-		deps.log.clear();
-
-		await list(deps, { json: true });
-
-		const [row] = JSON.parse(deps.out());
-		expect(row).not.toHaveProperty("changed");
-	});
-
-	it("says so plainly when there is nothing to list", async () => {
-		await list(deps);
-
-		expect(deps.out()).toContain("no tasks");
-	});
-});

package/list.ts

@@ -1,137 +0,0 @@
-import { color, type Logger } from "webappwiz/log";
-import type { Fs } from "webappwiz/system";
-import { age } from "./age";
-import { PLAN_FILE, plannedFiles } from "./plan";
-import { table } from "./table";
-import type { Worktree } from "./worktree";
-import type { WorktreeService } from "./worktree-service";
-
-interface Row {
-	task: string;
-	status: string;
-	lease: "held" | "stale" | "none";
-	ahead: number | null;
-	added: number | null;
-	removed: number | null;
-	age: string;
-	worktree: string | null;
-	/** Paths the task has touched, committed or not; only with `files`. */
-	changed?: string[] | null;
-	/** Paths its `ARBOR.md` plans to touch; only with `files`. */
-	planned?: string[];
-}
-
-export interface ListOptions {
-	/** Print the rows as JSON instead of a table. */
-	json?: boolean;
-	/**
-	 * Add each task's changed and planned files, which is what an agent checks
-	 * its own plan against before starting. Off by default: it costs git calls
-	 * and a file read per task.
-	 */
-	files?: boolean;
-}
-
-export async function list(
-	{ service, log, fs }: { service: WorktreeService; log: Logger; fs: Fs },
-	{ json = false, files = false }: ListOptions = {},
-): Promise<void> {
-	const rows: Row[] = [];
-	for (const worktree of await service.list()) {
-		const base = await row(worktree);
-		rows.push(files ? { ...base, ...(await paths(worktree, fs)) } : base);
-	}
-
-	if (json) {
-		log.info(JSON.stringify(rows, null, "\t"));
-		return;
-	}
-	if (rows.length === 0) {
-		log.info("no tasks: run `arbor add <task>` to start one");
-		return;
-	}
-	log.info(listing(rows));
-}
-
-async function row(worktree: Worktree): Promise<Row> {
-	const { state } = worktree;
-	const diff = state ? await worktree.diffStat() : null;
-	return {
-		task: worktree.task,
-		// One unreadable record shows as `unknown` instead of taking down the
-		// whole listing.
-		status: worktree.status,
-		lease: worktree.leaseStatus,
-		ahead: state ? await worktree.commitsAhead() : null,
-		added: diff?.added ?? null,
-		removed: diff?.removed ?? null,
-		age: state ? age(state.createdAt) : "?",
-		worktree: state ? worktree.path : null,
-	};
-}
-
-async function paths(
-	worktree: Worktree,
-	fs: Fs,
-): Promise<Pick<Row, "changed" | "planned">> {
-	const plan = worktree.exists
-		? await fs.read(`${worktree.path}/${PLAN_FILE}`).catch(() => null)
-		: null;
-	return {
-		changed: worktree.hasBranch ? await worktree.changedFiles() : null,
-		planned: plan === null ? [] : plannedFiles(plan),
-	};
-}
-
-function diff(row: Row): string {
-	if (row.added === null || row.removed === null) {
-		return "?";
-	}
-	return `${color.green(`+${row.added}`)} ${color.red(`-${row.removed}`)}`;
-}
-
-function listing(rows: Row[]): string {
-	const cells = rows.map((row) => [
-		row.task,
-		row.status,
-		row.lease,
-		row.ahead === null ? "?" : String(row.ahead),
-		diff(row),
-		row.age,
-	]);
-	const out = [
-		table(["TASK", "STATUS", "LEASE", "AHEAD", "DIFF", "AGE"], cells),
-	];
-	for (const row of rows) {
-		if (row.changed !== undefined) {
-			out.push("", ...files(row));
-		}
-	}
-	const orphaned = rows.filter((row) => row.status === "orphaned");
-	if (orphaned.length > 0) {
-		out.push(
-			"",
-			color.yellow(
-				`${orphaned.length} orphaned record(s): run \`arbor remove ${orphaned[0]?.task}\``,
-			),
-		);
-	}
-	return out.join("\n");
-}
-
-/**
- * One task's paths, each once: `changed` when the task has touched it,
- * `planned` when only its `ARBOR.md` names it so far.
- */
-function files(row: Row): string[] {
-	const changed = row.changed ?? [];
-	const planned = (row.planned ?? []).filter((path) => !changed.includes(path));
-	const lines = [
-		...changed.map((path) => `  changed  ${path}`),
-		...planned.map((path) => `  ${color.dim("planned")}  ${path}`),
-	];
-	return [
-		color.bold(row.task),
-		...(lines.length > 0 ? lines : [color.dim("  no files yet")]),
-	];
-}

package/load-config.test.ts

@@ -1,121 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from "bun:test";
-import { mkdtemp, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { NodeFs } from "webappwiz/system";
-import { FakePs } from "webappwiz/system/testing";
-import { Git } from "./git";
-import { loadConfig } from "./load-config";
-import { Testing } from "./testing";
-
-describe("loadConfig", () => {
-	const fs = new NodeFs();
-	let root: string;
-	let git: Git;
-
-	beforeEach(async () => {
-		root = await mkdtemp(join(tmpdir(), "arbor-config-"));
-		const ps = new FakePs();
-		// Stands in for a repo with no `origin/HEAD` to read.
-		ps.simulate(() => Promise.resolve(1));
-		git = new Git(root, { ps });
-	});
-
-	afterEach(async () => {
-		await rm(root, { recursive: true, force: true });
-	});
-
-	it("defaults the worktree root to a sibling of the repo, named after it", async () => {
-		const config = await loadConfig(root, { fs, git });
-
-		expect(config.worktreeRoot).toBe(`${root}-arbor`);
-	});
-
-	it("leaves every hook unset, so a repo runs only what it asks for", async () => {
-		const config = await loadConfig(root, { fs, git });
-
-		expect(config.postCheckout).toBeNull();
-		expect(config.postRewrite).toBeNull();
-		expect(config.preMerge).toBeNull();
-		expect(config.postMerge).toBeNull();
-	});
-
-	it("overrides only the defaults arbor.config.ts names", async () => {
-		await fs.write(
-			join(root, "arbor.config.ts"),
-			`export default { trunk: "trunk", mergeRetryCount: 7 };\n`,
-		);
-
-		const config = await loadConfig(root, { fs, git });
-
-		expect(config.trunk).toBe("trunk");
-		expect(config.mergeRetryCount).toBe(7);
-		expect(config.leaseStalenessMs).toBe(90_000);
-	});
-
-	it("falls back to main when the repo has no origin/HEAD", async () => {
-		const config = await loadConfig(root, { fs, git });
-
-		expect(config.trunk).toBe("main");
-	});
-
-	it("reports the config path and the remedy when the file will not import", async () => {
-		await fs.write(
-			join(root, "arbor.config.ts"),
-			`import "./nowhere-at-all";\nexport default {};\n`,
-		);
-
-		const failure = await loadConfig(root, { fs, git }).catch(
-			(entry: Error) => entry,
-		);
-
-		expect(failure).toBeInstanceOf(Error);
-		expect((failure as Error).message).toContain("arbor.config.ts");
-		expect((failure as Error).message).toContain("bun install");
-	});
-
-	it("takes the trunk from what origin/HEAD points at", async () => {
-		await using fixture = await Testing.open();
-		await originHead(fixture, "master");
-
-		const config = await loadConfig(fixture.root, {
-			fs,
-			git: new Git(fixture.root, { ps: fixture.ps }),
-		});
-
-		expect(config.trunk).toBe("master");
-	});
-
-	it("prefers the trunk arbor.config.ts names over what it detects", async () => {
-		await using fixture = await Testing.open();
-		await originHead(fixture, "master");
-		await fixture.fs.write(
-			join(fixture.root, "arbor.config.ts"),
-			`export default { trunk: "release" };\n`,
-		);
-
-		const config = await loadConfig(fixture.root, {
-			fs,
-			git: new Git(fixture.root, { ps: fixture.ps }),
-		});
-
-		expect(config.trunk).toBe("release");
-	});
-});
-
-/** Fabricates the ref a clone would fetch, without a remote to fetch from. */
-async function originHead(fixture: Testing, branch: string): Promise<void> {
-	await fixture.gitCli(
-		fixture.root,
-		"remote",
-		"add",
-		"origin",
-		"https://example.invalid/repo.git",
-	);
-	await fixture.gitCli(
-		fixture.root,
-		"symbolic-ref",
-		"refs/remotes/origin/HEAD",
-		`refs/remotes/origin/${branch}`,
-	);
-}

package/load-config.ts

@@ -1,62 +0,0 @@
-import { basename, resolve } from "node:path";
-import { type Fs, NodeFs } from "webappwiz/system";
-import type { Config } from "./config";
-import { Git } from "./git";
-
-export interface LoadConfigOptions {
-	/** What `arbor.config.ts` is looked for through; the real one by default. */
-	fs?: Fs;
-	/** What the trunk is detected through; the repo's own git by default. */
-	git?: Git;
-}
-
-/**
- * The settings arbor runs a repo with: what `arbor.config.ts` names, then the
- * branch `origin/HEAD` points at for the trunk, then arbor's own defaults.
- * Throws when the config file is there but cannot be imported.
- */
-export async function loadConfig(
-	root: string,
-	opts: LoadConfigOptions = {},
-): Promise<Config> {
-	const found = await file(opts.fs ?? new NodeFs(), root);
-	// Only a repo that has not said which branch is its trunk pays for the
-	// detecting spawn.
-	const trunk =
-		found.trunk ??
-		(await (opts.git ?? new Git(root)).defaultBranch()) ??
-		"main";
-	return { ...defaults(root, trunk), ...found };
-}
-
-function defaults(root: string, trunk: string): Config {
-	return {
-		trunk,
-		worktreeRoot: resolve(root, "..", `${basename(root)}-arbor`),
-		postCheckout: null,
-		postRewrite: null,
-		preMerge: null,
-		postMerge: null,
-		leaseStalenessMs: 90_000,
-		mergeRetryCount: 2,
-		removedCapacity: 50,
-		logCapacity: 1000,
-		todoStalenessMs: 30 * 24 * 60 * 60 * 1000,
-	};
-}
-
-async function file(fs: Fs, root: string): Promise<Partial<Config>> {
-	const path = `${root}/arbor.config.ts`;
-	if (!(await fs.exists(path))) {
-		return {};
-	}
-	// Falling back to the defaults would be worse than failing: a config arbor
-	// silently ignored is a `preMerge` gate that silently stopped running.
-	const mod = (await import(path).catch((cause: unknown) => {
-		throw new Error(
-			`could not load ${path}: ${cause}. Its imports may be stale: try \`bun install\` in ${root}.`,
-			{ cause },
-		);
-	})) as { default?: Partial<Config> };
-	return mod.default ?? {};
-}

package/log.test.ts

@@ -1,65 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from "bun:test";
-import { join } from "node:path";
-import { Exit } from "./exit";
-import { Journal } from "./journal";
-import { log } from "./log";
-import { Testing } from "./testing";
-
-describe("log", () => {
-	let deps: Testing;
-
-	beforeEach(async () => {
-		deps = await Testing.open();
-	});
-
-	afterEach(() => deps.disposeAsync());
-
-	it("records how each command ended, refusals included", async () => {
-		await deps.journal.record("create", "alpha", async () => {});
-		await expect(
-			deps.journal.record("merge", "alpha", () =>
-				Promise.reject(new Exit("tests_failed", "nope")),
-			),
-		).toBail("tests_failed");
-
-		await log(deps);
-
-		const out = deps.out();
-		expect(out).toContain("create");
-		expect(out).toContain("alpha");
-		expect(out).toContain("ok");
-		expect(out).toContain("tests_failed");
-
-		// Newest last, and --count trims from the front.
-		deps.log.clear();
-		await log(deps, { count: 1, json: true });
-		expect(JSON.parse(deps.out())).toMatchObject([
-			{ action: "merge", task: "alpha", reason: "tests_failed" },
-		]);
-	});
-
-	it("keeps the log capped and asking for none returns none", async () => {
-		// Room for two, so a third entry has to push the first off.
-		const journal = new Journal(join(deps.arborDir, "log.jsonl"), 2, {
-			fs: deps.fs,
-		});
-		await journal.record("create", "a", async () => {});
-		await journal.record("create", "b", async () => {});
-		await journal.record("create", "c", async () => {});
-
-		expect((await journal.tail(10)).map((entry) => entry.task)).toEqual([
-			"b",
-			"c",
-		]);
-		expect(await journal.tail(0)).toEqual([]);
-
-		await log({ journal, log: deps.log }, { json: true });
-		expect(JSON.parse(deps.out())).toHaveLength(2);
-	});
-
-	it("says so plainly when nothing has happened", async () => {
-		await log(deps);
-
-		expect(deps.out()).toContain("nothing recorded yet");
-	});
-});

package/log.ts

@@ -1,40 +0,0 @@
-import { color, type Logger } from "webappwiz/log";
-import { age } from "./age";
-import type { Entry, Journal } from "./journal";
-import { table } from "./table";
-
-/** Enough to cover a session's worth of work without scrolling. */
-export const DEFAULT_COUNT = 20;
-
-export interface LogOptions {
-	/** How many of the most recent entries to show. */
-	count?: number;
-	/** Print the entries as JSON instead of a table. */
-	json?: boolean;
-}
-
-export async function log(
-	{ journal, log }: { journal: Journal; log: Logger },
-	{ count = DEFAULT_COUNT, json = false }: LogOptions = {},
-): Promise<void> {
-	const entries = await journal.tail(count);
-
-	if (json) {
-		log.info(JSON.stringify(entries, null, "\t"));
-		return;
-	}
-	if (entries.length === 0) {
-		log.info("nothing recorded yet");
-		return;
-	}
-	log.info(table(["WHEN", "ACTION", "TASK", "RESULT"], entries.map(row)));
-}
-
-function row(entry: Entry): string[] {
-	return [
-		age(entry.at),
-		entry.action,
-		entry.task ?? "-",
-		entry.reason === null ? color.green("ok") : color.red(entry.reason),
-	];
-}