dw-sdlc 0.11.0 → 0.12.0

package/dist/commands/worker-start.js

@@ -0,0 +1,234 @@
+// `dw-sdlc worker start`: puts a Brief in a herdr terminal as a Worker's first message, on the command, model
+// and effort the config names, and reads back whether the Worker took it.
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { parseArgs } from "node:util";
+import { mainCheckout, repositoryRoot, resolveConfig, WORKER_EFFORTS } from "../agentic-config.js";
+import { isObject } from "../json-text.js";
+import { describe, hcObject, isLive, lead, refuse, Refusal, wholeNumber, workersOf } from "../worker/herdr.js";
+import { nameTab } from "../worker/tabs.js";
+export const summary = "start a Worker on a Brief in a herdr terminal";
+/** The most seconds the command looks for the Worker's tab in the window, beside the read-back. */
+const TAB_WAIT = 10;
+const USAGE = `Usage: dw-sdlc worker start --brief <file> --name <name> [--model <model>] [--effort <effort>]
+                            [--max-workers <n>] [--wait <seconds>] [--json]
+
+Starts a Worker in the background and gives it the Brief as its first message. It runs hc run with the name,
+the label role=worker, --outlive-parent and the repository as the folder, then worker.command of the config
+with --worktree <name>, --model, --effort and the Brief. worker.command is split on whitespace, so it holds
+no quoted word. --model and --effort default to worker.model and worker.effort. When the Lead sits in a
+herdr space the Worker joins it, and its tab, which herdr numbers, takes the Worker's name: the window lists
+the tab a moment after hc run, so the command looks for it for up to ${TAB_WAIT} seconds, or --wait when shorter,
+while it reads the terminal back.
+
+It reads the terminal back for up to --wait seconds (default 30), until the Worker shows work: its status
+turns working, blocked or done. It fails when herdr reports the first message as unsent, the terminal has
+ended, the Worker reports an error, or the Worker is still idle or silent when the time is up. It never sends
+the Brief again: read the terminal with hc read first.
+
+It refuses outside herdr ($HC_TERMINAL_ID unset) and when the Lead already has --max-workers live
+Workers (default 3). The name is 1-32 of a-z, 0-9, - and _; it names the worktree too.
+
+One line, or one JSON document with --json.
+
+Exit 0 started and delivered, 1 started but not delivered, 2 when it cannot run.`;
+const DEFAULT_MAX_WORKERS = 3;
+const DEFAULT_WAIT = 30;
+/** hc names a terminal with 1-32 of a-z, 0-9, - and _. */
+const NAME = /^[a-z0-9][a-z0-9_-]{0,31}$/;
+/** What a Worker reports once it has taken its first message. */
+const WORKING = new Set(["working", "blocked", "done"]);
+/** How long the read-back waits between two reads of the terminal. */
+const POLL_MS = 1000;
+function parseCli(argv) {
+    try {
+        const { values } = parseArgs({
+            args: argv,
+            options: {
+                help: { type: "boolean", short: "h" },
+                json: { type: "boolean" },
+                brief: { type: "string" },
+                name: { type: "string" },
+                model: { type: "string" },
+                effort: { type: "string" },
+                "max-workers": { type: "string" },
+                wait: { type: "string" }
+            }
+        });
+        if (values.help === true) {
+            return "help";
+        }
+        const { brief, name, model, effort } = values;
+        if (brief === undefined) {
+            return { error: "name the Brief file: --brief <file>" };
+        }
+        if (name === undefined || !NAME.test(name)) {
+            return { error: `--name takes 1-32 of a-z, 0-9, - and _, not ${JSON.stringify(name ?? "")}` };
+        }
+        if (model !== undefined && (model.trim() === "" || model.startsWith("-"))) {
+            return { error: `--model takes a model name, not ${JSON.stringify(model)}` };
+        }
+        if (effort !== undefined && !WORKER_EFFORTS.includes(effort)) {
+            return { error: `--effort takes one of ${WORKER_EFFORTS.join(", ")}, not ${JSON.stringify(effort)}` };
+        }
+        const max = wholeNumber("--max-workers", values["max-workers"], DEFAULT_MAX_WORKERS, 1);
+        const wait = wholeNumber("--wait", values.wait, DEFAULT_WAIT, 0);
+        if (typeof max === "object") {
+            return max;
+        }
+        if (typeof wait === "object") {
+            return wait;
+        }
+        return { brief, name, model, effort, max, wait, json: values.json === true };
+    }
+    catch (error) {
+        return { error: describe(error) };
+    }
+}
+/** The Brief's text; a file that is missing or holds only whitespace stops the command. */
+function readBrief(file) {
+    let text;
+    try {
+        text = readFileSync(resolve(file), "utf8");
+    }
+    catch (error) {
+        throw new Refusal(`cannot read the Brief ${file}: ${describe(error)}`);
+    }
+    if (text.trim() === "") {
+        throw new Refusal(`the Brief ${file} is empty`);
+    }
+    return text;
+}
+/** The status a Worker reports, if it has reported one. */
+function reportedStatus(terminal) {
+    const { status } = terminal;
+    return isObject(status) && typeof status.state === "string" ? status.state : undefined;
+}
+/** Why the Worker can no longer take the Brief, or undefined while it still may. */
+function failure(terminal) {
+    const { first_message: first, state } = terminal;
+    if (isObject(first) && first.sent === false) {
+        return typeof first.reason === "string" ? first.reason : "herdr gave no reason";
+    }
+    if (state !== "live") {
+        return "the terminal has finished";
+    }
+    return reportedStatus(terminal) === "error" ? "the Worker reports its status as error" : undefined;
+}
+/** Reads the terminal until the Worker shows work, for up to `wait` seconds; why it did not, or undefined once it did. */
+async function delivery(address, wait) {
+    const deadline = Date.now() + wait * 1000;
+    for (;;) {
+        let terminal;
+        try {
+            terminal = hcObject(["get", address, "--json"]);
+        }
+        catch (error) {
+            if (!(error instanceof Refusal)) {
+                throw error;
+            }
+            // The Worker is running by now, so a failed read is a Brief not confirmed, never a start that did not happen.
+            return `the terminal could not be read back: ${describe(error)}`;
+        }
+        const failed = failure(terminal);
+        if (failed !== undefined) {
+            return failed;
+        }
+        if (WORKING.has(reportedStatus(terminal) ?? "")) {
+            return undefined;
+        }
+        if (Date.now() >= deadline) {
+            return `the Worker showed no sign of work within ${wait} s`;
+        }
+        await sleep(POLL_MS);
+    }
+}
+/** The id of the herdr space the Lead sits in, if it sits in one. */
+function spaceOf(leadId) {
+    const { labels } = hcObject(["get", leadId, "--json"]);
+    const space = isObject(labels) ? labels["herdr.space"] : undefined;
+    return typeof space === "string" ? space : undefined;
+}
+async function start(cli) {
+    const brief = readBrief(cli.brief);
+    const leadId = lead();
+    const checkout = repositoryRoot(process.cwd());
+    // The Worker's --worktree makes a worktree of the repository itself, never of a linked one.
+    const root = mainCheckout(checkout) ?? checkout;
+    const worker = resolveConfig(checkout).config.worker;
+    const command = worker.command.split(/\s+/).filter(Boolean);
+    if (command.length === 0) {
+        throw new Refusal("worker.command holds no command", "set it in .ai/agentic.config.local.json, or remove the key");
+    }
+    const model = cli.model ?? worker.model;
+    const effort = cli.effort ?? worker.effort;
+    const live = workersOf(leadId, false).filter(isLive);
+    if (live.length >= cli.max) {
+        throw new Refusal(`${leadId} already has ${live.length} live Workers (the limit is ${cli.max})`, `carry one through first, or raise the limit with --max-workers ${live.length + 1}`);
+    }
+    const space = spaceOf(leadId);
+    const { address } = hcObject([
+        "run",
+        "--bg",
+        "--json",
+        "--name",
+        cli.name,
+        "--label",
+        "role=worker",
+        ...(space === undefined ? [] : ["--label", `herdr.space=${space}`]),
+        "--outlive-parent",
+        "--cwd",
+        root,
+        "--",
+        ...command,
+        "--worktree",
+        cli.name,
+        "--model",
+        model,
+        "--effort",
+        effort,
+        brief
+    ]);
+    if (typeof address !== "string") {
+        throw new Refusal("hc run answered no address for the terminal it started", "check hc ls before starting it again");
+    }
+    // Side by side, so the wait for the tab overlaps the wait for the Worker to start.
+    const naming = space === undefined ? Promise.resolve("none") : nameTab(address, cli.name, Math.min(TAB_WAIT, cli.wait));
+    const [named, reason] = await Promise.all([naming, delivery(address, cli.wait)]);
+    if (typeof named === "object") {
+        process.stderr.write(`dw-sdlc worker start: warning: ${named.kept}\n`);
+    }
+    if (cli.json) {
+        const tab = typeof named === "object" ? "kept" : named;
+        const started = { name: cli.name, address, command: worker.command, model, effort, cwd: root };
+        const document = { ...started, delivered: reason === undefined, ...(reason === undefined ? {} : { reason }), tab };
+        process.stdout.write(`${JSON.stringify(document, null, 2)}\n`);
+    }
+    if (reason !== undefined) {
+        process.stderr.write(`dw-sdlc worker start: ${cli.name} (${address}) started but its first message was not delivered: ${reason} — ` +
+            `run hc read ${address} to see why; do not send the Brief again before you have read it\n`);
+        return 1;
+    }
+    if (!cli.json) {
+        process.stdout.write(`started ${cli.name} (${address}) on ${model} at ${effort} effort\n`);
+    }
+    return 0;
+}
+export async function run(argv) {
+    const cli = parseCli(argv);
+    if (cli === "help") {
+        process.stdout.write(`${USAGE}\n`);
+        return 0;
+    }
+    if ("error" in cli) {
+        process.stderr.write(`dw-sdlc worker start: ${cli.error}\n\n${USAGE}\n`);
+        return 2;
+    }
+    try {
+        return await start(cli);
+    }
+    catch (error) {
+        return refuse("worker start", error);
+    }
+}

