dw-sdlc 0.5.1 → 0.7.0

package/dist/commands/references-setup.js

@@ -1,12 +1,12 @@
-// `dw-sdlc references setup` sets a repository up to declare References: the five files its USAGE names,
-// each written only when it would change. Existing content stays: a list gains the entries it lacks at
-// its end, nothing is removed or reordered, and a file the step cannot read as it expects is refused.
+// `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 { spawnSync } from "node:child_process";
 import { existsSync, lstatSync, mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { parseArgs } from "node:util";
-import { appendKey, parseObject, render } from "../json-text.js";
-import { CONFIG, readReferences } from "../references-key.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";
 const ROUTER = "references/AGENTS.md";
 /** A symlink to the Router, so Claude Code loads it. */
@@ -14,6 +14,8 @@ const ROUTER_LINK = "references/CLAUDE.md";
 const SETTINGS = ".claude/settings.json";
 const IGNORE = ".gitignore";
 const TEMPLATE = join(import.meta.dirname, "..", "..", "templates", "router.md");
+/** Where a file the setup creates points `$schema`: the schema the pinned package installs. */
+const SCHEMA = "../node_modules/dw-sdlc/config/references.schema.json";
 /** A clone's own agent files at any depth; Claude Code matches the globs against absolute paths. */
 const EXCLUDES = [
     "**/references/*/CLAUDE.md",
@@ -33,12 +35,13 @@ const USAGE = `Usage: dw-sdlc references setup [--root <dir>] [--dry-run | --che
 
 Sets the repository at --root, or the one the current directory sits in, up to declare References:
 the Router in ${ROUTER} with its CLAUDE.md symlink and, between its two markers, the table of each
-Reference's dir and when from the references key, claudeMdExcludes in ${SETTINGS} for the clones'
-own agent files, the ${IGNORE} lines that keep every clone out of git but the Router, and an empty
-references key in ${CONFIG}. Every file is 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.`;
+Reference's dir and when from ${REFERENCES_FILE}, claudeMdExcludes in ${SETTINGS} for the clones' own agent
+files, the ${IGNORE} lines that keep every clone out of git but the Router, and ${REFERENCES_FILE} itself
+with no References when it is missing. A references key in ${CONFIG} moves into a missing ${REFERENCES_FILE}
+and leaves the config; with the file there too, both stay and the step is refused. Every file is
+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);
 }
@@ -116,16 +119,43 @@ function withIgnoreLines(current) {
     const gap = head !== "" && !ignored ? "\n" : "";
     return { text: `${head}${gap}${missing.join("\n")}\n` };
 }
