dw-sdlc 0.21.0 → 0.21.1

package/dist/commands/recap.js

@@ -1,16 +1,15 @@
 // `dw-sdlc recap`: the facts a Recap rests on and whether the session can be closed, read from git and
 // gh. It writes nothing: the Action of the branch's pull request is the Ship script's decision, read.
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import { parseArgs } from "node:util";
 import { findRepository, mainCheckout, resolveConfig } from "../agentic-config.js";
+import { CannotRun, readArgs, usageError } from "../cannot-run.js";
+import { asked, must } from "../git.js";
+import { pausedIn } from "../paused-operation.js";
 import { decide, declaredPolicy, labelOf, lineOf } from "../pr/decide.js";
-import { CannotRun, defaultBranch, now, readBranch } from "../pr/read.js";
-import { holds, upstreamName } from "../pr/upstream.js";
+import { defaultBranch, ghReads, now } from "../pr/read.js";
+import { holds } from "../pr/upstream.js";
 import { READY_LABEL, readNext } from "../recap-next.js";
 import { rollup } from "../recap-primitives.js";
-import { isLive, Refusal, workersOf, workingFolders } from "../worker/herdr.js";
-import { asked, git } from "../working-tree.js";
+import { isLive, workersOf, workingFolders } from "../worker/herdr.js";
 export const summary = "the facts a Recap rests on, whether the session can be closed and what could come next";
 const USAGE = `Usage: dw-sdlc recap [--json]
 
@@ -54,14 +53,6 @@ Exit 0 the session can be closed, 1 it cannot, 2 when it cannot run.`;
 function plural(howMany, word) {
     return `${howMany} ${word}${howMany === 1 ? "" : "s"}`;
 }
-/** `git <args>` at `root`; what it prints, or a stop naming its problem. */
-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;
-}
 function count(root, args) {
     return Number(must(root, ["rev-list", "--count", ...args]));
 }
@@ -77,20 +68,6 @@ function upstreamOf(root, branch) {
     const [ref = "", track] = must(root, ["for-each-ref", `--format=${format}`, `refs/heads/${branch}`]).split(" ");
     return ref.startsWith(prefix) && track !== "[gone]" ? ref.slice(prefix.length) : null;
 }
-/** Git's own record of each paused operation, in the git directory a linked worktree keeps apart. */
-const PAUSES = [
-    { record: "rebase-merge", name: "rebase" },
-    { record: "rebase-apply", name: "rebase or am" },
-    { record: "MERGE_HEAD", name: "merge" },
-    { record: "CHERRY_PICK_HEAD", name: "cherry-pick" },
-    { record: "REVERT_HEAD", name: "revert" },
-    { record: "sequencer", name: "cherry-pick or revert" },
-    { record: "BISECT_LOG", name: "bisect" }
-];
-function pausedIn(root) {
-    const gitDir = must(root, ["rev-parse", "--absolute-git-dir"]);
-    return PAUSES.find(({ record }) => existsSync(join(gitDir, record)))?.name ?? null;
-}
 function readLocal(root) {
     const branch = asked(root, ["symbolic-ref", "--quiet", "--short", "HEAD"]) ?? null;
     const head = asked(root, ["rev-parse", "--verify", "--quiet", "HEAD"]) ?? null;
@@ -104,7 +81,7 @@ function readLocal(root) {
         uncommitted: status === "" ? 0 : status.split("\n").length,
         upstream,
         unpushed: head === null ? 0 : count(root, pushed),
-        paused: pausedIn(root),
+        paused: pausedIn(must(root, ["rev-parse", "--absolute-git-dir"])) ?? null,
         worktree: { linked: mainCheckout(root) !== undefined, path: root }
     };
 }
