@webappwiz/arbor 0.0.7 → 0.0.8

package/README.md

@@ -131,6 +131,23 @@ prescribes (`# <task>`, `## Goal`, `## Next` with something unchecked in it, a
 Warnings only, never a refusal: the agent that wrote the file is the one that
 runs `show` on it, and a rough plan still beats none.
 
+### `arbor wait <task> [--timeout-secs 300]`
+
+Blocks until a task stops moving, then prints where it stopped.
+
+Moving means `working` or `merging`. Everything else is somewhere it stays
+without a person: `escalated` (printed with its reason), `removed` (merged or
+discarded, and `arbor log` says which), or one of the broken statuses.
+
+This is for the agent whose own work overlaps a task already in flight and
+would rather rebase onto its result than against it. The timeout is short by
+design: five minutes, and then a `timeout` refusal that hands the decision
+back, rather than a session that blocks all afternoon on a tree nobody is
+driving. Wait again, work alongside it, or ask the human.
+
+Like `show` and `path`, it takes no lease, so watching a task cannot knock its
+agent off it.
+
 ### `arbor log [--count 20] [--json]`
 
 The last N things done here (`add`, `claim`, `merge`, `rm`, `escalate`,
@@ -221,6 +238,7 @@ The agent's control flow runs on these.
 | 11   | `orphaned`          | Record with no worktree. `arbor rm` it.                         |
 | 12   | `merge_failed`      | Trunk could not be fast-forwarded (usually a dirty main worktree). |
 | 13   | `already_removed`    | This task was removed earlier; nothing left to remove.              |
+| 14   | `timeout`           | `arbor wait` gave up: the task is still working or merging.        |
 
 Every failure prints a one-line JSON object on **stdout** (`{"reason": ...}`,
 plus fields like `paths` for conflicts) and the human explanation on **stderr**.

package/dev.d.ts

@@ -1,10 +1,24 @@
 import type { HttpServer } from "webappwiz/http";
 import type { Logger } from "webappwiz/log";
-import type { Fs } from "webappwiz/system";
+import { type Fs, type PortProvider } from "webappwiz/system";
 import type { Assets } from "./dev/assets.js";
 import type { Journal } from "./journal.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;
+/**
+ * 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;
+/** What `dev` lets a caller choose. */
+export interface DevOptions {
+    /** Where to listen; the port `--port` asked for, and the span above it. */
+    ports?: PortProvider;
+}
 /** A running server, and the one thing a caller ever wants to do with it. */
 export interface DevServer {
     port: number;
@@ -26,6 +40,4 @@ export declare function dev({ service, fs, journal, log, http, assets, }: {
     log: Logger;
     http: HttpServer;
     assets: Assets;
-}, { port }?: {
-    port?: number | undefined;
-}): Promise<DevServer>;
+}, { ports }?: DevOptions): Promise<DevServer>;

package/exit.d.ts

@@ -14,6 +14,7 @@ export declare const EXIT: {
     readonly orphaned: 11;
     readonly merge_failed: 12;
     readonly already_removed: 13;
+    readonly timeout: 14;
 };
 export type Reason = keyof typeof EXIT;
 /**

package/index.js

@@ -8,6 +8,7 @@ import { NodeFs as NodeFs7 } from "webappwiz/system";
 // arbor.ts
 import { cli } from "webappwiz/cmd";
 import { t } from "webappwiz/t";
+import { Duration as Duration3 } from "webappwiz/time";
 
 // add.ts
 import { color } from "webappwiz/log";
@@ -27,7 +28,8 @@ var EXIT = {
   exists: 10,
   orphaned: 11,
   merge_failed: 12,
-  already_removed: 13
+  already_removed: 13,
+  timeout: 14
 };
 
 class Exit extends Error {
@@ -60,7 +62,7 @@ function exits() {
 // add.ts
 var NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 var PLAN_FILE = "ARBOR.md";
-var PLAN = (task) => new MarkdownWriter().heading(1, task).heading(2, "Goal").heading(2, "Next").checklist("fill in Goal and list the steps here as `- [ ]` items").toString();
+var PLAN = (task) => new MarkdownWriter().heading(1, task).heading(2, "Goal").heading(2, "Files").heading(2, "Next").checklist("fill in Goal and list the steps here as `- [ ]` items").toString();
 async function add({
   service,
   shell,
@@ -159,6 +161,10 @@ ${changes.map((change) => `    ${change}`).join(`
 }
 
 // dev.ts
+import {
+  MAX_PORT,
+  OpenPortProvider
+} from "webappwiz/system";
 import { Duration } from "webappwiz/time";
 
 // snapshot.ts
@@ -219,7 +225,7 @@ import { NodeFs } from "webappwiz/system";
 // plan.ts
 import { Markdown } from "webappwiz/md";
 var SECTIONS = ["Goal", "Files", "Done", "Next", "Notes", "Blocked"];
-var REQUIRED = ["Goal", "Next"];
+var REQUIRED = ["Goal", "Files", "Next"];
 var UNCHECKED = /^[ \t]*- \[ \]/m;
 function checkPlan(text, { task, escalated = false }) {
   const md = Markdown.parse(text);
@@ -236,6 +242,9 @@ function checkPlan(text, { task, escalated = false }) {
   if (section("Goal") === "") {
     problems.push("## Goal is empty: say in a line or two what done means");
   }
+  if (section("Files") === "") {
+    problems.push("## Files is empty: list the file paths you plan to touch");
+  }
   const next = section("Next");
   if (next !== null && !UNCHECKED.test(next)) {
     problems.push("## Next has no `- [ ]` item: say what the next step is");
@@ -358,6 +367,15 @@ function fingerprint({ tasks, entries }) {
 
 // dev.ts
 var DEFAULT_PORT = 4269;
+var PORT_SPAN = 20;
+function devPorts(from) {
+  if (!Number.isInteger(from) || from < 0 || from > MAX_PORT) {
+    fail("usage", `invalid port '${from}': use a whole number 0 to ${MAX_PORT}`, {
+      port: from
+    });
+  }
+  return OpenPortProvider.span({ from, span: PORT_SPAN });
+}
 var POLL_MS = 2000;
 async function dev({
   service,
@@ -366,7 +384,7 @@ async function dev({
   log: log2,
   http,
   assets
-}, { port = DEFAULT_PORT } = {}) {
+}, { ports = devPorts(DEFAULT_PORT) } = {}) {
   const open = new Set;
   const encoder = new TextEncoder;
   let last = fingerprint(await snapshot(service, journal, { fs }));
@@ -428,7 +446,7 @@ async function dev({
       default:
         return new Response("not found", { status: 404 });
     }
-  }, { port, idleTimeout: Duration.zero() });
+  }, { port: await ports.get(), idleTimeout: Duration.zero() });
   log2.info(`arbor dev on http://localhost:${listening.port}`);
   return {
     port: listening.port,
@@ -1255,6 +1273,43 @@ async function rm({ service, log: log2 }, task, { force = false } = {}) {
 `));
 }
 
+// wait.ts
+import { color as color11 } from "webappwiz/log";
+import { Duration as Duration2, sleep } from "webappwiz/time";
+var DEFAULT_TIMEOUT = Duration2.mins(5);
+var POLL = Duration2.secs(2);
+var RUNNING = ["working", "merging"];
+async function wait({ service, log: log2 }, task, { timeout = DEFAULT_TIMEOUT, poll = POLL } = {}) {
+  const deadline = Date.now() + timeout.ms;
+  for (;; ) {
+    const worktree = await service.find(task);
+    if (worktree.status === "absent") {
+      fail("not_found", `no task '${task}': run \`arbor ls\` to see what there is`, { task });
+    }
+    if (!RUNNING.includes(worktree.status)) {
+      log2.info(report2(worktree));
+      return;
+    }
+    const left = deadline - Date.now();
+    if (left <= 0) {
+      fail("timeout", `'${task}' is still ${worktree.status} after ${timeout.secs}s: wait again, work alongside it and accept the rebase, or ask the human`, { task, status: worktree.status });
+    }
+    await sleep(Duration2.min(poll, Duration2.ms(left)));
+  }
+}
+function report2(worktree) {
+  const lines2 = [`${color11.bold(worktree.task)} ${worktree.status}`];
+  const escalation = worktree.state?.escalations?.at(-1)?.reason;
+  if (escalation) {
+    lines2.push(`  ${color11.yellow(`escalated: ${escalation}`)}`);
+  }
+  if (worktree.status === "removed") {
+    lines2.push("", `Nothing left of it here: \`arbor log\` says whether it landed.`);
+  }
+  return lines2.join(`
+`);
+}
+
 // arbor.ts
 var here = async ({
   service,
@@ -1274,14 +1329,20 @@ arbor.command("rm").description("discard a task: worktree, branch and state file
 }).action((opts, ctx) => ctx.journal.record("rm", opts.task, () => rm(ctx, opts.task, { force: opts.force })));
 arbor.command("ls").description("list every task: name, status, lease (held: an agent is on it now; stale: gone quiet, normal for a task mid-edit; none), commits ahead of trunk, age").option("json", t.boolean(), { default: false, description: "emit JSON" }).action((opts, ctx) => ls(ctx, { json: opts.json }));
 arbor.command("show").description("read one task without touching it: everything `ls` lists for it, plus the ARBOR.md its agent left at the worktree root; takes no lease, so it cannot knock that agent off its own tree").arg("task", t.string(), { description: "task name" }).option("json", t.boolean(), { default: false, description: "emit JSON" }).action((opts, ctx) => show(ctx, opts.task, { json: opts.json }));
+arbor.command("wait").description("block until a task stops moving: escalated, or gone (merged or removed), or broken; takes no lease, and gives up with `timeout` rather than waiting forever").arg("task", t.string(), { description: "task name" }).option("timeout-secs", t.number(), {
+  default: DEFAULT_TIMEOUT.secs,
+  description: "how long to wait before giving up"
+}).action((opts, ctx) => wait(ctx, opts.task, {
+  timeout: Duration3.secs(opts["timeout-secs"])
+}));
 arbor.command("log").description("show what has been done here recently: one line per add, claim, merge, rm, escalate and retry, with how it ended; outlives the tasks themselves").option("count", t.number(), {
   default: DEFAULT_COUNT,
   description: "how many entries to show"
 }).option("json", t.boolean(), { default: false, description: "emit JSON" }).action((opts, ctx) => log(ctx, { count: opts.count, json: opts.json }));
 arbor.command("dev").description("serve `ls`, `show` and `log` as a web page; read-only").option("port", t.number(), {
   default: DEFAULT_PORT,
-  description: "port to listen on"
-}).action((opts, ctx) => dev(ctx, { port: opts.port }));
+  description: "port to listen on, or the next open one above it"
+}).action((opts, ctx) => dev(ctx, { ports: devPorts(opts.port) }));
 arbor.command("path").description("print a task's worktree path, or the main tree with no task; names another agent's tree without taking its lease").arg("task", t.string(), {
   default: "",
   description: "task name; omit for the main tree"

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@webappwiz/arbor",
-	"version": "0.0.7",
+	"version": "0.0.8",
 	"description": "Runs several AI coding agents on one repository at once, each in its own git worktree",
 	"license": "MIT",
 	"author": "Jared Johnson",
@@ -17,7 +17,7 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"webappwiz": "^0.0.7"
+		"webappwiz": "^0.0.8"
 	},
 	"main": "./index.js",
 	"types": "./index.d.ts",

package/wait.d.ts

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