@webappwiz/arbor 0.0.30 → 0.0.31

package/add.d.ts

@@ -0,0 +1,23 @@
+import { type Logger } from "webappwiz/log";
+import type { Fs } from "webappwiz/system";
+import type { Config } from "./config.js";
+import type { Shell } from "./shell.js";
+import type { Todos } from "./todo.js";
+import type { WorktreeService } from "./worktree-service.js";
+export interface AddOptions {
+    /** Branch the task starts from and merges onto. Defaults to the trunk. */
+    base?: string;
+    /**
+     * The todos this task takes up: their words seed the plan's Goal, and
+     * nobody else can take them while the task lives.
+     */
+    todos?: number[];
+}
+export declare function add({ service, shell, config, log, fs, todos, }: {
+    service: WorktreeService;
+    shell: Shell;
+    config: Config;
+    log: Logger;
+    fs: Fs;
+    todos: Todos;
+}, task: string, { base, todos: ids }?: AddOptions): Promise<void>;

package/age.d.ts

@@ -0,0 +1,2 @@
+/** How long ago an ISO timestamp was, at the coarsest unit that still reads. */
+export declare function age(since: string): string;

package/arbor.d.ts

@@ -0,0 +1,11 @@
+import { type Deps } from "webappwiz/cmd";
+import type { Fs } from "webappwiz/system";
+import type { Assets } from "./dev/assets.js";
+import { type Repository } from "./repository.js";
+/** Everything `arbor` is run with, before the repository middleware adds to it. */
+export interface ArborDeps extends Deps {
+    fs: Fs;
+    /** The built page `dev` serves as its preview. */
+    assets: Assets;
+}
+export declare const arbor: import("webappwiz/cmd").Cli<ArborDeps, ArborDeps & Repository>;

package/attachments.d.ts

@@ -0,0 +1,36 @@
+import { type IdProvider } from "webappwiz/id";
+import type { Fs, Ps } from "webappwiz/system";
+/** A file handed over, as bytes so a pasted image needs no temp file. */
+export interface Attachment {
+    /** What it was called, kept in the stored name so the files stay apart. */
+    name: string;
+    bytes: Uint8Array;
+}
+/**
+ * The folder of files that belong to a todo: todo 7's beside its record, in
+ * `todos/7/`.
+ * Under `.git/arbor`, so nothing here is ever committed and every tree can
+ * open what it holds.
+ */
+export declare class Attachments {
+    readonly dir: string;
+    private readonly fs;
+    private readonly ids;
+    constructor(dir: string, fs: Fs, ids?: IdProvider);
+    /** Copies each file in, returning the absolute path each was stored at. */
+    store(files: Attachment[]): Promise<string[]>;
+    /** Whether `path` is one of this folder's files, and not a way out of it. */
+    owns(path: string): boolean;
+    /** Deletes the files given that are this folder's; others are left alone. */
+    remove(paths: string[]): Promise<void>;
+    /** Deletes the folder and everything in it. */
+    clear(): Promise<void>;
+}
+/**
+ * Reads files named on the command line, relative to the current directory or
+ * absolute, refusing the whole command over one that cannot be read.
+ */
+export declare function readFiles({ fs, ps }: {
+    fs: Fs;
+    ps: Ps;
+}, paths: string[]): Promise<Attachment[]>;

package/claim.d.ts

@@ -0,0 +1,11 @@
+import { type Logger } from "webappwiz/log";
+import type { WorktreeService } from "./worktree-service.js";
+/**
+ * The resume entry point: a fresh agent thread picking up existing work. An
+ * escalated task goes back to `working`, since someone is on it again; its
+ * merge budget stays as it was, which only `retry` refills.
+ */
+export declare function claim({ service, log }: {
+    service: WorktreeService;
+    log: Logger;
+}, task: string): Promise<void>;

package/config.d.ts

