dw-sdlc 0.11.0 → 0.12.1

package/dist/pr/read.js

@@ -93,18 +93,33 @@ export function read(named, command, sized) {
     requireAuth();
     return query(targetOf(named, command), sized);
 }
-/** The state of the current branch's pull request, open or not, or null when gh finds none. */
-export function readBranch(sized) {
-    requireAuth();
-    const view = gh(["pr", "view", "--json", "url"]);
+/** The pull request `gh pr view` resolves for the head branch `branch`, else the current one; null when none. */
+function viewed(branch) {
+    const view = gh(["pr", "view", ...(branch === undefined ? [] : [branch]), "--json", "url"]);
     if (view.status === 0) {
-        return query(parseOrCannotRun(() => parseView(view.stdout)), sized);
+        return parseOrCannotRun(() => parseView(view.stdout));
     }
     if (said(view.stderr).startsWith("no pull requests found")) {
         return null;
     }
     throw new CannotRun(`gh pr view failed: ${said(view.stderr)}`, REMEDIES.read);
 }
+/**
+ * The current branch's pull request, open or not, or null. gh tries `@{push}`, else the local name, which
+ * misses a branch pushed under another name; then `upstreamName` is asked, and `byUpstream` says so.
+ */
+export function readBranch(sized, upstreamName) {
+    requireAuth();
+    const own = viewed(undefined);
+    if (own !== null) {
+        return { pr: query(own, sized), byUpstream: false };
+    }
+    if (upstreamName === undefined) {
+        return null;
+    }
+    const found = viewed(upstreamName);
+    return found === null ? null : { pr: query(found, sized), byUpstream: true };
+}
 /** The default branch of the repository gh resolves from the current directory. */
 export function defaultBranch() {
     const view = gh(["repo", "view", "--json", "defaultBranchRef"]);
@@ -129,12 +144,23 @@ export function now() {
 export function readAgain(pr, sized) {
     return query(pr, sized);
 }
-/** The reply of the compare from `from` to `commit`; `what` names it when gh refuses it. */
+/**
+ * The compares this process has read, by repository and the two commits, so reads that share one ask gh
+ * once: a compare of two commits never changes.
+ */
+const COMPARES = new Map();
+/** The reply of the compare from `from` to `commit`, read once per process; `what` names it when gh refuses it. */
 function compared(pr, from, commit, what) {
+    const key = `${pr.repo} ${from}...${commit}`;
+    const known = COMPARES.get(key);
+    if (known !== undefined) {
+        return known;
+    }
     const reply = gh(compareArgs(pr.repo, from, commit));
     if (reply.status !== 0) {
         throw new CannotRun(`${pr.repo}#${pr.number}: ${what}: ${said(reply.stderr)}`, REMEDIES.read);
     }
+    COMPARES.set(key, reply.stdout);
     return reply.stdout;
 }
 /** Whether the head of `after` carries the base `before` read: the compare shows it behind by none. */
@@ -142,6 +168,17 @@ export function carriesBase(before, after) {
     const reply = compared(after, before.baseOid, after.head, `the compare with ${before.baseOid.slice(0, 7)}`);
     return parseOrCannotRun(() => behindOf(reply)) === 0;
 }
+/**
+ * `pr` and how many commits of its base its head lacks, from the compare of the base with the head,
+ * read only where the decision can reach the update: open, mergeable, not reported BEHIND already.
+ */
+export function withBehind(pr) {
+    if (pr.state !== "OPEN" || pr.mergeable !== "MERGEABLE" || pr.mergeStateStatus === "BEHIND") {
+        return pr;
+    }
+    const reply = compared(pr, pr.baseOid, pr.head, `the compare with ${pr.base}`);
+    return { ...pr, behindBy: parseOrCannotRun(() => behindOf(reply)) };
+}
 /** The own changes of `pr` at `commit`, from the compare with its base; null when it cannot show them whole. */
 function ownChanges(pr, commit) {
     const reply = compared(pr, pr.baseOid, commit, `the compare with ${commit.slice(0, 7)}`);
@@ -190,5 +227,6 @@ function query({ repo, number }, sized) {
         const remedy = problem.startsWith("Could not resolve to a") ? REMEDIES.target : REMEDIES.read;
         throw new CannotRun(`${repo}#${number}: ${problem}`, remedy);
     }
-    return withChanged(withCarried(parseOrCannotRun(() => parsePr(reply.stdout, repo))), sized);
+    const parsed = parseOrCannotRun(() => parsePr(reply.stdout, repo));
+    return withChanged(withCarried({ ...parsed, behindBy: null }), sized);
 }

package/dist/pr/state.d.ts

@@ -2,7 +2,7 @@
 export declare const REVIEW = "dw-sdlc/review";
 /** How the description of a success the script posts under off begins: no one read that head. */
 export declare const OFF_PREFIX = "off:";
-export declare const QUERY = "query($owner: String!, $name: String!, $number: Int!) {\n  repository(owner: $owner, name: $name) {\n    pullRequest(number: $number) {\n      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName baseRefName baseRefOid\n      viewerDidAuthor mergeCommit { oid }\n      reviewThreads(first: 100) { nodes { id isResolved isOutdated path line\n        comments(first: 1) { nodes { author { login } body } }\n        latest: comments(last: 1) { nodes { viewerDidAuthor } } } }\n      commits(last: 1) { nodes { commit { committedDate statusCheckRollup {\n        contexts(first: 50) { nodes {\n          ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }\n          ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }\n      history: commits(last: 100) { nodes { commit { oid parents { totalCount } status { context(name: \"dw-sdlc/review\") { state description } } } } }\n    }\n  }\n}";
+export declare const QUERY = "query($owner: String!, $name: String!, $number: Int!) {\n  repository(owner: $owner, name: $name) {\n    pullRequest(number: $number) {\n      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName baseRefName baseRefOid\n      baseRef { target { oid } } viewerDidAuthor mergeCommit { oid }\n      reviewThreads(first: 100) { nodes { id isResolved isOutdated path line\n        comments(first: 1) { nodes { author { login } body } }\n        latest: comments(last: 1) { nodes { viewerDidAuthor } } } }\n      commits(last: 1) { nodes { commit { committedDate statusCheckRollup {\n        contexts(first: 50) { nodes {\n          ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }\n          ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }\n      history: commits(last: 100) { nodes { commit { oid parents { totalCount } status { context(name: \"dw-sdlc/review\") { state description } } } } }\n    }\n  }\n}";
 export type Bucket = "pass" | "fail" | "pending" | "skipping";
 export type CiCheck = {
     name: string;
@@ -40,7 +40,10 @@ export type PrState = {
     headCommittedAt: string;
     branch: string;
     base: string;
-    /** The commit the base branch points at. */
+    /**
+     * The commit the base branch points at, read from the branch itself: GitHub's `baseRefOid` lags a
+     * base that just moved. A deleted base branch leaves `baseRefOid`.
+     */
     baseOid: string;
     mergeCommit: string | null;
     checks: CiCheck[];
@@ -57,6 +60,11 @@ export type PrState = {
      * auto` to route on: `unsized` when the compare cannot list them all, null when not read.
      */
     changed: ChangedFile[] | "unsized" | null;
+    /**
+     * How many commits of the base the head lacks, from the compare of the base with the head; null when
+     * not read.
+     */
+    behindBy: number | null;
 };
 /**
  * A file a Review would read: its name, its name before a rename, and the lines it adds and removes,
@@ -100,5 +108,5 @@ export declare function parseView(reply: string): {
 /** The default branch of the repository whose `gh repo view --json defaultBranchRef` printed `reply`. */
 export declare function parseDefaultBranch(reply: string): string;
 /** The state of the pull request in `reply`, the text `gh api graphql` printed for QUERY on `repo`. */
-export declare function parsePr(reply: string, repo: string): Omit<PrState, "carried" | "changed">;
+export declare function parsePr(reply: string, repo: string): Omit<PrState, "carried" | "changed" | "behindBy">;
 export {};

package/dist/pr/state.js

@@ -8,7 +8,7 @@ export const QUERY = `query($owner: String!, $name: String!, $number: Int!) {
   repository(owner: $owner, name: $name) {
     pullRequest(number: $number) {
       url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName baseRefName baseRefOid
-      viewerDidAuthor mergeCommit { oid }
+      baseRef { target { oid } } viewerDidAuthor mergeCommit { oid }
       reviewThreads(first: 100) { nodes { id isResolved isOutdated path line
         comments(first: 1) { nodes { author { login } body } }
         latest: comments(last: 1) { nodes { viewerDidAuthor } } } }
@@ -232,6 +232,7 @@ export function parsePr(reply, repo) {
     const rollup = childOrNull(commit, "statusCheckRollup");
     const mergeCommit = childOrNull(pr, "mergeCommit");
     const head = string(pr, "headRefOid");
+    const baseRef = childOrNull(pr, "baseRef");
     return {
         url: string(pr, "url"),
         repo,
@@ -246,7 +247,7 @@ export function parsePr(reply, repo) {
         headCommittedAt: time(commit, "committedDate"),
         branch: string(pr, "headRefName"),
         base: string(pr, "baseRefName"),
-        baseOid: string(pr, "baseRefOid"),
+        baseOid: baseRef === null ? string(pr, "baseRefOid") : string(child(baseRef, "target"), "oid"),
         mergeCommit: mergeCommit === null ? null : string(mergeCommit, "oid"),
         checks: rollup === null ? [] : nodes(rollup, "contexts").map((context) => checkOf(context, repo)),
         unresolvedThreads: nodes(pr, "reviewThreads")

package/dist/worker/herdr.d.ts

@@ -0,0 +1,48 @@
+import { type JsonObject } from "../json-text.ts";
+/** What stops a `worker` command before it acts: exit 2, the problem and, when there is one, its remedy. */
+export declare class Refusal extends Error {
+    remedy: string | undefined;
+    constructor(message: string, remedy?: string);
+}
+export type Called = {
+    status: number;
+    stdout: string;
+    stderr: string;
+};
+/** The first line of a tool's output that says anything, or the exit it ended with. */
+export declare function said(called: Called): string;
+/** `tool args` as a child process; a tool that is not on PATH stops the command. */
+export declare function call(tool: "hc" | "herdr-app", args: string[]): Called;
+/** The JSON object `hc <args>` prints; a failing call or a reply that is no object stops the command. */
+export declare function hcObject(args: string[]): JsonObject;
+/** What an error says, whatever was thrown. */
+export declare function describe(error: unknown): string;
+/** Reports a `Refusal` of `command` on stderr and answers exit 2; any other error is a bug and goes on up. */
+export declare function refuse(command: string, error: unknown): number;
+/** The option `flag` as a whole number from `min`, `fallback` when the command line leaves it out. */
+export declare function wholeNumber(flag: string, value: string | undefined, fallback: number, min: number): number | {
+    error: string;
+};
+/** The terminal the command runs in, which is the Lead of the Workers it starts or reads. */
+export declare function lead(): string;
+export type Worker = {
+    name: string;
+    address: string;
+    /** herdr's state: live or finished. */
+    state: string;
+    /** What the Worker reports (idle, working, done, blocked, error), `finished` once it has ended, `unknown` before it reports. */
+    status: string;
+    /** The folder it was launched in, or the one it works in once `workingFolders` has asked herdr. */
+    folder: string;
+};
+/** Whether herdr still runs the Worker's terminal; the one test of it every command shares. */
+export declare function isLive(worker: Worker): boolean;
+/**
+ * The Workers with the folder each live one works in, its worktree, which `hc get` reports as
+ * `foreground.cwd` and `hc ls` leaves out. A Worker herdr cannot tell it for keeps its launch folder.
+ */
+export declare function workingFolders(workers: Worker[]): Worker[];
+/** The Workers `lead` started, in the order herdr lists them; `all` adds the finished ones. */
+export declare function workersOf(leadId: string, all: boolean): Worker[];
+/** A table of rows, every column but the last padded to its widest cell and two spaces apart. */
+export declare function table(rows: string[][]): string;

package/dist/worker/herdr.js

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

package/dist/worker/tabs.d.ts

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

package/dist/worker/tabs.js

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

package/package.json

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