dw-sdlc 0.10.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.d.ts

@@ -1,4 +1,4 @@
-import type { PrMerge, PrReview, ReviewDepth } from "../agentic-config.ts";
+import type { PrMerge, PrReview, ResolvedConfig, ReviewDepth } from "../agentic-config.ts";
 import { type PrState, REVIEW } from "./state.ts";
 export { REVIEW };
 export type Status = "act" | "wait" | "park" | "done";
@@ -26,6 +26,8 @@ export type Policy = {
     };
     reviewCommand: string;
 };
+/** The policy a repository's `pr` key declares; a flag for one call goes over it. */
+export declare function declaredPolicy({ merge, review, reviewCommand }: ResolvedConfig["pr"]): Policy;
 /** An Action the pull request needs beside the one its answer names, so one push can fix several. */
 export type Blocker = {
     action: Action;
@@ -60,5 +62,9 @@ export declare function hostArgs(pr: PrState, action: ScriptAction, policy: Poli
 export declare function devCommand(pr: PrState, action: ScriptAction, policy: Policy): string;
 /** The merge left to the dev, `reason` saying why it is theirs. */
 export declare function readyToMerge(pr: PrState, policy: Policy, reason: string): Omit<Answer, "blockers">;
+/** `<status> <action>`, the action dropped when it repeats the status. */
+export declare function labelOf({ status, action }: Pick<Answer, "status" | "action">): string;
+/** The label and the reason, then the recheck and the command. */
+export declare function lineOf(answer: Answer): string;
 /** The Action `pr` needs at `now`, milliseconds since the epoch, under `policy`. */
 export declare function decide(pr: PrState, now: number, policy: Policy): Answer;

package/dist/pr/decide.js

@@ -4,6 +4,10 @@
 import { route } from "./route.js";
 import { awaitsReview, OFF_PREFIX, REVIEW } from "./state.js";
 export { REVIEW };
+/** The policy a repository's `pr` key declares; a flag for one call goes over it. */
+export function declaredPolicy({ merge, review, reviewCommand }) {
+    return { merge, review: { depth: review, source: "config" }, reviewCommand };
+}
 /** How long a head may carry no check before it parks as unverified, from its commit. */
 const GRACE_SECONDS = 120;
 /** How long CI may stay pending before it parks as stuck, from the first start among the pending checks. */
@@ -148,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}` })
     },
     {
@@ -279,6 +284,16 @@ const ROWS = [
         merging: true
     }
 ];
+/** `<status> <action>`, the action dropped when it repeats the status. */
+export function labelOf({ status, action }) {
+    return status === action ? status : `${status} ${action}`;
+}
+/** The label and the reason, then the recheck and the command. */
+export function lineOf(answer) {
+    const { reason, command, recheckAfter } = answer;
+    const recheck = recheckAfter === undefined ? "" : `, recheck in ${recheckAfter} s`;
+    return `${labelOf(answer)}: ${reason}${recheck}${command === undefined ? "" : ` — ${command}`}`;
+}
 function blockerOf({ action, actor, reason, details }) {
     return { action, actor, reason, ...(details === undefined ? {} : { details }) };
 }

package/dist/pr/read.d.ts

@@ -1,5 +1,5 @@
 import { type PrState } from "./state.ts";
-/** What stops a pr command before it answers: exit 2, the problem and its remedy on one line. */
+/** What stops a pr command or recap before it answers: exit 2, the problem and its remedy on one line. */
 export declare class CannotRun extends Error {
     remedy: string;
     constructor(message: string, remedy: string);
@@ -23,7 +23,18 @@ export declare function gh(args: string[]): {
  * `sized`, as `pr.review: auto` needs, the read sizes the changes a Review would read.
  */
 export declare function read(named: Named, command: string, sized: boolean): PrState;
+/** The state of the current branch's pull request, open or not, or null when gh finds none. */
+export declare function readBranch(sized: boolean): PrState | null;
+/** The default branch of the repository gh resolves from the current directory. */
+export declare function defaultBranch(): string;
+/** The time the decision reads: DW_SDLC_NOW, an ISO 8601 time a test sets, else the system clock. */
+export declare function now(): number;
 /** The state of `pr` once more, after an action the script performed on it: the same pull request. */
 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

@@ -1,10 +1,10 @@
-// The read both pr commands make: gh as a child process, its auth on the host gh api reads from, the
-// pull request a command names, and that pull request's state from one GraphQL request, with the two
-// compares that tell whether its head carries an earlier Review and the one that sizes its changes.
+// The read the pr commands and recap make: gh as a child process, its auth, the pull request a command names,
+// its state from one GraphQL request with the compares that tell whether its head carries an earlier Review
+// and that size its changes, and beside them the default branch and the clock the decision reads.
 import { spawnSync } from "node:child_process";
 import { behindOf, changedOf, changesOf, compareArgs, sameChanges } from "./delta.js";
-import { awaitsReview, parsePr, parseView, QUERY, ReplyError } from "./state.js";
-/** What stops a pr command before it answers: exit 2, the problem and its remedy on one line. */
+import { awaitsReview, parseDefaultBranch, parsePr, parseView, QUERY, ReplyError } from "./state.js";
+/** What stops a pr command or recap before it answers: exit 2, the problem and its remedy on one line. */
 export class CannotRun extends Error {
     remedy;
     constructor(message, remedy) {
@@ -17,7 +17,8 @@ const REMEDIES = {
     auth: "run gh auth login, or set GH_TOKEN",
     target: "check the number, or name the repository with -R owner/name",
     read: "check gh auth status and the network, then call again",
-    reply: "gh answered a shape dw-sdlc does not read; report it with the output of gh --version"
+    reply: "gh answered a shape dw-sdlc does not read; report it with the output of gh --version",
+    clock: "unset it: it stands in for the clock in tests"
 };
 /** The problem with `<n>` or `-R` as given on a command line, if there is one. */
 export function namedProblem(number, repo) {
@@ -76,29 +77,75 @@ function targetOf({ number, repo }, command) {
     }
     return parseOrCannotRun(() => parseView(view.stdout));
 }
-/**
- * The state of the pull request `named`; `command`, as `pr ship`, names the call in a remedy. With
- * `sized`, as `pr.review: auto` needs, the read sizes the changes a Review would read.
- */
-export function read(named, command, sized) {
+function requireAuth() {
     // The host gh api reads from: an account on any other host has no say in this call.
     const host = process.env.GH_HOST?.trim() || "github.com";
     const auth = gh(["auth", "status", "--active", "--hostname", host]);
     if (auth.status !== 0) {
         throw new CannotRun(`gh auth status failed: ${authProblem(auth.stderr)}`, REMEDIES.auth);
     }
+}
+/**
+ * The state of the pull request `named`; `command`, as `pr ship`, names the call in a remedy. With
+ * `sized`, as `pr.review: auto` needs, the read sizes the changes a Review would read.
+ */
+export function read(named, command, sized) {
+    requireAuth();
     return query(targetOf(named, command), sized);
 }
+/** The state of the current branch's pull request, open or not, or null when gh finds none. */
+export function readBranch(sized) {
+    requireAuth();
+    const view = gh(["pr", "view", "--json", "url"]);
+    if (view.status === 0) {
+        return query(parseOrCannotRun(() => parseView(view.stdout)), sized);
+    }
+    if (said(view.stderr).startsWith("no pull requests found")) {
+        return null;
+    }
+    throw new CannotRun(`gh pr view failed: ${said(view.stderr)}`, REMEDIES.read);
+}
+/** The default branch of the repository gh resolves from the current directory. */
+export function defaultBranch() {
+    const view = gh(["repo", "view", "--json", "defaultBranchRef"]);
+    if (view.status !== 0) {
+        throw new CannotRun(`gh repo view failed: ${said(view.stderr)}`, REMEDIES.read);
+    }
+    return parseOrCannotRun(() => parseDefaultBranch(view.stdout));
+}
+/** The time the decision reads: DW_SDLC_NOW, an ISO 8601 time a test sets, else the system clock. */
+export function now() {
+    const given = process.env.DW_SDLC_NOW?.trim();
+    if (given === undefined || given === "") {
+        return Date.now();
+    }
+    const time = Date.parse(given);
+    if (Number.isNaN(time)) {
+        throw new CannotRun(`DW_SDLC_NOW is ${JSON.stringify(given)}, not an ISO 8601 time`, REMEDIES.clock);
+    }
+    return time;
+}
 /** The state of `pr` once more, after an action the script performed on it: the same pull request. */
 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. */
@@ -106,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)}`);
@@ -154,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);
 }