@@ -0,0 +1,55 @@
+export interface Config {
+    /**
+     * The integration branch name. `merge` rebases a task onto this branch and
+     * then fast-forwards it to the result; new worktrees start from it.
+     */
+    trunk: string;
+    /** Directory holding one worktree per task, a sibling of the repo. */
+    worktreeRoot: string;
+    /** Command run by `add` in the new worktree, via `sh -c`. */
+    postCheckout: string | null;
+    /**
+     * Command run by `merge` after the rebase, before `preMerge`, via `sh -c`.
+     * A rebase can bring in a dependency the worktree has never installed, and
+     * whatever `preMerge` runs needs it.
+     */
+    postRewrite: string | null;
+    /**
+     * Command run by `merge` after the rebase, via `sh -c`. The last gate before
+     * the branch lands: a nonzero exit rolls the branch back and leaves the base
+     * untouched. Tests are the obvious thing to put here, but arbor has no
+     * opinion; a repo with nothing to run leaves it null and merges on a green
+     * rebase alone.
+     */
+    preMerge: string | null;
+    /**
+     * Command run by `merge` in the main tree after the base fast-forwards, via
+     * `sh -c`. The branch has already landed and the worktree is gone: a nonzero
+     * exit reports the failure but rolls nothing back.
+     */
+    postMerge: string | null;
+    /** How long since its last heartbeat before a task's lease is up for grabs. */
+    leaseStalenessMs: number;
+    /** Failed `merge` attempts a task gets before it must escalate or be removed. */
+    mergeRetryCount: number;
+    /**
+     * How many removed task names to keep, so `remove` can say "already removed"
+     * rather than "never existed". A flat cap with no age policy: losing the
+     * oldest costs a nicer message and nothing else.
+     */
+    removedCapacity: number;
+    /** How many entries `arbor log` keeps before the oldest fall off. */
+    logCapacity: number;
+    /**
+     * How long a todo can wait before `merge` stops recommending it and offers
+     * it for removal instead: work deferred that long has usually been done
+     * some other way, or stopped mattering.
+     */
+    todoStalenessMs: number;
+}
+/**
+ * Identity, for the types. `export default defineConfig({ ... })` in
+ * `arbor.config.ts` gets the key names and their types checked, and completion
+ * while writing it; a bare object literal gets neither.
+ */
+export declare function defineConfig(config: Partial<Config>): Partial<Config>;

package/config.js

@@ -0,0 +1,7 @@
+// config.ts
+function defineConfig(config) {
+  return config;
+}
+export {
+  defineConfig
+};

package/dev/assets.d.ts

@@ -0,0 +1,11 @@
+/** The three files the browser asks for, as the server hands them over. */
+export interface Assets {
+    /** The page, which asks for the other two. */
+    shell: string;
+    /** The React app, bundled for the browser. */
+    script: string;
+    /** The stylesheet, with Tailwind already compiled. */
+    styles: string;
+}
+/** The page this package ships. Serve each field's contents as-is. */
+export declare const assets: Assets;

package/dev.d.ts