package/dist/doctor-plugins.d.ts

@@ -0,0 +1,14 @@
+import type { Check, Probe } from "./commands/doctor.ts";
+/** The JSON `text` holds, whatever its kind: `claude plugin list --json` prints an array. */
+export declare function parseJson(text: string | undefined): unknown;
+/** The directory `plugin` runs from on this machine: the checkout of a directory marketplace, else the installed snapshot. */
+export declare function runningPluginRoot(probe: Probe, claude: string, plugin?: string): string | undefined;
+export declare function checkPlugin(probe: Probe, claude: string): Check;
+/** Whether the plugin's hooks and skills run the dw-sdlc the repository pins, the one its Gate runs. */
+export declare function checkPackage(probe: Probe, claude: string, root: string | undefined): Check;
+/**
+ * `sdlc-sessions`, which a machine may go without, so it never fails. Its copy of the package against
+ * the sdlc plugin's copy: the `package` line holds that one to the repository's pin.
+ */
+export declare function checkSessions(probe: Probe, claude: string): Check;
+export declare function versionBefore(version: string, threshold: string): boolean;

package/dist/doctor-plugins.js

@@ -0,0 +1,182 @@
+// The doctor's lines on the plugins: `sdlc` installed and enabled, the package it links against the one the
+// repository pins, and the optional `sdlc-sessions` with its own copy of the package.
+import { join } from "node:path";
+import { isObject } from "./json-text.js";
+import { EXACT_VERSION, parseCatalog, parsePins } from "./pins.js";
+/** The marketplace Claude Code registers this repository under, the plugin in it, and the package the plugin links to. */
+const MARKETPLACE = "dw-sdlc";
+const PLUGIN = "sdlc";
+const PLUGIN_ID = `${PLUGIN}@${MARKETPLACE}`;
+/** The plugin of the session helpers: optional, and it links a copy of the package of its own. */
+const SESSIONS = "sdlc-sessions";
+const SESSIONS_ID = `${SESSIONS}@${MARKETPLACE}`;
+const PACKAGE = "dw-sdlc";
+/** The JSON `text` holds, whatever its kind: `claude plugin list --json` prints an array. */
+export function parseJson(text) {
+    if (text === undefined) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The checkout a directory marketplace runs the plugin from, or undefined for a snapshot. */
+function liveCheckout(probe, claude) {
+    const known = parseJson(probe.read(join(claude, "plugins", "known_marketplaces.json")));
+    const entry = isObject(known) && isObject(known[MARKETPLACE]) ? known[MARKETPLACE] : undefined;
+    const source = entry !== undefined && isObject(entry.source) ? entry.source : undefined;
+    return source?.source === "directory" && typeof source.path === "string" ? source.path : undefined;
+}
+function pluginOrigin(probe, claude, installPath) {
+    const checkout = liveCheckout(probe, claude);
+    if (checkout !== undefined) {
+        return `runs live from ${checkout}/plugins/${PLUGIN}; a change there is in the next session`;
+    }
+    return `installed at ${installPath}; a change reaches it through claude plugin update`;
+}
+/** What `claude plugin list --json` prints, one object a plugin, or undefined when it does not answer. */
+function listedPlugins(probe) {
+    const { status, stdout } = probe.run("claude", ["plugin", "list", "--json"]);
+    const list = status === 0 ? parseJson(stdout) : undefined;
+    return Array.isArray(list) ? list.filter(isObject) : undefined;
+}
+/** The directory `plugin` runs from on this machine: the checkout of a directory marketplace, else the installed snapshot. */
+export function runningPluginRoot(probe, claude, plugin = PLUGIN) {
+    const checkout = liveCheckout(probe, claude);
+    if (checkout !== undefined) {
+        return join(checkout, "plugins", plugin);
+    }
+    const entry = listedPlugins(probe)?.find((item) => item.id === `${plugin}@${MARKETPLACE}`);
+    return entry !== undefined && typeof entry.installPath === "string" ? entry.installPath : undefined;
+}
+export function checkPlugin(probe, claude) {
+    const list = listedPlugins(probe);
+    if (list === undefined) {
+        return { name: "plugin", level: "FAIL", detail: "claude plugin list did not answer; is Claude Code installed?" };
+    }
+    const entry = list.find((item) => item.id === PLUGIN_ID);
+    if (entry === undefined) {
+        return {
+            name: "plugin",
+            level: "FAIL",
+            detail: `${PLUGIN_ID} is not installed. claude plugin marketplace add dominikwozniak/dw-sdlc --sparse .claude-plugin plugins packages && claude plugin install ${PLUGIN_ID} --scope user`
+        };
+    }
+    const version = typeof entry.version === "string" ? entry.version : "?";
+    const installPath = typeof entry.installPath === "string" ? entry.installPath : "?";
+    if (entry.enabled !== true) {
+        return {
+            name: "plugin",
+            level: "FAIL",
+            detail: `${version} installed but disabled, so no guard runs. claude plugin enable ${PLUGIN_ID}`
+        };
+    }
+    return {
+        name: "plugin",
+        level: "PASS",
+        detail: `${version} enabled; ${pluginOrigin(probe, claude, installPath)}`
+    };
+}
+/** The `version` of the package.json in `dir`, or undefined when there is none. */
+function manifestVersion(probe, dir) {
+    const manifest = parseJson(probe.read(join(dir, "package.json")));
+    return isObject(manifest) && typeof manifest.version === "string" ? manifest.version : undefined;
+}
+/** Whether the plugin's hooks and skills run the dw-sdlc the repository pins, the one its Gate runs. */
+export function checkPackage(probe, claude, root) {
+    const name = "package";
+    const manifest = root === undefined ? undefined : probe.read(join(root, "package.json"));
+    if (root === undefined || manifest === undefined) {
+        return { name, level: "INFO", detail: `no package.json here to pin ${PACKAGE}` };
+    }
+    let spec;
+    try {
+        spec = parsePins(manifest, parseCatalog(probe.read(join(root, "pnpm-workspace.yaml")) ?? ""))[PACKAGE];
+    }
+    catch {
+        return { name, level: "INFO", detail: `${join(root, "package.json")} is not JSON` };
+    }
+    if (spec === undefined) {
+        return { name, level: "INFO", detail: `the repository does not pin ${PACKAGE}` };
+    }
+    // `workspace:` or a range names no one version: the copy installed under node_modules is the one that runs.
+    const pinned = EXACT_VERSION.test(spec) ? spec : manifestVersion(probe, join(root, "node_modules", PACKAGE));
+    if (pinned === undefined) {
+        return { name, level: "WARN", detail: `the repository pins ${PACKAGE} ${spec}, not installed: pnpm install` };
+    }
+    const plugin = runningPluginRoot(probe, claude);
+    if (plugin === undefined) {
+        return { name, level: "INFO", detail: `no ${PLUGIN_ID} runs here to compare with the pinned ${pinned}` };
+    }
+    const linked = manifestVersion(probe, join(plugin, PACKAGE));
+    if (linked === undefined) {
+        return {
+            name,
+            level: "WARN",
+            detail: `the plugin at ${plugin} carries no ${PACKAGE}: an install from GitHub needs packages in its --sparse set`
+        };
+    }
+    if (linked !== pinned) {
+        const remedy = versionBefore(linked, pinned)
+            ? `claude plugin update ${PLUGIN_ID}`
+            : `pnpm add --save-dev --save-exact ${PACKAGE}@${linked}`;
+        return {
+            name,
+            level: "WARN",
+            detail: `drift: the plugin runs ${PACKAGE} ${linked} and the repository pins ${pinned}, so its hooks and skills run other code than the Gate. ${remedy}`
+        };
+    }
+    return { name, level: "PASS", detail: `${PACKAGE} ${linked} in the plugin and in the repository` };
+}
+/**
+ * `sdlc-sessions`, which a machine may go without, so it never fails. Its copy of the package against
+ * the sdlc plugin's copy: the `package` line holds that one to the repository's pin.
+ */
+export function checkSessions(probe, claude) {
+    const name = "sessions";
+    const list = listedPlugins(probe);
+    const entry = list?.find((item) => item.id === SESSIONS_ID);
+    if (entry === undefined) {
+        const detail = list === undefined ? "claude plugin list did not answer" : `no ${SESSIONS_ID}, so no /sdlc-recap`;
+        return { name, level: "INFO", detail };
+    }
+    const version = typeof entry.version === "string" ? entry.version : "?";
+    if (entry.enabled !== true) {
+        return { name, level: "WARN", detail: `${version} installed but disabled. claude plugin enable ${SESSIONS_ID}` };
+    }
+    const root = runningPluginRoot(probe, claude, SESSIONS);
+    const copy = root === undefined ? undefined : manifestVersion(probe, join(root, PACKAGE));
+    if (copy === undefined) {
+        return {
+            name,
+            level: "WARN",
+            detail: `${version} carries no ${PACKAGE}: an install from GitHub needs packages in its --sparse set`
+        };
+    }
+    const guards = runningPluginRoot(probe, claude);
+    const other = guards === undefined ? undefined : manifestVersion(probe, join(guards, PACKAGE));
+    if (other !== undefined && other !== copy) {
+        const behind = versionBefore(copy, other) ? SESSIONS_ID : PLUGIN_ID;
+        return {
+            name,
+            level: "WARN",
+            detail: `drift: ${SESSIONS} runs ${PACKAGE} ${copy} and ${PLUGIN} runs ${other}. claude plugin update ${behind}`
+        };
+    }
+    return { name, level: "PASS", detail: `${version} enabled, on ${PACKAGE} ${copy}` };
+}
+export function versionBefore(version, threshold) {
+    const a = version.split(".").map((part) => Number.parseInt(part, 10));
+    const b = threshold.split(".").map((part) => Number.parseInt(part, 10));
+    for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        if (x !== y) {
+            return x < y;
+        }
+    }
+    return false;
+}

