@webappwiz/arbor 0.0.30 → 0.0.32

package/journal.d.ts

@@ -0,0 +1,29 @@
+import { type Fs } from "webappwiz/system";
+/** One thing that was done to a task, and how it went. */
+export interface Entry {
+    at: string;
+    action: string;
+    /** The task it was about, or null when the command names none. */
+    task: string | null;
+    /** The refusal reason, or null when the command succeeded. */
+    reason: string | null;
+}
+/**
+ * What has been done in this repo, oldest first. Entries outlive their tasks:
+ * `merge` and `remove` take the record with them, so this is the only thing that
+ * remembers a task existed at all.
+ */
+/** What a `Journal` is stored through; the real filesystem by default. */
+export interface JournalOptions {
+    fs?: Fs;
+}
+export declare class Journal {
+    private readonly path;
+    private readonly capacity;
+    private readonly fs;
+    constructor(path: string, capacity: number, opts?: JournalOptions);
+    record<T>(action: string, task: string | null, run: () => Promise<T>): Promise<T>;
+    tail(count: number): Promise<Entry[]>;
+    private append;
+    private entries;
+}

package/list.d.ts

@@ -0,0 +1,18 @@
+import { type Logger } from "webappwiz/log";
+import type { Fs } from "webappwiz/system";
+import type { WorktreeService } from "./worktree-service.js";
+export interface ListOptions {
+    /** Print the rows as JSON instead of a table. */
+    json?: boolean;
+    /**
+     * Add each task's changed and planned files, which is what an agent checks
+     * its own plan against before starting. Off by default: it costs git calls
+     * and a file read per task.
+     */
+    files?: boolean;
+}
+export declare function list({ service, log, fs }: {
+    service: WorktreeService;
+    log: Logger;
+    fs: Fs;
+}, { json, files }?: ListOptions): Promise<void>;

package/load-config.d.ts

@@ -0,0 +1,15 @@
+import { type Fs } from "webappwiz/system";
+import type { Config } from "./config.js";
+import { Git } from "./git.js";
+export interface LoadConfigOptions {
+    /** What `arbor.config.ts` is looked for through; the real one by default. */
+    fs?: Fs;
+    /** What the trunk is detected through; the repo's own git by default. */
+    git?: Git;
+}
+/**
+ * The settings arbor runs a repo with: what `arbor.config.ts` names, then the
+ * branch `origin/HEAD` points at for the trunk, then arbor's own defaults.
+ * Throws when the config file is there but cannot be imported.
+ */
+export declare function loadConfig(root: string, opts?: LoadConfigOptions): Promise<Config>;

package/log.d.ts

@@ -0,0 +1,14 @@
+import { type Logger } from "webappwiz/log";
+import type { Journal } from "./journal.js";
+/** Enough to cover a session's worth of work without scrolling. */
+export declare const DEFAULT_COUNT = 20;
+export interface LogOptions {
+    /** How many of the most recent entries to show. */
+    count?: number;
+    /** Print the entries as JSON instead of a table. */
+    json?: boolean;
+}
+export declare function log({ journal, log }: {
+    journal: Journal;
+    log: Logger;
+}, { count, json }?: LogOptions): Promise<void>;

package/merge.d.ts

@@ -0,0 +1,24 @@
+import { type Logger } from "webappwiz/log";
+import type { Fs, Lock } from "webappwiz/system";
+import type { Config } from "./config.js";
+import type { Git } from "./git.js";
+import type { Shell } from "./shell.js";
+import type { Todos } from "./todos.js";
+import type { WorktreeService } from "./worktree-service.js";
+/**
+ * Lands the current worktree's branch on its base branch, trunk unless the
+ * task was created with `--base`. Never a merge commit: it rebases onto the
+ * base, runs the gate there, and fast-forwards the base with
+ * `git merge --ff-only`, in whichever worktree has the base checked out.
+ * History stays linear.
+ */
+export declare function merge({ service, git, lock, shell, config, log, todos, fs, }: {
+    service: WorktreeService;
+    git: Git;
+    lock: Lock;
+    shell: Shell;
+    config: Config;
+    log: Logger;
+    todos: Todos;
+    fs: Fs;
+}, cwd: string): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@webappwiz/arbor",
-	"version": "0.0.30",
+	"version": "0.0.32",
 	"description": "Runs several AI coding agents on one repository at once, each in its own git worktree",
 	"license": "MIT",
 	"author": "Jared Johnson",
@@ -10,14 +10,6 @@
 		"directory": "packages/arbor"
 	},
 	"type": "module",