@@ -0,0 +1,48 @@
+import { type AsyncResource } from "webappwiz/disposable";
+import type { Logger } from "webappwiz/log";
+import { type Fs, type PortProvider, type Ps } from "webappwiz/system";
+import type { Assets } from "./dev/assets.js";
+import type { Journal } from "./journal.js";
+import type { Todos } from "./todo.js";
+import type { WorktreeService } from "./worktree-service.js";
+/** Preferred, not required: `dev` moves up from here when it is taken. */
+export declare const DEFAULT_PORT = 4269;
+/** How far above the port asked for `dev` will look before giving up. */
+export declare const PORT_SPAN = 20;
+/** What `dev` lets a caller choose. */
+export interface DevOptions {
+    /** Where to listen; the port `--port` asked for, and the span above it. */
+    ports?: PortProvider;
+    /**
+     * Host names besides this machine's own that the page may be reached by,
+     * like the hostname of a tunnel. Anything else is refused, which is what
+     * stops another site from reading the repo through a browser pointed at
+     * localhost. Who may use those names is the tunnel's business, not arbor's.
+     */
+    hosts?: string[];
+}
+/** A running server, and the one thing a caller ever wants to do with it. */
+export interface DevServer extends AsyncResource {
+    port: number;
+}
+/**
+ * Serves what `todo list`, `list` and `show` print as one page that refetches
+ * when the repo changes, where a person adds, edits, reorders and removes
+ * todos. Anything that moves a task (merge, remove, claim) stays in the CLI,
+ * so a page that should not have been reachable can at worst change a todo.
+ */
+export declare function dev({ service, fs, ps, journal, todos, log, assets, }: {
+    service: WorktreeService;
+    fs: Fs;
+    ps: Ps;
+    journal: Journal;
+    todos: Todos;
+    log: Logger;
+    assets: Assets;
+}, { ports, hosts }?: DevOptions): Promise<DevServer>;
+/**
+ * Where `dev` will listen, given the port asked for. A flag is outside input,
+ * so a port that cannot exist is a refusal with an exit code rather than the
+ * assertion `OpenPortProvider` would raise for a bug in here.
+ */
+export declare function devPorts(from: number): PortProvider;

package/escalate.d.ts

@@ -0,0 +1,28 @@
+import { type Logger } from "webappwiz/log";
+import type { Fs, Lock } from "webappwiz/system";
+import type { Git } from "./git.js";
+import type { WorktreeService } from "./worktree-service.js";
+export interface EscalateOptions {
+    /** Task to escalate. Defaults to the one `cwd` is a worktree for. */
+    task?: string;
+    /**
+     * Ask a person to approve merging, rather than to answer questions: adds
+     * the question that asks it to the plan, with the reason as its detail.
+     * Refused while another question is unchecked.
+     */
+    review?: boolean;
+}
+/** The question a review asks. */
+export declare const REVIEW_SUBJECT = "Ready to merge?";
+/**
+ * The way out that is not "resolve the conflict badly to finish the task".
+ * When both sides restructured the same logic there is no correct merge, only
+ * a decision, and that belongs to a human.
+ */
+export declare function escalate({ service, git, lock, log, fs, }: {
+    service: WorktreeService;
+    git: Git;
+    lock: Lock;
+    log: Logger;
+    fs: Fs;
+}, reason: string, cwd: string, { task, review }?: EscalateOptions): Promise<void>;

package/exit.d.ts

@@ -0,0 +1,42 @@
+import type { Deps, Middleware } from "webappwiz/cmd";
+/** Exit codes are the API: an agent branches on these, not on prose. */
+export declare const EXIT: {
+    readonly usage: 1;
+    readonly conflict: 2;
+    readonly tests_failed: 3;
+    readonly lease_lost: 4;
+    readonly budget_exhausted: 5;
+    readonly lease_held: 6;
+    readonly dirty: 7;
+    readonly not_found: 8;
+    readonly hook_failed: 9;
+    readonly exists: 10;
+    readonly orphaned: 11;
+    readonly merge_failed: 12;
+    readonly already_removed: 13;
+    readonly timeout: 14;
+    readonly blocked: 16;
+};
+export type Reason = keyof typeof EXIT;
+/**
+ * A refusal, carrying the reason to branch on, a message to show, and any
+ * data worth reporting with it. `exits` turns one into output and a status
+ * code.
+ */
+export declare class Exit extends Error {
+    readonly reason: Reason;
+    readonly data: Record<string, unknown>;
+    constructor(reason: Reason, message: string, data?: Record<string, unknown>);
+}
+/**
+ * How a command refuses. Every call site means "and go no further", which is
+ * what the `never` return buys: the code below a `fail` is unreachable, and
+ * TypeScript narrows accordingly.
+ */
+export declare function fail(reason: Reason, message: string, data?: Record<string, unknown>): never;
+/**
+ * Decides what a refusal looks like (a machine-readable reason on stdout, a
+ * human explanation on stderr) and is the only place that ends the process.
+ * An agent branches on the first and reads the second.
+ */
+export declare function exits<C extends Deps>(): Middleware<C>;

