@webappwiz/arbor 0.0.28 → 0.0.30

package/AGENTS.md

@@ -0,0 +1,7 @@
+If you change this package's API, check that the agent skill at
+`packages/cli/templates/arbor.skill.md` is still in sync. That is the source;
+the copies under `.agents/skills/` and `.claude/skills/` are installed from it.
+
+`arbor` runs whichever checkout you are standing in, so working on this package
+from a worktree merges with the code you are editing. Pin the main tree for the
+merge itself: `WEBAPPWIZ_ROOT="$(arbor path)" arbor merge`.

package/README.md

@@ -105,7 +105,8 @@ configures none.
 
 A merge onto trunk ends by recommending what to do next: the open todo highest
 on the list that came up in the task that landed, since its context is
-freshest, or failing that the open todo highest on the list, plus any todo older than `todoStalenessMs` (30 days) offered for
+freshest, then one sharing a tag with the todos the task settled, the same
+area of work, or failing that the open todo highest on the list, plus any todo older than `todoStalenessMs` (30 days) offered for
 removal instead. The todos the task
 took up, with `--todo` or `todo take`, leave the list, since that work is now
 done; release one first to keep what is left of it.
@@ -148,7 +149,7 @@ down the listing; a record whose worktree vanished shows as `orphaned`.
 
 `--files` adds, under each task, every path it has changed (committed or
 not) and every path its `ARBOR.md` plans under `## Files` that it has not
-touched yet. This is the overlap check an agent runs before starting: its own
+touched yet. This is the overlap check an agent runs once it has planned: its own
 list of files against everyone else's.
 
 ```
@@ -229,23 +230,34 @@ the only thing that remembers a task landed at all. The last 1000 are kept
 The todos and the tasks in a browser, on `http://localhost:4269`, reloading
 themselves as anything changes. Built for a phone first.
 
+One page, tasks above the todos.
+
 Todos are cards in list order: drag one to reorder the list (a short press
 on a phone, or Space on its grip and the arrow keys), or tap it to reword,
 attach files to, or remove. A card shows its subject, two lines of its
-detail, and badges for its files and staleness, and a green edge with
+detail rendered as markdown, and badges for its files, tags and staleness, and a green edge with
 "Taken by <task>" once a task has taken it; its
 `#7` copies `[ARBOR TODO #7]`, which the agent skill reads as that todo, for
-pasting into a chat. Typing `@` in a todo offers the files and
+pasting into a chat. An opened todo shows its detail rendered, with Write and
+Preview to switch between the markdown and how it reads. Typing `@` in a todo offers the files and
 directories in the main tree, tracked or new but not ignored, and writes the
 one picked as `@path/from/root`; picking a directory keeps the list open on
-what is inside.
+what is inside. An opened todo's tags are edited there too, comma separated,
+and its `#7` copies the same reference as the card's.
+
+Tasks lists every task with a bar for its progress through its plan, counted
+from the checkboxes under `## Done` and `## Next` in its `ARBOR.md`, flagging
+only an escalated or broken status; tapping one opens its details and whole
+plan in a dialog.
 
-Tasks lists every task with its progress through its plan, flagging only an
-escalated or broken status; tapping one opens its details and whole plan in a dialog.
+A row of tags over the todos filters them, the way a mail client filters by
+label: All, then every tag a todo has. Tapping one there, or on a card, shows
+only its todos. Dragging a card while filtered moves it to the place in the
+whole list of the card it is dropped on, so the todos hidden between them
+shift around it.
 
-On a phone the tabs sit along the bottom, in reach of a thumb; on anything
-wider they run down a sidebar. If the server stops answering, the header says
-it is offline, since what the page shows may be stale.
+If the server stops answering, the header says it is offline, since what the
+page shows may be stale.
 
 Todo writes are the same functions as `arbor todo add`, `update` and
 `remove`. Questions are answered in the agent's chat, not here. Merging,
@@ -332,14 +344,15 @@ imports, a signature changed on one side and its callers on the other) and
 unreliable when both sides restructured the same logic, because then there is no
 correct merge, only a decision.
 
