@webappwiz/arbor 0.0.30 → 0.0.32

package/todos.d.ts

@@ -0,0 +1,75 @@
+import { type IdProvider } from "webappwiz/id";
+import { type Fs, type Lock } from "webappwiz/system";
+import { Attachments } from "./attachments.js";
+import { type TagState, Todo, type TodoNew, type TodoState } from "./todo.js";
+/** Every todo in the repo, one JSON file each under `.git/arbor/todos`. */
+export declare class Todos {
+    readonly dir: string;
+    /**
+     * Held while numbering a new todo, so two agents never share an id, and
+     * while writing one, so a move renumbering the rest never loses to a
+     * write of a position it just changed.
+     */
+    private readonly lock;
+    private readonly fs;
+    private readonly ids;
+    constructor(dir: string, 
+    /**
+     * Held while numbering a new todo, so two agents never share an id, and
+     * while writing one, so a move renumbering the rest never loses to a
+     * write of a position it just changed.
+     */
+    lock: Lock, opts?: TodosOptions);
+    /** Where a todo's files live, beside its record. */
+    attachments(id: number): Attachments;
+    /** Whether `path` is a file some todo holds, and not a way out of here. */
+    owns(path: string): boolean;
+    add(subject: string, from: string | null, { text, files, position, tags }?: TodoNew): Promise<Todo>;
+    /**
+     * Top of the list first. A file that will not parse is skipped rather than
+     * fatal, and positions are counted again from 1 as they are read, so a
+     * gap or a tie left by a crash, or a todo saved before they had any (it
+     * goes below those that do, oldest first), never shows.
+     */
+    all(): Promise<Todo[]>;
+    find(id: number): Promise<Todo>;
+    /** Every tag a todo on the list has, by name, with how many have it. */
+    tags(): Promise<TagState[]>;
+    /** The todos `task` has taken; what a merge or remove settles. */
+    takenBy(task: string): Promise<Todo[]>;
+    /**
+     * Puts a todo at `position`, 1 at the top, past the bottom meaning the
+     * bottom, and numbers the rest around it.
+     */
+    move(id: number, position: number): Promise<Todo>;
+    /**
+     * @internal Rewrites one todo as it stands on disk now, under the lock, so
+     * a change to its words or who has it never undoes a move made meanwhile.
+     */
+    revise(id: number, change: (state: TodoState) => TodoState): Promise<Todo>;
+    /** @internal Writes one todo. Rename makes the swap atomic for readers. */
+    save(state: TodoState): Promise<Todo>;
+    /** @internal Removes one, moving those below it up to close the gap. */
+    delete(id: number): Promise<void>;
+    private locked;
+    /** One todo as it stands on disk; call it under the lock. */
+    private state;
+    /**
+     * Slots `state` in at `position` among the rest and saves whichever moved.
+     * Call it under the lock.
+     */
+    private place;
+    /** Every todo in list order, with the positions it has on disk. */
+    private stored;
+    /** Saves each todo in `order` whose position on disk is not its place there. */
+    private renumber;
+    private path;
+    private lastId;
+    private read;
+}
+/** What `Todos` is stored through; the real filesystem by default. */
+export interface TodosOptions {
+    fs?: Fs;
+    /** Names stored files apart; a test counts. */
+    ids?: IdProvider;
+}

package/wait.d.ts

@@ -0,0 +1,22 @@
+import { type Logger } from "webappwiz/log";
+import { Duration } from "webappwiz/time";
+import type { WorktreeService } from "./worktree-service.js";
+/** How long `wait` gives a task before handing the wait back to its caller. */
+export declare const DEFAULT_TIMEOUT: Duration;
+export interface WaitOptions {
+    /** How long to wait before giving up. */
+    timeout?: Duration;
+    /** How long between reads of the record; the default suits a human's patience. */
+    poll?: Duration;
+}
+/**
+ * Blocks until a task stops moving: merged or removed (both leave the name
+ * `removed`), escalated to a human, or broken. Waiting is for the agent whose
+ * own work overlaps this one's and would rather rebase onto the result than
+ * against it, which is why the timeout is short enough to come back and think
+ * again rather than block a session for an afternoon.
+ */
+export declare function wait({ service, log }: {
+    service: WorktreeService;
+    log: Logger;
+}, task: string, { timeout, poll }?: WaitOptions): Promise<void>;

package/worktree-service.d.ts