package/git.d.ts

@@ -0,0 +1,77 @@
+import { type Fs, type Ps } from "webappwiz/system";
+export interface GitResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Every git call arbor makes, scoped to one repository. Agents are not allowed
+ * to run these themselves, since going through arbor is what makes concurrent
+ * work safe, so this is the only place git is spoken.
+ */
+/** What a `Git` works through; the real ones by default. */
+export interface GitOptions {
+    ps?: Ps;
+    fs?: Fs;
+}
+export declare class Git {
+    /** The main worktree, where trunk lives. */
+    readonly root: string;
+    private readonly ps;
+    private readonly fs;
+    constructor(
+    /** The main worktree, where trunk lives. */
+    root: string, opts?: GitOptions);
+    run(cwd: string, ...args: string[]): Promise<GitResult>;
+    out(cwd: string, ...args: string[]): Promise<string>;
+    branchExists(branch: string): Promise<boolean>;
+    /**
+     * The branch `origin/HEAD` points at, or null when the repo has no such ref:
+     * no remote, or a clone that never fetched it.
+     */
+    defaultBranch(): Promise<string | null>;
+    currentBranch(cwd: string): Promise<string>;
+    head(cwd: string): Promise<string>;
+    shortHead(cwd: string): Promise<string>;
+    porcelain(cwd: string): Promise<string[]>;
+    conflictedPaths(cwd: string): Promise<string[]>;
+    commitsAhead(trunk: string, branch: string): Promise<number | null>;
+    /** Lines added and removed on `branch` since it left `trunk`. */
+    diffStat(trunk: string, branch: string): Promise<{
+        added: number;
+        removed: number;
+    } | null>;
+    /**
+     * Every path `branch` touches since it left `trunk`, plus what is still
+     * uncommitted in `worktree` when there is one: an agent mid-task has usually
+     * committed nothing yet, and its edits are the overlap that matters most.
+     */
+    changedFiles(trunk: string, branch: string, worktree: string | null): Promise<string[] | null>;
+    /**
+     * Every path a person might point an agent at in the tree at `cwd`: the
+     * files git tracks, the new ones it does not ignore, and each directory
+     * above them, which ends in `/`. Sorted, relative to the tree's root.
+     */
+    paths(cwd: string): Promise<string[]>;
+    rebase(cwd: string, onto: string): Promise<GitResult>;
+    resetHard(cwd: string, commit: string): Promise<GitResult>;
+    checkout(branch: string): Promise<GitResult>;
+    mergeFfOnly(cwd: string, branch: string): Promise<GitResult>;
+    /**
+     * The worktree with `branch` checked out, or null when no worktree has it.
+     * Git allows one worktree per branch and that is the only place the branch
+     * can be advanced, so this is where a fast-forward has to happen.
+     */
+    worktreeFor(branch: string): Promise<string | null>;
+    addWorktree(branch: string, path: string, from: string): Promise<GitResult>;
+    removeWorktree(path: string): Promise<GitResult>;
+    /** Drops metadata for worktrees whose directories are gone. */
+    pruneWorktrees(): Promise<GitResult>;
+    deleteBranch(branch: string): Promise<GitResult>;
+    /** The one `.git` every worktree of this repo shares. */
+    commonDir(): Promise<string>;
+    /** The git directory belonging to a worktree, or null if it has none. */
+    worktreeGitDir(worktree: string): Promise<string | null>;
+    /** Half-finished merges and rebases a resuming agent is standing in. */
+    interruptedOps(worktree: string): Promise<string[]>;
+}

package/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};