dw-sdlc 0.20.0 → 0.21.1

package/dist/commands/setup.js

@@ -1,17 +1,18 @@
 // `dw-sdlc setup` sets a repository and this machine up for the sdlc plugin: the files its USAGE names,
 // each written only when its content would change, so a run is safe to repeat. Existing content is
 // merged, never replaced: other keys stay, and a file that is not a JSON object is refused.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join, relative } from "node:path";
+import { join, relative } from "node:path";
 import { pathToFileURL } from "node:url";
-import { parseArgs } from "node:util";
-import { COMMIT_CONVENTIONS, COMMITTED_FILE, DEFAULT_GUARDRAILS, LOCAL_FILE, SCHEMA_FILE, STRICTNESS, inferConfig, repositoryRoot, resolveConfig, schemaId, validateDocument } from "../agentic-config.js";
-import { exec } from "../exec.js";
+import { COMMIT_CONVENTIONS, COMMITTED_FILE, DEFAULT_GUARDRAILS, LOCAL_FILE, SCHEMA_FILE, STRICTNESS, inferConfig, mainCheckout, repositoryRoot, resolveConfig, schemaId, validateDocument } from "../agentic-config.js";
+import { readArgs, rootDir, usageError } from "../cannot-run.js";
+import { gitDirs } from "../git.js";
 import { isObject, parseObject, render } from "../json-text.js";
 import { withGate, withPackage } from "../setup-gate.js";
 import { GLOBAL_DENY, LEASE_RULE, RETIRED_DENY, repositoryDeny } from "../setup-rules.js";
 import { keptWorker, pinnedWorker } from "../setup-worker.js";
