@webappwiz/arbor 0.0.30 → 0.0.32

package/arbor.test.ts

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

package/arbor.ts

@@ -1,429 +0,0 @@
-import { cli, type Deps } from "webappwiz/cmd";
-import type { Fs } from "webappwiz/system";
-import { Duration } from "webappwiz/time";
-import { z } from "zod";
-import { add } from "./add";
-import { claim } from "./claim";
-import { DEFAULT_PORT, dev, devPorts } from "./dev";
-import type { Assets } from "./dev/assets";
-import { escalate } from "./escalate";
-import { exits, fail } from "./exit";
-import { list } from "./list";
-import { DEFAULT_COUNT, log as showLog } from "./log";
-import { merge } from "./merge";
-import { path } from "./path";
-import { remove } from "./remove";
-import { type Repository, repository } from "./repository";
-import { retry } from "./retry";
-import { show } from "./show";
-import {
-	todoAdd,
-	todoList,
-	todoRelease,
-	todoRemove,
-	todoShow,
-	todoTags,
-	todoTake,
-	todoUpdate,
-} from "./todo";
-import { DEFAULT_TIMEOUT, wait } from "./wait";
-
-/** Everything `arbor` is run with, before the repository middleware adds to it. */
-export interface ArborDeps extends Deps {
-	fs: Fs;
-	/** The built page `dev` serves as its preview. */
-	assets: Assets;
-}
-
-// Outermost first: a refusal raised in an action unwinds past `repository` and
-// stops at `exits`, which is the only thing that ends the process.
-export const arbor = cli<ArborDeps>("arbor")
-	.use(exits<ArborDeps>())
-	.use(repository<ArborDeps>());
-
-// Every action is handed the dependencies it runs with, so it passes the
-// context straight on: each command takes the few it names off it.
-arbor
-	.command("add")
-	.description(
-		"start a new task: create branch task/<task>, a worktree at ../<repo>-arbor/<task> and a state record",
-	)
-	.arg("task", z.string(), { description: "task name (lowercase-with-dashes)" })
-	.option("base", z.string(), {
-		default: "",
-		description:
-			"branch this task starts from and merges onto (default: trunk); `task/<other>` stacks this task on that one and lands the work in its worktree",
-	})
-	.option("todo", z.string(), {
-		default: "",
-		description:
-			"take up these todos, comma separated: their words become the plan's Goal, merging removes them, and removing the task puts them back",
-	})
-	.action((opts, ctx) =>
-		ctx.journal.record("add", opts.task, () =>
-			add(ctx, opts.task, {
-				base: opts.base || undefined,
-				todos: todoIds(opts.todo),
-			}),
-		),
-	);
-
-arbor
-	.command("claim")
-	.description(
-		"resume an existing task: take ownership of its worktree and print its path, status and any half-finished rebase; an escalated task goes back to working; refuses while another agent holds the lease, but takes a stale one silently, so `arbor show` first if the tree may not be abandoned",
-	)
-	.arg("task", z.string(), { description: "task name" })
-	.action((opts, ctx) =>
-		ctx.journal.record("claim", opts.task, () => claim(ctx, opts.task)),
-	);
-
-arbor
-	.command("merge")
-	.description(
-		"land this worktree's branch on its base (trunk unless created with --base): rebase onto it, run tests on the rebased code, fast-forward it in whichever worktree has it checked out, then discard the worktree, branch and record (linear history, never a merge commit, no flag to skip tests); requires committed work, refusing a dirty worktree",
-	)
-	.action(async (_opts, ctx) =>
-		ctx.journal.record("merge", await here(ctx), () =>
-			merge(ctx, ctx.ps.cwd()),
-		),
-	);
-
-arbor
-	.command("remove")
-	.description(
-		"discard a task: worktree, branch and state file; cheap and encouraged, since redoing a task against current trunk often beats a hard rebase",
-	)
-	.arg("task", z.string(), { description: "task name" })
-	.option("force", z.boolean(), {
-		default: false,
-		description: "discard even when another agent holds the lease",
-	})
-	.action((opts, ctx) =>
-		ctx.journal.record("remove", opts.task, () =>
-			remove(ctx, opts.task, { force: opts.force }),
-		),
-	);
-
-arbor
-	.command("list")
-	.description(
-		"list every task: name, status, lease (held: an agent is on it now; stale: gone quiet, normal for a task mid-edit; none), commits ahead of trunk, age",
-	)
-	.option("json", z.boolean(), { default: false, description: "emit JSON" })
-	.option("files", z.boolean(), {
-		default: false,
-		description:
-			"add each task's changed files (committed or not) and the files its ARBOR.md plans to touch, to check for overlap before starting",
-	})
-	.action((opts, ctx) => list(ctx, { json: opts.json, files: opts.files }));
-
-arbor
-	.command("show")
-	.description(
-		"read one task without touching it: everything `list` shows for it, plus the ARBOR.md its agent left at the worktree root; takes no lease, so it cannot knock that agent off its own tree",
-	)
-	.arg("task", z.string(), { description: "task name" })
-	.option("json", z.boolean(), { default: false, description: "emit JSON" })
-	.action((opts, ctx) => show(ctx, opts.task, { json: opts.json }));
-
-arbor
-	.command("wait")
-	.description(
-		"block until a task stops moving: escalated, or gone (merged or removed), or broken; takes no lease, and gives up with `timeout` rather than waiting forever",
-	)
-	.arg("task", z.string(), { description: "task name" })
-	.option("timeout-secs", z.coerce.number(), {
-		default: DEFAULT_TIMEOUT.secs,
-		description: "how long to wait before giving up",
-	})
-	.action((opts, ctx) =>
-		wait(ctx, opts.task, {
-			timeout: Duration.secs(opts["timeout-secs"]),
-		}),
-	);
-
-arbor
-	.command("log")
-	.description(
-		"show what has been done here recently: one line per add, claim, merge, remove, escalate, retry, todo and more, with how it ended; outlives the tasks themselves",
-	)
-	.option("count", z.coerce.number(), {
-		default: DEFAULT_COUNT,
-		description: "how many entries to show",
-	})
-	.option("json", z.boolean(), { default: false, description: "emit JSON" })
-	.action((opts, ctx) => showLog(ctx, { count: opts.count, json: opts.json }));
-
-arbor
-	.command("dev")
-	.description(
-		"serve the todos and the tasks as a web page on this machine, where todos can be added, updated, reordered or removed",
-	)
-	.option("port", z.coerce.number(), {
-		default: DEFAULT_PORT,
-		description: "port to listen on, or the next open one above it",
-	})
-	.option("allow-hosts", z.string(), {
-		default: "",
-		description:
-			"comma-separated host names the page may also be reached by, like a tunnel's; putting a login in front of them is the tunnel's job",
-	})
-	.action((opts, ctx) =>
-		dev(ctx, {
-			ports: devPorts(opts.port),
-			hosts: opts["allow-hosts"]
-				.split(",")
-				.map((host) => host.trim())
-				.filter(Boolean),
-		}),
-	);
-
-arbor
-	.command("path")
-	.description(
-		"print a task's worktree path, or the main tree with no task; names another agent's tree without taking its lease",
-	)
-	.arg("task", z.string(), {
-		default: "",
-		description: "task name; omit for the main tree",
-	})
-	.action((opts, ctx) => path(ctx, opts.task || undefined));
-
-arbor
-	.command("escalate")
-	.description(
-		"hand this task to a human and stop: records the reason, drops the lease and leaves the worktree exactly as it is; use instead of resolving a genuine conflict badly just to finish",
-	)
-	.arg("reason", z.string(), {
-		description:
-			"why this needs a human; with --review, what to look at before approving",
-	})
-	.option("task", z.string(), {
-		default: "",
-		description: "task name, when run outside its worktree",
-	})
-	.option("review", z.boolean(), {
-		default: false,
-		description:
-			"ask a person to approve merging: adds a `Ready to merge?` question under ## Blocked with the reason as its detail, answered in chat; refused while another question is unchecked",
-	})
-	.action(async (opts, ctx) =>
-		ctx.journal.record("escalate", opts.task || (await here(ctx)), () =>
-			escalate(ctx, opts.reason, ctx.ps.cwd(), {
-				task: opts.task || undefined,
-				review: opts.review,
-			}),
-		),
-	);
-
-arbor
-	.command("retry")
-	.description(
-		"give an escalated task another mergeRetryCount merge attempts and put it back to working; the way out of `budget_exhausted` that is not remove and redo, and only from escalated, so a human has seen the tree first",
-	)
-	.arg("task", z.string(), { description: "task name" })
-	.action((opts, ctx) =>
-		ctx.journal.record("retry", opts.task, () => retry(ctx, opts.task)),
-	);
-
-/** A place in the todo list, 1 at the top; absent leaves it to the command. */
-const position = z.coerce.number().int().positive().optional();
-
-const todo = arbor
-	.group("todo")
-	.description(
-		"defer work for later instead of growing the task you are in: `merge` recommends the next one when a task lands",
-	);
-
-todo
-	.command("add")
-	.description(
-		"note something to do later and move on; run from a worktree, it records the task it came up in",
-	)
-	.arg("subject", z.string(), { description: "what is left to do, in a line" })
-	.arg("text", z.string(), {
-		default: "",
-		description: "whatever more there is to say about it, in markdown",
-	})
-	.option("position", position, {
-		description:
-			"where it goes in the list, 1 at the top, pushing those from there down (default: the bottom)",
-	})
-	.option("file", z.string(), {
-		default: "",
-		description:
-			"files to attach, comma separated: copied under .git/arbor/todos/<id>/",
-	})
-	.option("tag", z.string(), {
-		default: "",
-		description:
-			"tags, comma separated, each one lowercase word (or a few joined by hyphens): the areas or goals it belongs to; `arbor todo tags` lists those in use",
-	})
-	.action(async (opts, ctx) => {
-		const from = await here(ctx);
-		await ctx.journal.record("todo add", from, () =>
-			todoAdd(ctx, opts.subject, from, {
-				text: opts.text,
-				position: opts.position,
-				files: commaList(opts.file),
-				tags: commaList(opts.tag),
-			}),
-		);
-	});
-
-todo
-	.command("list")
-	.description(
-		"every todo, top of the list first, with the task it came from and the task that took it up",
-	)
-	.option("json", z.boolean(), { default: false, description: "emit JSON" })
-	.option("open", z.boolean(), {
-		default: false,
-		description: "only todos no task has taken up: the ones free to pick up",
-	})
-	.option("tag", z.string(), {
-		default: "",
-		description: "only todos with this tag",
-	})
-	.action((opts, ctx) =>
-		todoList(ctx, {
-			json: opts.json,
-			open: opts.open,
-			tag: opts.tag || undefined,
-		}),
-	);
-
-todo
-	.command("tags")
-	.description(
-		"every tag in use, with how many todos have it: reuse one before making up another",
-	)
-	.option("json", z.boolean(), { default: false, description: "emit JSON" })
-	.action((opts, ctx) => todoTags(ctx, { json: opts.json }));
-
-todo
-	.command("show")
-	.description("one todo in full: where it stands, its files, and its detail")
-	.arg("id", z.coerce.number().int().positive(), { description: "todo id" })
-	.option("json", z.boolean(), { default: false, description: "emit JSON" })
-	.action((opts, ctx) => todoShow(ctx, opts.id, { json: opts.json }));
-
-todo
-	.command("update")
-	.description(
-		"say what a todo is in other words, move it up or down the list, tag it, or attach and drop files; it keeps its id",
-	)
-	.arg("id", z.coerce.number().int().positive(), { description: "todo id" })
-	.arg("text", z.string(), {
-		default: "",
-		description:
-			"whatever more there is to say about it, in markdown; leave out to keep the detail",
-	})
-	.option("subject", z.string(), {
-		default: "",
-		description: "what is left to do, in a line; leave out to keep it",
-	})
-	.option("position", position, {
-		description:
-			"where to move it in the list, 1 at the top; the others close up around it",
-	})
-	.option("file", z.string(), {
-		default: "",
-		description: "files to attach, comma separated",
-	})
-	.option("remove-file", z.string(), {
-		default: "",
-		description:
-			"attached files to drop, comma separated, by path or stored name",
-	})
-	.option("tag", z.string(), {
-		default: "",
-		description: "tags to add, comma separated",
-	})
-	.option("remove-tag", z.string(), {
-		default: "",
-		description: "tags to drop, comma separated",
-	})
-	.action((opts, ctx) =>
-		ctx.journal.record("todo update", null, () =>
-			todoUpdate(ctx, opts.id, {
-				subject: opts.subject,
-				text: opts.text,
-				position: opts.position,
-				files: commaList(opts.file),
-				removeFiles: commaList(opts["remove-file"]),
-				tags: commaList(opts.tag),
-				removeTags: commaList(opts["remove-tag"]),
-			}),
-		),
-	);
-
-todo
-	.command("take")
-	.description(
-		"take up todos for the task whose worktree you are in, as when they turn out to be part of its work: merging removes them, removing the task puts them back",
-	)
-	.rest("ids", z.coerce.number().int().positive(), {
-		description: "todo ids",
-	})
-	.action(async (opts, ctx) => {
-		const task = await here(ctx);
-		await ctx.journal.record("todo take", task, () =>
-			todoTake(ctx, opts.ids, task),
-		);
-	});
-
-todo
-	.command("release")
-	.description(
-		"put taken todos back on the list, as when a task lands without finishing them: `arbor todo update` the leftover first; from a worktree, only its own task's",
-	)
-	.rest("ids", z.coerce.number().int().positive(), {
-		description: "todo ids",
-	})
-	.action(async (opts, ctx) => {
-		const task = await here(ctx);
-		await ctx.journal.record("todo release", task, () =>
-			todoRelease(ctx, opts.ids, task),
-		);
-	});
-
-todo
-	.command("remove")
-	.description("drop a todo that was done some other way or no longer applies")
-	.arg("id", z.coerce.number().int().positive(), { description: "todo id" })
-	.action((opts, ctx) =>
-		ctx.journal.record("todo remove", null, () => todoRemove(ctx, opts.id)),
-	);
-
-/** `--todo 3,5` as ids, refusing anything that is not one. */
-function todoIds(raw: string): number[] {
-	return commaList(raw).map((value) => {
-		const id = Number(value);
-		if (!Number.isInteger(id) || id <= 0) {
-			fail("usage", `'${value}' is not a todo id`, { todo: value });
-		}
-		return id;
-	});
-}
-
-/** A comma-separated flag's values, with no empty ones. */
-function commaList(raw: string): string[] {
-	return raw
-		.split(",")
-		.map((value) => value.trim())
-		.filter(Boolean);
-}
-
-/**
- * Which task a command that takes no task name is about, so the journal can
- * name it. `merge` and `escalate` read it off the current branch.
- */
-async function here({
-	service,
-	git,
-	ps,
-}: ArborDeps & Repository): Promise<string | null> {
-	return service.taskFor(await git.currentBranch(ps.cwd()).catch(() => ""));
-}