-/** The config with an empty `references` key when it has none, inserted so its own layout stays. */
-function withEmptyKey(current) {
-    if (current === undefined) {
-        return { text: render({ references: [] }) };
+/** The text of a References file the setup creates, declaring `references`. */
+function fileOf(references) {
+    return render({ $schema: SCHEMA, version: 1, references });
+}
+/**
+ * Where the References come from: a `references` key left in the config moves into a missing file,
+ * and a repository with neither gets the file with no References; the file and the key both there
+ * are refused, and so is a key the parser refuses.
+ */
+function source(root) {
+    const key = leftoverKey(root);
+    const path = join(root, REFERENCES_FILE);
+    if (key === undefined) {
+        const reading = readFile(root);
+        if ("problem" in reading) {
+            // The problem is the file's own, and the Router's line names it; the file stays as it is.
+            return { problem: reading.problem, file: { text: readFileSync(path, "utf8") } };
+        }
+        return {
+            references: reading.references,
+            file: { text: existsSync(path) ? readFileSync(path, "utf8") : fileOf([]) }
+        };
     }
-    const config = parseObject(current);
-    if (config === undefined) {
-        return { refusal: "is not a JSON object; fix it by hand first" };
+    if (existsSync(path)) {
+        return { problem: leftoverProblem(true) };
+    }
+    const parsed = parseReferences(key);
+    if ("problem" in parsed) {
+        return { problem: `${CONFIG}: ${parsed.problem.path}: ${parsed.problem.message}; fix it by hand first` };
     }
-    return { text: Object.hasOwn(config, "references") ? current : appendKey(current, "references", []) };
+    return {
+        references: parsed.references,
+        file: { text: fileOf(key) },
+        config: (current) => current === undefined || parseObject(current) === undefined
+            ? { refusal: "is not a JSON object; fix it by hand first" }
+            : { text: removeKey(current, "references") }
+    };
 }
 /** The repository `dir` sits in, or `dir` itself outside one. */
 function toplevel(dir) {
@@ -135,12 +165,12 @@ function toplevel(dir) {
 function setup(root, dryRun) {
     const writer = new Writer(root, dryRun);
     const template = readFileSync(TEMPLATE, "utf8");
-    const reading = readReferences(root);
+    const from = source(root);
     writer.put(ROUTER, (current) => {
-        if ("problem" in reading) {
-            return { refusal: `${reading.problem}; the table comes from the key, so fix it first` };
+        if ("problem" in from) {
+            return { refusal: `${from.problem}; the table comes from ${REFERENCES_FILE}, so fix it first` };
         }
-        const next = withBlock(current ?? template, renderBlock(reading.references ?? []));
+        const next = withBlock(current ?? template, renderBlock(from.references ?? []));
         return "problem" in next ? { refusal: next.problem } : next;
     });
     writer.create(ROUTER_LINK, (path) => {
@@ -148,7 +178,10 @@ function setup(root, dryRun) {
     });
     writer.put(SETTINGS, withExcludes);
     writer.put(IGNORE, withIgnoreLines);
-    writer.put(CONFIG, withEmptyKey);
+    writer.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);
+    }
     return writer.steps;
 }
 export function run(argv) {

package/dist/commands/references-sync.js

@@ -1,4 +1,4 @@
-// `dw-sdlc references sync`, the Sync: every Reference the committed config declares brought to its ref
+// `dw-sdlc references sync`, the Sync: every Reference `.ai/references.json` declares brought to its ref
 // under references/<dir>, each clone shallow, blobless, detached and sparse where its entry says. An
 // entry that fails fails alone, and a repository that declares no References gets no output at all.
 import { spawnSync } from "node:child_process";
@@ -7,7 +7,7 @@ import { extname, join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import { parseArgs } from "node:util";
 import { readPins, resolveRef } from "../pins.js";
-import { CONFIG, readReferences } from "../references-key.js";
+import { REFERENCES_FILE, readReferences } from "../references-key.js";
 import { renderBlock, withBlock } from "../router-block.js";
 const CLONES = "references";
 const ROUTER = "references/AGENTS.md";
@@ -22,7 +22,7 @@ export const summary = "bring every declared Reference to its ref under referenc
 const USAGE = `Usage: dw-sdlc references sync [dir...]
   or:  pnpm references:sync [dir...], in a checkout of dw-sdlc
 
-Brings every Reference the references key of ${CONFIG} declares to its ref under ${CLONES}/<dir>, or
+Brings every Reference ${REFERENCES_FILE} declares to its ref under ${CLONES}/<dir>, or
 only the given dirs: a missing one cloned shallow, an existing one moved to its branch's head or its
 tag, holding the top-level files and the paths its only names when it has one, without the paths
 its skip names. Prints one line per Reference. Exit 1 when any Reference fails, 2 on a bad key,
@@ -304,7 +304,7 @@ export async function run(argv) {
     const references = reading.references ?? [];
     const unknown = cli.dirs.filter((dir) => !references.some((reference) => reference.dir === dir));
     if (unknown.length > 0) {
-        fail(`not in the references of ${CONFIG}: ${unknown.join(", ")}`);
+        fail(`not in ${REFERENCES_FILE}: ${unknown.join(", ")}`);
     }
     if (reading.references === undefined) {
         return 0;
@@ -335,7 +335,7 @@ export async function run(argv) {
             .map((entry) => `${CLONES}/${entry.name}`)
         : [];
     if (stray.length > 0) {
-        console.log(`Not listed in ${CONFIG}, left alone: ${stray.join(", ")}`);
+        console.log(`Not listed in ${REFERENCES_FILE}, left alone: ${stray.join(", ")}`);
     }
     return failed ? 1 : 0;
 }

package/dist/json-text.d.ts

@@ -5,3 +5,8 @@ export declare function parseObject(text: string): JsonObject | undefined;
 export declare function render(value: unknown): string;
 /** `text`, a JSON object, with `key` set to `value` after its last key, two spaces in. */
 export declare function appendKey(text: string, key: string, value: unknown): string;
+/**
+ * `text`, a JSON object, without its top-level `key`, every copy of it when the key repeats; the
+ * members around it keep their layout.
+ */
+export declare function removeKey(text: string, key: string): string;

package/dist/json-text.js

@@ -1,5 +1,5 @@
 // The text of a JSON object file as the setup commands read and write it: parsed only when it holds an
-// object, rendered two spaces in, and a key appended so a hand-formatted file keeps its layout.
+// object, rendered two spaces in, and a key appended or removed so a hand-formatted file keeps its layout.
 export function isObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -24,3 +24,76 @@ export function appendKey(text, key, value) {
     const rendered = JSON.stringify(value, null, 2).replaceAll("\n", "\n  ");
     return `${body}${comma}\n  ${JSON.stringify(key)}: ${rendered}\n${text.slice(close)}`;
 }
+/** The index just past the JSON string that opens at `start`, or the text's end when it never closes. */
+function stringEnd(text, start) {
+    let index = start + 1;
+    while (index < text.length && text[index] !== '"') {
+        index += text[index] === "\\" ? 2 : 1;
+    }
+    return Math.min(index + 1, text.length);
+}
+/** The start and end of the top-level member `key` in `text`, a JSON object, from its name to its value's end. */
+function memberSpan(text, key) {
+    let depth = 0;
+    let expectKey = false;
+    let start;
+    // Just past the last character that is not whitespace: where the member's value ends once a `,` or `}` follows.
+    let lastValue = 0;
+    for (let index = 0; index < text.length;) {
+        const char = text.charAt(index);
+        if (char === '"') {
+            const end = stringEnd(text, index);
+            if (depth === 1 && expectKey) {
+                expectKey = false;
+                if (start === undefined && JSON.parse(text.slice(index, end)) === key) {
+                    start = index;
+                }
+            }
+            lastValue = end;
+            index = end;
+            continue;
+        }
+        if (char === "{" || char === "[") {
+            depth += 1;
+            expectKey = char === "{" && depth === 1;
+        }
+        else if (char === "}" || char === "]") {
+            depth -= 1;
+            if (depth === 0 && start !== undefined) {
+                return { start, end: lastValue };
+            }
+        }
+        else if (char === "," && depth === 1) {
+            if (start !== undefined) {
+                return { start, end: lastValue };
+            }
+            expectKey = true;
+        }
+        if (!/\s/.test(char)) {
+            lastValue = index + 1;
+        }
+        index += 1;
+    }
+    return undefined;
+}
+/**
+ * `text`, a JSON object, without its top-level `key`, every copy of it when the key repeats; the
+ * members around it keep their layout.
+ */
+export function removeKey(text, key) {
+    const span = memberSpan(text, key);
+    if (span === undefined) {
+        return text;
+    }
+    return removeKey(withoutSpan(text, span), key);
+}
+/** `text` without the member at `span` and the comma that joins it to its neighbour. */
+function withoutSpan(text, span) {
+    const after = text.slice(span.end).match(/^\s*,\s*/);
+    if (after !== null) {
+        return text.slice(0, span.start) + text.slice(span.end + after[0].length);
+    }
+    const before = text.slice(0, span.start).match(/,?\s*$/);
+    const cut = span.start - (before?.[0].length ?? 0);
+    return text.slice(0, cut) + text.slice(span.end);
+}

package/dist/pr/decide.d.ts

@@ -0,0 +1,36 @@
+import type { PrMerge } from "../agentic-config.ts";
+import type { PrState } from "./state.ts";
+export type Status = "act" | "wait" | "park" | "done";
+export type Actor = "script" | "agent" | "dev";
+export type Action = "done" | "stop" | "wait" | "fix-conflicts" | "update-branch" | "fix-ci" | "address-review" | "review" | "unverified" | "ci-stuck" | "awaiting-reply" | "mark-ready" | "awaiting-approval" | "ready-to-merge" | "merge";
+/** The Actions the script performs itself, each one gh command. */
+export type ScriptAction = "update-branch" | "mark-ready" | "merge";
+/** An Action the pull request needs beside the one its answer names, so one push can fix several. */
+export type Blocker = {
+    action: Action;
+    actor: Actor;
+    reason: string;
+    details?: Record<string, unknown>;
+};
+export type Answer = Blocker & {
+    status: Status;
+    /** A shell-quoted command, when there is one to run. */
+    command?: string;
+    /** Seconds to wait before calling again. */
+    recheckAfter?: number;
+    blockers: Blocker[];
+};
+/** The words as one POSIX shell command line, each word that needs it single-quoted. */
+export declare function shellLine(words: string[]): string;
+export declare function isScriptAction(action: Action): action is ScriptAction;
+/**
+ * The gh arguments of a script Action, `-R` naming the repository when `named`. The update merges the
+ * base in, never --rebase, which rewrites the branch on GitHub; the merge names the head it read.
+ */
+export declare function hostArgs(pr: PrState, action: ScriptAction, named: boolean): string[];
+/** The command a script Action leaves the dev to run, from a checkout of the repository. */
+export declare function devCommand(pr: PrState, action: ScriptAction): string;
+/** The merge left to the dev, `reason` saying why it is theirs. */
+export declare function readyToMerge(pr: PrState, reason: string): Omit<Answer, "blockers">;
+/** The Action `pr` needs at `now`, milliseconds since the epoch, when `merge` says who merges it. */
+export declare function decide(pr: PrState, now: number, merge: PrMerge): Answer;

package/dist/pr/decide.js

@@ -0,0 +1,216 @@
+// The decision of the Ship script: one ordered list of rows, and the first row whose `when` holds for
+// the pull request answers its Action at the time given; every later row that holds rides in its
+// blockers. The last rows say who merges what no row before them holds back.
+/** How long a head may carry no check before it parks as unverified, from its commit. */
+const GRACE_SECONDS = 120;
+/** How long CI may stay pending before it parks as stuck, from the first start among the pending checks. */
+const BUDGET_MINUTES = 40;
+/** The prefix of the contexts the script posts itself, as `dw-sdlc/review`: never CI. */
+const OWN_PREFIX = "dw-sdlc/";
+/** The commit status a clean review of the head leaves on it. */
+const REVIEW = "dw-sdlc/review";
+/** The words as one POSIX shell command line, each word that needs it single-quoted. */
+export function shellLine(words) {
+    return words.map((word) => (/^[\w./:=@%+,-]+$/.test(word) ? word : `'${word.replaceAll("'", `'\\''`)}'`)).join(" ");
+}
+function ciOf(pr) {
+    return pr.checks.filter((check) => !check.name.startsWith(OWN_PREFIX));
+}
+function pendingOf(pr) {
+    return ciOf(pr).filter((check) => check.bucket === "pending");
+}
+function failingOf(pr) {
+    return ciOf(pr).filter((check) => check.bucket === "fail");
+}
+/** A failing check as the agent reads it: its link, and the command that prints a GitHub Actions job's log. */
+function failure({ name, link, log }) {
+    return { name, link, ...(log === null ? {} : { log: shellLine(log) }) };
+}
+/** The unresolved threads whose last comment is the viewer's, or with `false` someone else's. */
+function threads(pr, lastByViewer) {
+    return pr.unresolvedThreads.filter((thread) => thread.lastByViewer === lastByViewer);
+}
+function listed({ id, path, line, author, body }) {
+    return { id, path, line, author, body };
+}
+const HOST = {
+    "update-branch": { verb: "update-branch", flags: () => [] },
+    "mark-ready": { verb: "ready", flags: () => [] },
+    merge: { verb: "merge", flags: (pr) => ["--squash", "--match-head-commit", pr.head] }
+};
+export function isScriptAction(action) {
+    return Object.hasOwn(HOST, action);
+}
+/**
+ * The gh arguments of a script Action, `-R` naming the repository when `named`. The update merges the
+ * base in, never --rebase, which rewrites the branch on GitHub; the merge names the head it read.
+ */
+export function hostArgs(pr, action, named) {
+    const { verb, flags } = HOST[action];
+    return ["pr", verb, String(pr.number), ...(named ? ["-R", pr.repo] : []), ...flags(pr)];
+}
+/** The command a script Action leaves the dev to run, from a checkout of the repository. */
+export function devCommand(pr, action) {
+    return shellLine(["gh", ...hostArgs(pr, action, false)]);
+}
+/** The merge left to the dev, `reason` saying why it is theirs. */
+export function readyToMerge(pr, reason) {
+    return { status: "park", action: "ready-to-merge", actor: "dev", reason, command: devCommand(pr, "merge") };
+}
+const ROWS = [
+    {
+        when: (pr) => pr.state === "MERGED",
+        answer: (pr) => ({
+            status: "done",
+            action: "done",
+            actor: "dev",
+            reason: pr.mergeCommit === null ? "merged" : `merged as ${pr.mergeCommit.slice(0, 7)}`,
+            command: shellLine(["git", "push", "origin", "--delete", pr.branch]),
+            ...(pr.mergeCommit === null ? {} : { details: { mergeCommit: pr.mergeCommit } })
+        }),
+        alone: true
+    },
+    {
+        when: (pr) => pr.state === "CLOSED",
+        answer: () => ({ status: "park", action: "stop", actor: "dev", reason: "closed without merging" }),
+        alone: true
+    },
+    {
+        when: (pr) => pr.mergeable === "UNKNOWN",
+        answer: () => ({
+            status: "wait",
+            action: "wait",
+            actor: "script",
+            reason: "mergeability-unknown",
+            recheckAfter: 15
+        }),
+        alone: true
+    },
+    {
+        when: (pr) => pr.mergeable === "CONFLICTING",
+        answer: (pr) => ({
+            status: "act",
+            action: "fix-conflicts",
+            actor: "agent",
+            reason: `conflicts with ${pr.base}`,
+            details: { base: pr.base }
+        })
+    },
+    {
+        when: (pr) => pr.mergeStateStatus === "BEHIND",
+        answer: (pr) => ({ status: "act", action: "update-branch", actor: "script", reason: `behind ${pr.base}` })
+    },
+    {
+        when: (pr) => failingOf(pr).length > 0,
+        answer: (pr) => ({
+            status: "act",
+            action: "fix-ci",
+            actor: "agent",
+            reason: `${failingOf(pr).length} check(s) failing`,
+            details: { checks: failingOf(pr).map(failure) }
+        })
+    },
+    {
+        when: (pr) => threads(pr, false).length > 0,
+        answer: (pr) => ({
+            status: "act",
+            action: "address-review",
+            actor: "agent",
+            reason: `${threads(pr, false).length} unresolved thread(s)`,
+            details: { threads: threads(pr, false).map(listed) }
+        })
+    },
+    {
+        when: (pr) => pr.reviewDecision === "CHANGES_REQUESTED",
+        answer: () => ({ status: "act", action: "address-review", actor: "agent", reason: "changes requested" })
+    },
+    {
+        when: (pr) => !pr.checks.some((check) => check.name === REVIEW && check.bucket === "pass"),
+        answer: (pr) => ({
+            status: "act",
+            action: "review",
+            actor: "agent",
+            reason: `no ${REVIEW} success on ${pr.head.slice(0, 7)}`
+        })
+    },
+    {
+        when: (pr) => ciOf(pr).length === 0,
+        answer: (pr, now) => now - Date.parse(pr.headCommittedAt) <= GRACE_SECONDS * 1000
+            ? { status: "wait", action: "wait", actor: "script", reason: "unverified", recheckAfter: 15 }
+            : {
+                status: "park",
+                action: "unverified",
+                actor: "dev",
+                reason: `no check reported on ${pr.head.slice(0, 7)} within ${GRACE_SECONDS} s of its commit`,
+                command: devCommand(pr, "merge")
+            }
+    },
+    {
+        when: (pr) => pendingOf(pr).length > 0,
+        answer: (pr, now) => {
+            const pending = pendingOf(pr);
+            // A check queued and not yet started counts from the head's commit.
+            const start = Math.min(...pending.map((check) => Date.parse(check.startedAt ?? pr.headCommittedAt)));
+            const minutes = Math.floor((now - start) / 60_000);
+            return now - start <= BUDGET_MINUTES * 60_000
+                ? { status: "wait", action: "wait", actor: "script", reason: "ci-pending", recheckAfter: 60 }
+                : {
+                    status: "park",
+                    action: "ci-stuck",
+                    actor: "dev",
+                    reason: `${pending.length} check(s) pending for ${minutes} min, past the ${BUDGET_MINUTES} min budget`
+                };
+        }
+    },
+    {
+        when: (pr) => threads(pr, true).length > 0,
+        answer: (pr) => ({
+            status: "park",
+            action: "awaiting-reply",
+            actor: "dev",
+            reason: `${threads(pr, true).length} thread(s) await a reply`,
+            details: { threads: threads(pr, true).map(listed) }
+        })
+    },
+    {
+        when: (pr) => pr.draft,
+        answer: () => ({ status: "act", action: "mark-ready", actor: "script", reason: "still a draft" })
+    },
+    {
+        when: (pr) => pr.reviewDecision === "REVIEW_REQUIRED",
+        answer: () => ({
+            status: "park",
+            action: "awaiting-approval",
+            actor: "dev",
+            reason: "an approving review is required"
+        })
+    },
+    {
+        when: (pr) => !pr.viewerDidAuthor,
+        answer: (pr) => readyToMerge(pr, "another author's pull request: the merge is the dev's"),
+        merging: true
+    },
+    {
+        when: (_, merge) => merge === "auto",
+        answer: () => ({ status: "act", action: "merge", actor: "script", reason: "green, reviewed and the viewer's own" }),
+        merging: true
+    },
+    {
+        when: (_, merge) => merge === "ask",
+        answer: (pr) => readyToMerge(pr, "pr.merge is ask: the merge is the dev's"),
+        merging: true
+    }
+];
+function blockerOf({ action, actor, reason, details }) {
+    return { action, actor, reason, ...(details === undefined ? {} : { details }) };
+}
+/** The Action `pr` needs at `now`, milliseconds since the epoch, when `merge` says who merges it. */
+export function decide(pr, now, merge) {
+    const index = ROWS.findIndex((row) => row.when(pr, merge));
+    const row = ROWS[index];
+    if (row === undefined) {
+        throw new Error(`no row of the decision matches ${pr.url} under pr.merge ${merge}`);
+    }
+    const later = row.alone === true ? [] : ROWS.slice(index + 1).filter((other) => !other.merging && other.when(pr, merge));
+    return { ...row.answer(pr, now), blockers: later.map((other) => blockerOf(other.answer(pr, now))) };
+}

package/dist/pr/read.d.ts

@@ -0,0 +1,24 @@
+import { type PrState } from "./state.ts";
+/** What stops a pr command before it answers: exit 2, the problem and its remedy on one line. */
+export declare class CannotRun extends Error {
+    remedy: string;
+    constructor(message: string, remedy: string);
+}
+/** The pull request a command line names; what it leaves out, `gh pr view` resolves. */
+export type Named = {
+    number: number | undefined;
+    repo: string | undefined;
+};
+/** The problem with `<n>` or `-R` as given on a command line, if there is one. */
+export declare function namedProblem(number: string | undefined, repo: string | undefined): string | undefined;
+/** What gh said went wrong: the first line of its stderr, without its `gh: ` prefix or its `X` icon. */
+export declare function said(stderr: string): string;
+export declare function gh(args: string[]): {
+    status: number;
+    stdout: string;
+    stderr: string;
+};
+/** The state of the pull request `named`; `command`, as `pr ship`, names the call in a remedy. */
+export declare function read(named: Named, command: string): PrState;
+/** The state of `pr` once more, after an action the script performed on it: the same pull request. */
+export declare function readAgain(pr: PrState): PrState;

package/dist/pr/read.js

@@ -0,0 +1,112 @@
+// The read both pr commands make: gh as a child process, its auth on the host gh api reads from, the
+// pull request a command names, and that pull request's state from one GraphQL request.
+import { spawnSync } from "node:child_process";
+import { parsePr, parseView, QUERY, ReplyError } from "./state.js";
+/** What stops a pr command before it answers: exit 2, the problem and its remedy on one line. */
+export class CannotRun extends Error {
+    remedy;
+    constructor(message, remedy) {
+        super(message);
+        this.remedy = remedy;
+    }
+}
+const REMEDIES = {
+    missing: "install the GitHub CLI from https://cli.github.com",
+    auth: "run gh auth login, or set GH_TOKEN",
+    target: "check the number, or name the repository with -R owner/name",
+    read: "check gh auth status and the network, then call again",
+    reply: "gh answered a shape dw-sdlc does not read; report it with the output of gh --version"
+};
+/** The problem with `<n>` or `-R` as given on a command line, if there is one. */
+export function namedProblem(number, repo) {
+    if (number !== undefined && !/^[1-9]\d*$/.test(number)) {
+        return `${JSON.stringify(number)} is not a pull request number`;
+    }
+    if (repo !== undefined && !/^[\w.-]+\/[\w.-]+$/.test(repo)) {
+        return `-R takes owner/name, not ${JSON.stringify(repo)}`;
+    }
+    return undefined;
+}
+function firstLine(text) {
+    return text.trim().split("\n")[0] ?? "";
+}
+/** What gh said went wrong: the first line of its stderr, without its `gh: ` prefix or its `X` icon. */
+export function said(stderr) {
+    return firstLine(stderr).replace(/^(?:gh: |X )/, "");
+}
+/** The problem `gh auth status` reports: its line marked `X` under the host, else its first line. */
+function authProblem(stderr) {
+    const marked = stderr.split("\n").find((line) => line.trimStart().startsWith("X "));
+    return marked === undefined ? firstLine(stderr) : marked.trim().slice(2);
+}
+export function gh(args) {
+    const result = spawnSync("gh", args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    if (result.error !== undefined) {
+        if ("code" in result.error && result.error.code === "ENOENT") {
+            throw new CannotRun("gh is not on PATH", REMEDIES.missing);
+        }
+        throw result.error;
+    }
+    return { status: result.status ?? 1, stdout: result.stdout, stderr: result.stderr };
+}
+/** What `parse` returns; a reply it cannot parse stops the command, naming the field. */
+function parseOrCannotRun(parse) {
+    try {
+        return parse();
+    }
+    catch (error) {
+        if (error instanceof ReplyError) {
+            throw new CannotRun(`the reply does not parse: ${error.message}`, REMEDIES.reply);
+        }
+        throw error;
+    }
+}
+/** The pull request named in full, or the one `gh pr view` resolves from what is given. */
+function targetOf({ number, repo }, command) {
+    if (number !== undefined && repo !== undefined) {
+        return { repo, number };
+    }
+    const named = [...(number === undefined ? [] : [String(number)]), ...(repo === undefined ? [] : ["-R", repo])];
+    const view = gh(["pr", "view", ...named, "--json", "url"]);
+    if (view.status !== 0) {
+        const remedy = `name it: dw-sdlc ${command} <n> -R owner/name`;
+        throw new CannotRun(`gh pr view found no pull request: ${firstLine(view.stderr)}`, remedy);
+    }
+    return parseOrCannotRun(() => parseView(view.stdout));
+}
+/** The state of the pull request `named`; `command`, as `pr ship`, names the call in a remedy. */
+export function read(named, command) {
+    // The host gh api reads from: an account on any other host has no say in this call.
+    const host = process.env.GH_HOST?.trim() || "github.com";
+    const auth = gh(["auth", "status", "--active", "--hostname", host]);
+    if (auth.status !== 0) {
+        throw new CannotRun(`gh auth status failed: ${authProblem(auth.stderr)}`, REMEDIES.auth);
+    }
+    return query(targetOf(named, command));
+}
+/** The state of `pr` once more, after an action the script performed on it: the same pull request. */
+export function readAgain(pr) {
+    return query(pr);
+}
+/** The state of pull request `number` of `repo`, from one GraphQL request. */
+function query({ repo, number }) {
+    const [owner = "", name = ""] = repo.split("/");
+    const reply = gh([
+        "api",
+        "graphql",
+        "-f",
+        `query=${QUERY}`,
+        "-f",
+        `owner=${owner}`,
+        "-f",
+        `name=${name}`,
+        "-F",
+        `number=${number}`
+    ]);
+    if (reply.status !== 0) {
+        const problem = said(reply.stderr);
+        const remedy = problem.startsWith("Could not resolve to a") ? REMEDIES.target : REMEDIES.read;
+        throw new CannotRun(`${repo}#${number}: ${problem}`, remedy);
+    }
+    return parseOrCannotRun(() => parsePr(reply.stdout, repo));
+}