+import { stepLines, Writer } from "../setup-writer.js";
 export const summary = "adopt the Gate where asked, and write this machine's local config layer, the git excludes and the permission rules";
 const USAGE = `Usage: dw-sdlc setup [--root <dir>] [--home <dir>]
        [--convention <preset>] [--force-push deny|ask|lease] [--commit-on-protected deny|allow]
@@ -53,11 +54,6 @@ const PLUGIN = "sdlc";
 const PACKAGE_LINK = "dw-sdlc";
 /** The two plugins the sdlc plugin replaced, which the marketplace does not list (ADR 0010). */
 const RETIRED_PLUGINS = ["guardrails", "references"].map((name) => `${name}@${MARKETPLACE}`);
-/** A read-only git command, the one thing the setup runs in the repository. */
-function git(root, args) {
-    const result = exec("git", ["-C", root, ...args]);
-    return result.status === 0 ? result.stdout.trim() : undefined;
-}
 /** The committed layer when it is valid; an absent or invalid one sets nothing, as the resolver drops it. */
 function committedConfig(root) {
     const path = join(root, COMMITTED_FILE);
@@ -188,41 +184,6 @@ function union(existing, additions) {
 function readJson(path) {
     return existsSync(path) ? (parseObject(readFileSync(path, "utf8")) ?? "invalid") : undefined;
 }
-class Writer {
-    steps = [];
-    dryRun;
-    constructor(dryRun) {
-        this.dryRun = dryRun;
-    }
-    /** Writes when the text differs from what is on disk; records the outcome under `label`, with what the write does. */
-    put(label, path, text, detail) {
-        const current = existsSync(path) ? readFileSync(path, "utf8") : undefined;
-        if (current === text) {
-            this.steps.push({ file: label, outcome: "unchanged" });
-            return;
-        }
-        if (!this.dryRun) {
-            mkdirSync(dirname(path), { recursive: true });
-            writeFileSync(path, text);
-        }
-        this.steps.push(detail === undefined ? { file: label, outcome: "wrote" } : { file: label, outcome: "wrote", detail });
-    }
-    refuse(label, detail) {
-        this.steps.push({ file: label, outcome: "refused", detail });
-    }
-    /** The step's file as `change` leaves it: written, unchanged or refused. */
-    apply(label, path, change) {
-        if ("refusal" in change) {
-            this.refuse(label, change.refusal);
-        }
-        else {
-            this.put(label, path, change.text, change.detail);
-        }
-    }
-    byHand(label, detail) {
-        this.steps.push({ file: label, outcome: "by hand", detail });
-    }
-}
 /** The enabledPlugins edit settings that still enable a retired plugin need; none where they enable neither. */
 function enabledPluginsEdit(settings) {
     const enabled = isObject(settings.enabledPlugins) ? settings.enabledPlugins : {};
@@ -238,19 +199,16 @@ function enabledPluginsEdit(settings) {
 }
 /**
  * Where the repository's files live: the main checkout for a linked worktree, since every worktree reads
- * the local config from there when it has none of its own, and Claude Code reads the local settings there.
+ * the local config from there when it has none of its own, and Claude Code reads the local settings there;
+ * the excludes go to the git dir every worktree shares.
  */
-function mainCheckout(root) {
-    const common = git(root, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
-    if (common === undefined) {
-        return { checkout: root, gitDir: join(root, ".git") };
-    }
-    return { checkout: dirname(common), gitDir: common };
+function repositoryFiles(root) {
+    return { checkout: mainCheckout(root) ?? root, gitDir: gitDirs(root)?.commonDir ?? join(root, ".git") };
 }
 export function setup(options) {
     const writer = new Writer(options.dryRun);
     const root = repositoryRoot(options.root);
-    const { checkout, gitDir } = mainCheckout(root);
+    const { checkout, gitDir } = repositoryFiles(root);
     const claudeDir = options.claudeDir ?? join(options.home, ".claude");
     // 1. The local config: inference, the convention (the flag's, else the file's pin), the guardrails block
     // the file holds with the flags' pins. A layer of `$schema` alone tells the guards nothing: not written.
@@ -266,13 +224,13 @@ export function setup(options) {
         const { worker, detail } = pinnedWorker(keptWorker(existing), options.path ?? process.env.PATH);
         const local = localConfig(checkout, claudeDir, convention, pinned.guardrails, worker);
         if (Object.keys(local).length === 1 && (localCurrent === undefined || sameContent(existing, local))) {
-            writer.steps.push({ file: LOCAL_FILE, outcome: "skipped", detail: "the layer would hold only $schema" });
+            writer.skip(LOCAL_FILE, "the layer would hold only $schema");
         }
         else if (localCurrent !== undefined && !sameContent(existing, local) && !options.force) {
             writer.refuse(LOCAL_FILE, "exists with other content; pass --force to overwrite it");
         }
         else {
-            writer.put(LOCAL_FILE, localPath, render(local), detail);
+            writer.apply(LOCAL_FILE, localPath, { text: render(local), detail });
         }
     }
     // 2. The exclude entries, appended to whatever the file holds: they keep both local files out of git
@@ -283,11 +241,11 @@ export function setup(options) {
     const missing = [LOCAL_FILE, ".claude/settings.local.json"].filter((entry) => !lines.includes(entry));
     const excludeLabel = relative(checkout, excludePath).startsWith("..") ? excludePath : relative(checkout, excludePath);
     if (missing.length === 0) {
-        writer.steps.push({ file: excludeLabel, outcome: "unchanged" });
+        writer.apply(excludeLabel, excludePath, { text: excludeText });
     }
     else {
         const separator = excludeText === "" || excludeText.endsWith("\n") ? "" : "\n";
-        writer.put(excludeLabel, excludePath, excludeText + separator + missing.join("\n") + "\n");
+        writer.apply(excludeLabel, excludePath, { text: excludeText + separator + missing.join("\n") + "\n" });
     }
     // 3. The repository's deny rules, the backstop for the hooks where jq is missing, merged into the main
     // checkout's local settings.
@@ -301,7 +259,7 @@ export function setup(options) {
         const permissions = isObject(settings.permissions) ? settings.permissions : {};
         const deny = union(permissions.deny, repositoryDeny(root)).filter((rule) => !RETIRED_DENY.includes(rule));
         settings.permissions = { ...permissions, deny };
-        writer.put(".claude/settings.local.json", localSettingsPath, render(settings));
+        writer.apply(".claude/settings.local.json", localSettingsPath, { text: render(settings) });
     }
     // 4. The user file, under $CLAUDE_CONFIG_DIR when it is set: the lease exception, "$defaults" kept, and
     // the irreversible non-git set.
@@ -320,7 +278,7 @@ export function setup(options) {
         settings.autoMode = { ...autoMode, allow };
         const permissions = isObject(settings.permissions) ? settings.permissions : {};
         settings.permissions = { ...permissions, deny: union(permissions.deny, GLOBAL_DENY) };
-        writer.put(userLabel, userPath, render(settings));
+        writer.apply(userLabel, userPath, { text: render(settings) });
         const edit = enabledPluginsEdit(settings);
         if (edit !== undefined) {
             writer.byHand(userLabel, edit);
@@ -341,48 +299,39 @@ export function setup(options) {
     }
     return writer.steps;
 }
-function fail(message, code) {
-    console.error(`guardrails:setup: ${message}`);
-    process.exit(code);
-}
 export function run(argv) {
-    let values;
-    try {
-        values = parseArgs({
-            args: argv,
-            options: {
-                help: { type: "boolean", short: "h" },
-                root: { type: "string" },
-                home: { type: "string" },
-                convention: { type: "string" },
-                "force-push": { type: "string" },
-                "commit-on-protected": { type: "string" },
-                "add-package": { type: "boolean" },
-                force: { type: "boolean" },
-                "dry-run": { type: "boolean" }
-            }
-        }).values;
-    }
-    catch (error) {
-        fail(`${error instanceof Error ? error.message : String(error)}\n\n${USAGE}`, 2);
-    }
+    const { values } = readArgs({
+        args: argv,
+        options: {
+            help: { type: "boolean", short: "h" },
+            root: { type: "string" },
+            home: { type: "string" },
+            convention: { type: "string" },
+            "force-push": { type: "string" },
+            "commit-on-protected": { type: "string" },
+            "add-package": { type: "boolean" },
+            force: { type: "boolean" },
+            "dry-run": { type: "boolean" }
+        }
+    }, USAGE);
     if (values.help === true) {
         console.log(USAGE);
         return 0;
     }
     if (values.convention !== undefined && !isConvention(values.convention)) {
-        fail(`--convention must be ${COMMIT_CONVENTIONS.join(" or ")}, not '${values.convention}'\n\n${USAGE}`, 2);
+        throw usageError(`--convention must be ${COMMIT_CONVENTIONS.join(" or ")}, not '${values.convention}'`, USAGE);
     }
     const forcePush = values["force-push"];
     if (forcePush !== undefined && !isForcePush(forcePush)) {
-        fail(`--force-push must be ${STRICTNESS.forcePush.join(", ")}, not '${forcePush}'\n\n${USAGE}`, 2);
+        throw usageError(`--force-push must be ${STRICTNESS.forcePush.join(", ")}, not '${forcePush}'`, USAGE);
     }
     const commitOnProtected = values["commit-on-protected"];
     if (commitOnProtected !== undefined && !isCommitOnProtected(commitOnProtected)) {
-        fail(`--commit-on-protected must be ${STRICTNESS.commitOnProtected.join(" or ")}, not '${commitOnProtected}'\n\n${USAGE}`, 2);
+        const allowed = STRICTNESS.commitOnProtected.join(" or ");
+        throw usageError(`--commit-on-protected must be ${allowed}, not '${commitOnProtected}'`, USAGE);
     }
     const steps = setup({
-        root: values.root ?? process.cwd(),
+        root: rootDir(values.root),
         home: values.home ?? homedir(),
         claudeDir: values.home === undefined ? process.env.CLAUDE_CONFIG_DIR : undefined,
         force: values.force === true,
@@ -392,9 +341,8 @@ export function run(argv) {
         commitOnProtected,
         addPackage: values["add-package"] === true
     });
-    for (const step of steps) {
-        const verb = step.outcome === "wrote" && values["dry-run"] === true ? "would write" : step.outcome;
-        console.log(`${verb.padEnd(11)} ${step.file}${step.detail === undefined ? "" : ` — ${step.detail}`}`);
+    for (const line of stepLines(steps, values["dry-run"] === true)) {
+        console.log(line);
     }
     return steps.some((step) => step.outcome === "refused") ? 1 : 0;
 }

package/dist/commands/sweep.js

@@ -1,16 +1,15 @@
 // `dw-sdlc sweep`: removes each linked worktree whose whole set passes and each Landed local branch.
 // docs/adr/0015 sets its bounds: it runs from the main checkout, never forces and never writes to a remote.
 import { existsSync } from "node:fs";
-import { parseArgs } from "node:util";
 import { findRepository, mainCheckout, resolveConfig } from "../agentic-config.js";
-import { exec, SLOW_LIMIT_MS } from "../exec.js";
-import { repositoryFreeEnv } from "../git-env.js";
-import { isCommitLanded, isLanded } from "../landed.js";
-import { shellLine } from "../pr/decide.js";
-import { CannotRun } from "../pr/read.js";
-import { byHand, holdersOf, keptIn, lockAfterStop, lockHolder, outsideWorktrees, readTerminals, removeTerminal, stopsOf, sweepingTerminal, whyHeld } from "../sweep-terminals.js";
-import { branchesOf, dirtyFiles, pausedOperation, switchOff, worktreesOf } from "../sweep-trees.js";
-import { asked, git } from "../working-tree.js";
+import { CannotRun, readArgs, usageError } from "../cannot-run.js";
+import { SLOW_LIMIT_MS } from "../exec.js";
+import { asked, git } from "../git.js";
+import { isCommitLanded } from "../landed.js";
+import { shellLine } from "../shell-line.js";
+import { apply } from "../sweep-removal.js";
+import { holdersOf, keptIn, lockHolder, outsideWorktrees, readTerminals, stopsOf, sweepingTerminal, whyHeld } from "../sweep-terminals.js";
+import { branchesOf, forcedDelete, heldBranch, switchOff, tipOf, unlockCommand, whyUnclean, worktreesOf } from "../sweep-trees.js";
 import { lockVerdict } from "../worktree-lock.js";
 export const summary = "removes Landed branches and clean worktrees whose work has landed, names what it keeps";
 const USAGE = `Usage: dw-sdlc sweep [--dry-run] [--json]
