dw-sdlc 0.12.1 → 0.14.0

package/dist/sweep-terminals.js

@@ -0,0 +1,262 @@
+// What a Sweep does with herdr terminals: it stops and removes only a Worker of its own whose turn has ended,
+// in a worktree that goes in the same Sweep or is already gone. docs/adr/0015 sets the bounds.
+import { existsSync, realpathSync } from "node:fs";
+import { isObject, parseObject } from "./json-text.js";
+import { shellLine } from "./pr/decide.js";
+import { CannotRun } from "./pr/read.js";
+import { worktreesOf } from "./sweep-trees.js";
+import { call, hcObject, isLive, Refusal, said, workersOf } from "./worker/herdr.js";
+import { lockVerdict } from "./worktree-lock.js";
+/** Statuses of a Worker that is not at the end of its turn, with how the Sweep says it. */
+const AT_WORK = {
+    working: "working",
+    blocked: "blocked, waiting for the dev",
+    unknown: "yet to report"
+};
+/** The address of the terminal the Sweep runs in, or undefined outside herdr. */
+export function sweepingTerminal() {
+    const id = process.env.HC_TERMINAL_ID;
+    return id === undefined || id === "" ? undefined : id;
+}
+function word(value) {
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+/**
+ * Each live terminal with the folder it works in, `hc get`'s foreground. An `hc get` that fails stops the
+ * Sweep, since a terminal in a folder it cannot see must not count as absent; one gone since the listing is dropped.
+ */
+function foldersOf(list) {
+    return list.flatMap((worker) => {
+        if (!isLive(worker)) {
+            return [{ ...worker, pid: undefined }];
+        }
+        const got = call("hc", ["get", worker.address, "--json"]);
+        if (got.status === 3) {
+            return [];
+        }
+        const parsed = got.status === 0 ? parseObject(got.stdout) : undefined;
+        if (parsed === undefined) {
+            throw new Refusal(`hc get ${worker.address} failed: ${got.status === 0 ? "its reply is no JSON object" : said(got)}`);
+        }
+        const { cwd, pid } = isObject(parsed.foreground) ? parsed.foreground : { cwd: undefined, pid: undefined };
+        const there = typeof cwd === "string" && cwd !== "" ? { ...worker, folder: cwd } : worker;
+        return [{ ...there, pid: typeof pid === "number" ? pid : undefined }];
+    });
+}
+/** The live terminals `hc ls` lists, each with the folder it works in. */
+function liveTerminals() {
+    const { terminals } = hcObject(["ls", "--json"]);
+    if (!Array.isArray(terminals)) {
+        throw new Refusal("hc ls answered no list of terminals", "check hc --version");
+    }
+    const places = new Map();
+    const listed = terminals.flatMap((entry) => {
+        const address = isObject(entry) ? word(entry.address) : undefined;
+        if (!isObject(entry) || address === undefined || typeof entry.cwd !== "string") {
+            throw new Refusal("hc ls answered a terminal without an address or a folder", "check hc --version");
+        }
+        places.set(address, word(entry.where));
+        const name = word(entry.name) ?? address;
+        return [{ name, address, state: "live", status: word(entry.status) ?? "unknown", folder: entry.cwd }];
+    });
+    return foldersOf(listed).map(({ name, address, folder }) => ({
+        name,
+        address,
+        folder,
+        place: places.get(address) ?? folder
+    }));
+}
+/**
+ * Reads herdr for the sweeping terminal `own`: its Workers, finished ones included, and the other live
+ * terminals. An `hc` that fails stops the Sweep, since a terminal it cannot see must not count as absent.
+ */
+export function readTerminals(own) {
+    try {
+        const workers = foldersOf(workersOf(own, true));
+        const live = liveTerminals();
+        const addresses = new Set(workers.map(({ address }) => address));
+        return {
+            own: live.find(({ address }) => address === own),
+            workers,
+            others: live.filter(({ address }) => address !== own && !addresses.has(address))
+        };
+    }
+    catch (error) {
+        if (error instanceof Refusal) {
+            throw new CannotRun(error.message, error.remedy ?? "check hc, then call again");
+        }
+        throw error;
+    }
+}
+function canonical(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+function isInside(folder, root) {
+    return folder === root || folder.startsWith(root.endsWith("/") ? root : `${root}/`);
+}
+/** The deepest of `roots` whose folder holds `folder`, or undefined. */
+function treeOf(folder, roots) {
+    const real = canonical(folder);
+    const holding = roots.filter((root) => isInside(folder, root) || isInside(real, canonical(root)));
+    return holding.toSorted((a, b) => b.length - a.length)[0];
+}
+/** A Worker whose terminal is live but whose folder is gone, with no worktree of `roots` around it, could commit nothing more. */
+export function workerWithoutFolder({ workers }, roots) {
+    const standing = roots.filter((root) => existsSync(root));
+    return workers.filter((worker) => isLive(worker) && !existsSync(worker.folder) && treeOf(worker.folder, standing) === undefined);
+}
+/** The terminals in the folder of each of `trees`; the main checkout `main` takes those not in a linked one. */
+export function holdersOf({ own, workers, others }, main, trees) {
+    const held = new Map();
+    const standing = [main, ...trees].filter((root) => existsSync(root));
+    const place = (folder, holder) => {
+        const tree = treeOf(folder, standing);
+        if (tree !== undefined && tree !== main) {
+            held.set(tree, [...(held.get(tree) ?? []), holder]);
+        }
+    };
+    if (own !== undefined) {
+        place(own.folder, { role: "own", terminal: own });
+    }
+    for (const terminal of others) {
+        place(terminal.folder, { role: "other", terminal });
+    }
+    for (const worker of workers) {
+        if (isLive(worker)) {
+            place(worker.folder, { role: "worker", worker });
+        }
+    }
+    return held;
+}
+/** How the Sweep says a Worker that is working, blocked or yet to report is, or undefined for one that is done. */
+export function atWork({ status }) {
+    return AT_WORK[status];
+}
+/** What the terminals in a worktree keep it for, or null when only Workers at the end of their turn are in it. */
+export function whyHeld(holders) {
+    const reasons = [];
+    const kills = [];
+    for (const holder of holders) {
+        if (holder.role === "own") {
+            reasons.push(`the terminal this Sweep runs in, ${holder.terminal.address}, is in it`);
+        }
+        else if (holder.role === "other") {
+            const { address, place } = holder.terminal;
+            reasons.push(`another session's terminal ${address} is in it, at ${place}`);
+            kills.push(shellLine(["hc", "kill", address]));
+        }
+        else {
+            const at = atWork(holder.worker);
+            if (at !== undefined) {
+                reasons.push(`its Worker ${holder.worker.name} (${holder.worker.address}) is ${at}`);
+            }
+        }
+    }
+    return reasons.length === 0
+        ? null
+        : { reason: reasons.join("; "), command: kills.length === 0 ? null : kills.join(" && ") };
+}
+/** The terminals of the Workers done in a worktree that goes, to stop and remove with it. */
+export function stopsOf(holders, tree) {
+    return holders.flatMap((holder) => holder.role === "worker"
+        ? [
+            {
+                kind: "terminal",
+                name: holder.worker.address,
+                reason: `Worker ${holder.worker.name} is ${holder.worker.status}: stopped, then removed with its worktree`,
+                stop: true,
+                tree
+            }
+        ]
+        : []);
+}
+/** Stops, if `item` asks, and removes its terminal; the words of the `hc` that refused, or undefined when it is gone. */
+export function removeTerminal(item) {
+    try {
+        if (item.stop === true) {
+            const killed = call("hc", ["kill", item.name]);
+            // 11: the terminal finished between the read and the stop.
+            if (killed.status !== 0 && killed.status !== 11) {
+                return `hc kill ${item.name} failed: ${said(killed)}`;
+            }
+        }
+        const removed = call("hc", ["rm", item.name]);
+        // 3: the terminal is gone already.
+        return removed.status === 0 || removed.status === 3 ? undefined : `hc rm ${item.name} failed: ${said(removed)}`;
+    }
+    catch (error) {
+        if (error instanceof Refusal) {
+            return error.message;
+        }
+        throw error;
+    }
+}
+/** The Workers no worktree of this Sweep decides: a finished one is removed, one whose folder is gone goes under the status rule. */
+export function outsideWorktrees(terminals, roots) {
+    const remove = [];
+    const keep = [];
+    for (const worker of terminals.workers.filter((one) => !isLive(one))) {
+        remove.push({ kind: "terminal", name: worker.address, reason: `Worker ${worker.name} is finished`, stop: false });
+    }
+    for (const worker of workerWithoutFolder(terminals, roots)) {
+        const at = atWork(worker);
+        if (at === undefined) {
+            const reason = `Worker ${worker.name} is ${worker.status} and its folder ${worker.folder} is gone: stopped, then removed`;
+            remove.push({ kind: "terminal", name: worker.address, reason, stop: true });
+        }
+        else {
+            keep.push({ name: worker.address, reason: `Worker ${worker.name} is ${at}, its folder ${worker.folder} is gone` });
+        }
+    }
+    return { remove, keep };
+}
+/** The command that stops or removes the terminal of a planned terminal by hand. */
+export function byHand(item) {
+    return item.stop === true
+        ? `${shellLine(["hc", "kill", item.name])}; ${shellLine(["hc", "rm", item.name])}`
+        : shellLine(["hc", "rm", item.name]);
+}
+/** The Worker in `holders` whose program is the process a live lock names, when it may be stopped. */
+export function lockHolder(pid, holders) {
+    for (const holder of holders) {
+        if (holder.role === "worker" && holder.worker.pid === pid && atWork(holder.worker) === undefined) {
+            return holder.worker;
+        }
+    }
+    return undefined;
+}
+/** The lock of the worktree at `path` read again once its Worker is stopped, given the program a moment to end. */
+export function lockAfterStop(root, path) {
+    let verdict = { state: "none" };
+    for (let attempt = 0; attempt < 15; attempt++) {
+        verdict = lockVerdict(path, worktreesOf(root).find((tree) => tree.path === path)?.lock);
+        if (verdict.state !== "stays") {
+            return verdict;
+        }
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+    }
+    return verdict;
+}
+/** The terminals in a worktree that stays which the Sweep lists as kept: Workers, and another session's terminals. */
+export function keptIn(holders, tree) {
+    return holders.flatMap((holder) => {
+        if (holder.role === "other") {
+            const { address, place } = holder.terminal;
+            const reason = `another session's terminal, in the worktree at ${tree}, at ${place}`;
+            return [{ name: address, reason, command: shellLine(["hc", "kill", address]) }];
+        }
+        if (holder.role === "worker") {
+            const { name, address, status } = holder.worker;
+            const at = atWork(holder.worker);
+            return [
+                { name: address, reason: `Worker ${name} is ${at ?? `${status}, but its worktree stays`}`, command: null }
+            ];
+        }
+        return [];
+    });
+}

package/dist/sweep-trees.d.ts

@@ -0,0 +1,17 @@
+/** `git <args>` at `root`, or a stop naming its problem. */
+export declare function must(root: string, args: string[]): string;
+export type Tree = {
+    path: string;
+    head: string;
+    branch: string | undefined;
+    lock: string | undefined;
+    prunable: boolean;
+};
+/** Every worktree of the repository, the main checkout first. */
+export declare function worktreesOf(root: string): Tree[];
+/** The files `git status` lists in the worktree at `path`, ignored ones aside, or why it cannot be read. */
+export declare function dirtyFiles(path: string): string[] | {
+    error: string;
+};
+/** The operation paused in the worktree at `path`: its git dir holds the state git resumes it from. */
+export declare function pausedOperation(path: string): string | undefined;

package/dist/sweep-trees.js

@@ -0,0 +1,72 @@
+// What a Sweep reads of a repository's linked worktrees: where each lies, what it has checked out, its lock,
+// the files that hold it and the operation paused in it.
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { repositoryFreeEnv } from "./git-env.js";
+import { CannotRun } from "./pr/read.js";
+import { asked, git } from "./working-tree.js";
+/** `git <args>` at `root`, or a stop naming its problem. */
+export function must(root, args) {
+    const result = git(root, args);
+    if ("error" in result) {
+        throw new CannotRun(result.error, "check the repository with git status");
+    }
+    return result.out;
+}
+/** Every worktree of the repository, the main checkout first. */
+export function worktreesOf(root) {
+    const trees = [];
+    let tree;
+    for (const line of must(root, ["worktree", "list", "--porcelain"]).split("\n")) {
+        if (line.startsWith("worktree ")) {
+            tree = { path: line.slice("worktree ".length), head: "", branch: undefined, lock: undefined, prunable: false };
+            trees.push(tree);
+        }
+        else if (tree !== undefined && line.startsWith("HEAD ")) {
+            tree.head = line.slice("HEAD ".length);
+        }
+        else if (tree !== undefined && line.startsWith("branch refs/heads/")) {
+            tree.branch = line.slice("branch refs/heads/".length);
+        }
+        else if (tree !== undefined && (line === "locked" || line.startsWith("locked "))) {
+            tree.lock = line.slice("locked".length).trim();
+        }
+        else if (tree !== undefined && (line === "prunable" || line.startsWith("prunable "))) {
+            tree.prunable = true;
+        }
+    }
+    return trees;
+}
+/** The files `git status` lists in the worktree at `path`, ignored ones aside, or why it cannot be read. */
+export function dirtyFiles(path) {
+    const args = ["-C", path, "status", "--porcelain=v1", "-z", "--untracked-files=all"];
+    const result = spawnSync("git", args, { encoding: "utf8", env: repositoryFreeEnv(), maxBuffer: 64 * 1024 * 1024 });
+    if (result.status !== 0) {
+        const said = result.stderr.split("\n").find((line) => line.trim() !== "");
+        return { error: `git status: ${said?.trim() ?? `exited ${result.status ?? "on a signal"}`}` };
+    }
+    const files = [];
+    const entries = result.stdout.split("\0").filter((entry) => entry !== "");
+    for (let index = 0; index < entries.length; index++) {
+        const entry = entries[index] ?? "";
+        files.push(entry.slice(3));
+        if (entry.startsWith("R") || entry.startsWith("C")) {
+            index++;
+        }
+    }
+    return files;
+}
+const OPERATIONS = [
+    ["rebase-merge", "rebase"],
+    ["rebase-apply", "rebase or am"],
+    ["MERGE_HEAD", "merge"],
+    ["CHERRY_PICK_HEAD", "cherry-pick"],
+    ["REVERT_HEAD", "revert"],
+    ["BISECT_LOG", "bisect"]
+];
+/** The operation paused in the worktree at `path`: its git dir holds the state git resumes it from. */
+export function pausedOperation(path) {
+    const dir = asked(path, ["rev-parse", "--absolute-git-dir"]);
+    return dir === undefined ? undefined : OPERATIONS.find(([file]) => existsSync(join(dir, file)))?.[1];
+}

package/dist/working-tree.d.ts

@@ -4,6 +4,8 @@ export declare function git(root: string, args: string[], index?: string): {
 } | {
     error: string;
 };
+/** `git <args>` at `root`, or undefined when it exits non-zero as a question answered no. */
+export declare function asked(root: string, args: string[]): string | undefined;
 /** The tree of the checkout at `root` and its git dir, or why it has none. */
 export declare function workingTree(root: string): {
     tree: string;

package/dist/working-tree.js

@@ -20,6 +20,11 @@ export function git(root, args, index) {
     const reason = result.error?.message ?? result.stderr.split("\n").find((line) => line.trim() !== "");
     return { error: `git ${args[0] ?? ""}: ${reason?.trim() ?? `exited ${result.status ?? "on a signal"}`}` };
 }
+/** `git <args>` at `root`, or undefined when it exits non-zero as a question answered no. */
+export function asked(root, args) {
+    const result = git(root, args);
+    return "out" in result ? result.out : undefined;
+}
 /**
  * The tree `git write-tree` hashes from a copy of the index after `git add -A` on it: the copy keeps the
  * stat cache, so only what changed is read again; identical content survives a commit, an amend or a

package/dist/worktree-lock.d.ts

@@ -0,0 +1,18 @@
+/** The process is gone: `held` is the reason to put back should the removal fail, `why` what the Sweep tells. */
+export type StaleLock = {
+    state: "stale";
+    held: string;
+    why: string;
+};
+/** A lock that keeps the worktree; `pid` is the live process a Claude Code lock names. */
+export type LockStays = {
+    state: "stays";
+    reason: string;
+    command: string | null;
+    pid?: number;
+};
+export type LockVerdict = {
+    state: "none";
+} | StaleLock | LockStays;
+/** What the lock of the worktree at `path`, held for `reason`, says about whether the Sweep may lift it. */
+export declare function lockVerdict(path: string, reason: string | undefined): LockVerdict;

package/dist/worktree-lock.js

@@ -0,0 +1,64 @@
+// What a worktree's lock means to a Sweep. Claude Code locks the worktree of a session with the reason
+// `claude session <name> (pid <N> start <time>)`, <time> as `ps -o lstart` writes it in UTC. Such a lock is
+// stale once no process N runs or N started at another time. Any other reason is the dev's to lift.
+import { spawnSync } from "node:child_process";
+import { shellLine } from "./pr/decide.js";
+const CLAUDE_LOCK = /^claude session .* \(pid (?<pid>\d{1,10}) start (?<start>.+)\)$/;
+const MAX_PID = 2 ** 31 - 1;
+const squeezed = (text) => text.trim().replace(/\s+/g, " ");
+/**
+ * Whether process `pid` runs and, if so, its start time as `ps` writes it in UTC and in local time, so a
+ * live lock is never taken for stale over a time zone.
+ */
+function runningOf(pid) {
+    try {
+        process.kill(pid, 0);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ESRCH") {
+            return { at: "gone" };
+        }
+    }
+    const starts = [{ TZ: "UTC" }, {}]
+        .map((zone) => {
+        const env = { ...process.env, LC_ALL: "C", ...zone };
+        const result = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8", env });
+        return result.status === 0 ? squeezed(result.stdout) : "";
+    })
+        .filter((start) => start !== "");
+    return starts.length === 0 ? { at: "unknown" } : { at: "running", starts };
+}
+/** What the lock of the worktree at `path`, held for `reason`, says about whether the Sweep may lift it. */
+export function lockVerdict(path, reason) {
+    if (reason === undefined) {
+        return { state: "none" };
+    }
+    const unlock = shellLine(["git", "worktree", "unlock", path]);
+    const { pid: pidText = "", start = "" } = CLAUDE_LOCK.exec(reason)?.groups ?? {};
+    const pid = Number(pidText);
+    if (pidText === "" || pid < 1 || pid > MAX_PID) {
+        const said = reason === "" ? "locked, with no reason given" : `locked: ${reason}`;
+        return { state: "stays", reason: said, command: unlock };
+    }
+    const now = runningOf(pid);
+    if (now.at === "gone") {
+        return { state: "stale", held: reason, why: `pid ${pid} is gone, no process runs under it` };
+    }
+    if (now.at === "unknown") {
+        return { state: "stays", reason: `locked: ${reason}; ps could not say whether pid ${pid} runs`, command: unlock };
+    }
+    if (!now.starts.includes(squeezed(start))) {
+        const started = now.starts[0] ?? "";
+        return {
+            state: "stale",
+            held: reason,
+            why: `pid ${pid} is gone, it now belongs to another process (started ${started} UTC)`
+        };
+    }
+    return {
+        state: "stays",
+        reason: `locked by a live Claude Code session: pid ${pid} is running (${reason})`,
+        command: null,
+        pid
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dw-sdlc",
-  "version": "0.12.1",
+  "version": "0.14.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": {