dw-sdlc 0.11.0 → 0.12.0

package/dist/worker/herdr.js

@@ -0,0 +1,115 @@
+// What the `worker` commands share: `hc` and `herdr-app` as child processes, the Lead a command acts for,
+// and the Workers herdr lists for it.
+import { spawnSync } from "node:child_process";
+import { isObject, parseObject } from "../json-text.js";
+/** What stops a `worker` command before it acts: exit 2, the problem and, when there is one, its remedy. */
+export class Refusal extends Error {
+    remedy;
+    constructor(message, remedy) {
+        super(message);
+        this.remedy = remedy;
+    }
+}
+/** The first line of a tool's output that says anything, or the exit it ended with. */
+export function said(called) {
+    const line = `${called.stderr}\n${called.stdout}`.split("\n").find((text) => text.trim() !== "");
+    return line?.trim() ?? `exited ${called.status}`;
+}
+/** `tool args` as a child process; a tool that is not on PATH stops the command. */
+export function call(tool, args) {
+    const result = spawnSync(tool, args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    if (result.error !== undefined) {
+        if ("code" in result.error && result.error.code === "ENOENT") {
+            throw new Refusal(`${tool} is not on PATH`, "install herdr, or run the command in a terminal herdr started");
+        }
+        throw result.error;
+    }
+    return { status: result.status ?? 1, stdout: result.stdout, stderr: result.stderr };
+}
+/** The JSON object `hc <args>` prints; a failing call or a reply that is no object stops the command. */
+export function hcObject(args) {
+    const called = call("hc", args);
+    if (called.status !== 0) {
+        throw new Refusal(`hc ${args[0] ?? ""} failed: ${said(called)}`);
+    }
+    const parsed = parseObject(called.stdout);
+    if (parsed === undefined) {
+        throw new Refusal(`hc ${args[0] ?? ""} answered something that is no JSON object`, "check hc --version");
+    }
+    return parsed;
+}
+/** What an error says, whatever was thrown. */
+export function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Reports a `Refusal` of `command` on stderr and answers exit 2; any other error is a bug and goes on up. */
+export function refuse(command, error) {
+    if (!(error instanceof Refusal)) {
+        throw error;
+    }
+    process.stderr.write(`dw-sdlc ${command}: ${error.message}${error.remedy === undefined ? "" : ` — ${error.remedy}`}\n`);
+    return 2;
+}
+/** The option `flag` as a whole number from `min`, `fallback` when the command line leaves it out. */
+export function wholeNumber(flag, value, fallback, min) {
+    const number = value === undefined ? fallback : Number(value);
+    return Number.isInteger(number) && number >= min
+        ? number
+        : { error: `${flag} takes a whole number from ${min}, not ${JSON.stringify(value)}` };
+}
+/** The terminal the command runs in, which is the Lead of the Workers it starts or reads. */
+export function lead() {
+    const id = process.env.HC_TERMINAL_ID;
+    if (id === undefined || id === "") {
+        throw new Refusal("outside herdr: $HC_TERMINAL_ID is not set", "run it in a terminal herdr started, where the Lead has an address");
+    }
+    return id;
+}
+/** Whether herdr still runs the Worker's terminal; the one test of it every command shares. */
+export function isLive(worker) {
+    return worker.state === "live";
+}
+/**
+ * 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 function workingFolders(workers) {
+    return workers.map((worker) => {
+        if (!isLive(worker)) {
+            return worker;
+        }
+        const got = call("hc", ["get", worker.address, "--json"]);
+        const foreground = got.status === 0 ? parseObject(got.stdout)?.foreground : undefined;
+        const cwd = isObject(foreground) ? foreground.cwd : undefined;
+        return typeof cwd === "string" && cwd !== "" ? { ...worker, folder: cwd } : worker;
+    });
+}
+function word(value) {
+    return typeof value === "string" ? value : undefined;
+}
+/** The Workers `lead` started, in the order herdr lists them; `all` adds the finished ones. */
+export function workersOf(leadId, all) {
+    const listing = hcObject(["ls", "--json", ...(all ? ["--all"] : []), "--label", "role=worker"]);
+    const { terminals } = listing;
+    if (!Array.isArray(terminals)) {
+        throw new Refusal("hc ls answered no list of terminals", "check hc --version");
+    }
+    return terminals.flatMap((entry) => {
+        if (!isObject(entry) || entry.parent !== leadId) {
+            return [];
+        }
+        const { address, state, cwd } = entry;
+        if (typeof address !== "string" || typeof state !== "string" || typeof cwd !== "string") {
+            throw new Refusal("hc ls answered a terminal without an address, state or folder", "check hc --version");
+        }
+        const status = state === "finished" ? "finished" : (word(entry.status) ?? "unknown");
+        return [{ name: word(entry.name) ?? address, address, state, status, folder: cwd }];
+    });
+}
+/** A table of rows, every column but the last padded to its widest cell and two spaces apart. */
+export function table(rows) {
+    const widths = (rows[0] ?? []).map((_, column) => Math.max(...rows.map((row) => (row[column] ?? "").length)));
+    return rows
+        .map((row) => row.map((cell, column) => (column === row.length - 1 ? cell : cell.padEnd((widths[column] ?? 0) + 2))).join(""))
+        .join("\n");
+}

package/dist/worker/tabs.d.ts

@@ -0,0 +1,9 @@
+/** What naming a tab came to: `kept` says why it stays numbered, a warning and never a failure. */
+export type Named = "renamed" | {
+    kept: string;
+};
+/**
+ * Names the tab holding `address`, reading `herdr-app ls` again for up to `boundSeconds`, since the window
+ * lists a terminal's tab a moment after `hc run` returns.
+ */
+export declare function nameTab(address: string, name: string, boundSeconds: number): Promise<Named>;

package/dist/worker/tabs.js

@@ -0,0 +1,62 @@
+// The tab of a Worker's terminal in the herdr window: `hc run` with a `herdr.space` label opens one that herdr
+// numbers, and `herdr-app` names it.
+import { setTimeout as sleep } from "node:timers/promises";
+import { isObject, parseObject } from "../json-text.js";
+import { call, Refusal, said } from "./herdr.js";
+/** The tabs `herdr-app ls` shows, each with the addresses of its terminals. */
+function tabsOf() {
+    const listed = call("herdr-app", ["ls"]);
+    if (listed.status !== 0) {
+        throw new Refusal(`herdr-app ls failed: ${said(listed)}`);
+    }
+    const parsed = parseObject(listed.stdout);
+    if (parsed === undefined) {
+        throw new Refusal("herdr-app ls answered no JSON object");
+    }
+    const spaces = Array.isArray(parsed.spaces) ? parsed.spaces : [];
+    return spaces
+        .flatMap((space) => (isObject(space) && Array.isArray(space.tabs) ? space.tabs : []))
+        .flatMap((tab) => {
+        if (!isObject(tab) || typeof tab.id !== "string" || !Array.isArray(tab.terminals)) {
+            return [];
+        }
+        const terminals = tab.terminals.flatMap((entry) => isObject(entry) && typeof entry.terminal === "string" ? [entry.terminal] : []);
+        return [{ id: tab.id, terminals }];
+    });
+}
+/** The `error` of a herdr-app reply `{ "error": "..." }`. */
+function errorOf(stdout) {
+    const parsed = parseObject(stdout);
+    return typeof parsed?.error === "string" ? parsed.error : undefined;
+}
+/** How long `nameTab` waits between two reads of `herdr-app ls`. */
+const RETRY_MS = 250;
+/**
+ * Names the tab holding `address`, reading `herdr-app ls` again for up to `boundSeconds`, since the window
+ * lists a terminal's tab a moment after `hc run` returns.
+ */
+export async function nameTab(address, name, boundSeconds) {
+    try {
+        const deadline = Date.now() + boundSeconds * 1000;
+        const find = () => tabsOf().find((candidate) => candidate.terminals.includes(address));
+        let tab = find();
+        while (tab === undefined && Date.now() < deadline) {
+            await sleep(RETRY_MS);
+            tab = find();
+        }
+        if (tab === undefined) {
+            return { kept: `the tab of ${address} is not in herdr-app ls within ${boundSeconds} s, so it keeps herdr's name` };
+        }
+        const renamed = call("herdr-app", ["do", "tab.rename", "--id", tab.id, "--name", name]);
+        if (renamed.status !== 0) {
+            return { kept: `herdr-app could not rename the tab of ${address}: ${errorOf(renamed.stdout) ?? said(renamed)}` };
+        }
+        return "renamed";
+    }
+    catch (error) {
+        if (error instanceof Refusal) {
+            return { kept: `the tab of ${address} keeps herdr's name: ${error.message}` };
+        }
+        throw error;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dw-sdlc",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "The Gate and the agentic config of a repository: the dw-sdlc bin with the Gate, the setup, the doctor, the config check, the Sync and setup of References, and the Ship script that drives a pull request to merged; the resolver of the config's layers, its JSON Schema and the validator that reads it.",
   "license": "MIT",
   "repository": {