@@ -26,11 +25,15 @@ config, else the branch origin/HEAD names) and removes, never forcing:
 It keeps, and names with the reason and the command to run yourself:
   a worktree that fails the set: the files that hold it with the forced removal, the paused operation, the
   lock's reason with git worktree unlock, a live Claude Code lock named by its pid, a HEAD that is not Landed;
-  the default branch, the base branch, a protected branch and a branch a kept worktree has checked out; a
+  the default branch, the base branch, a protected branch and a branch a kept worktree has checked out or a
+  rebase paused there works on; a
   Landed branch the main checkout has checked out, clean and with nothing paused, with git switch to the base;
   a branch whose work is on no commit of the base, with the forced delete.
+It reads each worktree again just before it goes, its Worker stopped: one whose HEAD, branch or lock changed
+since it was judged, or that holds a file or a paused operation by then, stays. A branch goes only while it
+points at the commit judged Landed; one that moved since stays.
 It never changes anything on a remote: the fetch only writes remote-tracking refs. A removal git refuses is
-kept with git's words, and the sweep goes on.
+kept with git's words, one that outlives its time limit with the limit it hit, and the sweep goes on.
 
 In herdr ($HC_TERMINAL_ID set) it reads, with hc, the Workers of this session, the terminals whose parent is
 this one, and every other live terminal. A Worker whose status is none of working, blocked or yet to report
