@mutmutco/installer-face 0.2.1 → 0.4.1

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# 0.4.1
+
+- Capture bootstrap output and validate recorded installer transcripts.
+- Preserve one final receipt across native bootstrap continuation.
+- Use completed phase labels and retain transcript framing.
+
+# 0.4.0
+
+- Own maintenance ordering and outcomes from a validated product declaration.
+- Share payload entry generation instead of embedding per-product installer scripts.
+- Keep one console owner across nested installation and self-update handoff.
+- Carry deferred and failed child outcomes across Windows shims.
+- Record channel-tagged transcripts with authentication data excluded.
+- Enforce completed-run conformance and preserve narrow-terminal diagnostics.

package/README.md

@@ -15,26 +15,67 @@ Jerv-Hub wrote this renderer, MM-Strategy copied it, and the copy immediately fo
 breaking its own two-space rule. Four copies are four drifts waiting, and prose cannot stop drift;
 only shared code and a shared guard can.
 
-## Use
+## Use the shared run
+
+Product install/update entrypoints call `runMaintenance(declaration, args, engines)`.
+The package owns phase ordering, self-update handoff, scheduler completion, outcome reporting and
+cleanup. Product engines return version, surface and failure facts; they do not draw a run.
+The declaration contains the canonical product key (`mmi` and `jerv` aliases are accepted), gate
+URL, canonical doctor command, and a nonempty unique surface list
+`{ id, npm?, bin?, kind?, activation? }`.
+
+`createInstallerRun` is the lower-level owner used by the shared launcher, not a reason for each
+product to author another installer. `renderPayloadEntry` generates the npm-install/converge entry
+from tarball names and a declared convergence command. Product release scripts supply those facts.
+
+The package owns greeting, phase names, spinner, surface status, receipt and sign-off.
+`phase` accepts preflight, resolve, download, verify, install, activate, doctor, sign-in, check,
+arm and verify-release. Its facts are state (running/ok/fail/note), seconds, measure and safe detail.
+`surface` accepts updated/current/failed/skipped/retry/pending/kept. `finish` accepts version,
+total, updated, failed and optional retry, dryRun, installed, deferred and safe detail.
+Missing version or deferred work never reports ready. Counts must describe the same operation set.
+Pass `dryRun: true` in options so individual rows also say “would update”.
+
+`operation: "install"` selects the canonical first-install welcome.
+`start()` and `finish()` are idempotent. `stop()` clears transient work. The orchestration wrapper
+always stops the spinner, including when an operation throws; the caller retains error handling.
+Use the manual lifecycle for a self-reexec that transfers final receipt ownership to its child.
+
+`signIn({url, code})` owns device-login instructions. The code is visible in the terminal and
+redacted in transcripts. `relay(text, channel)` and `milestone({step,state,ms})` accept only safe
+child diagnostics: never pass authentication responses, credentials or raw provider errors.
+
+TTY, color, width, environment, animation and output sink can be injected through options.
+Non-TTY output is plain append-only text. NO_COLOR disables color, not the visual structure.
+Nested processes suppress greetings and send their final outcome to the console owner.
+The private outcome channel works through Windows command shims as well as direct child processes;
+a successful process exit never turns a deferred result into readiness.
+Animations never write milestones. `MM_FACE_TRANSCRIPT` appends JSONL `{channel,text}` records
+for emitted output, preserving ANSI and stdout/stderr/spinner channels. Capture the owning outer
+run for the console transcript. Untrusted external output is displayed but represented by an
+omission marker in saved transcripts; authentication output cannot be a golden reference.
+Transcripts are opt-in and must never contain secrets. A recorded fixture is not evidence of a
+real signed-in advertised installer run; that acceptance remains a separate human check.
+
+The lower-level `createFace` API remains for doctor rows and compatibility. New installer consumers
+must not compose their own lifecycle from its primitives.
+
+### Self re-exec continuation
+
+A process that re-execs itself onto an inherited console sets `MM_FACE_CONTINUES` to the
+comma-separated phase names already drawn. `createFace` reads it directly: `welcome()` returns no
+lines, and each `face.continues(phase, kind)` consumes one inherited phase. A failure always returns
+false and consumes the inherited phase, so neither it nor a later retry can be hidden.
 
 ```ts
-import { createFace, assertFaceConformance } from '@mutmutco/installer-face';
-
-const face = createFace({
-  product: 'jerv-hub',
-  color: Boolean(process.stdout.isTTY && !process.env.NO_COLOR && process.env.TERM !== 'dumb'),
-  columns: process.stdout.columns,
-});
-
-for (const line of face.welcome()) console.log(line);
-console.log(face.step('Registering MCP server', 2));
-console.log(face.relay(childOutput));          // another program's output, inside the rail
-for (const line of face.receipt([...])) console.log(line);
-console.log(face.signOff());
+if (!face.continues('preflight', result.ok ? 'ok' : 'fail')) {
+  console.log(face.step('preflight', result.seconds, result.ok ? 'ok' : 'fail'));
+}
 ```
 
-Colour is a DECISION the caller passes in, never sniffed here: the same face is used by processes
-whose stdout is a pipe, and a face drawn into a pipe is the bug this package exists to prevent.
+The optional `env` input exists for tests; normal callers use `process.env`. Missing or empty means a
+fresh face. Only an inheriting spawn sets the variable — never a person starting a wrapped command
+on a fresh console.
 
 ### Served one-liners
 

package/dist/conformance.d.ts

