@webappwiz/arbor 0.0.28 → 0.0.30

package/journal.d.ts

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

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

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

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

@@ -1,24 +0,0 @@
-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/path.d.ts

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

@@ -1,83 +0,0 @@
-/** 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

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

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

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

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

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

@@ -1,31 +0,0 @@
-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;
-    /** 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, }: {
-    service: WorktreeService;
-    todos: Todos;
-    fs: Fs;
-}): 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

@@ -1,5 +0,0 @@
-/**
- * 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

@@ -1,230 +0,0 @@
-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[];
-}
-/** 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[];
-}
-/** 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;
-}
-/**
- * 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 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, }: 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 }?: 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>;
-    /** 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 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): 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;
-}
-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;
-}
-export declare function todoAdd(deps: {
-    todos: Todos;
-    log: Logger;
-    fs: Fs;
-    ps: Ps;
-}, subject: string, from: string | null, { text, files, position }?: TodoAddOptions): Promise<Todo>;
-export declare function todoList({ todos, log }: {
-    todos: Todos;
-    log: Logger;
-}, { json }?: 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[];
-}
-export declare function todoUpdate(deps: {
-    todos: Todos;
-    log: Logger;
-    fs: Fs;
-    ps: Ps;
-}, id: number, { subject, text, position, files, removeFiles, }?: 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>;

package/wait.d.ts

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