halfcycle 0.4.4 → 0.4.6

package/dist/draw/index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The client half of `npx halfcycle@latest draw architecture` (System view · E1,
+ * feature `diagram-files-for-docs`, AC1, AC4, AC5, AC6 and AC8's missing route).
+ *
+ * THE ORDER IS THE SPEC'S. (1) read and check `docs/system.json`; (2) report it and
+ * get its version — both through `system`'s own first stage,
+ * `checkAndReportDescription` (`../system-report.ts`), never a copy of it; (3) ask the
+ * service to draw that version; (4) check all five files, every look's picture and the
+ * Mermaid, then write them; (5) print the Markdown, whose image line is the embedded
+ * look's PNG (`EMBED_IMAGE_REL`, `./write.ts`, composed from the same table as that
+ * file's path). The place and the files already there are checked on the machine
+ * before anything is sent, and again just before writing, so a refusal this command
+ * can make locally never costs a request, and a change made while it waited is still
+ * seen.
+ *
+ * ONE RESPONSE-HANDLING RULE, the Build Record path's. A body that parses under
+ * `systemDrawResultSchema` (`@halfcycle/events`, the one home of the shape) is
+ * authoritative, whatever its status. Otherwise the service's missing-route answer to
+ * this POST means it predates drawing — asked of `isMissingRoute`
+ * (`../missing-route.ts`), the one predicate, never a copy of its expression; a
+ * missing report route says the same, because either way this service cannot draw.
+ * Anything else is reported by its status and the service's own sentence.
+ *
+ * NO BYTE OF THE RESPONSE DECIDES A PATH (INV-023): the response gives contents only;
+ * where they go is `./write.ts`'s constants.
+ *
+ * WHAT LEAVES THE MACHINE. The checked description (through the shared stage), then
+ * only `{ version, picture: 'architecture' }`.
+ *
+ * INV-001: Node builtins, the global `fetch`, `@halfcycle/events` and `@halfcycle/core`
+ * only. SHIPS TO CLIENT DISK inside the CLI: every string here is a sentence a person
+ * reads, so none names an internal register, route or setting; no comment sits beside
+ * an object member.
+ */
+import { type SystemDrawDrawn } from '@halfcycle/events';
+import type { RepoCredential } from '../open-phase.js';
+import { type SystemDeps, type SystemRun } from '../system-report.js';
+import { type DiagramSet, type DiagramWriteResult } from './write.js';
+export { ARCHITECTURE_NAME, DIAGRAM_DIR_REL, DIAGRAM_FILES, DIAGRAM_MARKER_LINE, EMBED_IMAGE_REL, EMBEDDED_LOOK, PICTURE_NAMES, checkPictures, diagramRel, pngOf, svgOf, diagramPaths, writeDiagramSet, } from './write.js';
+/** The usage line, printed for any argument but `architecture`. */
+export declare const DRAW_USAGE = "npx halfcycle@latest draw architecture [--repo <root>]";
+/**
+ * What the arguments after `draw` came to: the repository root to work in, or usage.
+ * Exactly one positional, `architecture`, and at most one `--repo <root>`; anything
+ * else, including no argument, is usage. A phase name never reaches here in E1.
+ */
+export type DrawArgs = {
+    ok: true;
+    repoRoot: string | undefined;
+} | {
+    ok: false;
+};
+export declare function parseDrawArgs(argv: readonly string[]): DrawArgs;
+/**
+ * What came of asking for the drawing. `drawn`: the Mermaid and every look's picture,
+ * parsed under the strict result schema (so no look is missing and none is extra) but
+ * not yet checked. `refused`: the service's reason. `no-route`: this service cannot draw yet.
+ * `unavailable`: it could not be drawn, and `why` says so.
+ */
+export type DrawOutcome = {
+    kind: 'drawn';
+    drawn: SystemDrawDrawn;
+} | {
+    kind: 'refused';
+    reason: string;
+} | {
+    kind: 'no-route';
+} | {
+    kind: 'unavailable';
+    why: string;
+};
+/** The address the drawing is asked of: the engagement is one path segment, encoded once. */
+export declare function systemDrawUrl(credential: RepoCredential): string;
+/**
+ * Ask the service to draw `version`. Never throws: the network, the service and an
+ * answer this CLI cannot read are each an outcome the caller prints.
+ */
+export declare function requestDrawing(credential: RepoCredential, version: number): Promise<DrawOutcome>;
+/** The pieces `runDraw` reaches outside itself through; replaced in tests. */
+export interface DrawDeps extends SystemDeps {
+    readonly draw: (credential: RepoCredential, version: number) => Promise<DrawOutcome>;
+    readonly write: (repoRoot: string, set: DiagramSet) => DiagramWriteResult;
+}
+/** The Markdown to paste into a document directly under `docs/`, and the line before it. */
+export declare function pasteLines(mermaid: string): string;
+/**
+ * The whole verb, in the order the module header gives. Exit 0 only when the five
+ * files are written or already up to date and the Markdown is printed.
+ */
+export declare function runDraw(repoRoot: string, deps: DrawDeps): Promise<SystemRun>;
+//# sourceMappingURL=index.d.ts.map

package/dist/draw/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/draw/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAkD,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGzG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAA6B,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACjG,OAAO,EAWL,KAAK,UAAU,EACf,KAAK,kBAAkB,EACxB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,aAAa,EACb,aAAa,EACb,UAAU,EACV,KAAK,EACL,KAAK,EACL,YAAY,EACZ,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,mEAAmE;AACnE,eAAO,MAAM,UAAU,2DAA2D,CAAC;AAEnF;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC;AAElF,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,QAAQ,CAiB/D;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,eAAe,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC,6FAA6F;AAC7F,wBAAgB,aAAa,CAAC,UAAU,EAAE,cAAc,GAAG,MAAM,CAEhE;AAUD;;;GAGG;AACH,wBAAsB,cAAc,CAAC,UAAU,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAmDtG;AAED,8EAA8E;AAC9E,MAAM,WAAW,QAAS,SAAQ,UAAU;IAC1C,QAAQ,CAAC,IAAI,EAAE,CAAC,UAAU,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IACrF,QAAQ,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,KAAK,kBAAkB,CAAC;CAC3E;AAMD,4FAA4F;AAC5F,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CASlD;AAYD;;;GAGG;AACH,wBAAsB,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,CAiElF"}

package/dist/draw/write.d.ts

@@ -0,0 +1,232 @@
+/**
+ * The architecture pictures writer — what `draw architecture` writes into the person's
+ * repository (System view · E1, feature `diagram-files-for-docs`, AC4, AC5, AC6 and
+ * the "someone else's file in the way" behaviour).
+ *
+ * NO BYTE OF THE RESPONSE DECIDES A PATH (INV-023). Every path here is composed from
+ * `repoRoot` (the caller's `--repo` or the working directory), the constant directory
+ * `docs/diagrams` and the constant name `architecture` with a constant extension. The
+ * response contributes file CONTENTS only; nothing in it is ever joined, resolved or
+ * compared as a path. `DiagramPaths` is built by `diagramPaths(repoRoot)` alone.
+ *
+ * FIVE FILES, ONE TABLE. Each look in `SYSTEM_PICTURE_THEMES` (`@halfcycle/events`, the
+ * one list of looks) has a PNG and an SVG; the Mermaid is one file, because Mermaid has
+ * no look. A look selects its file name from `PICTURE_NAMES`, a constant typed against
+ * `SystemPictureTheme`, so a look the list does not hold has no name and the compiler
+ * refuses a look the table forgets. The looks are iterated from the list, never from
+ * the response's keys: the strict result schema already refused any other key, and
+ * this module would not read one if it came. Which look documents embed is
+ * `EMBEDDED_LOOK`, and only there: the printed image line (`EMBED_IMAGE_REL`) is
+ * composed from the same file-name table as that look's path, so the line and the file
+ * cannot name different pictures.
+ *
+ * THE REALPATH CHECK (AC5). Before anything is made or written, the realpath of the
+ * nearest existing ancestor of `docs/diagrams` must lie inside the realpath of the
+ * repository. "Exists" is asked with `lstat`, so a dangling link is the ancestor and
+ * its failed realpath refuses, rather than being stepped over as absent. A planted
+ * `docs` link pointing out of the repository therefore refuses before `mkdir`. The
+ * same check runs again on `docs/diagrams` itself after `mkdir`, before the first file
+ * is created, so a directory made through a link cannot be written into. RESIDUAL: a
+ * process racing this one, swapping a directory for a link between that second check
+ * and a rename, is not closed by a userspace check; the window is a few syscalls.
+ *
+ * IN THE WAY (the spec's ownership rule). The command writes only files it recognises
+ * as its own: an SVG whose first line is the marker. Any SVG without the marker is
+ * named and nothing is written. Each PNG is ours only beside ITS OWN marked SVG
+ * (`architecture.png` with `architecture.svg`, `architecture.flightdeck.png` with
+ * `architecture.flightdeck.svg`), never another look's. The Mermaid file is ours only
+ * beside the embedded look's marked SVG, `architecture.svg`, the one whose name it
+ * shares. Anything at one of the five paths that is not a regular file (a link, a
+ * folder) is in the way too: replacing a link would silently turn it into a file, and
+ * following one would write somewhere this check never looked.
+ *
+ * LEFTOVER TEMPORARIES, BY THE SAME RULE. A run that dies (killed, power cut) between
+ * staging and its last rename leaves `<name>.tmp` files with no chance to clear them.
+ * Each one is judged by the rule its final file is judged by, one rule for both: an
+ * SVG temporary is ours if its first line is the marker; a PNG temporary is ours only
+ * beside its own look's marked SVG, at the final path or as that SVG's own marked
+ * temporary; the Mermaid temporary likewise only beside the embedded look's marked SVG
+ * or its marked temporary. Anything else at a temporary path (a person's own file,
+ * unmarked or unpaired, or anything that is not a regular file) is in the way, named,
+ * and never deleted. Ours are removed just before staging, so the exclusive create
+ * below never meets one and never has to delete a file it did not create. They are
+ * not removed on an up-to-date run, which touches no file (AC6); a dead run's
+ * temporaries always sit beside a final file that differs from them, so the same
+ * description run again is never up to date while they remain. RESIDUAL: a death
+ * between the create and the first byte written leaves an empty SVG temporary, which
+ * carries no marker and so is named as in the way; the window is one syscall.
+ *
+ * ALL OR NOTHING (AC4). Every check on the five files runs before any file is touched.
+ * Then each changed file is written to `<name>.tmp` beside it, every temporary first,
+ * and renamed into place one by one. If a rename fails, every file already renamed
+ * gets its previous bytes back, or is removed if it did not exist before; a file that
+ * cannot be put back is removed and named. The SVGs are renamed FIRST on purpose, then
+ * the PNGs, then the Mermaid (`DIAGRAM_FILES`'s order), and every SVG temporary is
+ * staged before any PNG or Mermaid one: if the process dies at any point, every PNG
+ * and Mermaid file or temporary it left has its owning marked SVG (final or temporary)
+ * already there, so the next run recognises all of it as its own, clears the
+ * temporaries and writes.
+ *
+ * UP TO DATE (AC6). Each of the five files' bytes is compared with the new bytes first,
+ * and an equal file is not written at all, so an unchanged description leaves every
+ * modification time as it was.
+ *
+ * ONE SEAM. The file operations go through `RecordPairIo`, the Build Record writer's
+ * seam (`../build-record/write.ts`), widened to take bytes, so the exclusive create
+ * has one implementation and a test can fail any one rename.
+ *
+ * INV-001: Node builtins, `@halfcycle/events` and this package only. SHIPS TO CLIENT
+ * DISK inside the CLI: every string here is a sentence a person reads, and no comment
+ * sits beside an object member.
+ */
+import { type SystemDrawDrawn, type SystemPictureTheme } from '@halfcycle/events';
+import { type RecordPairIo } from '../build-record/write.js';
+/** The one directory the pictures go in, relative to the repository root, `/`-separated. */
+export declare const DIAGRAM_DIR_REL = "docs/diagrams";
+/** The one picture name E1 draws; also the Mermaid file's name. */
+export declare const ARCHITECTURE_NAME = "architecture";
+/**
+ * Each look's file name, before its extension: Broadsheet takes the bare name, Flight
+ * Deck the name with its look after it. Typed against the one list of looks, so the
+ * table cannot hold a look the list does not, or miss one it does.
+ */
+export declare const PICTURE_NAMES: Readonly<Record<SystemPictureTheme, string>>;
+/**
+ * The look documents embed, and the only place that choice is made. Its PNG is the
+ * printed image line, and its SVG is the one the Mermaid file sits beside.
+ */
+export declare const EMBEDDED_LOOK: SystemPictureTheme;
+/**
+ * The first line of every SVG this command writes, and the only thing that makes an
+ * existing SVG ours. The service prepends it; the CLI checks it before writing and
+ * reads it on the next run. Its one home is the description contract.
+ */
+export declare const DIAGRAM_MARKER_LINE = "<!-- drawn by Halfcycle from docs/system.json -->";
+/** One look's SVG or PNG. */
+export type PictureFile = `${SystemPictureTheme}.svg` | `${SystemPictureTheme}.png`;
+/** Which of the five files: a look's SVG or PNG, or the one Mermaid file. */
+export type DiagramFile = PictureFile | 'mmd';
+/** A look's SVG. */
+export declare function svgOf(look: SystemPictureTheme): PictureFile;
+/** A look's PNG. */
+export declare function pngOf(look: SystemPictureTheme): PictureFile;
+/**
+ * The five files, in the order they are renamed: every SVG, then every PNG, then the
+ * Mermaid, as the module header says why.
+ */
+export declare const DIAGRAM_FILES: readonly DiagramFile[];
+/**
+ * The embedded picture as a document directly under `docs/` names it:
+ * `diagrams/architecture.png`. Composed from the same table as that file's path.
+ */
+export declare const EMBED_IMAGE_REL: string;
+/** The fixed paths, composed from `repoRoot` and constants only. */
+export interface DiagramPaths {
+    readonly repoRoot: string;
+    readonly dir: string;
+    readonly file: Readonly<Record<DiagramFile, string>>;
+}
+export declare function diagramPaths(repoRoot: string): DiagramPaths;
+/** A file's place as a person finds it: `docs/diagrams/architecture.svg`. */
+export declare function diagramRel(which: DiagramFile): string;
+/**
+ * The five files in the order a person reads them: each look's PNG then its SVG, then
+ * the Mermaid file.
+ */
+export declare const DIAGRAM_FILES_AS_LISTED: readonly DiagramFile[];
+/** `a`, `a and b`, `a, b and c`: a list as a sentence says it. */
+export declare function spokenList(items: readonly string[]): string;
+/**
+ * What the place the pictures go came to. `ok`: safe to write there. Otherwise the
+ * sentence to print, already naming the remedy.
+ */
+export type PlaceCheck = {
+    ok: true;
+} | {
+    ok: false;
+    why: string;
+};
+/**
+ * THE REALPATH CHECK (AC5), as the module header states it: the nearest ancestor of
+ * `docs/diagrams` that `lstat` finds must resolve inside the repository and be a
+ * folder. Run before anything is sent and again before anything is made.
+ */
+export declare function checkDiagramPlace(paths: DiagramPaths): PlaceCheck;
+/** What is at the five paths now. `null`: nothing. Bytes: a regular file's contents. */
+export type ExistingSet = Readonly<Record<DiagramFile, Uint8Array | null>>;
+/**
+ * What reading the existing set came to: the set and which leftover temporaries are
+ * ours to clear, or the first file in the way (`temp`: the temporary beside it).
+ */
+export type ExistingRead = {
+    ok: true;
+    existing: ExistingSet;
+    ourTemps: readonly DiagramFile[];
+} | {
+    ok: false;
+    inTheWay: DiagramFile;
+    temp: boolean;
+};
+/**
+ * Read what is at the five paths and at their five temporaries, and apply the one
+ * ownership rule to both, as the module header states it. The final files are judged
+ * first, in the order that names the deciding file: every SVG, then each PNG against
+ * its own look's SVG, then the Mermaid file against the embedded look's SVG. Then the
+ * temporaries in the same order, where a PNG or Mermaid temporary's owner may be the
+ * marked SVG at its final path or that SVG's own marked temporary. Anything that is not
+ * a regular file, final or temporary, is in the way.
+ */
+export declare function readExistingSet(paths: DiagramPaths): ExistingRead;
+/** The sentence for a file in the way, or for the temporary file beside it when `temp`. */
+export declare function inTheWayLine(which: DiagramFile, temp?: boolean): string;
+/** The five files as bytes, checked and ready to write. */
+export type DiagramSet = Readonly<Record<DiagramFile, Uint8Array>>;
+/** What checking the drawn pictures came to: the bytes, or what was wrong, in plain words. */
+export type PictureCheck = {
+    ok: true;
+    set: DiagramSet;
+} | {
+    ok: false;
+    why: string;
+};
+/**
+ * AC4's checks on what the service drew, all before anything is written, for each look
+ * in the list: the PNG's signature and decoded size; the SVG's marker line, its `<svg`
+ * start and `</svg>` end (one newline allowed after), and its size. Then the Mermaid's
+ * `flowchart` start and its size, once. The sizes are the events package's bounds,
+ * checked again on the bytes about to be written rather than trusted from the parse.
+ * Each sentence names the file the bad bytes were for, so a person reading it knows
+ * which picture was wrong.
+ */
+export declare function checkPictures(drawn: SystemDrawDrawn): PictureCheck;
+/**
+ * What writing came to. `up-to-date`: every file already held these bytes and none
+ * was touched. `written`: the files in `changed` were replaced or created.
+ * `in-the-way` / `unsafe`: refused before anything was made, with the sentence.
+ * `failed`: a write failed; every file is as it was, except those in `removed`, which
+ * could not be put back and were removed.
+ */
+export type DiagramWriteResult = {
+    kind: 'up-to-date';
+} | {
+    kind: 'written';
+    changed: DiagramFile[];
+} | {
+    kind: 'in-the-way';
+    file: DiagramFile;
+    temp: boolean;
+} | {
+    kind: 'unsafe';
+    why: string;
+} | {
+    kind: 'failed';
+    file: DiagramFile;
+    removed: DiagramFile[];
+};
+/**
+ * Write the checked pictures into `docs/diagrams`, all or nothing, as the module
+ * header states. Never throws for a file-system failure: it is a `failed` result,
+ * and the set on disk is the old one.
+ */
+export declare function writeDiagramSet(repoRoot: string, set: DiagramSet, io?: RecordPairIo): DiagramWriteResult;
+//# sourceMappingURL=write.d.ts.map

package/dist/draw/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/draw/write.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1356,7 +1356,7 @@ function createProjectIdentityFile(targetRepoRoot) {
 }
 
 // dist/install-manifest.js
-import { Buffer } from "node:buffer";
+import { Buffer as Buffer2 } from "node:buffer";
 import { createHash } from "node:crypto";
 var INSTALL_MANIFEST_REL = ".halfcycle/install-manifest.json";
 var INSTALL_MANIFEST_FORMAT = "halfcycle-install-manifest/v1";
@@ -1367,7 +1367,7 @@ function lineKey(line) {
   return line.endsWith("\r") ? line.slice(0, -1) : line;
 }
 function fileSha256(bytes) {
-  const text = typeof bytes === "string" ? bytes : Buffer.from(bytes).toString("utf-8");
+  const text = typeof bytes === "string" ? bytes : Buffer2.from(bytes).toString("utf-8");
   return sha256Hex(text.split("\n").map(lineKey).join("\n"));
 }
 function canonicalJson(value) {
@@ -1813,6 +1813,8 @@ var WRITE_ALLOWLIST = [
   BUNDLE_PIN_REL,
   ".halfcycle/bin",
   "docs/build-records",
+  // Architecture pictures the draw command writes from Halfcycle's answer. The installer never writes here; keep the entry so this path stays declared as one Halfcycle writes.
+  "docs/diagrams",
   "test/fixtures/captured",
   MCP_REGISTRATION_REL,
   ".gitattributes",
@@ -3889,10 +3891,14 @@ function assertInsideOutDir(outDir, candidate, identity) {
     throw new InvalidPhaseIdentityError(identity, BUILD_RECORD_DIR);
   }
 }
-function createExclusiveOnDisk(path, text) {
+function createExclusiveOnDisk(path, data) {
+  const bytes = typeof data === "string" ? Buffer.from(data, "utf-8") : data;
   const fd = openSync(path, "wx");
   try {
-    writeSync(fd, text);
+    let written = 0;
+    while (written < bytes.length) {
+      written += writeSync(fd, bytes, written, bytes.length - written);
+    }
   } catch (err) {
     closeSync(fd);
     rmSync3(path, { force: true });
@@ -4009,6 +4015,22 @@ function replaceOne(io, tmp, finalPath, text) {
 
 // dist/build-record/obtain.js
 import { relative as relative3 } from "node:path";
+
+// dist/missing-route.js
+var MESSAGE = {
+  GET: /^Route GET .* not found\.$/s,
+  POST: /^Route POST .* not found\.$/s
+};
+function isMissingRoute(method, status, body) {
+  if (status !== 404 || typeof body !== "object" || body === null)
+    return false;
+  const { error, message } = body;
+  if (error !== "Not Found" || typeof message !== "string")
+    return false;
+  return MESSAGE[method].test(message);
+}
+
+// dist/build-record/obtain.js
 var REFUSAL_FOLLOW_UP = {
   "still-open": "Nothing was written. The record is produced when the phase closes.",
   "reopened": "Nothing was written. A new record is produced when the phase closes again.",
@@ -4020,12 +4042,6 @@ var REFUSAL_REASONS = phaseRecordRefusalReasonSchema.options;
 function buildRecordUrl(credential, phase) {
   return `${credential.serviceUrl}/engagements/${encodeURIComponent(credential.engagementId)}/phases/${encodeURIComponent(phase)}/build-record`;
 }
-function isMissingRoute(status, body) {
-  if (status !== 404 || typeof body !== "object" || body === null)
-    return false;
-  const { error, message } = body;
-  return error === "Not Found" && typeof message === "string" && /^Route GET .* not found\.$/s.test(message);
-}
 async function obtainBuildRecord(credential, repoRoot, phase, io = NODE_RECORD_PAIR_IO) {
   const url = buildRecordUrl(credential, phase);
   let res;
@@ -4082,7 +4098,7 @@ async function obtainBuildRecord(credential, repoRoot, phase, io = NODE_RECORD_P
       headline: latestCloseHeadline(answer.record)
     };
   }
-  if (isMissingRoute(res.status, raw)) {
+  if (isMissingRoute("GET", res.status, raw)) {
     return { kind: "unavailable", why: "this Halfcycle service does not provide Build Records yet." };
   }
   const message = typeof raw === "object" && raw !== null && typeof raw.message === "string" ? raw.message : null;