@@ -4,6 +4,14 @@ export interface ConformanceOptions {
     columns?: number;
     /** False asserts the PLAIN lane: no colour, and no glyphs or frames at all. */
     tty?: boolean;
+    /**
+     * True asserts the NESTED lane — a run under `MM_OUTER_CONSOLE=1`, where an outer program already
+     * opened the console and will close it. Steps and failures still print; a greeting, a success
+     * receipt or a sign-off from here is the duplicate face the owner saw on 2026-09-20 (#6893).
+     */
+    nested?: boolean;
+    /** Assert a completed human run, not a single renderer fragment. */
+    complete?: boolean;
 }
 /**
  * Assert a rendered surface against the contract. `lines` is what the surface actually printed,

package/dist/face.d.ts

@@ -38,17 +38,48 @@ export declare function faceWidth(columns?: number): number;
 /** Break at word boundaries, hard-slicing a token longer than the line itself. */
 export declare function wrapWords(text: string, width: number): string[];
 export type StepKind = 'ok' | 'fail' | 'note';
+/**
+ * What the RIGHT column carries (#6895, owner 2026-09-20).
+ *
+ * One column, one rule: progress while the work runs, elapsed time when it finishes. A number is
+ * measured seconds and renders as `2s`; a string is the surface's own measure and renders verbatim
+ * (`6.9 MB`, `3.1/6.9 MB`). Before this there were two visual languages — a right-aligned time for
+ * steps and a homegrown `[████░░] 42%` bar for downloads — and no ASCII bar returns with it.
+ */
+export type StepMeasure = number | string | null;
+export interface ReceiptOptions {
+    /**
+     * False when the run did NOT reach ready. A failure always prints, in every lane — suppressing it
+     * would hide a failed install behind someone else's box (#6810, #6858).
+     */
+    ready?: boolean;
+}
 export interface Face {
     readonly identity: ProductIdentity;
     readonly width: number;
-    /** `◆ <product> — Mutatis Mutandis` and the product's own warm line. */
+    /**
+     * True when an OUTER console owns this run's outcome (`MM_OUTER_CONSOLE=1`). Read it to skip work
+     * that only the console owner should do — animating a spinner, printing a summary of its own.
+     */
+    readonly nested: boolean;
+    /** True when finished steps leave as milestones on the parent's channel instead of being drawn. */
+    readonly emitsProgress: boolean;
+    /** `◆ <product> — Mutatis Mutandis` and the product's own warm line; empty on a continuation. */
     welcome(): string[];
-    /** One durable line for one finished step: glyph, title, and a measured time when truthful. */
-    step(title: string, seconds?: number | null, kind?: StepKind): string;
+    /** Consume one phase inherited through MM_FACE_CONTINUES; failures are always new information. */
+    continues(phase: string, kind?: StepKind): boolean;
+    /** One durable line for one finished step: glyph, title, and the right-column measure. */
+    step(title: string, measure?: StepMeasure, kind?: StepKind): string;
+    /**
+     * The canonical success receipt, composed from the product table: `✔  <name> is ready.`, the one
+     * fact the surface alone knows, and the table's own health command. A surface supplies ONLY what
+     * changed — the other two lines are never retyped at a call site (#6895).
+     */
+    outcome(changed: string, options?: ReceiptOptions): string[];
     /** Another program's output, kept inside the face at the step-title column. */
     relay(text: string): string;
-    /** The closing box: what changed, and one suggested command. */
-    receipt(lines: string[] | string): string[];
+    /** The closing box: what changed, and one suggested command. Empty when an outer console owns it. */
+    receipt(lines: string[] | string, options?: ReceiptOptions): string[];
     /** The sign-off, in the product accent. */
     signOff(): string;
     /** A refusal that reads as a face line rather than a bare error string. */
@@ -56,9 +87,12 @@ export interface Face {
     paint(sgr: string, text: string): string;
 }
 export interface FaceOptions {
+    operation?: 'install' | 'update';
     product: string;
     /** False emits no escape codes at all, so a piped or logged run is byte-stable plain text. */
     color?: boolean;
     columns?: number;
+    /** Injectable only so tests do not mutate process.env; normal callers inherit process.env. */
+    env?: Readonly<NodeJS.ProcessEnv>;
 }
-export declare function createFace({ product, color, columns }: FaceOptions): Face;
+export declare function createFace({ product, color, columns, env, operation }: FaceOptions): Face;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { createFace, faceWidth, stripColor, visibleWidth, wrapWords, GLYPH, PALETTE, TITLE_COLUMN } from './face.js';
-export type { Face, FaceOptions, StepKind } from './face.js';
+export type { Face, FaceOptions, ReceiptOptions, StepKind, StepMeasure } from './face.js';
 export { PRODUCTS, identityFor } from './products.js';
 export type { ProductIdentity } from './products.js';
 export { renderShellFace, renderPowerShellFace } from './shell.js';
@@ -9,3 +9,12 @@ export { createSpinner, SPINNER_FRAMES } from './spinner.js';
 export type { Spinner, SpinnerOptions } from './spinner.js';
 export { assertFaceConformance, assertScriptConformance } from './conformance.js';
 export type { ConformanceOptions, ScriptConformanceOptions } from './conformance.js';
+export { createInstallerRun, validateInstallerProduct, runInstaller } from './run.js';
+export type { InstallerProduct, InstallerRun, InstallerRunOptions, InstallerPhase, InstallerPhaseFacts, InstallerSurfaceFacts, InstallerFinish, InstallerChannel } from './run.js';
+export { renderPayloadEntry } from './payload.js';
+export type { PayloadEntryOptions } from './payload.js';
+export { runMaintenance } from './maintenance.js';
+export type { MaintenanceArm, MaintenanceSummary } from './maintenance.js';
+export { validateInstallerOutcome, readInstallerOutcome, writeInstallerOutcome } from './outcome.js';
+export type { InstallerOutcome } from './outcome.js';
+export { assertInstallerTranscript } from './transcript.js';