@webappwiz/arbor 0.0.30 → 0.0.31

package/todo.d.ts

@@ -0,0 +1,264 @@
+import { type IdProvider } from "webappwiz/id";
+import { type Logger } from "webappwiz/log";
+import { type Fs, type Lock, type Ps } from "webappwiz/system";
+import { type Attachment, Attachments } from "./attachments.js";
+/** What a todo is on disk: one file apiece, so two agents never rewrite one. */
+export interface TodoState {
+    id: number;
+    /** What is left to do, in a line. */
+    subject: string;
+    /** Whatever more there is to say about it, or empty when the line is enough. */
+    text: string;
+    /** Where it stands in the list, 1 at the top: the one to pick up first. */
+    position: number;
+    /** The task it came up in, or null when a person added it from the main tree. */
+    from: string | null;
+    createdAt: string;
+    /** The task working on it now, or null while it waits to be picked up. */
+    takenBy: string | null;
+    /** Absolute paths of the files attached, in `todos/<id>/`. */
+    files: string[];
+    /** What it belongs to, sorted: the areas or goals it adds up to with others. */
+    tags: string[];
+}
+/** A tag in use, with how many todos have it. */
+export interface TagState {
+    tag: string;
+    todos: number;
+}
+/** `tags` deduped and sorted, refusing any not written the one way. */
+export declare function tagList(tags: string[]): string[];
+/** A todo's words, place or files changed: new ones added, some of the old kept. */
+export interface TodoChange {
+    /** A new line; the old one stays when this is absent. */
+    subject?: string;
+    /** New detail, empty for none; the old stays when this is absent. */
+    text?: string;
+    /** Where to move it in the list; it stays put when this is absent. */
+    position?: number;
+    /** Files to add. */
+    files?: Attachment[];
+    /** The paths of the files it has now to keep; absent keeps them all. */
+    keep?: string[];
+    /** Its tags from now on; the old stay when this is absent. */
+    tags?: string[];
+}
+/** What a new todo has besides its subject, all of it optional. */
+export interface TodoNew {
+    /** Whatever more there is to say about it. */
+    text?: string;
+    files?: Attachment[];
+    /** Where it goes in the list, pushing those from there down; the bottom by default. */
+    position?: number;
+    tags?: string[];
+}
+/**
+ * Work deferred for later: what an agent notes when something outside its
+ * task comes up, so it can move on instead of growing the task. Kept under the
+ * shared `.git`, so every worktree sees a new one at once, with nothing to
+ * commit and nothing to merge.
+ */
+export declare class Todo {
+    private readonly todos;
+    readonly state: TodoState;
+    constructor(todos: Todos, state: TodoState);
+    get id(): number;
+    get subject(): string;
+    get text(): string;
+    get position(): number;
+    get from(): string | null;
+    get takenBy(): string | null;
+    get createdAt(): Date;
+    /** How long it has waited, in milliseconds. */
+    get waited(): number;
+    /** Marks it as the work of `task`, refusing one another task already has. */
+    take(task: string): Promise<Todo>;
+    /** Puts it back on the list, as when the task that took it is removed. */
+    release(): Promise<Todo>;
+    get files(): string[];
+    get tags(): string[];
+    get attachments(): Attachments;
+    /**
+     * Says what is left to do in other words, with other files, or higher or
+     * lower in the list, keeping its id and history.
+     */
+    update({ subject, text, position, files, keep, tags, }: TodoChange): Promise<Todo>;
+    remove(): Promise<void>;
+}
+/** What `Todos` is stored through; the real filesystem by default. */
+export interface TodosOptions {
+    fs?: Fs;
+    /** Names stored files apart; a test counts. */
+    ids?: IdProvider;
+}
+/** 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 a finished task should be followed by, and what should just go. */
+export interface Recommendation {
+    /** The todo to pick up next, or null when there is nothing fresh left. */
+    next: Todo | null;
+    /** Todos left waiting so long they probably no longer apply. */
+    stale: Todo[];
+}
+/**
+ * Which todo to take up after `task`: one that came up in it first, since
+ * whoever just finished it knows that context best, then one sharing a tag
+ * in `settled`, those of the todos it finished, the same area of work, then the open one highest
+ * on the list, which is how whoever keeps the list says what matters most.
+ * Todos past `staleness` are never recommended, only offered for removal.
+ */
+export declare function recommend(todos: Todos, task: string | null, staleness: number, settled?: string[]): Promise<Recommendation>;
+/** The lines `merge` ends with, or none when there is nothing to say. */
+export declare function recommendation({ next, stale }: Recommendation): string[];
+export interface TodoListOptions {
+    /** Print the todos as JSON instead of a table. */
+    json?: boolean;
+    /** Only those no task has taken: the ones free to pick up. */
+    open?: boolean;
+    /** Only those with this tag. */
+    tag?: string;
+}
+export interface TodoFileOptions {
+    /** Files to attach, relative to the current directory or absolute. */
+    files?: string[];
+}
+export interface TodoAddOptions extends TodoFileOptions {
+    /** Whatever more there is to say than the subject. */
+    text?: string;
+    /** Where it goes in the list, 1 at the top; the bottom by default. */
+    position?: number;
+    tags?: string[];
+}
+export declare function todoAdd(deps: {
+    todos: Todos;
+    log: Logger;
+    fs: Fs;
+    ps: Ps;
+}, subject: string, from: string | null, { text, files, position, tags }?: TodoAddOptions): Promise<Todo>;
+export declare function todoList({ todos, log }: {
+    todos: Todos;
+    log: Logger;
+}, { json, open, tag }?: TodoListOptions): Promise<void>;
+export interface TodoShowOptions {
+    /** Print the todo as JSON instead of prose. */
+    json?: boolean;
+}
+/** One todo in full: what `todo list` shows of it, its files, and its detail. */
+export declare function todoShow({ todos, log }: {
+    todos: Todos;
+    log: Logger;
+}, id: number, { json }?: TodoShowOptions): Promise<void>;
+export interface TodoUpdateOptions extends TodoFileOptions {
+    /** A new line; the old one stays when this is absent or empty. */
+    subject?: string;
+    /** New detail; the old stays when this is absent or empty. */
+    text?: string;
+    /** Where to move it in the list, 1 at the top; it stays put when absent. */
+    position?: number;
+    /** Attached files to drop, by path or by the name they were stored under. */
+    removeFiles?: string[];
+    /** Tags to add. */
+    tags?: string[];
+    /** Tags to drop. */
+    removeTags?: string[];
+}
+export declare function todoUpdate(deps: {
+    todos: Todos;
+    log: Logger;
+    fs: Fs;
+    ps: Ps;
+}, id: number, { subject, text, position, files, removeFiles, tags, removeTags, }?: TodoUpdateOptions): Promise<Todo>;
+/**
+ * Takes up todos for `task` after it started, as when one turns out to be
+ * part of the work. Every id is checked before any is taken, so one that is
+ * gone or another task's refuses them all.
+ */
+export declare function todoTake({ todos, log }: {
+    todos: Todos;
+    log: Logger;
+}, ids: number[], task: string | null): Promise<Todo[]>;
+/**
+ * Puts todos back on the list, as when a task is landing without finishing
+ * them: say what is left with `arbor todo update` first. From a worktree it
+ * gives back only its own task's todos.
+ */
+export declare function todoRelease({ todos, log }: {
+    todos: Todos;
+    log: Logger;
+}, ids: number[], task: string | null): Promise<Todo[]>;
+export declare function todoRemove({ todos, log }: {
+    todos: Todos;
+    log: Logger;
+}, id: number): Promise<void>;
+export interface TodoTagsOptions {
+    /** Print the tags as JSON instead of a table. */
+    json?: boolean;
+}
+/** Every tag in use, with how many todos have it: the names to reuse first. */
+export declare function todoTags({ todos, log }: {
+    todos: Todos;
+    log: Logger;
+}, { json }?: TodoTagsOptions): Promise<void>;

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): 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";
+/** 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;
+}
+/**
+ * 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[]>;
+}

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" },
-		});
-	});
-});