-### `arbor todo add <subject> [text] [--position <n>] [--file <path>]`, `arbor todo list [--json]`, `arbor todo show <id> [--json]`, `arbor todo update <id> [text] [--subject <subject>] [--position <n>] [--file <path>] [--remove-file <name>]`, `arbor todo take <id...>`, `arbor todo release <id...>`, `arbor todo remove <id>`
+### `arbor todo add <subject> [text] [--position <n>] [--file <path>] [--tag <tag>]`, `arbor todo list [--json] [--open] [--tag <tag>]`, `arbor todo show <id> [--json]`, `arbor todo update <id> [text] [--subject <subject>] [--position <n>] [--file <path>] [--remove-file <name>] [--tag <tag>] [--remove-tag <tag>]`, `arbor todo tags [--json]`, `arbor todo take <id...>`, `arbor todo release <id...>`, `arbor todo remove <id>`
 
 Work deferred for later. When something outside the task comes up (a bug next
 door, a follow-up the reviewer asked for, a question that turns out to be its
 own project), the agent notes it with `arbor todo add` and carries on instead
 of growing the task. Run from a worktree, `add` records the task it came up
 in. A todo is a subject, one line that `list` and `merge` show, and an optional
-detail below it that `show` prints in full.
+detail below it in markdown, which `show` prints in full and the `dev` page
+renders.
 
 The list is in order: position 1 is the top, and after a task's own todos,
 the open todo highest on it is the one `merge` recommends next. A new one goes to the bottom, or with
@@ -358,6 +371,8 @@ run from a worktree, adds them to the task already under way, all or none.
 A task can hold any number. `release` puts them back on the list, from a
 worktree only its own task's: a task landing with one half done rewords it to
 what is left with `update`, then releases it, so the merge leaves it open.
+`list --open` shows only those no task holds, which is what an agent
+looking for work to pick up wants.
 `update` rewords one, its detail as the argument and its subject with
 `--subject`, and keeps its number; `remove` drops one done some other way or
 no longer wanted.
@@ -367,6 +382,13 @@ no longer wanted.
 one, named by path or by its stored file name (`todo show` lists them). They
 go when the todo does.
 
+`--tag uploads,merge` tags a todo with the areas or goals it belongs to; a
+todo can have several tags and a tag many todos. A tag is a lowercase word,
+or a few joined by hyphens, and anything else is refused, so one area never
+splits into two spellings. `update --tag` adds tags, `--remove-tag` drops them,
+`list --tag` shows only one tag's todos, and `todo tags` lists every tag in
+use with how many todos have it.
+
 ### `arbor retry <task>`
 
 Grants an escalated task another `mergeRetryCount` merge attempts and puts it

package/add.test.ts

@@ -0,0 +1,125 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { join } from "node:path";
+import { add } from "./add";
+import { Testing } from "./testing";
+
+describe("add", () => {
+	let deps: Testing;
+
+	beforeEach(async () => {
+		deps = await Testing.open();
+	});
+
+	afterEach(() => deps.disposeAsync());
+
+	it("makes a worktree, a branch and a record", async () => {
+		await add(deps, "alpha");
+
+		const state = (await deps.service.find("alpha")).state;
+		expect(state).toMatchObject({
+			task: "alpha",
+			branch: "task/alpha",
+			status: "working",
+			mergeAttempts: 0,
+		});
+		expect(await deps.fs.exists(join(state?.worktree ?? "", "README.md"))).toBe(
+			true,
+		);
+		expect(
+			await deps.gitCli(
+				state?.worktree ?? "",
+				"rev-parse",
+				"--abbrev-ref",
+				"HEAD",
+			),
+		).toBe("task/alpha");
+		expect(deps.out()).toContain("added alpha");
+	});
+
+	it("leaves a stub ARBOR.md for the agent to fill in", async () => {
+		await add(deps, "alpha");
+
+		const state = (await deps.service.find("alpha")).state;
+		const plan = await deps.fs.read(join(state?.worktree ?? "", "ARBOR.md"));
+		expect(plan).toStartWith("# alpha\n");
+		expect(plan).toContain("## Goal");
+		expect(plan).toContain("## Files");
+		expect(plan).toContain("- [ ]");
+	});
+
+	it("excludes the plan from git, once, so no task can commit it", async () => {
+		await add(deps, "alpha");
+		await add(deps, "beta");
+
+		const exclude = await deps.fs.read(
+			join(deps.root, ".git", "info", "exclude"),
+		);
+		expect(exclude.split("\n").filter((line) => line === "ARBOR.md")).toEqual([
+			"ARBOR.md",
+		]);
+		const state = (await deps.service.find("alpha")).state;
+		expect(
+			await deps.gitCli(state?.worktree ?? "", "status", "--porcelain"),
+		).toBe("");
+	});
+
+	it("refuses a name that is already taken and points at claim", async () => {
+		await add(deps, "alpha");
+
+		await expect(add(deps, "alpha")).toBail("exists", {
+			message: "arbor claim alpha",
+		});
+	});
+
+	it("rejects names that are not legal branch or directory names", async () => {
+		const names = ["Alpha", "a b", "feature/x", "-alpha", ""];
+
+		await Promise.all(
+			names.map((name) => expect(add(deps, name)).toBail("usage")),
+		);
+	});
+
+	it("refuses a repo with submodules, before making anything", async () => {
+		await deps.fs.write(join(deps.root, ".gitmodules"), "");
+
+		await expect(add(deps, "alpha")).toBail("usage", {
+			message: ".gitmodules",
+		});
+		expect((await deps.service.find("alpha")).gone).toBe(true);
+	});
+
+	it("reports a failed postCheckout hook but keeps the worktree", async () => {
+		deps.config.postCheckout = "exit 3";
+
+		await expect(add(deps, "alpha")).toBail("hook_failed");
+		const state = (await deps.service.find("alpha")).state;
+		expect(await deps.fs.exists(state?.worktree ?? "")).toBe(true);
+	});
+
+	it("tells the postCheckout hook which branch the trunk is", async () => {
+		deps.config.trunk = "master";
+		deps.config.postCheckout = "printenv ARBOR_TRUNK > trunk.txt";
+
+		await add(deps, "alpha", { base: "main" });
+
+		const state = (await deps.service.find("alpha")).state;
+		expect(await deps.fs.read(join(state?.worktree ?? "", "trunk.txt"))).toBe(
+			"master\n",
+		);
+	});
+
+	it("names the trunk and the config when the trunk is not a branch", async () => {
+		deps.config.trunk = "master";
+
+		await expect(add(deps, "alpha")).toBail("usage", {
+			message: ["trunk 'master'", "arbor.config.ts"],
+		});
+	});
+
+	it("refuses with a reason, a message and the data behind it", async () => {
+		await expect(add(deps, "Alpha")).toBail("usage", {
+			message: "invalid task name 'Alpha'",
+			data: { task: "Alpha" },
+		});
+	});
+});

