@webappwiz/arbor 0.0.28 → 0.0.30

package/worktree.ts

@@ -0,0 +1,239 @@
+import type { GitResult } from "./git";
+import type { WorktreeService } from "./worktree-service";
+
+/** 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;
+	/**
+	 * For a task handed over to be approved rather than to answer questions,
+	 * the question in its plan that asks for the approval, `4`.
+	 */
+	review?: 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" // nothing under this name, and no memory of one
+	| "removed" // discarded earlier; still remembered
+	| "orphaned" // a record whose directory is gone
+	| "stray" // a leftover branch, with no directory or record
+	| "unrecorded" // a directory with no record
+	| "unknown"; // a record that would not parse
+
+/** 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 class Worktree {
+	// scry-ignore classes-over-function-exports: the service is what hands out Worktrees, so the two are one design in two files, and an interface here would have one implementation and still expose the service's Git
+	constructor(
+		private readonly service: WorktreeService,
+		private readonly snapshot: WorktreeSnapshot,
+	) {}
+
+	get task(): string {
+		return this.snapshot.task;
+	}
+
+	get branch(): string {
+		return this.snapshot.branch;
+	}
+
+	/** Where this task's work lands: its recorded base branch, else trunk. */
+	get base(): string {
+		return this.snapshot.state?.base ?? this.service.trunk;
+	}
+
+	get path(): string {
+		return this.snapshot.path;
+	}
+
+	get state(): TaskState | null {
+		return this.snapshot.state;
+	}
+
+	get lease(): LeaseState | null {
+		return this.snapshot.state?.lease ?? null;
+	}
+
+	get leaseHeld(): boolean {
+		// The pid check matters because every arbor command is its own short-lived
+		// process: without it a tree would stay locked for the whole staleness
+		// window after a command that merely finished, and `add` would block the
+		// `merge` that follows it.
+		const { lease } = this;
+		const { ps, config } = this.service;
+		if (!lease) {
+			return false;
+		}
+		if (Date.now() - Date.parse(lease.heartbeatAt) >= config.leaseStalenessMs) {
+			return false;
+		}
+		return lease.hostname === ps.hostname ? ps.alive(lease.pid) : true;
+	}
+
+	get leaseStatus(): "held" | "stale" | "none" {
+		return !this.lease ? "none" : this.leaseHeld ? "held" : "stale";
+	}
+
+	get leaseOurs(): boolean {
+		const { ps } = this.service;
+		return this.lease?.pid === ps.pid && this.lease.hostname === ps.hostname;
+	}
+
+	get leaseHeldByOther(): boolean {
+		return this.leaseHeld && !this.leaseOurs;
+	}
+
+	get mergeAttempts(): number {
+		return this.snapshot.state?.mergeAttempts ?? 0;
+	}
+
+	get exists(): boolean {
+		return this.snapshot.exists;
+	}
+
+	get hasBranch(): boolean {
+		return this.snapshot.hasBranch;
+	}
+
+	get removedAt(): string | null {
+		return this.snapshot.removedAt;
+	}
+
+	get status(): WorktreeStatus {
+		const { state, exists, hasBranch, removedAt, corrupt } = this.snapshot;
+		if (corrupt) {
+			return "unknown";
+		}
+		if (state) {
+			return exists ? state.status : "orphaned";
+		}
+		if (exists) {
+			return "unrecorded";
+		}
+		if (hasBranch) {
+			return "stray";
+		}
+		return removedAt ? "removed" : "absent";
+	}
+
+	get gone(): boolean {
+		return this.status === "absent" || this.status === "removed";
+	}
+
+	/**
+	 * 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.
+	 */
+	async save(changes: Partial<TaskState> = {}): Promise<Worktree> {
+		const now = new Date().toISOString();
+		const state: TaskState = {
+			task: this.task,
+			branch: this.branch,
+			worktree: this.path,
+			status: "working",
+			lease: null,
+			mergeAttempts: 0,
+			createdAt: now,
+			...(this.snapshot.state ?? {}),
+			...changes,
+			updatedAt: now,
+		};
+		await this.service.saveRecord(state);
+		return new Worktree(this.service, {
+			...this.snapshot,
+			state,
+			corrupt: false,
+		});
+	}
+
+	take(changes: Partial<TaskState> = {}): Promise<Worktree> {
+		const { ps } = this.service;
+		return this.save({
+			...changes,
+			lease: {
+				pid: ps.pid,
+				hostname: ps.hostname,
+				heartbeatAt: new Date().toISOString(),
+			},
+		});
+	}
+
+	/** Re-reads from disk. `merge` needs this: the record is the truth. */
+	reload(): Promise<Worktree> {
+		return this.service.find(this.task);
+	}
+
+	/** Removes the directory, the branch, and the record; remembers the name. */
+	discard(): Promise<GitResult> {
+		return this.service.discard(this);
+	}
+
+	commitsAhead(): Promise<number | null> {
+		return this.service.git.commitsAhead(this.base, this.branch);
+	}
+
+	diffStat(): Promise<{ added: number; removed: number } | null> {
+		return this.service.git.diffStat(this.base, this.branch);
+	}
+
+	/** Committed and uncommitted paths this task touches; null without a branch. */
+	changedFiles(): Promise<string[] | null> {
+		return this.service.git.changedFiles(
+			this.base,
+			this.branch,
+			this.exists ? this.path : null,
+		);
+	}
+
+	uncommitted(): Promise<string[]> {
+		return this.service.git.porcelain(this.path);
+	}
+
+	interruptedOps(): Promise<string[]> {
+		return this.service.git.interruptedOps(this.path);
+	}
+}

package/add.d.ts

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

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

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

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

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

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

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

package/dev/assets.d.ts

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

@@ -1,47 +0,0 @@
-import { type AsyncResource } from "webappwiz/disposable";
-import type { Logger } from "webappwiz/log";
-import { type Fs, type PortProvider } 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, journal, todos, log, assets, }: {
-    service: WorktreeService;
-    fs: Fs;
-    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

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

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

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

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