halfcycle 0.4.5 → 0.4.7

package/dist/close-phase.d.ts

@@ -38,7 +38,7 @@
  * note. The service freezes both into the phase's Build Record; the caller fetches
  * that record afterwards (`build-record/obtain.ts`).
  */
-import { type AcceptanceOutcome, type PhaseCloseDecision } from '@halfcycle/events';
+import { type AcceptanceOutcome, type MethodUpdate, type PhaseCloseDecision } from '@halfcycle/events';
 import { type PhaseStampFailure, type RepoCredential } from './open-phase.js';
 /**
  * Whether the commit this phase closed at could be read, and if so the full hash
@@ -76,6 +76,13 @@ export interface ClosedPhase {
     stampFailure: PhaseStampFailure | null;
     /** The commit sent with the close, or why none could be read. */
     closeCommit: CloseCommitOutcome;
+    /**
+     * The method version this close moved the project to (`existing-projects-carry-on`
+     * AC2), or `null` when it did not move. An older control's answer carries no
+     * field at all, which reads the same as `null` here — this CLI then prints
+     * and writes nothing about a move, exactly as it did before this field existed.
+     */
+    methodUpdated: MethodUpdate | null;
 }
 /**
  * Read the full HEAD commit of the NAMED repository, before the close is sent.

package/dist/close-phase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"close-phase.d.ts","sourceRoot":"","sources":["../src/close-phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAmB,KAAK,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAG/F;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElG;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,4EAA4E;AAC5E,eAAO,MAAM,aAAa,EAAE,gBAAkE,CAAC;AAE/F,uFAAuF;AACvF,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,YAAY,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACvC,iEAAiE;IACjE,WAAW,EAAE,kBAAkB,CAAC;CACjC;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,kBAAkB,CA4BhF;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;aAExB,MAAM,EAAE,MAAM;IAE9B;;;;;OAKG;aACa,OAAO,CAAC,EAAE,MAAM;IAChC;;;;;;;;;;OAUG;aACa,IAAI,CAAC,EAAE,MAAM;gBApBb,MAAM,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM;IACf;;;;;OAKG;IACa,OAAO,CAAC,EAAE,MAAM,YAAA;IAChC;;;;;;;;;;OAUG;IACa,IAAI,CAAC,EAAE,MAAM,YAAA;CAKhC;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,UAAU,CAC9B,UAAU,EAAE,cAAc,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,kBAAkB,EACzB,IAAI,CAAC,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,GAAE,gBAAgC,GACvC,OAAO,CAAC,WAAW,CAAC,CAyEtB"}
+{"version":3,"file":"close-phase.d.ts","sourceRoot":"","sources":["../src/close-phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAmB,KAAK,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAG/F;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElG;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,4EAA4E;AAC5E,eAAO,MAAM,aAAa,EAAE,gBAAkE,CAAC;AAE/F,uFAAuF;AACvF,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,YAAY,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACvC,iEAAiE;IACjE,WAAW,EAAE,kBAAkB,CAAC;IAChC;;;;;OAKG;IACH,aAAa,EAAE,YAAY,GAAG,IAAI,CAAC;CACpC;AAcD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,kBAAkB,CA4BhF;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;aAExB,MAAM,EAAE,MAAM;IAE9B;;;;;OAKG;aACa,OAAO,CAAC,EAAE,MAAM;IAChC;;;;;;;;;;OAUG;aACa,IAAI,CAAC,EAAE,MAAM;gBApBb,MAAM,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM;IACf;;;;;OAKG;IACa,OAAO,CAAC,EAAE,MAAM,YAAA;IAChC;;;;;;;;;;OAUG;IACa,IAAI,CAAC,EAAE,MAAM,YAAA;CAKhC;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,UAAU,CAC9B,UAAU,EAAE,cAAc,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,kBAAkB,EACzB,IAAI,CAAC,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,GAAE,gBAAgC,GACvC,OAAO,CAAC,WAAW,CAAC,CAiFtB"}

package/dist/draw/index.d.ts

@@ -0,0 +1,135 @@
+/**
+ * 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) and of
+ * `draw phase <phase>` (System view · E2, feature `draw-phase-picture`, AC1 and AC5).
+ *
+ * THE ORDER IS THE SPEC'S. (1) read and check `docs/system.json`; for a phase, read and
+ * check its plan in the same stage's `beforeSend`, through `plan`'s own
+ * `readAndCheckPlan` (`../plan.ts`), never a copy of it; then the place and the files in
+ * the way; (2) report the description and get its version — both through `system`'s
+ * own first stage, `checkAndReportDescription` (`../system-report.ts`), never a copy of
+ * it; for a phase, then report the plan through `DrawDeps.reportPlan`, `plan`'s own
+ * request (`reportPhasePlan`), sending the very plan `beforeSend` checked, never a
+ * second read of the file; (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 (`embedImageLink`,
+ * `./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.
+ *
+ * A PHASE'S FILES. The base name is `phaseDiagramBase(phase)`, `renderPhaseSegment`'s
+ * segment. A phase that is not a valid identity is refused naming it, before anything
+ * is read; so is one whose base name ends in the Flight Deck word, in any case, whose
+ * Broadsheet files would take another phase's Flight Deck names.
+ *
+ * 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.
+ * For a phase, the plan route and the draw route's phase arm ship in one service
+ * release, so a missing plan route is the one signal that this service cannot draw
+ * phase pictures, and the draw route is then never asked. 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 and the base name this module chose from
+ * the arguments.
+ *
+ * WHAT LEAVES THE MACHINE. The checked description (through the shared stage); for a
+ * phase, the checked plan (through `plan`'s request); then only the draw request,
+ * `{ version, picture: 'architecture' }` or `{ picture: 'phase', phase, planVersion }`.
+ *
+ * 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, type SystemDrawRequest } from '@halfcycle/events';
+import type { RepoCredential } from '../open-phase.js';
+import { type PlanDeps } from '../plan.js';
+import { type SystemDeps, type SystemRun } from '../system-report.js';
+import { type DiagramBaseName, type DiagramSet, type DiagramWriteResult, type EmbeddingDoc } from './write.js';
+export { ARCHITECTURE_BASE, ARCHITECTURE_NAME, DIAGRAM_DIR_REL, DIAGRAM_FILES, DIAGRAM_MARKER_LINE, EMBEDDED_LOOK, baseTakesFlightDeckNames, checkPictures, diagramRel, embedImageLink, embedImageName, markdownLinkName, phaseDiagramBase, pictureNames, pngOf, svgOf, diagramPaths, writeDiagramSet, type DiagramBaseName, } from './write.js';
+/** The usage line, printed for anything but `architecture` or `phase <phase>`. */
+export declare const DRAW_USAGE = "npx halfcycle@latest draw (architecture | phase <phase>) [--repo <root>]";
+/** Which picture: the whole system's, or one phase's plan on it. */
+export type DrawPicture = {
+    kind: 'architecture';
+} | {
+    kind: 'phase';
+    phase: string;
+};
+/**
+ * What the arguments after `draw` came to: the picture and the repository root to work
+ * in, or usage. `architecture` alone, or `phase` followed by exactly one phase, plus at
+ * most one `--repo <root>`; anything else, including no argument and `phase` with no
+ * name, is usage. The phase is not checked here: a name that cannot be a phase is the
+ * verb's to refuse, by name.
+ */
+export type DrawArgs = {
+    ok: true;
+    picture: DrawPicture;
+    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 the picture `request` names. 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, request: SystemDrawRequest): Promise<DrawOutcome>;
+/**
+ * The pieces `runDraw` reaches outside itself through; replaced in tests. `reportPlan`
+ * is `plan`'s own request, used only for a phase.
+ */
+export interface DrawDeps extends SystemDeps {
+    readonly reportPlan: PlanDeps['reportPlan'];
+    readonly draw: (credential: RepoCredential, request: SystemDrawRequest) => Promise<DrawOutcome>;
+    readonly write: (repoRoot: string, base: DiagramBaseName, set: DiagramSet) => DiagramWriteResult;
+}
+/**
+ * What a picture is pasted as: the document it goes in, and the image's alt text.
+ * The architecture's goes directly under `docs/`; a phase's in its own document in
+ * `docs/phases/`.
+ */
+export type PasteTarget = {
+    doc: EmbeddingDoc;
+    alt: string;
+    base: DiagramBaseName;
+};
+/** The architecture's paste target. */
+export declare const ARCHITECTURE_PASTE: PasteTarget;
+/** A phase's paste target: `Phase <name>`, in `docs/phases/`. */
+export declare function phasePaste(phase: string): PasteTarget;
+/** The Markdown to paste into the document `target` names, and the line before it. */
+export declare function pasteLines(mermaid: string, target: PasteTarget): 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, picture: DrawPicture, 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":"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"}