package/add.ts

@@ -0,0 +1,192 @@
+import { color, type Logger } from "webappwiz/log";
+import { MarkdownWriter } from "webappwiz/md";
+import type { Fs } from "webappwiz/system";
+import type { Config } from "./config";
+import { fail } from "./exit";
+import { PLAN_FILE } from "./plan";
+import type { Shell } from "./shell";
+import type { Todo, Todos } from "./todo";
+import type { WorktreeService } from "./worktree-service";
+
+const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export interface AddOptions {
+	/** Branch the task starts from and merges onto. Defaults to the trunk. */
+	base?: string;
+	/**
+	 * The todos this task takes up: their words seed the plan's Goal, and
+	 * nobody else can take them while the task lives.
+	 */
+	todos?: number[];
+}
+
+export async function add(
+	{
+		service,
+		shell,
+		config,
+		log,
+		fs,
+		todos,
+	}: {
+		service: WorktreeService;
+		shell: Shell;
+		config: Config;
+		log: Logger;
+		fs: Fs;
+		todos: Todos;
+	},
+	task: string,
+	{ base = config.trunk, todos: ids = [] }: AddOptions = {},
+): Promise<void> {
+	if (!NAME.test(task)) {
+		fail(
+			"usage",
+			`invalid task name '${task}': use lowercase letters, digits and dashes`,
+			{ task },
+		);
+	}
+
+	// A worktree gets its own empty submodule directories, so every task would
+	// have to bootstrap them before anything builds. Refuse the repo instead.
+	// Git only reads the superproject's top-level file, so there is nowhere else
+	// to look; a stale one with no live gitlink refuses too, which is the safe
+	// direction to be wrong in.
+	if (await fs.exists(`${service.git.root}/.gitmodules`)) {
+		fail(
+			"usage",
+			"this repo has git submodules (.gitmodules), which arbor does not support: worktrees do not share them",
+			{ task },
+		);
+	}
+
+	const found = await service.find(task);
+	if (found.status === "stray") {
+		fail(
+			"exists",
+			`branch ${found.branch} exists without a worktree: run \`arbor remove ${task}\` first`,
+			{ task, branch: found.branch },
+		);
+	}
+	if (!found.gone) {
+		fail(
+			"exists",
+			`task '${task}' already exists: run \`arbor claim ${task}\``,
+			{ task, worktree: found.path },
+		);
+	}
+
+	// Looked up before anything is created, so a todo that is gone or taken
+	// refuses the whole add instead of leaving a tree behind.
+	const taken: Todo[] = [];
+	for (const id of new Set(ids)) {
+		const todo = await todos.find(id);
+		if (todo.takenBy) {
+			await todo.take(task); // refuses, naming the task that has it
+		}
+		taken.push(todo);
+	}
+
+	const added = await service.add(task, { base });
+	if (added.code !== 0) {
+		// git's own "invalid reference" sends people to the branch, when what is
+		// wrong is which branch arbor thinks the trunk is.
+		const missingTrunk =
+			base === config.trunk && !(await service.git.branchExists(base));
+		fail(
+			"usage",
+			missingTrunk
+				? `trunk '${base}' is not a branch in this repo: set \`trunk\` in arbor.config.ts`
+				: `git worktree add failed: ${added.stderr}`,
+			{ task },
+		);
+	}
+
+	const worktree = await (await service.find(task)).take({ base });
+
+	// The plan is scratch for one task and must never land on trunk. Excluding
+	// it through the shared `.git` covers every worktree at once and leaves the
+	// repo's own .gitignore, which arbor would have to commit to, alone.
+	const info = `${await service.git.commonDir()}/info`;
+	const excluded = await fs.read(`${info}/exclude`).catch(() => "");
+	if (!excluded.split("\n").includes(PLAN_FILE)) {
+		await fs.mkdir(info);
+		await fs.write(
+			`${info}/exclude`,
+			`${excluded.trimEnd()}\n${PLAN_FILE}\n`.trimStart(),
+		);
+	}
+
+	await fs.write(
+		`${worktree.path}/${PLAN_FILE}`,
+		PLAN(task, taken.length === 0 ? null : goal(taken)),
+	);
+	for (const todo of taken) {
+		await todo.take(task);
+	}
+
+	// A fresh worktree shares no untracked files with the repo: no node_modules,
+	// no .env. That is what the hook is for.
+	if (config.postCheckout) {
+		const { exitCode } = await shell.stream(
+			config.postCheckout,
+			worktree.path,
+			{
+				env: {
+					ARBOR_TASK: task,
+					ARBOR_WORKTREE: worktree.path,
+					ARBOR_TRUNK: config.trunk,
+				},
+			},
+		);
+		if (exitCode !== 0) {
+			// The worktree stays. Rolling back would throw away a tree the agent
+			// can fix by hand and re-run the hook in.
+			fail(
+				"hook_failed",
+				`postCheckout hook failed (exit ${exitCode}); worktree left in place at ${worktree.path}`,
+				{ task, worktree: worktree.path },
+			);
+		}
+	}
+
+	log.info(
+		`${color.green("added")} ${task}\n  worktree: ${worktree.path}\n  branch:   ${worktree.branch}\n  base:     ${base}`,
+	);
+}
+
+/**
+ * Todos as a Goal: each one's subject and detail, and each file attached to it
+ * by path, which stay readable until the task lands and takes the todo with
+ * it. One todo is the Goal as it stands; several are each named by id.
+ */
+function goal(todos: Todo[]): string {
+	return todos
+		.map((todo) => {
+			const subject =
+				todos.length === 1 ? todo.subject : `Todo ${todo.id}: ${todo.subject}`;
+			return [
+				subject,
+				todo.text,
+				todo.files.map((path) => `Attached: \`${path}\``).join("\n"),
+			]
+				.filter(Boolean)
+				.join("\n\n");
+		})
+		.join("\n\n");
+}
+
+/** The plan a fresh task starts with. `## Goal` is the todos it takes up, if
+ * any; it and `## Files` are otherwise left empty on purpose: `arbor show` nags
+ * until the agent fills them in. */
+function PLAN(task: string, goal: string | null): string {
+	const writer = new MarkdownWriter().heading(1, task).heading(2, "Goal");
+	if (goal !== null) {
+		writer.text(goal);
+	}
+	return writer
+		.heading(2, "Files")
+		.heading(2, "Next")
+		.checklist("fill in Goal and list the steps here as `- [ ]` items")
+		.toString();
+}