package/assets.d.ts

@@ -1,9 +0,0 @@
-// Bun imports any file as text with `with { type: "text" }`, but its types only
-// declare the extensions it treats as text by default, and for `.html` and
-// `.css` it declares something else entirely. The three files the dev page is
-// served from are written as `.txt` for that reason: they are blobs a server
-// hands to a browser, not modules anything here imports for their exports.
-declare module "*.txt" {
-	const text: string;
-	export default text;
-}

package/attachments.ts

@@ -1,87 +0,0 @@
-import { basename, resolve } from "node:path";
-import { type IdProvider, UuidProvider } from "webappwiz/id";
-import type { Fs, Ps } from "webappwiz/system";
-import { fail } from "./exit";
-
-/** A file handed over, as bytes so a pasted image needs no temp file. */
-export interface Attachment {
-	/** What it was called, kept in the stored name so the files stay apart. */
-	name: string;
-	bytes: Uint8Array;
-}
-
-/**
- * The folder of files that belong to a todo: todo 7's beside its record, in
- * `todos/7/`.
- * Under `.git/arbor`, so nothing here is ever committed and every tree can
- * open what it holds.
- */
-export class Attachments {
-	constructor(
-		readonly dir: string,
-		private readonly fs: Fs,
-		private readonly ids: IdProvider = new UuidProvider(),
-	) {}
-
-	/** Copies each file in, returning the absolute path each was stored at. */
-	async store(files: Attachment[]): Promise<string[]> {
-		if (files.length === 0) {
-			return [];
-		}
-		await this.fs.mkdir(this.dir);
-		const stored: string[] = [];
-		for (const file of files) {
-			const path = `${this.dir}/${this.ids.next()}-${safe(file.name)}`;
-			await this.fs.writeBytes(path, file.bytes);
-			stored.push(path);
-		}
-		return stored;
-	}
-
-	/** Whether `path` is one of this folder's files, and not a way out of it. */
-	owns(path: string): boolean {
-		return resolve(path).startsWith(`${resolve(this.dir)}/`);
-	}
-
-	/** Deletes the files given that are this folder's; others are left alone. */
-	async remove(paths: string[]): Promise<void> {
-		for (const path of paths.filter((path) => this.owns(path))) {
-			await this.fs.rm(path, { force: true });
-		}
-	}
-
-	/** Deletes the folder and everything in it. */
-	async clear(): Promise<void> {
-		await this.fs.rm(this.dir, { recursive: true, force: true });
-	}
-}
-
-/**
- * Reads files named on the command line, relative to the current directory or
- * absolute, refusing the whole command over one that cannot be read.
- */
-export async function readFiles(
-	{ fs, ps }: { fs: Fs; ps: Ps },
-	paths: string[],
-): Promise<Attachment[]> {
-	const read: Attachment[] = [];
-	for (const given of paths) {
-		const path = resolve(ps.cwd(), given);
-		const bytes = await fs.readBytes(path).catch(() => null);
-		if (bytes === null) {
-			fail("usage", `cannot read ${path}: nothing was changed`, {
-				file: path,
-			});
-		}
-		read.push({ name: basename(path), bytes });
-	}
-	return read;
-}
-
-/**
- * A stored name that survives being written into a one-line reply: paths are
- * separated by spaces there, so nothing in them may be one.
- */
-function safe(name: string): string {
-	return basename(name).replace(/[^\w.-]+/g, "-") || "attachment";
-}