@webappwiz/arbor 0.0.30 → 0.0.31

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 "./todo.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.31",
 	"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.31",
 		"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 "./todo.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 "./todo.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,35 @@
+import type { Fs } from "webappwiz/system";
+import { type Details } from "./show.js";
+import type { TodoState, Todos } from "./todo.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;