package/dist/pr/decide.js

@@ -152,7 +152,8 @@ const ROWS = [
         })
     },
     {
-        when: (pr) => pr.mergeStateStatus === "BEHIND",
+        // GitHub reports BEHIND only under a rule that a branch be up to date; the compare tells it anywhere.
+        when: (pr) => pr.mergeStateStatus === "BEHIND" || (pr.behindBy ?? 0) > 0,
         answer: (pr) => ({ status: "act", action: "update-branch", actor: "script", reason: `behind ${pr.base}` })
     },
     {

package/dist/pr/read.d.ts

@@ -33,3 +33,8 @@ export declare function now(): number;
 export declare function readAgain(pr: PrState, sized: boolean): PrState;
 /** Whether the head of `after` carries the base `before` read: the compare shows it behind by none. */
 export declare function carriesBase(before: PrState, after: PrState): boolean;
+/**
+ * `pr` and how many commits of its base its head lacks, from the compare of the base with the head,
+ * read only where the decision can reach the update: open, mergeable, not reported BEHIND already.
+ */
+export declare function withBehind(pr: PrState): PrState;

package/dist/pr/read.js

@@ -129,12 +129,23 @@ export function now() {
 export function readAgain(pr, sized) {
     return query(pr, sized);
 }
-/** The reply of the compare from `from` to `commit`; `what` names it when gh refuses it. */
+/**
+ * The compares this process has read, by repository and the two commits, so reads that share one ask gh
+ * once: a compare of two commits never changes.
+ */
+const COMPARES = new Map();
+/** The reply of the compare from `from` to `commit`, read once per process; `what` names it when gh refuses it. */
 function compared(pr, from, commit, what) {
+    const key = `${pr.repo} ${from}...${commit}`;
+    const known = COMPARES.get(key);
+    if (known !== undefined) {
+        return known;
+    }
     const reply = gh(compareArgs(pr.repo, from, commit));
     if (reply.status !== 0) {
         throw new CannotRun(`${pr.repo}#${pr.number}: ${what}: ${said(reply.stderr)}`, REMEDIES.read);
     }
+    COMPARES.set(key, reply.stdout);
     return reply.stdout;
 }
 /** Whether the head of `after` carries the base `before` read: the compare shows it behind by none. */
@@ -142,6 +153,17 @@ export function carriesBase(before, after) {
     const reply = compared(after, before.baseOid, after.head, `the compare with ${before.baseOid.slice(0, 7)}`);
     return parseOrCannotRun(() => behindOf(reply)) === 0;
 }
+/**
+ * `pr` and how many commits of its base its head lacks, from the compare of the base with the head,
+ * read only where the decision can reach the update: open, mergeable, not reported BEHIND already.
+ */
+export function withBehind(pr) {
+    if (pr.state !== "OPEN" || pr.mergeable !== "MERGEABLE" || pr.mergeStateStatus === "BEHIND") {
+        return pr;
+    }
+    const reply = compared(pr, pr.baseOid, pr.head, `the compare with ${pr.base}`);
+    return { ...pr, behindBy: parseOrCannotRun(() => behindOf(reply)) };
+}
 /** The own changes of `pr` at `commit`, from the compare with its base; null when it cannot show them whole. */
 function ownChanges(pr, commit) {
     const reply = compared(pr, pr.baseOid, commit, `the compare with ${commit.slice(0, 7)}`);
@@ -190,5 +212,6 @@ function query({ repo, number }, sized) {
         const remedy = problem.startsWith("Could not resolve to a") ? REMEDIES.target : REMEDIES.read;
         throw new CannotRun(`${repo}#${number}: ${problem}`, remedy);
     }
-    return withChanged(withCarried(parseOrCannotRun(() => parsePr(reply.stdout, repo))), sized);
+    const parsed = parseOrCannotRun(() => parsePr(reply.stdout, repo));
+    return withChanged(withCarried({ ...parsed, behindBy: null }), sized);
 }

package/dist/pr/state.d.ts

@@ -2,7 +2,7 @@
 export declare const REVIEW = "dw-sdlc/review";
 /** How the description of a success the script posts under off begins: no one read that head. */
 export declare const OFF_PREFIX = "off:";
-export declare const QUERY = "query($owner: String!, $name: String!, $number: Int!) {\n  repository(owner: $owner, name: $name) {\n    pullRequest(number: $number) {\n      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName baseRefName baseRefOid\n      viewerDidAuthor mergeCommit { oid }\n      reviewThreads(first: 100) { nodes { id isResolved isOutdated path line\n        comments(first: 1) { nodes { author { login } body } }\n        latest: comments(last: 1) { nodes { viewerDidAuthor } } } }\n      commits(last: 1) { nodes { commit { committedDate statusCheckRollup {\n        contexts(first: 50) { nodes {\n          ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }\n          ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }\n      history: commits(last: 100) { nodes { commit { oid parents { totalCount } status { context(name: \"dw-sdlc/review\") { state description } } } } }\n    }\n  }\n}";
+export declare const QUERY = "query($owner: String!, $name: String!, $number: Int!) {\n  repository(owner: $owner, name: $name) {\n    pullRequest(number: $number) {\n      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName baseRefName baseRefOid\n      baseRef { target { oid } } viewerDidAuthor mergeCommit { oid }\n      reviewThreads(first: 100) { nodes { id isResolved isOutdated path line\n        comments(first: 1) { nodes { author { login } body } }\n        latest: comments(last: 1) { nodes { viewerDidAuthor } } } }\n      commits(last: 1) { nodes { commit { committedDate statusCheckRollup {\n        contexts(first: 50) { nodes {\n          ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }\n          ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }\n      history: commits(last: 100) { nodes { commit { oid parents { totalCount } status { context(name: \"dw-sdlc/review\") { state description } } } } }\n    }\n  }\n}";
 export type Bucket = "pass" | "fail" | "pending" | "skipping";
 export type CiCheck = {
     name: string;
@@ -40,7 +40,10 @@ export type PrState = {
     headCommittedAt: string;
     branch: string;
     base: string;
-    /** The commit the base branch points at. */
+    /**
+     * The commit the base branch points at, read from the branch itself: GitHub's `baseRefOid` lags a
+     * base that just moved. A deleted base branch leaves `baseRefOid`.
+     */
     baseOid: string;
     mergeCommit: string | null;
     checks: CiCheck[];
@@ -57,6 +60,11 @@ export type PrState = {
      * auto` to route on: `unsized` when the compare cannot list them all, null when not read.
      */
     changed: ChangedFile[] | "unsized" | null;
+    /**
+     * How many commits of the base the head lacks, from the compare of the base with the head; null when
+     * not read.
+     */
+    behindBy: number | null;
 };
 /**
  * A file a Review would read: its name, its name before a rename, and the lines it adds and removes,
@@ -100,5 +108,5 @@ export declare function parseView(reply: string): {
 /** The default branch of the repository whose `gh repo view --json defaultBranchRef` printed `reply`. */
 export declare function parseDefaultBranch(reply: string): string;
 /** The state of the pull request in `reply`, the text `gh api graphql` printed for QUERY on `repo`. */
-export declare function parsePr(reply: string, repo: string): Omit<PrState, "carried" | "changed">;
+export declare function parsePr(reply: string, repo: string): Omit<PrState, "carried" | "changed" | "behindBy">;
 export {};

package/dist/pr/state.js

@@ -8,7 +8,7 @@ export const QUERY = `query($owner: String!, $name: String!, $number: Int!) {
   repository(owner: $owner, name: $name) {
     pullRequest(number: $number) {
       url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName baseRefName baseRefOid
-      viewerDidAuthor mergeCommit { oid }
+      baseRef { target { oid } } viewerDidAuthor mergeCommit { oid }
       reviewThreads(first: 100) { nodes { id isResolved isOutdated path line
         comments(first: 1) { nodes { author { login } body } }
         latest: comments(last: 1) { nodes { viewerDidAuthor } } } }
@@ -232,6 +232,7 @@ export function parsePr(reply, repo) {
     const rollup = childOrNull(commit, "statusCheckRollup");
     const mergeCommit = childOrNull(pr, "mergeCommit");
     const head = string(pr, "headRefOid");
+    const baseRef = childOrNull(pr, "baseRef");
     return {
         url: string(pr, "url"),
         repo,
@@ -246,7 +247,7 @@ export function parsePr(reply, repo) {
         headCommittedAt: time(commit, "committedDate"),
         branch: string(pr, "headRefName"),
         base: string(pr, "baseRefName"),
-        baseOid: string(pr, "baseRefOid"),
+        baseOid: baseRef === null ? string(pr, "baseRefOid") : string(child(baseRef, "target"), "oid"),
         mergeCommit: mergeCommit === null ? null : string(mergeCommit, "oid"),
         checks: rollup === null ? [] : nodes(rollup, "contexts").map((context) => checkOf(context, repo)),
         unresolvedThreads: nodes(pr, "reviewThreads")

package/dist/worker/herdr.d.ts

@@ -0,0 +1,48 @@
+import { type JsonObject } from "../json-text.ts";
+/** What stops a `worker` command before it acts: exit 2, the problem and, when there is one, its remedy. */
+export declare class Refusal extends Error {
+    remedy: string | undefined;
+    constructor(message: string, remedy?: string);
+}
+export type Called = {
+    status: number;
+    stdout: string;
+    stderr: string;
+};
+/** The first line of a tool's output that says anything, or the exit it ended with. */
+export declare function said(called: Called): string;
+/** `tool args` as a child process; a tool that is not on PATH stops the command. */
+export declare function call(tool: "hc" | "herdr-app", args: string[]): Called;
+/** The JSON object `hc <args>` prints; a failing call or a reply that is no object stops the command. */
+export declare function hcObject(args: string[]): JsonObject;
+/** What an error says, whatever was thrown. */
+export declare function describe(error: unknown): string;
+/** Reports a `Refusal` of `command` on stderr and answers exit 2; any other error is a bug and goes on up. */
+export declare function refuse(command: string, error: unknown): number;
+/** The option `flag` as a whole number from `min`, `fallback` when the command line leaves it out. */
+export declare function wholeNumber(flag: string, value: string | undefined, fallback: number, min: number): number | {
+    error: string;
+};
+/** The terminal the command runs in, which is the Lead of the Workers it starts or reads. */
+export declare function lead(): string;
+export type Worker = {
+    name: string;
+    address: string;
+    /** herdr's state: live or finished. */
+    state: string;
+    /** What the Worker reports (idle, working, done, blocked, error), `finished` once it has ended, `unknown` before it reports. */
+    status: string;
+    /** The folder it was launched in, or the one it works in once `workingFolders` has asked herdr. */
+    folder: string;
+};
+/** Whether herdr still runs the Worker's terminal; the one test of it every command shares. */
+export declare function isLive(worker: Worker): boolean;
+/**
+ * The Workers with the folder each live one works in, its worktree, which `hc get` reports as
+ * `foreground.cwd` and `hc ls` leaves out. A Worker herdr cannot tell it for keeps its launch folder.
+ */
+export declare function workingFolders(workers: Worker[]): Worker[];
+/** The Workers `lead` started, in the order herdr lists them; `all` adds the finished ones. */
+export declare function workersOf(leadId: string, all: boolean): Worker[];
+/** A table of rows, every column but the last padded to its widest cell and two spaces apart. */
+export declare function table(rows: string[][]): string;