@webappwiz/arbor 0.0.28 → 0.0.30

package/arbor.ts

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

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

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

package/build.ts

@@ -0,0 +1,98 @@
+import { dirname, resolve } from "node:path";
+import { Scanner } from "@tailwindcss/oxide";
+import { compile } from "tailwindcss";
+
+/**
+ * Builds the `arbor dev` page: the React app as one script, and the stylesheet
+ * with Tailwind compiled. `dev/assets.ts` imports both as text, so they end up
+ * inside the bundle a release publishes and the server hands them straight to
+ * the browser.
+ *
+ * This runs here rather than on the first page load of every `arbor dev`, which
+ * is what keeps React and Tailwind out of the published dependencies: a person
+ * installing the CLI has no use for a toolchain that already ran. It is also
+ * the only place the compile can read our own configuration, since `arbor dev`
+ * runs inside whatever repository the user is in.
+ *
+ * `bun run build` in this package, and `bun install` at the workspace root,
+ * which is what puts the output there for a fresh checkout.
+ */
+
+const here = import.meta.dirname;
+const out = `${here}/dev/build`;
+
+/** The browser script, as one file with React and the page's modules in it. */
+async function script(): Promise<string> {
+	const built = await Bun.build({
+		entrypoints: [`${here}/dev/main.tsx`],
+		target: "browser",
+		// React's production build: the development one is several times the
+		// size, slower, and asks the person on the page to install DevTools.
+		define: { "process.env.NODE_ENV": '"production"' },
+		minify: true,
+		// Left to throw, a failure arrives as an AggregateError that says only
+		// "Bundle failed": which import went missing is in the logs, and whoever
+		// is reading the terminal needs that to know it is their install.
+		throw: false,
+	});
+	const [output] = built.outputs;
+	if (output === undefined) {
+		throw new Error(built.logs.map(String).join("\n"));
+	}
+	return output.text();
+}
+
+/**
+ * Where a package's stylesheet is: the `style` entry of its `exports`, which is
+ * where CSS packages like tw-animate-css put it. Bun's resolver does not
+ * follow that condition, so the package is found by walking up to it.
+ */
+async function stylesheet(name: string): Promise<string> {
+	for (let dir = here; ; dir = dirname(dir)) {
+		const root = `${dir}/node_modules/${name}`;
+		const manifest = Bun.file(`${root}/package.json`);
+		if (await manifest.exists()) {
+			const { exports, style } = await manifest.json();
+			const entry = exports?.["."]?.style ?? style ?? "index.css";
+			return resolve(root, entry);
+		}
+		if (dir === dirname(dir)) {
+			throw new Error(`no stylesheet package '${name}' above ${here}`);
+		}
+	}
+}
+
+/** The stylesheet, with only the utilities the page actually uses in it. */
+async function styles(): Promise<string> {
+	const base = `${here}/dev`;
+	const compiler = await compile(await Bun.file(`${base}/styles.css`).text(), {
+		base,
+		loadStylesheet: async (id: string, from: string) => {
+			// A stylesheet is asked for by bare package name (`@import "tailwindcss"`),
+			// then the parts of it by relative path. Only the bare names need module
+			// resolution; the rest are paths off a base already inside the package.
+			const path = id.startsWith(".")
+				? resolve(from, id)
+				: await stylesheet(id);
+			return {
+				path,
+				base: dirname(path),
+				content: await Bun.file(path).text(),
+			};
+		},
+	});
+	// The `@source` lines in styles.css say which files to read class names out
+	// of. Tailwind emits only the utilities it finds there.
+	return compiler.build(new Scanner({ sources: compiler.sources }).scan());
+}
+
+// All three as `.txt`: what they hold is a blob the server hands to a browser,
+// and the extensions they were authored under mean something else to a
+// compiler. `.js` would have tsc typecheck a bundle that already compiled, and
+// Bun's own types read `.html` and `.css` imports as something other than text.
+await Bun.write(
+	`${out}/shell.txt`,
+	await Bun.file(`${here}/dev/index.html`).text(),
+);
+await Bun.write(`${out}/main.txt`, await script());
+await Bun.write(`${out}/styles.txt`, await styles());