dw-sdlc 0.11.0 → 0.12.0

package/dist/agentic-config.d.ts

@@ -36,7 +36,7 @@ export type PrConfig = {
     reviewCommand: string;
 };
 /** Claude Code's effort levels, lowest first: what `worker.effort` takes. */
-declare const WORKER_EFFORTS: readonly ["low", "medium", "high", "xhigh", "max"];
+export declare const WORKER_EFFORTS: readonly ["low", "medium", "high", "xhigh", "max"];
 export type WorkerEffort = (typeof WORKER_EFFORTS)[number];
 /** How a Worker's Claude Code session starts: the words that start it, its model and its effort. */
 export type WorkerConfig = {

package/dist/agentic-config.js

@@ -14,7 +14,7 @@ export const COMMIT_CONVENTIONS = ["ticket-key", "conventional"];
 /** The Review depths, strictest first: what the dev's `--review` names. */
 export const REVIEW_DEPTHS = ["full", "light", "off"];
 /** Claude Code's effort levels, lowest first: what `worker.effort` takes. */
-const WORKER_EFFORTS = ["low", "medium", "high", "xhigh", "max"];
+export const WORKER_EFFORTS = ["low", "medium", "high", "xhigh", "max"];
 /** Strictest value first; the local override may only move towards the front. */
 export const STRICTNESS = {
     forcePush: ["deny", "ask", "lease"],

package/dist/cli.js

@@ -12,6 +12,9 @@ import * as recap from "./commands/recap.js";
 import * as referencesSetup from "./commands/references-setup.js";
 import * as referencesSync from "./commands/references-sync.js";
 import * as setup from "./commands/setup.js";
+import * as workerLs from "./commands/worker-ls.js";
+import * as workerReport from "./commands/worker-report.js";
+import * as workerStart from "./commands/worker-start.js";
 const COMMANDS = new Map([
     ["gate", gate],
     ["check", check],
@@ -23,7 +26,10 @@ const COMMANDS = new Map([
     ["references setup", referencesSetup],
     ["pr ship", prShip],
     ["pr reviewed", prReviewed],
-    ["recap", recap]
+    ["recap", recap],
+    ["worker start", workerStart],
+    ["worker ls", workerLs],
+    ["worker report", workerReport]
 ]);
 function usage() {
     const width = Math.max(...[...COMMANDS.keys()].map((name) => name.length)) + 2;

package/dist/commands/doctor.d.ts

@@ -40,11 +40,6 @@ export type Inputs = {
 };
 /** Claude Code's config dir: `$CLAUDE_CONFIG_DIR` when set, the way Claude Code reads it, else `~/.claude`. */
 export declare function claudeConfigDir(env: Record<string, string | undefined>, home: string): string;
-/** The marketplace Claude Code registers this repository under, the plugin in it, and the package the plugin links to. */
-export declare const MARKETPLACE = "dw-sdlc";
-export declare const PLUGIN = "sdlc";
-export declare const PLUGIN_ID = "sdlc@dw-sdlc";
-export declare const PACKAGE = "dw-sdlc";
 /** rtk find passes -exec through verbatim from this release; before it, `rtk find … -exec` exits 1. */
 export declare const RTK_FIND_EXEC_FIXED = "0.46.0";
 export declare const PNPM_MINIMUM_RELEASE_AGE = 10080;

package/dist/commands/doctor.js

@@ -7,19 +7,12 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { findRepository, resolveConfig } from "../agentic-config.js";
-import { EXACT_VERSION, parseCatalog, parsePins } from "../pins.js";
+import { checkPackage, checkPlugin, checkSessions, parseJson, runningPluginRoot, versionBefore } from "../doctor-plugins.js";
+import { isObject } from "../json-text.js";
 /** Claude Code's config dir: `$CLAUDE_CONFIG_DIR` when set, the way Claude Code reads it, else `~/.claude`. */
 export function claudeConfigDir(env, home) {
     return env.CLAUDE_CONFIG_DIR ?? join(home, ".claude");
 }
-/** The marketplace Claude Code registers this repository under, the plugin in it, and the package the plugin links to. */
-export const MARKETPLACE = "dw-sdlc";
-export const PLUGIN = "sdlc";
-export 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}`;
-export const PACKAGE = "dw-sdlc";
 /** rtk find passes -exec through verbatim from this release; before it, `rtk find … -exec` exits 1. */
 export const RTK_FIND_EXEC_FIXED = "0.46.0";
 export const PNPM_MINIMUM_RELEASE_AGE = 10080;
@@ -37,20 +30,6 @@ export const realProbe = {
         return (result.stdout ?? "").trim().split("\n")[0] ?? "";
     }
 };
-function isObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function parseJson(text) {
-    if (text === undefined) {
-        return undefined;
-    }
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        return undefined;
-    }
-}
 function checkJq(probe) {
     const { status, stdout } = probe.run("jq", ["--version"]);
     if (status === 0) {
@@ -58,151 +37,6 @@ function checkJq(probe) {
     }
     return { name: "jq", level: "FAIL", detail: "missing: every guard is silent without it. brew install jq" };
 }
-/** 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. */
-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;
-}
-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. */
-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.
- */
-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}` };
-}
 /** Every hook command string in a settings file, whatever the event and matcher. */
 function hookCommands(settings) {
     if (!isObject(settings) || !isObject(settings.hooks)) {
@@ -241,18 +75,6 @@ export function rtkExcludes(toml) {
     }
     return [...(match[1] ?? "").matchAll(/"([^"]*)"/g)].map((entry) => entry[1] ?? "");
 }
-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;
-}
 // The plugin's rtk-rewrite.sh is the one wiring of `rtk hook claude`; a second one in the user
 // settings rewrites again, and in a linked worktree that copy is what the isolation check refuses.
 function checkRtk(probe, home, claude) {
@@ -299,6 +121,14 @@ function checkRtk(probe, home, claude) {
         detail: `rtk ${version} behind the plugin's rewrite hook; exclude_commands: ${excludes.join(", ") || "none"}`
     };
 }
+/** herdr's `hc` in the agent's shell, which a Lead starts its Workers through; a machine may go without it. */
+function checkHc(probe) {
+    const hc = probe.shell("command -v hc");
+    if (hc === "") {
+        return { name: "hc", level: "INFO", detail: "no hc on PATH, so no /sdlc-delegate: install herdr to run Workers" };
+    }
+    return { name: "hc", level: "PASS", detail: `${hc}, so a Lead can start Workers` };
+}
 function checkSafeChain(probe) {
     const binary = probe.shell("command -v safe-chain");
     if (binary === "") {
@@ -381,6 +211,7 @@ export function diagnose(inputs) {
         checkPlugin(probe, claude),
         checkPackage(probe, claude, inputs.config === undefined ? undefined : inputs.root),
         checkSessions(probe, claude),
+        checkHc(probe),
         checkRtk(probe, home, claude),
         checkSafeChain(probe),
         checkPnpmReleaseAge(probe, home),

package/dist/commands/pr-ship.js

@@ -4,7 +4,7 @@
 import { parseArgs } from "node:util";
 import { repositoryRoot, resolveConfig, REVIEW_DEPTHS } from "../agentic-config.js";
 import { decide, declaredPolicy, devCommand, hostArgs, isScriptAction, lineOf, readyToMerge, REVIEW, shellLine } from "../pr/decide.js";
-import { CannotRun, carriesBase, gh, namedProblem, now, read, readAgain, said } from "../pr/read.js";
+import { CannotRun, carriesBase, gh, namedProblem, now, read, readAgain, said, withBehind } from "../pr/read.js";
 export const summary = "decide the Action one pull request needs next, as a line or JSON";
 const USAGE = `Usage: dw-sdlc pr ship [<n>] [-R owner/name] [--merge] [--review full|light|off] [--dry-run] [--json] [--verbose]
 
@@ -13,7 +13,9 @@ is omitted, and answers the Action it needs next: the status, the action, whose
 The script performs its own Actions, each at most once and then reads again: it updates a branch
 behind its base, marks a draft ready once nothing else holds it back, and squash merges a pull
 request ready to merge under pr.merge auto in .ai/agentic.config.json or with --merge for this call;
-under ask, the default, it parks with the merge command. A head without a ${REVIEW} success
+under ask, the default, it parks with the merge command. A branch is behind when the compare of
+the base with the head shows the head lacks a commit of the base, or GitHub reports BEHIND, which
+it does only under a rule that a branch be up to date. A head without a ${REVIEW} success
 gets the Review depth --review names for this call, else pr.review: under full the agent reviews it
 with the command pr.reviewCommand names, /code-review by default; under light one sdlc-reviewer
 subagent reads the diff; under off the script posts the success itself, its description saying
@@ -143,7 +145,7 @@ function handedOver(pr, policy, answer, action, reason) {
 function ship(cli, policy) {
     // Only pr.review auto routes the depth from the changes, so only it reads them.
     const sized = policy.review.depth === "auto";
-    let pr = read(cli, "pr ship", sized);
+    let pr = withBehind(read(cli, "pr ship", sized));
     const performed = [];
     // The head each Action ran on.
     const postedOn = new Map();
@@ -177,7 +179,7 @@ function ship(cli, policy) {
         const record = { action, command, exit: status, ...(message === "" ? {} : { stderr: message }) };
         postedOn.set(action, before.head);
         try {
-            pr = readAgain(pr, sized);
+            pr = withBehind(readAgain(pr, sized));
             performed.push({ ...record, ok: TOOK[action](before, pr) });
         }
         catch (error) {

package/dist/commands/recap.js

@@ -6,6 +6,7 @@ import { parseArgs } from "node:util";
 import { findRepository, mainCheckout, resolveConfig } from "../agentic-config.js";
 import { decide, declaredPolicy, labelOf, lineOf } from "../pr/decide.js";
 import { CannotRun, defaultBranch, now, readBranch } from "../pr/read.js";
+import { isLive, Refusal, workersOf, workingFolders } from "../worker/herdr.js";
 import { git } from "../working-tree.js";
 export const summary = "the facts a Recap rests on and whether the session can be closed";
 const USAGE = `Usage: dw-sdlc recap [--json]
@@ -21,7 +22,9 @@ The session cannot be closed over any of these:
   a commit pushed nowhere or only part of the way;
   an open pull request, whatever its Action;
   commits on top of the base that no pull request holds. The default branch and a branch
-  guardrails.protectedBranches names need no pull request.
+  guardrails.protectedBranches names need no pull request;
+  a live Worker this session started as a Lead, in a terminal herdr started ($HC_TERMINAL_ID): its
+  report has no one to reach once the Lead is gone. A Worker whose turn ended is still live.
 
 A pull request closed without merging merges nothing, and a detached HEAD names no pull request. There a
 commit counts as pushed only on a remote branch, and the command asks the remote which branches still
@@ -30,8 +33,9 @@ stand. A branch force-pushed since the last fetch can still read as holding it,
 A linked worktree is a reason beside the verdict, never against it: the session cannot remove the
 directory it runs in.
 
-One line a fact, or one document with --json. Needs an authenticated gh and a remote it can read. A
-detached HEAD or a repository with no remote asks gh nothing, and the pull request fact says so.
+One line a fact, or one document with --json. Needs an authenticated gh and a remote it can read, and in
+herdr hc on PATH. A detached HEAD or a repository with no remote asks gh nothing, and the pull request
+fact says so; outside herdr the workers fact says so.
 
 Exit 0 the session can be closed, 1 it cannot, 2 when it cannot run.`;
 function plural(howMany, word) {
@@ -96,6 +100,25 @@ function readLocal(root) {
         worktree: { linked: mainCheckout(root) !== undefined, path: root }
     };
 }
+/** The live Workers this session started as a Lead, each in the folder it works in; null outside herdr. */
+function liveWorkers() {
+    const lead = process.env.HC_TERMINAL_ID;
+    if (lead === undefined || lead === "") {
+        return null;
+    }
+    try {
+        return workingFolders(workersOf(lead, false).filter(isLive));
+    }
+    catch (error) {
+        if (error instanceof Refusal) {
+            throw new CannotRun(error.message, error.remedy ?? "check hc ls, then call again");
+        }
+        throw error;
+    }
+}
+function workersText(workers) {
+    return workers.map((worker) => `${worker.name} (${worker.status})`).join(", ");
+}
 /** The current branch's pull request and the Action the Ship script's decision gives it, or null. */
 function readShipped(root) {
     // An invalid config layer resolves to ask and full, as in the Ship script.
@@ -105,14 +128,12 @@ function readShipped(root) {
 }
 /**
  * The tracking refs, as `--remotes` names them, that the remote contradicts, which only a fetch would show:
- * a branch it no longer has, its `HEAD`, and the session's own branch where it moved. Any other branch that
- * moved, such as the base, counts as holding what it held; plugins/sdlc-sessions/README.md says why.
+ * a branch it no longer has, its `HEAD`, and the session's own branch where it moved. A remote out of reach
+ * holds nothing; any other moved branch counts as before (plugins/sdlc-sessions/README.md says why).
  */
 function staleTracking(root, { branch, upstream }) {
     return remotesOf(root).flatMap((remote) => {
-        const live = new Map(must(root, ["ls-remote", "--heads", remote])
-            .split("\n")
-            .map((line) => {
+        const live = new Map((asked(root, ["ls-remote", "--heads", remote]) ?? "").split("\n").map((line) => {
             const [oid = "", ref = ""] = line.split("\t");
             return [ref.replace("refs/heads/", `${remote}/`), oid];
         }));
@@ -196,7 +217,7 @@ function cleanReason(askedGh) {
         : "nothing is uncommitted or unpushed; gh was not asked";
     return { id: "clean", blocks: false, text };
 }
-function reasonsOf(local, shipped, ahead, orphaned, askedGh) {
+function reasonsOf(local, { shipped, ahead, orphaned, askedGh, workers }) {
     const all = [];
     if (local.paused !== null) {
         all.push({ id: "paused", blocks: true, text: `a ${local.paused} is paused` });
@@ -218,6 +239,10 @@ function reasonsOf(local, shipped, ahead, orphaned, askedGh) {
     if (shipped !== null) {
         all.push(pullRequestReason(shipped));
     }
+    if (workers !== null && workers.length > 0) {
+        const text = `${plural(workers.length, "live Worker")}: ${workersText(workers)}`;
+        all.push({ id: "workers", blocks: true, text });
+    }
     if (!all.some((reason) => reason.blocks)) {
         all.unshift(cleanReason(askedGh));
     }
@@ -234,7 +259,13 @@ function closeOf(reasons) {
     const line = `Close the session: ${verdict}, because ${shown.map((reason) => reason.text).join("; ")}`;
     return { verdict, line, reasons };
 }
-function linesOf(local, shipped, askedGh, line) {
+function workersLine(workers) {
+    if (workers === null) {
+        return "not in herdr";
+    }
+    return workers.length === 0 ? "none live" : `${workers.length} live: ${workersText(workers)}`;
+}
+function linesOf(local, { shipped, askedGh, workers }, line) {
     const none = askedGh ? "none" : "gh not asked";
     return [
         `branch: ${local.branch ?? "detached HEAD"}`,
@@ -242,6 +273,7 @@ function linesOf(local, shipped, askedGh, line) {
         `upstream: ${local.upstream ?? "none"}, ${local.unpushed} unpushed`,
         `pull request: ${shipped === null ? none : `${shipped.pr.url} ${lineOf(shipped.answer)}`}`,
         `worktree: ${local.worktree.linked ? `linked at ${local.worktree.path}` : "main checkout"}`,
+        `workers: ${workersLine(workers)}`,
         line
     ].join("\n");
 }
@@ -276,14 +308,20 @@ function report(json) {
     // An open pull request can still take the head, and a commit-less repository has nothing to merge.
     const nothingToMerge = held || shipped?.pr.state === "OPEN" || head === null;
     const ahead = asksGh && !nothingToMerge ? aheadOf(root, branch, shipped) : null;
-    const orphaned = orphanedOf(root, read, shipped, held);
-    const close = closeOf(reasonsOf(local, shipped, ahead, orphaned, asksGh));
+    const facts = {
+        shipped,
+        ahead,
+        orphaned: orphanedOf(root, read, shipped, held),
+        askedGh: asksGh,
+        workers: liveWorkers()
+    };
+    const close = closeOf(reasonsOf(local, facts));
     const pullRequest = shipped === null
         ? null
         : { url: shipped.pr.url, number: shipped.pr.number, state: shipped.pr.state, ...shipped.answer };
     const output = json
-        ? JSON.stringify({ ...local, askedGh: asksGh, pullRequest, close }, null, 2)
-        : linesOf(local, shipped, asksGh, close.line);
+        ? JSON.stringify({ ...local, askedGh: asksGh, pullRequest, workers: facts.workers, close }, null, 2)
+        : linesOf(local, facts, close.line);
     process.stdout.write(`${output}\n`);
     return close.verdict === "yes" ? 0 : 1;
 }

package/dist/commands/worker-ls.d.ts

@@ -0,0 +1,2 @@
+export declare const summary = "list the Workers this Lead started and their states";
+export declare function run(argv: string[]): number;

package/dist/commands/worker-ls.js

@@ -0,0 +1,53 @@
+// `dw-sdlc worker ls`: the Workers the calling Lead started, with the state herdr holds them in.
+import { parseArgs } from "node:util";
+import { describe, lead, refuse, table, workersOf, workingFolders } from "../worker/herdr.js";
+export const summary = "list the Workers this Lead started and their states";
+const USAGE = `Usage: dw-sdlc worker ls [--json]
+
+Lists the Workers the calling Lead started (terminals labelled role=worker whose parent is this
+terminal): name, address, herdr's state, status and folder. A live Worker's folder is the one it works
+in, its worktree, as hc get reports it; a finished one, or one herdr cannot tell it for, shows the folder
+it was launched in. The status is what the Worker reports, one of idle, working, done, blocked, error, or
+finished once its terminal has ended; unknown before it reports. herdr's done means a turn ended, not the
+task: the Worker's Recap says whether the task is done. Finished Workers stay listed until they are
+removed with hc rm.
+
+Needs a terminal herdr started ($HC_TERMINAL_ID) and hc on PATH. One line a Worker, or one JSON array
+with --json.
+
+Exit 0 listed, 2 when it cannot run.`;
+export function run(argv) {
+    let json;
+    try {
+        const { values } = parseArgs({
+            args: argv,
+            options: { help: { type: "boolean", short: "h" }, json: { type: "boolean" } }
+        });
+        if (values.help === true) {
+            process.stdout.write(`${USAGE}\n`);
+            return 0;
+        }
+        json = values.json === true;
+    }
+    catch (error) {
+        process.stderr.write(`dw-sdlc worker ls: ${describe(error)}\n\n${USAGE}\n`);
+        return 2;
+    }
+    try {
+        const workers = workingFolders(workersOf(lead(), true));
+        if (json) {
+            process.stdout.write(`${JSON.stringify(workers, null, 2)}\n`);
+        }
+        else if (workers.length === 0) {
+            process.stdout.write("no Workers\n");
+        }
+        else {
+            const rows = workers.map((worker) => [worker.name, worker.address, worker.state, worker.status, worker.folder]);
+            process.stdout.write(`${table([["NAME", "ADDRESS", "STATE", "STATUS", "FOLDER"], ...rows])}\n`);
+        }
+        return 0;
+    }
+    catch (error) {
+        return refuse("worker ls", error);
+    }
+}

package/dist/commands/worker-report.d.ts

@@ -0,0 +1,2 @@
+export declare const summary = "deliver a Recap to the Lead, retrying while it is blocked";
+export declare function run(argv: string[]): Promise<number>;

package/dist/commands/worker-report.js

@@ -0,0 +1,117 @@
+// `dw-sdlc worker report`: delivers a Worker's Recap to its Lead, and keeps trying while the Lead is blocked.
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { parseArgs } from "node:util";
+import { call, describe, lead, refuse, Refusal, said, wholeNumber } from "../worker/herdr.js";
+export const summary = "deliver a Recap to the Lead, retrying while it is blocked";
+const USAGE = `Usage: dw-sdlc worker report --to <lead> --recap <file> [--attempts <n>] [--interval <seconds>]
+
+Sends the Recap in <file> to the Lead's terminal with hc send. A Recap of one short line goes as itself;
+anything longer goes as the absolute path of its file, which the Lead reads.
+
+hc send exits 9 when the Lead is blocked on a dialog. The command then waits --interval seconds (default
+60) and sends again, up to --attempts sends (default 30), and exits 1 when the Lead is still blocked. It
+never passes --force: typing into a blocked Lead may answer its dialog. Any other refusal of hc send ends
+it at once with exit 1.
+
+Needs a terminal herdr started ($HC_TERMINAL_ID) and hc on PATH.
+
+Exit 0 delivered, 1 not delivered, 2 when it cannot run.`;
+/** `hc send` exits with this when the target is blocked on a permission or a question. */
+const BLOCKED = 9;
+const DEFAULT_ATTEMPTS = 30;
+const DEFAULT_INTERVAL = 60;
+/** The longest Recap that goes as itself, in characters; a longer one goes as a path. */
+const SHORT = 300;
+function parseCli(argv) {
+    try {
+        const { values } = parseArgs({
+            args: argv,
+            options: {
+                help: { type: "boolean", short: "h" },
+                to: { type: "string" },
+                recap: { type: "string" },
+                attempts: { type: "string" },
+                interval: { type: "string" }
+            }
+        });
+        if (values.help === true) {
+            return "help";
+        }
+        const { to, recap } = values;
+        if (to === undefined || to === "") {
+            return { error: "name the Lead's terminal: --to <lead>" };
+        }
+        if (recap === undefined) {
+            return { error: "name the Recap file: --recap <file>" };
+        }
+        const attempts = wholeNumber("--attempts", values.attempts, DEFAULT_ATTEMPTS, 1);
+        const interval = wholeNumber("--interval", values.interval, DEFAULT_INTERVAL, 0);
+        if (typeof attempts === "object") {
+            return attempts;
+        }
+        if (typeof interval === "object") {
+            return interval;
+        }
+        return { to, recap, attempts, interval };
+    }
+    catch (error) {
+        return { error: describe(error) };
+    }
+}
+/** What to send for the Recap in `file`: the Recap itself when it is one short line, else the file's path. */
+function messageFor(file) {
+    const path = resolve(file);
+    let text;
+    try {
+        text = readFileSync(path, "utf8").trim();
+    }
+    catch (error) {
+        throw new Refusal(`cannot read the Recap ${file}: ${describe(error)}`);
+    }
+    if (text === "") {
+        throw new Refusal(`the Recap ${file} is empty`);
+    }
+    return { message: text.includes("\n") || text.length > SHORT ? path : text, path };
+}
+async function report({ to, recap, attempts, interval }) {
+    lead();
+    const { message, path } = messageFor(recap);
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        const sent = call("hc", ["send", to, message]);
+        if (sent.status === 0) {
+            process.stdout.write(`reported to ${to}\n`);
+            return 0;
+        }
+        if (sent.status !== BLOCKED) {
+            process.stderr.write(`dw-sdlc worker report: hc send failed: ${said(sent)} — the Recap stays at ${path}\n`);
+            return 1;
+        }
+        if (attempt === attempts) {
+            break;
+        }
+        process.stderr.write(`dw-sdlc worker report: ${to} is blocked; waiting ${interval} s (attempt ${attempt} of ${attempts})\n`);
+        await sleep(interval * 1000);
+    }
+    process.stderr.write(`dw-sdlc worker report: gave up after ${attempts} attempts: ${to} is still blocked — ` +
+        `the Recap stays at ${path}; say so on your screen so the dev can open ${to}\n`);
+    return 1;
+}
+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 report: ${cli.error}\n\n${USAGE}\n`);
+        return 2;
+    }
+    try {
+        return await report(cli);
+    }
+    catch (error) {
+        return refuse("worker report", error);
+    }
+}

package/dist/commands/worker-start.d.ts

@@ -0,0 +1,2 @@
+export declare const summary = "start a Worker on a Brief in a herdr terminal";
+export declare function run(argv: string[]): Promise<number>;