@@ -0,0 +1,51 @@
+import { type Fs, type Ps } from "webappwiz/system";
+import type { Config } from "./config.js";
+import type { Git, GitResult } from "./git.js";
+import { type TaskState, Worktree } from "./worktree.js";
+export interface AddOptions {
+    /** Branch the new worktree starts from. Defaults to the trunk. */
+    base?: string;
+}
+/**
+ * Where tasks live and everything persistent about them: the worktree
+ * directories, the records under `.git/arbor/tasks`, and the names of tasks
+ * already removed. One name, one lookup, whatever state it turns out to be in.
+ */
+/** What a `WorktreeService` works through; the real ones by default. */
+export interface WorktreeServiceOptions {
+    fs?: Fs;
+    ps?: Ps;
+}
+export declare class WorktreeService {
+    readonly git: Git;
+    readonly config: Config;
+    private readonly tasksDir;
+    private readonly removedDir;
+    private readonly fs;
+    readonly ps: Ps;
+    constructor(git: Git, config: Config, arborDir: string, opts?: WorktreeServiceOptions);
+    init(): Promise<void>;
+    get trunk(): string;
+    /** Where a task's worktree lives: a sibling of the repo, never inside it. */
+    pathFor(task: string): string;
+    branchFor(task: string): string;
+    taskFor(branch: string | null): string | null;
+    recordPath(task: string): string;
+    /** Always answers; the returned worktree's status says what was found. */
+    find(task: string): Promise<Worktree>;
+    list(): Promise<Worktree[]>;
+    /** Adds the branch and the working directory. The record comes after. */
+    add(task: string, { base }?: AddOptions): Promise<GitResult>;
+    discard(worktree: Worktree): Promise<GitResult>;
+    /** Writes a task's record. A concurrent reader sees the old one or the new. */
+    saveRecord(state: TaskState): Promise<void>;
+    private readRecord;
+    private removedPath;
+    private removedAt;
+    /**
+     * Remembers a removed name so a second `remove` can say "already removed"
+     * instead of "never existed", then drops the oldest so the list of
+     * remembered names cannot grow without bound.
+     */
+    private rememberRemoved;
+}

package/worktree.d.ts

@@ -0,0 +1,95 @@
+import type { GitResult } from "./git.js";
+import type { WorktreeService } from "./worktree-service.js";
+/**
+ * One task, whether or not it is still there. Commands ask the service for
+ * one of these and read its status rather than assembling the same handful of
+ * existence checks themselves.
+ */
+export declare class Worktree {
+    private readonly service;
+    private readonly snapshot;
+    constructor(service: WorktreeService, snapshot: WorktreeSnapshot);
+    get task(): string;
+    get branch(): string;
+    /** Where this task's work lands: its recorded base branch, else trunk. */
+    get base(): string;
+    get path(): string;
+    get state(): TaskState | null;
+    get lease(): LeaseState | null;
+    get leaseHeld(): boolean;
+    get leaseStatus(): "held" | "stale" | "none";
+    get leaseOurs(): boolean;
+    get leaseHeldByOther(): boolean;
+    get mergeAttempts(): number;
+    get exists(): boolean;
+    get hasBranch(): boolean;
+    get removedAt(): string | null;
+    get status(): WorktreeStatus;
+    get gone(): boolean;
+    /**
+     * Merges changes into the record and writes it. Works on a name that has no
+     * record yet, which is how `add` writes the first one and how `claim`
+     * rebuilds one from a worktree found on disk.
+     */
+    save(changes?: Partial<TaskState>): Promise<Worktree>;
+    take(changes?: Partial<TaskState>): Promise<Worktree>;
+    /** Re-reads from disk. `merge` needs this: the record is the truth. */
+    reload(): Promise<Worktree>;
+    /** Removes the directory, the branch, and the record; remembers the name. */
+    discard(): Promise<GitResult>;
+    commitsAhead(): Promise<number | null>;
+    diffStat(): Promise<{
+        added: number;
+        removed: number;
+    } | null>;
+    /** Committed and uncommitted paths this task touches; null without a branch. */
+    changedFiles(): Promise<string[] | null>;
+    uncommitted(): Promise<string[]>;
+    interruptedOps(): Promise<string[]>;
+}
+/** The status a task's own record carries. */
+export type RecordStatus = "working" | "merging" | "escalated";
+/** What a task's record stores about who is driving it. */
+export interface LeaseState {
+    pid: number;
+    hostname: string;
+    heartbeatAt: string;
+}
+export interface Escalation {
+    reason: string;
+    at: string;
+    /**
+     * For a task handed over to be approved rather than to answer questions,
+     * the question in its plan that asks for the approval, `4`.
+     */
+    review?: string;
+}
+export interface TaskState {
+    task: string;
+    branch: string;
+    worktree: string;
+    /** The branch this task lands on. Absent in old records: trunk. */
+    base?: string;
+    status: RecordStatus;
+    lease: LeaseState | null;
+    mergeAttempts: number;
+    createdAt: string;
+    updatedAt: string;
+    escalations?: Escalation[];
+}
+/**
+ * Everything a name can turn out to be. The record's own status when the
+ * task is intact, and otherwise the way in which it is not.
+ */
+export type WorktreeStatus = RecordStatus | "absent" | "removed" | "orphaned" | "stray" | "unrecorded" | "unknown";
+/** What the service found on disk. */
+export interface WorktreeSnapshot {
+    task: string;
+    branch: string;
+    path: string;
+    state: TaskState | null;
+    exists: boolean;
+    hasBranch: boolean;
+    removedAt: string | null;
+    corrupt: boolean;
+}

package/AGENTS.md

@@ -1,7 +0,0 @@
-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/add.test.ts

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

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

@@ -1,11 +0,0 @@
-/** 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`;
-}