dw-sdlc 0.20.0 → 0.21.1

package/dist/sweep-terminals.js

@@ -1,11 +1,10 @@
 // What a Sweep does with herdr terminals: it stops and removes only a Worker of its own whose turn has ended,
 // in a worktree that goes in the same Sweep or is already gone. docs/adr/0015 sets the bounds.
 import { existsSync, realpathSync } from "node:fs";
-import { isObject, parseObject } from "./json-text.js";
-import { shellLine } from "./pr/decide.js";
-import { CannotRun } from "./pr/read.js";
+import { CannotRun } from "./cannot-run.js";
+import { shellLine } from "./shell-line.js";
 import { worktreesOf } from "./sweep-trees.js";
-import { call, hcObject, isLive, Refusal, said, workersOf } from "./worker/herdr.js";
+import { isLive, listTerminals, readTerminal, removeTerminal, stopTerminal, workersOf } from "./worker/herdr.js";
 import { lockVerdict } from "./worktree-lock.js";
 /** Statuses of a Worker that is not at the end of its turn, with how the Sweep says it. */
 const AT_WORK = {
@@ -18,53 +17,30 @@ export function sweepingTerminal() {
     const id = process.env.HC_TERMINAL_ID;
     return id === undefined || id === "" ? undefined : id;
 }
-function word(value) {
-    return typeof value === "string" && value !== "" ? value : undefined;
-}
 /**
- * Each live terminal with the folder it works in, `hc get`'s foreground. An `hc get` that fails stops the
- * Sweep, since a terminal in a folder it cannot see must not count as absent; one gone since the listing is dropped.
+ * Each Worker with the folder it works in and its program's pid, as `hc get` reports them. One gone since the
+ * listing is dropped; an `hc get` that fails stops the Sweep, since a terminal in a folder it cannot see must
+ * not count as absent.
  */
-function foldersOf(list) {
-    return list.flatMap((worker) => {
+function located(workers) {
+    return workers.flatMap((worker) => {
         if (!isLive(worker)) {
             return [{ ...worker, pid: undefined }];
         }
-        const got = call("hc", ["get", worker.address, "--json"]);
-        if (got.status === 3) {
-            return [];
-        }
-        const parsed = got.status === 0 ? parseObject(got.stdout) : undefined;
-        if (parsed === undefined) {
-            throw new Refusal(`hc get ${worker.address} failed: ${got.status === 0 ? "its reply is no JSON object" : said(got)}`);
-        }
-        const { cwd, pid } = isObject(parsed.foreground) ? parsed.foreground : { cwd: undefined, pid: undefined };
-        const there = typeof cwd === "string" && cwd !== "" ? { ...worker, folder: cwd } : worker;
-        return [{ ...there, pid: typeof pid === "number" ? pid : undefined }];
+        const reading = readTerminal(worker.address);
+        return "gone" in reading ? [] : [{ ...worker, folder: reading.folder ?? worker.folder, pid: reading.pid }];
     });
 }
 /** The live terminals `hc ls` lists, each with the folder it works in. */
 function liveTerminals() {
-    const { terminals } = hcObject(["ls", "--json"]);
-    if (!Array.isArray(terminals)) {
-        throw new Refusal("hc ls answered no list of terminals", "check hc --version");
-    }
-    const places = new Map();
-    const listed = terminals.flatMap((entry) => {
-        const address = isObject(entry) ? word(entry.address) : undefined;
-        if (!isObject(entry) || address === undefined || typeof entry.cwd !== "string") {
-            throw new Refusal("hc ls answered a terminal without an address or a folder", "check hc --version");
+    return listTerminals().flatMap(({ address, name, folder, place }) => {
+        const reading = readTerminal(address);
+        if ("gone" in reading) {
+            return [];
         }
-        places.set(address, word(entry.where));
-        const name = word(entry.name) ?? address;
-        return [{ name, address, state: "live", status: word(entry.status) ?? "unknown", folder: entry.cwd }];
+        const working = reading.folder ?? folder;
+        return [{ address, name, folder: working, place: place ?? working }];
     });
-    return foldersOf(listed).map(({ name, address, folder }) => ({
-        name,
-        address,
-        folder,
-        place: places.get(address) ?? folder
-    }));
 }
 /**
  * Reads herdr for the sweeping terminal `own`: its Workers, finished ones included, and the other live
@@ -72,7 +48,7 @@ function liveTerminals() {
  */
 export function readTerminals(own) {
     try {
-        const workers = foldersOf(workersOf(own, true));
+        const workers = located(workersOf(own, true));
         const live = liveTerminals();
         const addresses = new Set(workers.map(({ address }) => address));
         return {
@@ -82,10 +58,7 @@ export function readTerminals(own) {
         };
     }
     catch (error) {
-        if (error instanceof Refusal) {
-            throw new CannotRun(error.message, error.remedy ?? "check hc, then call again");
-        }
-        throw error;
+        throw error instanceof CannotRun ? error.orRemedy("check hc, then call again") : error;
     }
 }
 function canonical(path) {
@@ -176,21 +149,12 @@ export function stopsOf(holders, tree) {
         : []);
 }
 /** Stops, if `item` asks, and removes its terminal; the words of the `hc` that refused, or undefined when it is gone. */
-export function removeTerminal(item) {
+export function takeDown(item) {
     try {
-        if (item.stop === true) {
-            const killed = call("hc", ["kill", item.name]);
-            // 11: the terminal finished between the read and the stop.
-            if (killed.status !== 0 && killed.status !== 11) {
-                return `hc kill ${item.name} failed: ${said(killed)}`;
-            }
-        }
-        const removed = call("hc", ["rm", item.name]);
-        // 3: the terminal is gone already.
-        return removed.status === 0 || removed.status === 3 ? undefined : `hc rm ${item.name} failed: ${said(removed)}`;
+        return (item.stop === true ? stopTerminal(item.name) : undefined) ?? removeTerminal(item.name);
     }
     catch (error) {
-        if (error instanceof Refusal) {
+        if (error instanceof CannotRun) {
             return error.message;
         }
         throw error;

package/dist/sweep-trees.d.ts

@@ -1,5 +1,11 @@
-/** `git <args>` at `root`, or a stop naming its problem. */
-export declare function must(root: string, args: string[]): string;
+/** The forced delete of `branch`, the dev's to run. */
+export declare function forcedDelete(branch: string): string;
+/** The forced removal of the worktree at `path`, the dev's to run; git wants --force twice for one still locked. */
+export declare function forcedRemoval(path: string, locked?: boolean): string;
+/** The unlock of the worktree at `path`, the dev's to run. */
+export declare function unlockCommand(path: string): string;
+/** The commit the local `branch` points at, or undefined once it is gone. */
+export declare function tipOf(root: string, branch: string): string | undefined;
 /** The local branches of the repository at `root`. */
 export declare function branchesOf(root: string): string[];
 export type Tree = {
@@ -9,14 +15,24 @@ export type Tree = {
     lock: string | undefined;
     prunable: boolean;
 };
-/** Every worktree of the repository, the main checkout first. */
+/** Every worktree of the repository, the main checkout first; -z leaves a path or a lock's reason unquoted. */
 export declare function worktreesOf(root: string): Tree[];
 /** The files `git status` lists in the worktree at `path`, ignored ones aside, or why it cannot be read. */
 export declare function dirtyFiles(path: string): string[] | {
     error: string;
 };
+/** What in the worktree at `path` a removal could lose, a paused operation or a file git status lists, or null. */
+export declare function whyUnclean(path: string, locked: boolean): {
+    reason: string;
+    command: string | null;
+} | null;
 /** The operation paused in the worktree at `path`: its git dir holds the state git resumes it from. */
 export declare function pausedOperation(path: string): string | undefined;
+/** The branch git keeps from a delete for the worktree `tree`, and why: checked out there, or a rebase of it paused there. */
+export declare function heldBranch(tree: Tree): {
+    branch: string;
+    reason: string;
+} | undefined;
 /** The dev's way off `branch`, checked out in the main checkout at `root`: null until it is Landed and nothing there could be lost. */
 export declare function switchOff(root: string, base: {
     name: string;

package/dist/sweep-trees.js

@@ -1,20 +1,27 @@
 // What a Sweep reads of a repository's branches and worktrees: where each worktree lies, what it has checked
-// out, its lock, the files that hold it and the operation paused in it, and the way off the main checkout's.
-import { existsSync } from "node:fs";
+// out, its lock, the files that hold it and the operation paused in it, and the way off the main checkout's;
+// beside them, the commands the dev runs for what the Sweep keeps.
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { exec } from "./exec.js";
-import { repositoryFreeEnv } from "./git-env.js";
+import { asked, git, must } from "./git.js";
 import { isLanded } from "./landed.js";
-import { shellLine } from "./pr/decide.js";
-import { CannotRun } from "./pr/read.js";
-import { asked, git } from "./working-tree.js";
-/** `git <args>` at `root`, or a stop naming its problem. */
-export function must(root, args) {
-    const result = git(root, args);
-    if ("error" in result) {
-        throw new CannotRun(result.error, "check the repository with git status");
-    }
-    return result.out;
+import { pausedIn } from "./paused-operation.js";
+import { shellLine } from "./shell-line.js";
+/** The forced delete of `branch`, the dev's to run. */
+export function forcedDelete(branch) {
+    return shellLine(["git", "branch", "-D", branch]);
+}
+/** The forced removal of the worktree at `path`, the dev's to run; git wants --force twice for one still locked. */
+export function forcedRemoval(path, locked = false) {
+    return shellLine(["git", "worktree", "remove", "--force", ...(locked ? ["--force"] : []), path]);
+}
+/** The unlock of the worktree at `path`, the dev's to run. */
+export function unlockCommand(path) {
+    return shellLine(["git", "worktree", "unlock", path]);
+}
+/** The commit the local `branch` points at, or undefined once it is gone. */
+export function tipOf(root, branch) {
+    return asked(root, ["rev-parse", "--verify", "-q", `refs/heads/${branch}^{commit}`]);
 }
 /** The local branches of the repository at `root`. */
 export function branchesOf(root) {
@@ -22,11 +29,11 @@ export function branchesOf(root) {
         .split("\n")
         .filter((name) => name !== "");
 }
-/** Every worktree of the repository, the main checkout first. */
+/** Every worktree of the repository, the main checkout first; -z leaves a path or a lock's reason unquoted. */
 export function worktreesOf(root) {
     const trees = [];
     let tree;
-    for (const line of must(root, ["worktree", "list", "--porcelain"]).split("\n")) {
+    for (const line of must(root, ["worktree", "list", "--porcelain", "-z"]).split("\0")) {
         if (line.startsWith("worktree ")) {
             tree = { path: line.slice("worktree ".length), head: "", branch: undefined, lock: undefined, prunable: false };
             trees.push(tree);
@@ -48,14 +55,12 @@ export function worktreesOf(root) {
 }
 /** The files `git status` lists in the worktree at `path`, ignored ones aside, or why it cannot be read. */
 export function dirtyFiles(path) {
-    const args = ["-C", path, "status", "--porcelain=v1", "-z", "--untracked-files=all"];
-    const result = exec("git", args, { env: repositoryFreeEnv() });
-    if (result.status !== 0) {
-        const said = result.stderr.split("\n").find((line) => line.trim() !== "");
-        return { error: `git status: ${said?.trim() ?? `exited ${result.status ?? "on a signal"}`}` };
+    const status = git(path, ["status", "--porcelain=v1", "-z", "--untracked-files=all"], { raw: true });
+    if ("error" in status) {
+        return status;
     }
     const files = [];
-    const entries = result.stdout.split("\0").filter((entry) => entry !== "");
+    const entries = status.out.split("\0").filter((entry) => entry !== "");
     for (let index = 0; index < entries.length; index++) {
         const entry = entries[index] ?? "";
         files.push(entry.slice(3));
@@ -65,18 +70,49 @@ export function dirtyFiles(path) {
     }
     return files;
 }
-const OPERATIONS = [
-    ["rebase-merge", "rebase"],
-    ["rebase-apply", "rebase or am"],
-    ["MERGE_HEAD", "merge"],
-    ["CHERRY_PICK_HEAD", "cherry-pick"],
-    ["REVERT_HEAD", "revert"],
-    ["BISECT_LOG", "bisect"]
-];
+/** What in the worktree at `path` a removal could lose, a paused operation or a file git status lists, or null. */
+export function whyUnclean(path, locked) {
+    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 };
+    }
+    return files.length === 0
+        ? null
+        : { reason: `modified or untracked: ${files.join(", ")}`, command: forcedRemoval(path, locked) };
+}
 /** The operation paused in the worktree at `path`: its git dir holds the state git resumes it from. */
 export function pausedOperation(path) {
     const dir = asked(path, ["rev-parse", "--absolute-git-dir"]);
-    return dir === undefined ? undefined : OPERATIONS.find(([file]) => existsSync(join(dir, file)))?.[1];
+    return dir === undefined ? undefined : pausedIn(dir);
+}
+/** The branch a rebase paused in the worktree at `path` works on; git lists that worktree as detached. */
+function rebasedBranch(path) {
+    const dir = asked(path, ["rev-parse", "--absolute-git-dir"]);
+    if (dir === undefined) {
+        return undefined;
+    }
+    for (const state of ["rebase-merge", "rebase-apply"]) {
+        const file = join(dir, state, "head-name");
+        const name = existsSync(file) ? readFileSync(file, "utf8").trim() : "";
+        if (name.startsWith("refs/heads/")) {
+            return name.slice("refs/heads/".length);
+        }
+    }
+    return undefined;
+}
+/** The branch git keeps from a delete for the worktree `tree`, and why: checked out there, or a rebase of it paused there. */
+export function heldBranch(tree) {
+    if (tree.branch !== undefined) {
+        return { branch: tree.branch, reason: `checked out in the worktree at ${tree.path}` };
+    }
+    const branch = rebasedBranch(tree.path);
+    return branch === undefined
+        ? undefined
+        : { branch, reason: `a rebase paused in the worktree at ${tree.path} holds it` };
 }
 /** The dev's way off `branch`, checked out in the main checkout at `root`: null until it is Landed and nothing there could be lost. */
 export function switchOff(root, base, branch) {

package/dist/worker/herdr.d.ts

@@ -1,24 +1,68 @@
-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;
+import { type Called } from "../exec.ts";
+/** A terminal as `hc ls --json` lists it. */
+export type Listed = {
+    address: string;
+    /** Its name, else its address. */
+    name: string;
+    /** The terminal that started it. */
+    parent: string | undefined;
+    /** herdr's state: live or finished. */
+    state: string;
+    /** The word it reports, undefined before it reports one. */
+    status: string | undefined;
+    /** The folder it was launched in. */
+    folder: string;
+    /** The place herdr shows it at: its space and tab. */
+    place: string | undefined;
+};
+/** A terminal as `hc get --json` reports it. */
+export type Reading = {
+    /** herdr's state: live or finished. */
+    state: string | undefined;
+    /** The state its program reports. */
+    status: string | undefined;
+    /** The herdr space it sits in, its `herdr.space` label. */
+    space: string | undefined;
+    /** Whether herdr sent its first message, and why not when it did not. */
+    firstMessage: {
+        sent: boolean;
+        reason: string | undefined;
+    } | undefined;
+    /** The folder its foreground program works in. */
+    folder: string | undefined;
+    /** That program's pid. */
+    pid: number | undefined;
+};
+/** `herdr-app args`, the window's CLI; one not on PATH, or past its limit, stops the command. */
+export declare function herdrApp(args: string[]): Called;
+/** The terminals `hc ls` lists: the live ones, every one with `all`, only those labelled `label` when given. */
+export declare function listTerminals(filter?: {
+    all?: boolean;
+    label?: string;
+}): Listed[];
+/** What `hc get` reports of the terminal at `address`, or `gone`, in hc's words, when herdr has no such terminal. */
+export declare function readTerminal(address: string): Reading | {
+    gone: string;
+};
+export type Start = {
+    name: string;
+    /** Its labels, each passed as `--label key=value` in order. */
+    labels: Record<string, string>;
+    /** The folder it starts in. */
+    cwd: string;
+    /** The program and its arguments. */
+    argv: string[];
+};
+/** Runs `argv` in a terminal of its own in the background, outliving its caller; the address hc gives it. */
+export declare function startTerminal({ name, labels, cwd, argv }: Start): string;
+/** Stops the terminal at `address`: hc's words when it refuses, undefined once it is stopped or had finished. */
+export declare function stopTerminal(address: string): string | undefined;
+/** Removes the terminal at `address`: hc's words when it refuses, undefined once it is gone. */
+export declare function removeTerminal(address: string): string | undefined;
+/** Types `message` into the terminal at `address`: `sent`, `blocked` while it sits on a dialog, else hc's words. */
+export declare function sendTo(address: string, message: string): "sent" | "blocked" | {
+    refused: 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;
@@ -38,11 +82,11 @@ export type Worker = {
 /** 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.
+ * The Workers with the folder each live one works in, its worktree, which `hc get` reports 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. */
+/** The Workers `leadId` 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;