-	"module": "index.ts",
-	"bin": {
-		"arbor": "./index.ts"
-	},
-	"exports": {
-		".": "./index.ts",
-		"./config": "./config.ts"
-	},
 	"imports": {
 		"#dev/*": "./dev/*"
 	},
@@ -28,31 +20,22 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"webappwiz": "0.0.29",
+		"webappwiz": "^0.0.32",
 		"zod": "^4.4.3"
 	},
-	"devDependencies": {
-		"@base-ui/react": "^1.8.0",
-		"@dnd-kit/core": "^6.3.1",
-		"@dnd-kit/modifiers": "^9.0.0",
-		"@dnd-kit/sortable": "^10.0.0",
-		"@dnd-kit/utilities": "^3.2.2",
-		"@tailwindcss/oxide": "^4.3.3",
-		"@testing-library/react": "^16.3.1",
-		"@types/react": "^19.2.18",
-		"@types/react-dom": "^19.2.4",
-		"@webappwiz/react": "0.0.29",
-		"class-variance-authority": "^0.7.1",
-		"clsx": "^2.1.1",
-		"lucide-react": "^1.49.0",
-		"markdown-to-jsx": "^9.10.3",
-		"react": "^19.2.8",
-		"react-dom": "^19.2.8",
-		"tailwind-merge": "^3.7.0",
-		"tailwindcss": "^4.3.3",
-		"tw-animate-css": "^1.4.0"
+	"main": "./index.js",
+	"types": "./index.d.ts",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"default": "./index.js"
+		},
+		"./config": {
+			"types": "./config.d.ts",
+			"default": "./config.js"
+		}
 	},
-	"scripts": {
-		"build": "bun run build.ts"
+	"bin": {
+		"arbor": "./index.js"
 	}
 }

package/path.d.ts

@@ -0,0 +1,13 @@
+import type { Logger } from "webappwiz/log";
+import type { WorktreeService } from "./worktree-service.js";
+/**
+ * Where a task lives, or (with no task) the main tree. Nothing but the path
+ * on stdout, so it composes: `cd "$(arbor path)"`, `zed -a "$(arbor path x)"`.
+ * Moving between trees is `cd` and nothing else, and the main tree is the one
+ * path a process standing in a worktree cannot otherwise name: git's
+ * `--show-toplevel` hands back the worktree it is already in.
+ */
+export declare function path({ service, log }: {
+    service: WorktreeService;
+    log: Logger;
+}, task?: string): Promise<void>;

package/plan.d.ts

@@ -0,0 +1,83 @@
+/** The plan each task keeps at its worktree root, excluded from git. */
+export declare const PLAN_FILE = "ARBOR.md";
+/**
+ * The paths an `ARBOR.md` says its task will touch: each top-level bullet
+ * under `## Files`, taken as written. Prose around the list is left out, and a
+ * plan with no such section plans nothing.
+ */
+export declare function plannedFiles(text: string): string[];
+/**
+ * One `- [ ] 9.` item under `## Blocked`: something only a person can do.
+ * The item's line is its subject; lines indented under it are its body, and
+ * `- (a) ...` or `- [a] ...` lines among them are the answers it offers.
+ */
+export interface Question {
+    /** As the plan numbers it, `9`: the name a reply goes by. */
+    number: string;
+    /** Checked off, which the agent does once it has acted on the reply. */
+    done: boolean;
+    /** The item's own line, without its checkbox, number or reply. */
+    text: string;
+    /**
+     * The markdown indented under it, dedented, choices left out: detail,
+     * code blocks, `![shot](/abs/path.png)` images. Empty when there is none.
+     */
+    body: string;
+    /** Whatever follows ` → `, or null when nobody has answered yet. */
+    reply: string | null;
+    /**
+     * What a person added once the reply was read, oldest first: each an
+     * indented `→ ` line under the question.
+     */
+    followUps: string[];
+    /**
+     * The answers it offers, in order. Empty for a question answered in words
+     * alone. A reply can always add words to its picks, or answer in words
+     * instead.
+     */
+    choices: Choice[];
+    /**
+     * `one` for `- (a)` choices, at most one of which a reply picks; `any` for
+     * `- [a]` choices, where it picks all that apply. Null without choices.
+     */
+    pick: "one" | "any" | null;
+}
+/** One answer a question offers: `- (b) Migrate on next login`. */
+export interface Choice {
+    /** The letter it goes by: `b`. */
+    key: string;
+    text: string;
+}
+/**
+ * Every numbered item under `## Blocked`, open or checked off, each with the
+ * indented lines under it. The reply is read off the item's own line: an
+ * answer is one line, written by `arbor reply` or by hand after the arrow.
+ */
+export declare function questions(text: string): Question[];
+/**
+ * The plan with a new open question at the end of `## Blocked`, the section
+ * made if missing, numbered after the highest there. Returns the plan and
+ * the number it went by.
+ */
+export declare function withQuestion(text: string, subject: string, body?: string): {
+    plan: string;
+    number: string;
+};
+/**
+ * A question's number however a person typed it: `9`, `9.`, `Q9` and `q9:`
+ * all mean `9`. Null for anything that is not a number at all.
+ */
+export declare function questionNumber(raw: string): string | null;
+export interface PlanOptions {
+    /** The task name the title is expected to match. */
+    task: string;
+    /** Whether the task has escalated, which makes `## Blocked` required. */
+    escalated?: boolean;
+}
+/**
+ * Every way a task's `ARBOR.md` departs from the shape the agent skill
+ * prescribes, phrased for the agent that wrote it. Advisory only: a resumable
+ * plan is the point, and a malformed one still beats none, so nothing here
+ * blocks a merge.
+ */
+export declare function checkPlan(text: string, { task, escalated }: PlanOptions): string[];

