@webappwiz/arbor 0.0.1

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 `rm` 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/load-config.d.ts

@@ -0,0 +1,7 @@
+import { type Fs } from "webappwiz/system";
+import type { Config } from "./config.js";
+export interface LoadConfigOptions {
+    /** What `arbor.config.ts` is looked for through; the real one by default. */
+    fs?: Fs;
+}
+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/ls.d.ts

@@ -0,0 +1,10 @@
+import { type Logger } from "webappwiz/log";
+import type { WorktreeService } from "./worktree-service.js";
+export interface LsOptions {
+    /** Print the rows as JSON instead of a table. */
+    json?: boolean;
+}
+export declare function ls({ service, log }: {
+    service: WorktreeService;
+    log: Logger;
+}, { json }?: LsOptions): Promise<void>;

package/merge.d.ts

@@ -0,0 +1,20 @@
+import { type Logger } from "webappwiz/log";
+import type { Lock } from "webappwiz/system";
+import type { Config } from "./config.js";
+import type { Git } from "./git.js";
+import type { Shell } from "./shell.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`. History stays linear.
+ */
+export declare function merge({ service, git, lock, shell, config, log, }: {
+    service: WorktreeService;
+    git: Git;
+    lock: Lock;
+    shell: Shell;
+    config: Config;
+    log: Logger;
+}, cwd: string): Promise<void>;

package/package.json

@@ -0,0 +1,37 @@
+{
+	"name": "@webappwiz/arbor",
+	"version": "0.0.1",
+	"description": "Runs several AI coding agents on one repository at once, each in its own git worktree",
+	"license": "MIT",
+	"author": "Jared Johnson",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/jaredjj3/webappwiz.git",
+		"directory": "packages/arbor"
+	},
+	"type": "module",
+	"engines": {
+		"bun": ">=1.3"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"webappwiz": "^0.0.1"
+	},
+	"main": "./index.js",
+	"types": "./index.d.ts",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"default": "./index.js"
+		},
+		"./config": {
+			"types": "./config.d.ts",
+			"default": "./config.js"
+		}
+	},
+	"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,13 @@
+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/repository.d.ts

@@ -0,0 +1,23 @@
+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 { 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;
+}
+/**
+ * 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 `rm` 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/rm.d.ts

@@ -0,0 +1,17 @@
+import { type Logger } from "webappwiz/log";
+import type { WorktreeService } from "./worktree-service.js";
+export interface RmOptions {
+    /** 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 rm({ service, log }: {
+    service: WorktreeService;
+    log: Logger;
+}, task: string, { force }?: RmOptions): Promise<void>;

package/shell.d.ts

@@ -0,0 +1,21 @@
+import { type Ps, type SpawnCaptureResult, type SpawnOptions, type SpawnResult } from "webappwiz/system";
+/** Spawn options for a shell command. `cwd` is the worktree it runs against. */
+export type ShellRunOptions = SpawnOptions & {
+    cwd: string;
+};
+/** 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, opts: ShellRunOptions): Promise<SpawnCaptureResult>;
+    /** Inherits stdio, for commands the agent should watch as they run. */
+    stream(command: string, opts: ShellRunOptions): Promise<SpawnResult>;
+}

package/show.d.ts

@@ -0,0 +1,43 @@
+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;
+    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 `ls` 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, { json }?: ShowOptions): Promise<void>;
+/**
+ * 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 interface TaskDetailsOptions {
+    /** What the worktree is read through; the real filesystem by default. */
+    fs?: Fs;
+}
+export declare function taskDetails(worktree: Worktree, opts?: TaskDetailsOptions): Promise<Details>;

package/snapshot.d.ts

@@ -0,0 +1,24 @@
+import { type Fs } from "webappwiz/system";
+import type { Entry, Journal } from "./journal.js";
+import { type Details } from "./show.js";
+import type { WorktreeService } from "./worktree-service.js";
+/** Everything one page shows: `ls` and `show` for each task, plus `log`. */
+export interface Snapshot {
+    tasks: Details[];
+    entries: Entry[];
+}
+/**
+ * Reads the whole repo the way `ls`, `show` and `log` do. Takes no lease, so
+ * serving a page cannot knock an agent off the tree it is driving.
+ */
+export interface SnapshotOptions {
+    /** What the worktrees are read through; the real filesystem by default. */
+    fs?: Fs;
+}
+export declare function snapshot(service: WorktreeService, journal: Journal, opts?: SnapshotOptions): 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({ tasks, entries }: 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/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 `rm` 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,88 @@
+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;
+}
+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>;
+    uncommitted(): Promise<string[]>;
+    interruptedOps(): Promise<string[]>;
+}