@@ -50,24 +53,13 @@ ends the Sweep with exit 2 before anything is removed.
 
 Exit 0 nothing is kept but the default, the base or a protected branch, 1 something else is, 2 when it
 cannot run: in a linked worktree, with no base to read, when the fetch fails or when hc fails in herdr.`;
-function forcedDelete(branch) {
-    return shellLine(["git", "branch", "-D", branch]);
-}
-/** The forced removal; git wants --force twice for a worktree still locked. */
-function forcedRemoval(path, locked = false) {
-    return shellLine(["git", "worktree", "remove", "--force", ...(locked ? ["--force"] : []), path]);
-}
 function fetchOrigin(root) {
     if (asked(root, ["remote", "get-url", "origin"]) === undefined) {
         return;
     }
-    const result = exec("git", ["-C", root, "fetch", "--quiet", "origin"], {
-        env: repositoryFreeEnv(),
-        limitMs: SLOW_LIMIT_MS
-    });
-    if (result.status !== 0) {
-        const said = result.stderr.split("\n").find((line) => line.trim() !== "");
-        throw new CannotRun(`git fetch origin failed: ${said?.trim() ?? `exited ${result.status}`}`, "check the network, then call again");
+    const fetched = git(root, ["fetch", "--quiet", "origin"], { limitMs: SLOW_LIMIT_MS });
+    if ("error" in fetched) {
+        throw new CannotRun(`git fetch origin failed: ${fetched.said}`, "check the network, then call again");
     }
 }
 /** The branch refs/remotes/origin/HEAD names, if it names one of origin. */
@@ -106,22 +98,12 @@ function whyTreeStays(root, baseRef, tree, lock, holders) {
         const prune = shellLine(["git", "worktree", "prune"]);
         return {
             reason: "its folder is gone",
-            command: lock.state === "stale" ? `${shellLine(["git", "worktree", "unlock", path])} && ${prune}` : prune
+            command: lock.state === "stale" ? `${unlockCommand(path)} && ${prune}` : prune
         };
     }
-    const operation = pausedOperation(path);
-    if (operation !== undefined) {
-        return { reason: `a ${operation} is paused in it`, command: null };
-    }
-    const files = dirtyFiles(path);
-    if ("error" in files) {
-        return { reason: files.error, command: null };
-    }
-    if (files.length > 0) {
-        return {
-            reason: `modified or untracked: ${files.join(", ")}`,
-            command: forcedRemoval(path, lock.state === "stale")
-        };
+    const unclean = whyUnclean(path, lock.state === "stale");
+    if (unclean !== null) {
+        return unclean;
     }
     if (!isCommitLanded(root, baseRef, tree.head)) {
         const at = tree.branch === undefined ? `its detached HEAD ${tree.head.slice(0, 9)}` : `its HEAD on ${tree.branch}`;
@@ -144,8 +126,8 @@ function stays(branch, { head, baseBranch, protectedBranches, held }) {
     if (protectedBranches.includes(branch)) {
         return standing("a protected branch");
     }
-    const path = held.get(branch);
-    return path === undefined ? null : { reason: `checked out in the worktree at ${path}`, command: null, dev: true };
+    const hold = held.get(branch);
+    return hold === undefined ? null : { reason: hold.reason, command: null, dev: true };
 }
 /** Fetches origin, then sorts each linked worktree, local branch and Worker's terminal into what goes and what stays. */
 function judge(root, terminals) {
@@ -170,9 +152,10 @@ function judge(root, terminals) {
     });
     const staying = verdicts.filter(({ why }) => why !== null).map(({ tree }) => tree);
     const held = new Map();
-    for (const { path, branch } of [checkout, ...staying]) {
-        if (branch !== undefined) {
-            held.set(branch, path);
+    for (const tree of [checkout, ...staying]) {
+        const hold = heldBranch(tree);
+        if (hold !== undefined) {
+            held.set(hold.branch, { path: tree.path, reason: hold.reason });
         }
     }
     const footing = {
@@ -190,12 +173,15 @@ function judge(root, terminals) {
         }
         judged.add(name);
         const why = stays(name, footing);
-        const off = why?.dev === true && held.get(name) === checkout.path ? switchOff(root, base, name) : null;
+        const off = why?.dev === true && held.get(name)?.path === checkout.path ? switchOff(root, base, name) : null;
         if (why !== null) {
             kept.push({ kind: "branch", name, ...why, ...off });
+            return;
         }
-        else if (isLanded(root, base.ref, name)) {
-            removed.push({ kind: "branch", name, reason: `Landed on ${baseName}` });
+        // The tip read once, so the branch goes only while it still points at the commit judged Landed.
+        const tip = tipOf(root, name);
+        if (tip !== undefined && isCommitLanded(root, base.ref, tip)) {
+            removed.push({ kind: "branch", name, reason: `Landed on ${baseName}`, at: tip });
         }
         else {
             const reason = `its work is on no commit of ${baseName} since it forked`;
@@ -221,6 +207,7 @@ function judge(root, terminals) {
             kind: "worktree",
             name: tree.path,
             reason,
+            at: tree.head,
             ...(tree.branch === undefined ? {} : { holds: tree.branch }),
             ...(lock.state === "stale" ? { stale: lock } : {}),
             ...(workerLock === undefined ? {} : { workerLock })
@@ -232,86 +219,6 @@ function judge(root, terminals) {
     branchesOf(root).forEach(judgeBranch);
     return { base: baseName, removed, kept };
 }
-/** Removes `item`; the item kept when git refuses it, with git's words, or undefined once it is gone. */
-function removal(root, item, heldBy, unstopped) {
-    const refused = (reason, command) => ({
-        kind: item.kind,
-        name: item.name,
-        reason,
-        command,
-        dev: true
-    });
-    if (item.kind === "terminal") {
-        const failed = removeTerminal(item);
-        if (failed === undefined) {
-            return undefined;
-        }
-        if (item.tree !== undefined) {
-            unstopped.set(item.tree, `its Worker's terminal ${item.name} stays: ${failed}`);
-        }
-        return refused(failed, byHand(item));
-    }
-    if (item.kind === "worktree") {
-        const refusedWith = (reason, command) => {
-            if (item.holds !== undefined) {
-                heldBy.set(item.holds, item.name);
-            }
-            return refused(reason, command);
-        };
-        const unstoppable = unstopped.get(item.name);
-        if (unstoppable !== undefined) {
-            return refusedWith(unstoppable, null);
-        }
-        if (item.workerLock !== undefined) {
-            const now = lockAfterStop(root, item.name);
-            if (now.state === "stays") {
-                return refusedWith(`its Worker's terminal was stopped, but ${now.reason}`, now.command);
-            }
-            if (now.state === "stale") {
-                item.stale = now;
-            }
-            delete item.workerLock;
-        }
-        if (item.stale !== undefined) {
-            const lifted = git(root, ["worktree", "unlock", "--", item.name]);
-            if ("error" in lifted) {
-                return refusedWith(lifted.error, shellLine(["git", "worktree", "unlock", item.name]));
-            }
-        }
-        const result = git(root, ["worktree", "remove", "--", item.name]);
-        if (!("error" in result)) {
-            return undefined;
-        }
-        const relocked = item.stale === undefined
-            ? undefined
-            : git(root, ["worktree", "lock", "--reason", item.stale.held, "--", item.name]);
-        const lost = relocked !== undefined && "error" in relocked ? `; its lock could not be put back: ${relocked.error}` : "";
-        return refusedWith(`${result.error}${lost}`, forcedRemoval(item.name, item.stale !== undefined));
-    }
-    const path = heldBy.get(item.name);
-    if (path !== undefined) {
-        return refused(`checked out in the worktree at ${path}`, null);
-    }
-    const result = git(root, ["branch", "-D", "--", item.name]);
-    return "error" in result ? refused(result.error, forcedDelete(item.name)) : undefined;
-}
-/** Removes each item judged to go, in order; a refused worktree keeps the branch it holds as well. */
-function apply({ base, removed, kept }, root) {
-    const gone = [];
-    const refused = [];
-    const heldBy = new Map();
-    const unstopped = new Map();
-    for (const item of removed) {
-        const stayed = removal(root, item, heldBy, unstopped);
-        if (stayed === undefined) {
-            gone.push(item);
-        }
-        else {
-            refused.push(stayed);
-        }
-    }
-    return { base, removed: gone, kept: [...kept, ...refused] };
-}
 /** The removed items as the Sweep tells them: a stale lock lifted comes just before its worktree. */
 function shownOf(removed) {
     return removed.flatMap(({ kind, name, reason, stale, workerLock }) => {
@@ -340,24 +247,19 @@ function linesOf({ dryRun, terminalsRead, removed, kept }) {
     return [...(out.length === 0 ? ["nothing to sweep"] : out), ...note].join("\n");
 }
 function parseCli(argv) {
-    try {
-        const { values, positionals } = parseArgs({
-            args: argv,
-            allowPositionals: true,
-            options: {
-                help: { type: "boolean", short: "h" },
-                json: { type: "boolean" },
-                "dry-run": { type: "boolean" }
-            }
-        });
-        if (positionals.length > 0 && values.help !== true) {
-            return { error: `it takes no argument, not ${JSON.stringify(positionals[0])}` };
+    const { values, positionals } = readArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            help: { type: "boolean", short: "h" },
+            json: { type: "boolean" },
+            "dry-run": { type: "boolean" }
         }
-        return { help: values.help === true, json: values.json === true, dryRun: values["dry-run"] === true };
-    }
-    catch (error) {
-        return { error: error instanceof Error ? error.message : String(error) };
+    }, USAGE);
+    if (positionals.length > 0 && values.help !== true) {
+        throw usageError(`it takes no argument, not ${JSON.stringify(positionals[0])}`, USAGE);
     }
+    return { help: values.help === true, json: values.json === true, dryRun: values["dry-run"] === true };
 }
 function sweep(json, dryRun) {
     const root = findRepository(process.cwd());
@@ -384,22 +286,9 @@ function sweep(json, dryRun) {
 }
 export function run(argv) {
     const cli = parseCli(argv);
-    if ("error" in cli) {
-        process.stderr.write(`dw-sdlc sweep: ${cli.error}\n\n${USAGE}\n`);
-        return 2;
-    }
     if (cli.help) {
         process.stdout.write(`${USAGE}\n`);
         return 0;
     }
-    try {
-        return sweep(cli.json, cli.dryRun);
-    }
-    catch (error) {
-        if (error instanceof CannotRun) {
-            process.stderr.write(`dw-sdlc sweep: ${error.message} — ${error.remedy}\n`);
-            return 2;
-        }
-        throw error;
-    }
+    return sweep(cli.json, cli.dryRun);
 }

package/dist/commands/worker-ls.js

@@ -1,6 +1,6 @@
 // `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";
+import { readArgs } from "../cannot-run.js";
+import { lead, 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]
 
@@ -17,37 +17,21 @@ 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;
+    const { values } = readArgs({ args: argv, options: { help: { type: "boolean", short: "h" }, json: { type: "boolean" } } }, USAGE);
+    if (values.help === true) {
+        process.stdout.write(`${USAGE}\n`);
+        return 0;
     }
-    catch (error) {
-        process.stderr.write(`dw-sdlc worker ls: ${describe(error)}\n\n${USAGE}\n`);
-        return 2;
+    const workers = workingFolders(workersOf(lead(), true));
+    if (values.json === true) {
+        process.stdout.write(`${JSON.stringify(workers, null, 2)}\n`);
     }
-    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;
+    else if (workers.length === 0) {
+        process.stdout.write("no Workers\n");
     }
-    catch (error) {
-        return refuse("worker ls", error);
+    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;
 }