@@ -118,28 +95,18 @@ function liveWorkers() {
         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;
+        throw error instanceof CannotRun ? error.orRemedy("check hc ls, then call again") : 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. The one
- * found by the upstream's name counts only when it holds the head: a branch started from another tracks
- * that branch until its first push.
- */
-function readShipped(root, branch, head) {
+/** This checkout's pull request and the Action the Ship script's decision gives it, or null when it has none. */
+function readShipped(root) {
     // An invalid config layer resolves to ask and full, as in the Ship script.
     const policy = declaredPolicy(resolveConfig(root).config.pr);
-    const found = readBranch(policy.review.depth === "auto", head === null ? undefined : upstreamName(root, branch));
-    if (found === null || (found.byUpstream && !holds(found.pr, head))) {
-        return null;
-    }
-    return { pr: found.pr, answer: decide(found.pr, now(), policy) };
+    const found = ghReads(policy.review.depth === "auto").checkout(root);
+    return "problem" in found ? null : { pr: found, answer: decide(found, now(), policy) };
 }
 /**
  * The tracking refs, as `--remotes` names them, that the remote contradicts, which only a fetch would show:
@@ -309,20 +276,15 @@ function linesOf(local, { shipped, askedGh, workers, next }, primitives, line) {
     ].join("\n");
 }
 function parseCli(argv) {
-    try {
-        const { values, positionals } = parseArgs({
-            args: argv,
-            allowPositionals: true,
-            options: { help: { type: "boolean", short: "h" }, json: { type: "boolean" } }
-        });
-        if (positionals.length > 0 && values.help !== true) {
-            return { error: `it takes no argument, not ${JSON.stringify(positionals[0])}` };
-        }
-        return { help: values.help === true, json: values.json === true };
-    }
-    catch (error) {
-        return { error: error instanceof Error ? error.message : String(error) };
-    }
+    const { values, positionals } = readArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { help: { type: "boolean", short: "h" }, json: { type: "boolean" } }
+    }, 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 };
 }
 function report(json) {
     const root = findRepository(process.cwd());
@@ -333,7 +295,7 @@ function report(json) {
     const { branch, head } = read;
     // A detached HEAD names no branch for gh to look up, and a repository with no remote has no GitHub.
     const asksGh = branch !== null && remotesOf(root).length > 0;
-    const shipped = asksGh ? readShipped(root, branch, head) : null;
+    const shipped = asksGh ? readShipped(root) : null;
     const held = shipped !== null && holds(shipped.pr, head);
     const local = standing(root, read, shipped, held);
     // An open pull request can still take the head, and a commit-less repository has nothing to merge.
@@ -369,22 +331,9 @@ function report(json) {
 }
 export function run(argv) {
     const cli = parseCli(argv);
-    if ("error" in cli) {
-        process.stderr.write(`dw-sdlc recap: ${cli.error}\n\n${USAGE}\n`);
-        return 2;
-    }
     if (cli.help) {
         process.stdout.write(`${USAGE}\n`);
         return 0;
     }
-    try {
-        return report(cli.json);
-    }
-    catch (error) {
-        if (error instanceof CannotRun) {
-            process.stderr.write(`dw-sdlc recap: ${error.message} — ${error.remedy}\n`);
-            return 2;
-        }
-        throw error;
-    }
+    return report(cli.json);
 }

package/dist/commands/references-setup.js

@@ -1,13 +1,14 @@
 // `dw-sdlc references setup` sets a repository up to declare References: the files its USAGE names,
 // each written only when it would change. A list gains the entries it lacks at its end; the one removal
 // is a `references` key moving out of the agentic config. A file it cannot read as expected is refused.
-import { existsSync, lstatSync, mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { parseArgs } from "node:util";
-import { exec } from "../exec.js";
+import { existsSync, readFileSync, symlinkSync } from "node:fs";
+import { join } from "node:path";
+import { repositoryRoot } from "../agentic-config.js";
+import { readArgs, rootDir } from "../cannot-run.js";
 import { parseObject, removeKey, render } from "../json-text.js";
 import { CONFIG, REFERENCES_FILE, leftoverKey, leftoverProblem, parseReferences, readFile } from "../references-key.js";
 import { renderBlock, withBlock } from "../router-block.js";
+import { stepLines, Writer } from "../setup-writer.js";
 const ROUTER = "references/AGENTS.md";
 /** A symlink to the Router, so Claude Code loads it. */
 const ROUTER_LINK = "references/CLAUDE.md";
@@ -42,47 +43,6 @@ and leaves the config; with the file there too, both stay and the step is refuse
 written only when it would change, and the text around the Router's table never; --dry-run reports
 without writing, and --check does the same and exits 1 when a file would change. Prints one line
 per file. Exit 1 when a file is refused, 2 on a bad argument.`;
-function messageOf(error) {
-    return error instanceof Error ? error.message : String(error);
-}
-function fail(message) {
-    console.error(`references:setup: ${message}`);
-    process.exit(2);
-}
-class Writer {
-    steps = [];
-    root;
-    dryRun;
-    constructor(root, dryRun) {
-        this.root = root;
-        this.dryRun = dryRun;
-    }
-    record(file, changed, write) {
-        if (changed && !this.dryRun) {
-            const path = join(this.root, file);
-            mkdirSync(dirname(path), { recursive: true });
-            write(path);
-        }
-        this.steps.push({ file, outcome: changed ? "wrote" : "unchanged" });
-    }
-    /** The text `change` gives `file`, from what `file` holds now; written when the two differ. */
-    put(file, change) {
-        const path = join(this.root, file);
-        const current = existsSync(path) ? readFileSync(path, "utf8") : undefined;
-        const next = change(current);
-        if ("refusal" in next) {
-            this.steps.push({ file, outcome: "refused", detail: next.refusal });
-            return;
-        }
-        this.record(file, next.text !== current, (target) => {
-            writeFileSync(target, next.text);
-        });
-    }
-    /** `file`, made by `make` when nothing sits at its path, a dangling symlink included; never replaced. */
-    create(file, make) {
-        this.record(file, lstatSync(join(this.root, file), { throwIfNoEntry: false }) === undefined, make);
-    }
-}
 /** The settings with claudeMdExcludes holding every glob of EXCLUDES, those it lacks appended. */
 function withExcludes(current) {
     if (current === undefined) {
@@ -157,59 +117,51 @@ function source(root) {
             : { text: removeKey(current, "references") }
     };
 }
-/** The repository `dir` sits in, or `dir` itself outside one. */
-function toplevel(dir) {
-    const result = exec("git", ["-C", dir, "rev-parse", "--show-toplevel"]);
-    return result.status === 0 ? result.stdout.trim() : dir;
-}
 function setup(root, dryRun) {
-    const writer = new Writer(root, dryRun);
+    const writer = new Writer(dryRun);
+    /** `file` of the repository, under its own name, as `change` leaves it. */
+    const put = (file, change) => {
+        writer.apply(file, join(root, file), change);
+    };
     const template = readFileSync(TEMPLATE, "utf8");
     const from = source(root);
-    writer.put(ROUTER, (current) => {
+    put(ROUTER, (current) => {
         if ("problem" in from) {
             return { refusal: `${from.problem}; the table comes from ${REFERENCES_FILE}, so fix it first` };
         }
         const next = withBlock(current ?? template, renderBlock(from.references ?? []));
         return "problem" in next ? { refusal: next.problem } : next;
     });
-    writer.create(ROUTER_LINK, (path) => {
+    writer.create(ROUTER_LINK, join(root, ROUTER_LINK), (path) => {
         symlinkSync("AGENTS.md", path);
     });
-    writer.put(SETTINGS, withExcludes);
-    writer.put(IGNORE, withIgnoreLines);
-    writer.put(REFERENCES_FILE, () => ("problem" in from ? (from.file ?? { refusal: from.problem }) : from.file));
+    put(SETTINGS, withExcludes);
+    put(IGNORE, withIgnoreLines);
+    put(REFERENCES_FILE, "problem" in from ? (from.file ?? { refusal: from.problem }) : from.file);
     if (!("problem" in from) && from.config !== undefined) {
-        writer.put(CONFIG, from.config);
+        put(CONFIG, from.config);
     }
     return writer.steps;
 }
 export function run(argv) {
-    let values;
-    try {
-        values = parseArgs({
-            args: argv,
-            options: {
-                help: { type: "boolean", short: "h" },
-                root: { type: "string" },
-                "dry-run": { type: "boolean" },
-                check: { type: "boolean" }
-            }
-        }).values;
-    }
-    catch (error) {
-        fail(`${messageOf(error)}\n\n${USAGE}`);
-    }
+    const { values } = readArgs({
+        args: argv,
+        options: {
+            help: { type: "boolean", short: "h" },
+            root: { type: "string" },
+            "dry-run": { type: "boolean" },
+            check: { type: "boolean" }
+        }
+    }, USAGE);
     if (values.help === true) {
         console.log(USAGE);
         return 0;
     }
     const check = values.check === true;
     const dryRun = values["dry-run"] === true || check;
-    const steps = setup(toplevel(values.root ?? process.cwd()), dryRun);
-    for (const step of steps) {
-        const verb = step.outcome === "wrote" && dryRun ? "would write" : step.outcome;
-        console.log(`${verb.padEnd(11)} ${step.file}${step.detail === undefined ? "" : ` — ${step.detail}`}`);
+    const steps = setup(repositoryRoot(rootDir(values.root)), dryRun);
+    for (const line of stepLines(steps, dryRun)) {
+        console.log(line);
     }
     const refused = steps.some((step) => step.outcome === "refused");
     return refused || (check && steps.some((step) => step.outcome === "wrote")) ? 1 : 0;

package/dist/commands/references-sync.js

@@ -4,9 +4,10 @@
 import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { extname, join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
-import { parseArgs } from "node:util";
-import { exec, SLOW_LIMIT_MS } from "../exec.js";
-import { repositoryFreeEnv } from "../git-env.js";
+import { repositoryRoot } from "../agentic-config.js";
+import { CannotRun, messageOf, readArgs } from "../cannot-run.js";
+import { SLOW_LIMIT_MS } from "../exec.js";
+import { asked, git } from "../git.js";
 import { readPins, resolveRef } from "../pins.js";
 import { REFERENCES_FILE, readReferences } from "../references-key.js";
 import { renderBlock, withBlock } from "../router-block.js";
@@ -29,17 +30,10 @@ tag, holding the top-level files and the paths its only names when it has one, w
 its skip names. Prints one line per Reference. Exit 1 when any Reference fails, 2 on a bad key,
 config or argument, in which case nothing is synced. One Sync runs in a checkout at a time; a
 second one waits for it up to ${WAIT_SECONDS} s, or REFERENCES_SYNC_WAIT seconds.`;
-function messageOf(error) {
-    return error instanceof Error ? error.message : String(error);
-}
 /** The code a failed system call throws with, as "ENOENT", or undefined. */
 function codeOf(error) {
     return error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : undefined;
 }
-function fail(message) {
-    console.error(`references:sync: ${message}`);
-    process.exit(2);
-}
 /** REFERENCES_SYNC_WAIT when it names a number of seconds, else WAIT_SECONDS. */
 function waitSeconds() {
     const given = process.env.REFERENCES_SYNC_WAIT?.trim();
@@ -134,23 +128,13 @@ async function lock(root, seconds) {
         rmSync(own, { force: true });
     }
 }
-function git(args, cwd) {
-    // Each call finds its repository from `cwd`.
-    const env = repositoryFreeEnv();
-    const result = exec("git", args, { ...(cwd === undefined ? {} : { cwd }), env, limitMs: SLOW_LIMIT_MS });
-    // git's error on one line, so each Reference stays one line of the report.
-    const err = (result.stderr ?? "")
-        .split("\n")
-        .map((line) => line.trim())
-        .filter(Boolean)
-        .join(" ");
-    return { ok: result.status === 0, out: (result.stdout ?? "").trim(), err };
-}
-/** Runs one git step of a sync, `gitOptions` ahead of it; throws with git's error when it fails. */
-function step(args, cwd, gitOptions = []) {
-    const result = git([...gitOptions, ...args], cwd);
-    if (!result.ok) {
-        throw new Error(`git ${args.join(" ")}: ${result.err}`);
+/** Every git call of a Sync: one that fetches may take long, and its error stays one line of the report. */
+const SYNC = { limitMs: SLOW_LIMIT_MS, whole: true };
+/** Runs one git step of a sync from `dir`, `gitOptions` ahead of it; throws with git's error when it fails. */
+function step(args, dir, gitOptions = []) {
+    const result = git(dir, [...gitOptions, ...args], SYNC);
+    if ("error" in result) {
+        throw new Error(`git ${args.join(" ")}: ${result.said}`);
     }
 }
 /** A GitHub repository fetches with the GitHub CLI's credentials, so a private one clones too. */
@@ -170,11 +154,11 @@ function sparsePatterns({ only, skip }) {
     const kept = only.length === 0 ? ["/*"] : ["/*", "!/*/", ...only.map((path) => `/${path}`)];
     return [...kept, ...skip.map((path) => `!/${path}`)];
 }
-/** Whether the tree fetched into `cwd` holds `path`, a directory when it ends in `/`. Reads trees only. */
-function fetchedTreeHas(path, cwd) {
-    const listed = git(["ls-tree", "FETCH_HEAD", "--", path.replace(/\/+$/, "")], cwd);
-    if (!listed.ok) {
-        throw new Error(`git ls-tree FETCH_HEAD: ${listed.err}`);
+/** Whether the tree fetched into `dir` holds `path`, a directory when it ends in `/`. Reads trees only. */
+function fetchedTreeHas(path, dir) {
+    const listed = git(dir, ["ls-tree", "FETCH_HEAD", "--", path.replace(/\/+$/, "")], SYNC);
+    if ("error" in listed) {
+        throw new Error(`git ls-tree FETCH_HEAD: ${listed.said}`);
     }
     // `<mode> <type> <object>\t<path>`, or nothing when the tree lacks the path.
     const type = listed.out.split(" ")[1];
@@ -192,14 +176,14 @@ function sync(root, reference, ref) {
     };
     try {
         if (existsSync(target)) {
-            const origin = git(["remote", "get-url", "origin"], target);
-            if (!existsSync(join(target, ".git")) || !origin.ok || origin.out !== repository) {
+            const origin = asked(target, ["remote", "get-url", "origin"], SYNC);
+            if (!existsSync(join(target, ".git")) || origin !== repository) {
                 return `${CLONES}/${dir} exists and is not a clone of ${repository}; move it aside and run again`;
             }
         }
         else {
             // An empty repository, so the one fetch below brings only the ref, a branch or a tag alike.
-            step(["init", "--quiet", target]);
+            step(["init", "--quiet", target], root);
             step(["remote", "add", "origin", repository], target);
         }
         fetching(["fetch", "--quiet", "--depth", "1", "--filter=blob:none", "origin", ref]);
@@ -223,17 +207,8 @@ function sync(root, reference, ref) {
     return undefined;
 }
 function parseCli(argv) {
-    try {
-        const { values, positionals } = parseArgs({
-            args: argv,
-            allowPositionals: true,
-            options: { help: { type: "boolean", short: "h" } }
-        });
-        return { help: values.help === true, dirs: positionals };
-    }
-    catch (error) {
-        fail(`${messageOf(error)}\n\n${USAGE}`);
-    }
+    const { values, positionals } = readArgs({ args: argv, allowPositionals: true, options: { help: { type: "boolean", short: "h" } } }, USAGE);
+    return { help: values.help === true, dirs: positionals };
 }
 /**
  * One line when the Router or its table is missing or behind `references`, naming the setup to run,
@@ -277,7 +252,7 @@ function syncAll(root, selected) {
             problem = messageOf(error);
         }
         if (problem === undefined) {
-            const head = git(["rev-parse", "--short", "HEAD"], join(root, CLONES, reference.dir)).out;
+            const head = asked(join(root, CLONES, reference.dir), ["rev-parse", "--short", "HEAD"], SYNC) ?? "";
             console.log(`${CLONES}/${reference.dir}  ${head}  ${reference.repository} ${ref}`);
         }
         else {
@@ -293,26 +268,27 @@ export async function run(argv) {
         console.log(USAGE);
         return 0;
     }
-    const toplevel = git(["rev-parse", "--show-toplevel"]);
-    const root = toplevel.ok ? toplevel.out : process.cwd();
+    const root = repositoryRoot(process.cwd());
     const reading = readReferences(root);
     if ("problem" in reading) {
-        fail(`${reading.problem}; nothing synced`);
+        throw new CannotRun(`${reading.problem}; nothing synced`);
     }
     const references = reading.references ?? [];
     const unknown = cli.dirs.filter((dir) => !references.some((reference) => reference.dir === dir));
     if (unknown.length > 0) {
-        fail(`not in ${REFERENCES_FILE}: ${unknown.join(", ")}`);
+        throw new CannotRun(`not in ${REFERENCES_FILE}: ${unknown.join(", ")}`);
     }
     if (reading.references === undefined) {
         return 0;
     }
     const selected = cli.dirs.length === 0 ? references : references.filter((reference) => cli.dirs.includes(reference.dir));
     const seconds = waitSeconds();
-    const attempt = await lock(root, seconds).catch((error) => fail(`${CLONES}/${LOCK}: ${messageOf(error)}; nothing synced`));
+    const attempt = await lock(root, seconds).catch((error) => {
+        throw new CannotRun(`${CLONES}/${LOCK}: ${messageOf(error)}; nothing synced`);
+    });
     let failed = false;
     if ("heldBy" in attempt) {
-        console.error(`references:sync: another Sync (pid ${attempt.heldBy}) still holds ${CLONES}/${LOCK} after ${seconds} s; the clones are what it leaves`);
+        console.error(`dw-sdlc references sync: another Sync (pid ${attempt.heldBy}) still holds ${CLONES}/${LOCK} after ${seconds} s; the clones are what it leaves`);
     }
     else {
         try {

package/dist/commands/setup.d.ts

@@ -1,11 +1,6 @@
 import { type CommitConvention, type CommitOnProtected, type ForcePush } from "../agentic-config.ts";
-/** `by hand` is an edit the setup names and leaves to the user; `skipped` is a file it has no reason to write. */
-export type Outcome = "wrote" | "unchanged" | "skipped" | "refused" | "by hand";
-export type Step = {
-    file: string;
-    outcome: Outcome;
-    detail?: string;
-};
+import { type Step } from "../setup-writer.ts";
+export type { Step };
 export type SetupOptions = {
     root: string;
     home: string;