package/age.ts

@@ -0,0 +1,11 @@
+/** How long ago an ISO timestamp was, at the coarsest unit that still reads. */
+export function age(since: string): string {
+	const minutes = Math.floor((Date.now() - Date.parse(since)) / 60_000);
+	if (minutes < 60) {
+		return `${minutes}m`;
+	}
+	if (minutes < 60 * 24) {
+		return `${Math.floor(minutes / 60)}h`;
+	}
+	return `${Math.floor(minutes / (60 * 24))}d`;
+}

package/arbor.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, it } from "bun:test";
+import { basename, join } from "node:path";
+import { arbor } from "./arbor";
+import { Testing } from "./testing";
+
+/**
+ * The cli in this process, run with fakes: the same commands `e2e.test.ts`
+ * spawns, minus the subprocess. What it proves is the wiring, that every
+ * dependency an action uses arrives through `run`.
+ */
+describe("arbor cli", () => {
+	it("runs its commands against the dependencies it is given", async () => {
+		await using env = await Testing.open();
+		env.ps.cd(env.root);
+		const deps = {
+			log: env.log,
+			fs: env.fs,
+			ps: env.ps,
+			assets: env.assets,
+		};
+
+		await arbor.run(deps, ["add", "alpha"]);
+		await arbor.run(deps, ["list", "--json"]);
+
+		const rows = JSON.parse(String(env.log.entries.at(-1)?.message));
+		expect(rows).toMatchObject([{ task: "alpha", status: "working" }]);
+		expect(await env.fs.exists(join(`${env.root}-arbor`, "alpha"))).toBe(true);
+	});
+
+	it("escalates a task and edits its todos", async () => {
+		await using env = await Testing.open();
+		env.ps.cd(env.root);
+		const deps = {
+			log: env.log,
+			fs: env.fs,
+			ps: env.ps,
+			assets: env.assets,
+		};
+		await arbor.run(deps, ["add", "alpha"]);
+		const worktree = await env.service.find("alpha");
+		await env.fs.write(
+			join(worktree.path, "ARBOR.md"),
+			"# alpha\n\n## Blocked\n\n- [ ] 1. Open it.\n",
+		);
+		await env.fs.write(join(env.root, "a.png"), "a");
+		env.ps.cd(worktree.path);
+		await arbor.run(deps, ["escalate", "needs a person"]);
+
+		env.ps.cd(env.root);
+		await arbor.run(deps, [
+			"todo",
+			"add",
+			"write docs",
+			"the CLI first",
+			"--file",
+			"a.png",
+		]);
+		const [attached = ""] = (await env.todos.find(1)).files;
+		await arbor.run(deps, [
+			"todo",
+			"update",
+			"1",
+			"--subject",
+			"write the docs",
+			"--position",
+			"1",
+			"--remove-file",
+			basename(attached),
+		]);
+		expect((await env.todos.find(1)).state).toMatchObject({
+			subject: "write the docs",
+			text: "the CLI first",
+			position: 1,
+			files: [],
+		});
+
+		await arbor.run(deps, ["log", "--json"]);
+		const entries = JSON.parse(String(env.log.entries.at(-1)?.message));
+		expect(entries.map((entry: { action: string }) => entry.action)).toContain(
+			"escalate",
+		);
+	});
+
+	it("asks for a review from the command line", async () => {
+		await using env = await Testing.open();
+		env.ps.cd(env.root);
+		const deps = {
+			log: env.log,
+			fs: env.fs,
+			ps: env.ps,
+			assets: env.assets,
+		};
+		await arbor.run(deps, ["add", "alpha"]);
+
+		await arbor.run(deps, [
+			"escalate",
+			"check the header",
+			"--task",
+			"alpha",
+			"--review",
+		]);
+
+		const worktree = await env.service.find("alpha");
+		expect(worktree.state?.escalations?.at(-1)?.review).toBe("1");
+		expect(await env.fs.read(join(worktree.path, "ARBOR.md"))).toContain(
+			"- [ ] 1. Ready to merge?\n  check the header\n",
+		);
+	});
+
+	it("reports a refusal as a reason, a message and an exit code", async () => {
+		await using env = await Testing.open();
+		env.ps.cd(env.root);
+
+		await arbor.run(
+			{
+				log: env.log,
+				fs: env.fs,
+				ps: env.ps,
+				assets: env.assets,
+			},
+			["claim", "nope"],
+		);
+
+		expect(env.out()).toContain('"reason":"not_found"');
+		expect(env.proc.lastExit()).toBe(8);
+	});
+
+	it("refuses a port that cannot exist rather than trying to listen", async () => {
+		await using env = await Testing.open();
+		env.ps.cd(env.root);
+
+		await arbor.run(
+			{
+				log: env.log,
+				fs: env.fs,
+				ps: env.ps,
+				assets: env.assets,
+			},
+			["dev", "--port", "99999"],
+		);
+
+		expect(env.out()).not.toContain("  reply ");
+		expect(env.proc.lastExit()).toBe(1);
+	});
+});