package/remove.d.ts

@@ -0,0 +1,19 @@
+import { type Logger } from "webappwiz/log";
+import type { Todos } from "./todos.js";
+import type { WorktreeService } from "./worktree-service.js";
+export interface RemoveOptions {
+    /** Discard the tree even when another agent holds its lease. */
+    force?: boolean;
+}
+/**
+ * Discards a whole task: `git worktree remove` plus the branch and the
+ * record.
+ *
+ * Throwing a task away and redoing it against current trunk is usually cheaper
+ * than a hard rebase, so this is meant to be used freely.
+ */
+export declare function remove({ service, log, todos, }: {
+    service: WorktreeService;
+    log: Logger;
+    todos: Todos;
+}, task: string, { force }?: RemoveOptions): Promise<void>;

package/repository.d.ts

@@ -0,0 +1,25 @@
+import type { Deps, Middleware } from "webappwiz/cmd";
+import { type Fs, type Lock } from "webappwiz/system";
+import type { Config } from "./config.js";
+import { Git } from "./git.js";
+import { Journal } from "./journal.js";
+import { Shell } from "./shell.js";
+import { Todos } from "./todos.js";
+import { WorktreeService } from "./worktree-service.js";
+/** What a command gets to work with, once there is a repository to work in. */
+export interface Repository {
+    config: Config;
+    git: Git;
+    service: WorktreeService;
+    lock: Lock;
+    shell: Shell;
+    journal: Journal;
+    todos: Todos;
+}
+/**
+ * Runs the action against the repository `cwd` sits in, and refuses to run it
+ * at all when that is not a repository.
+ */
+export declare function repository<C extends Deps & {
+    fs: Fs;
+}>(at?: string): Middleware<C, C & Repository>;

package/retry.d.ts

@@ -0,0 +1,17 @@
+import { type Logger } from "webappwiz/log";
+import type { Config } from "./config.js";
+import type { WorktreeService } from "./worktree-service.js";
+/**
+ * The way back from `budget_exhausted`. A task that has spent its merge
+ * attempts gets another `mergeRetryCount` of them, instead of `remove` and redo.
+ *
+ * Only from `escalated`, and deliberately: the budget's whole job is to make an
+ * agent stop and hand the task over. An agent that could grant itself more
+ * would be back to grinding against a moving trunk forever, so the price of a
+ * fresh budget is that a human has looked at the tree first.
+ */
+export declare function retry({ service, config, log, }: {
+    service: WorktreeService;
+    config: Config;
+    log: Logger;
+}, task: string): Promise<void>;

package/shell.d.ts

@@ -0,0 +1,17 @@
+import { type Ps, type SpawnCaptureResult, type SpawnOptions, type SpawnResult } from "webappwiz/system";
+/** What a `Shell` spawns through; the real process by default. */
+export interface ShellOptions {
+    ps?: Ps;
+}
+/**
+ * Runs the commands a repo configures (the lifecycle hooks) as shell strings
+ * rather than argv, since that is how a repo writes them.
+ */
+export declare class Shell {
+    private readonly ps;
+    constructor(opts?: ShellOptions);
+    /** Captures output, for commands whose failure has to be reported back. */
+    run(command: string, cwd: string, opts?: SpawnOptions): Promise<SpawnCaptureResult>;
+    /** Inherits stdio, for commands the agent should watch as they run. */
+    stream(command: string, cwd: string, opts?: SpawnOptions): Promise<SpawnResult>;
+}