package/dist/draw/write.d.ts

@@ -0,0 +1,282 @@
+/**
+ * The pictures writer — what `draw architecture` and `draw phase` write 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; widened to a base name by
+ * E2, feature `draw-phase-picture` AC5).
+ *
+ * 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 a BASE NAME with a constant extension. A base name is a
+ * `DiagramBaseName`, and only two things make one: `ARCHITECTURE_BASE` (the constant
+ * `architecture`) and `phaseDiagramBase(phase)` (`renderPhaseSegment`'s segment, the
+ * one home of a phase's file segment). The type is branded, so a string from anywhere
+ * else, a response included, does not compile where a base name is asked for. The
+ * response contributes file CONTENTS only; nothing in it is ever joined, resolved or
+ * compared as a path. `DiagramPaths` is built by `diagramPaths(repoRoot, base)` alone.
+ *
+ * Every rule below is stated for the architecture's names, which are the base name
+ * `architecture`; a phase's are the same with its base name in their place.
+ *
+ * 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 `pictureNames(base)`, a table 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 (`embedImageLink`) 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 PhaseIdentity, 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 architecture picture's name; also its Mermaid file's name. */
+export declare const ARCHITECTURE_NAME = "architecture";
+declare const diagramBaseBrand: unique symbol;
+/**
+ * The name a set of five files is built from. Branded so only the two makers below
+ * produce one: a plain string, a response's included, is a compile error where a base
+ * name is asked for (INV-023).
+ */
+export type DiagramBaseName = string & {
+    readonly [diagramBaseBrand]: true;
+};
+/** The architecture's base name. */
+export declare const ARCHITECTURE_BASE: DiagramBaseName;
+/**
+ * A phase's base name: `renderPhaseSegment(phase)`, so `notifications` gives
+ * `phase-notifications`. Throws on an invalid identity, as that function does; the
+ * verb checks the identity first and reports it rather than throwing.
+ */
+export declare function phaseDiagramBase(phase: PhaseIdentity): DiagramBaseName;
+/**
+ * Would this base name's Broadsheet files take another set's Flight Deck names?
+ * `phase-a.flightdeck.png` is phase `a`'s Flight Deck picture, so a base name ending in
+ * the Flight Deck word, in any case (a case-insensitive file system would collide
+ * too), is refused before anything is sent.
+ */
+export declare function baseTakesFlightDeckNames(base: DiagramBaseName): boolean;
+/**
+ * Each look's file name, before its extension: Broadsheet takes the bare base name,
+ * Flight Deck the base 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 function pictureNames(base: DiagramBaseName): 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's file name in `docs/diagrams`: `architecture.png`. Composed
+ * from the same table as that file's path, so the printed image line and the file
+ * cannot name different pictures.
+ */
+export declare function embedImageName(base: DiagramBaseName): string;
+/**
+ * Where the document the picture is pasted into sits: directly under `docs/` (the
+ * architecture's), or in `docs/phases/` (a phase's).
+ */
+export type EmbeddingDoc = 'docs' | 'docs/phases';
+/**
+ * A file name as a Markdown link target: percent-encoded (`encodeURIComponent`), and
+ * `(` and `)` too, which would otherwise end the link.
+ */
+export declare function markdownLinkName(name: string): string;
+/**
+ * The embedded picture as a document at `doc` links it: `diagrams/architecture.png`
+ * from `docs/`, `../diagrams/phase-notifications.png` from `docs/phases/`. The file
+ * name is the one `embedImageName` gives, encoded for a link.
+ */
+export declare function embedImageLink(base: DiagramBaseName, doc: EmbeddingDoc): 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, base: DiagramBaseName): DiagramPaths;
+/** A file's place as a person finds it: `docs/diagrams/architecture.svg`. */
+export declare function diagramRel(base: DiagramBaseName, 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(base: DiagramBaseName, 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, base: DiagramBaseName): 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, base: DiagramBaseName, set: DiagramSet, io?: RecordPairIo): DiagramWriteResult;
+export {};
+//# 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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"}