package/show.d.ts

@@ -0,0 +1,53 @@
+import { type Logger } from "webappwiz/log";
+import { type Fs } from "webappwiz/system";
+import type { Worktree } from "./worktree.js";
+import type { WorktreeService } from "./worktree-service.js";
+export interface Details {
+    task: string;
+    status: string;
+    branch: string;
+    base: string;
+    worktree: string;
+    lease: "held" | "stale" | "none";
+    ahead: number | null;
+    added: number | null;
+    removed: number | null;
+    age: string | null;
+    escalation: string | null;
+    /**
+     * While escalated to be approved, the question that asks for it, `4`;
+     * null otherwise.
+     */
+    review: string | null;
+    plan: string | null;
+    /** How the `ARBOR.md` departs from the shape the skill prescribes. */
+    planProblems: string[];
+}
+export interface ShowOptions {
+    /** Print the details as JSON instead of prose. */
+    json?: boolean;
+}
+/**
+ * One task in full: what `list` shows for it, plus the `ARBOR.md` its agent
+ * left at the worktree root. Reading a tree this way takes no lease, so it
+ * cannot knock the agent driving it off its own work.
+ */
+export declare function show({ service, fs, log }: {
+    service: WorktreeService;
+    fs: Fs;
+    log: Logger;
+}, task: string, opts?: ShowOptions): Promise<void>;
+/** Configures how {@link TaskDetails} gathers a task's info. */
+export interface TaskDetailsOptions {
+    /** What the worktree is read through; the real filesystem by default. */
+    fs?: Fs;
+}
+/**
+ * Everything there is to say about one task. Split out so `dev` can render the
+ * same fields this prints, rather than assembling its own and drifting.
+ */
+export declare class TaskDetails {
+    private readonly fs;
+    constructor(opts?: TaskDetailsOptions);
+    get(worktree: Worktree): Promise<Details>;
+}

package/snapshot.d.ts

@@ -0,0 +1,36 @@
+import type { Fs } from "webappwiz/system";
+import { type Details } from "./show.js";
+import type { TodoState } from "./todo.js";
+import type { Todos } from "./todos.js";
+import type { WorktreeService } from "./worktree-service.js";
+/**
+ * Everything one page shows: `todo list`, and `list` and `show` for each
+ * task.
+ */
+export interface Snapshot {
+    /** The repository's directory name, so a page among many says whose it is. */
+    repo: string;
+    /** Where the repository sits, with the home directory as `~`. */
+    path: string;
+    /** Past this age a todo is offered for removal rather than recommended. */
+    todoStalenessMs: number;
+    todos: TodoState[];
+    tasks: Details[];
+}
+/**
+ * Reads the whole repo the way the CLI's read commands do. Takes no lease, so
+ * the page can sit open on a live tree without disturbing the agent in it.
+ */
+export declare function snapshot({ service, todos, fs, home, }: {
+    service: WorktreeService;
+    todos: Todos;
+    fs: Fs;
+    /** The home directory to show as `~`, when there is one. */
+    home?: string;
+}): Promise<Snapshot>;
+/**
+ * What the page is actually showing, minus the fields that move on their own.
+ * `age` ticks every minute, and hashing it would push to every open page for
+ * nothing.
+ */
+export declare function fingerprint({ todos, tasks }: Snapshot): string;

package/table.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Columns padded to their widest cell. Padding goes by visible width, not
+ * string length: cells carry color codes.
+ */
+export declare function table(header: string[], rows: string[][]): string;

package/todo.d.ts

@@ -0,0 +1,202 @@
+import { type Logger } from "webappwiz/log";
+import type { Fs, Ps } from "webappwiz/system";
+import { type Attachment, type Attachments } from "./attachments.js";
+import type { Todos } from "./todos.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[];
+}
+/**
+ * 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>;
+}
+/** 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[];
+}
+/**
+ * A subject and its detail, trimmed. A subject running past one line keeps
+ * only the first, the rest leading the detail, so the list stays one line a
+ * todo however it was written.
+ */
+export declare function wording(subject: string, text: string): {
+    subject: string;
+    text: string;
+};
+/** 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 any of these tags; every todo when empty. */
+    tags?: 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, tags }?: 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>;