@mutmutco/installer-face 0.2.1 → 0.4.1

package/dist/maintenance.d.ts

@@ -0,0 +1,52 @@
+import { type InstallerRun } from './run.js';
+/** Facts produced by a product's convergence engine. No terminal labels or layout. */
+export interface MaintenanceArm {
+    surface: string;
+    from: string | null;
+    to: string;
+    verdict: 'ok' | 'skip' | 'defer' | 'fail';
+    detail: string;
+    repeatFailure?: boolean;
+    launchStaged?: boolean;
+}
+export interface MaintenanceSummary {
+    target: string | null;
+    surfaces: {
+        id: string;
+        present: boolean;
+        action: string;
+    }[];
+    exit: number;
+    detail?: string;
+    deferred?: boolean;
+    reexec: {
+        dist: string;
+        target: string;
+        from: string | null;
+    } | null;
+}
+/** One install/update lifecycle, including scheduler ordering and self-update continuation. */
+export declare function runMaintenance<S extends MaintenanceSummary>(product: unknown, args: string[], dependencies: {
+    engine: (options: {
+        dryRun: boolean;
+        shippedTarget?: string;
+        narrate?: (line: string) => void;
+        onTargetResolved?: (target: string, gate: string | null) => void;
+        onPhase?: (line: string) => void;
+        onArm?: (arm: MaintenanceArm) => void;
+    }) => Promise<S>;
+    counts: (summary: S) => {
+        total: number;
+        updated: number;
+        failed: number;
+        retry: number;
+    };
+    diagnose: (arm: MaintenanceArm) => string | undefined;
+    schedule: () => {
+        ok: boolean;
+        detail: string;
+    };
+    handOff: (next: NonNullable<S['reexec']>, args: string[], env: NodeJS.ProcessEnv) => number;
+    shippedTarget?: string;
+    run?: InstallerRun;
+}): Promise<number>;

package/dist/outcome.d.ts

@@ -0,0 +1,6 @@
+import type { InstallerFinish } from './run.js';
+export type InstallerOutcome = InstallerFinish;
+/** Child facts cross a process boundary; unknown fields and inconsistent counts are errors. */
+export declare function validateInstallerOutcome(value: unknown): InstallerOutcome;
+export declare function writeInstallerOutcome(path: string, value: unknown): void;
+export declare function readInstallerOutcome(path: string): InstallerOutcome | undefined;

package/dist/payload.d.ts

@@ -0,0 +1,7 @@
+/** Product declarations provide operations; this package owns the executable payload entry. */
+export interface PayloadEntryOptions {
+    tarballs: string[];
+    converge: string[];
+    shippedFlag?: string;
+}
+export declare function renderPayloadEntry({ tarballs, converge, shippedFlag }: PayloadEntryOptions): string;

package/dist/products.d.ts

@@ -5,6 +5,12 @@ export interface ProductIdentity {
     readonly accent: string;
     /** The warm line under the welcome. Verbatim from the guidebook; never composed at a call site. */
     readonly warm: string;
+    readonly installWarm: string;
+    /**
+     * The product's own health command, as the guidebook writes it. It is the ONE suggested command
+     * the receipt closes with, so it is data here rather than a string each surface retypes (#6895).
+     */
+    readonly doctor: string;
 }
 export declare const PRODUCTS: Readonly<Record<string, ProductIdentity>>;
 /** The identity for a product key. An unknown key is a caller bug, and failing here is cheaper than

package/dist/run.d.ts

@@ -0,0 +1,86 @@
+import { type StepKind, type StepMeasure } from './face.js';
+export interface InstallerProduct {
+    product: string;
+    gate: string;
+    doctor: string;
+    surfaces: {
+        id: string;
+        npm?: string;
+        bin?: string;
+        kind?: string;
+        activation?: string;
+    }[];
+}
+export declare function validateInstallerProduct(value: unknown): InstallerProduct;
+declare const PHASES: {
+    readonly preflight: readonly ["Checking prerequisites", "Checked prerequisites"];
+    readonly resolve: readonly ["Resolving the release", "Resolved the release"];
+    readonly download: readonly ["Downloading the payload", "Downloaded the payload"];
+    readonly 'sign-in': readonly ["Signing in", "Signed in"];
+    readonly check: readonly ["Checking surfaces", "Checked surfaces"];
+    readonly arm: readonly ["Scheduling updates", "Armed hourly updates"];
+    readonly 'verify-release': readonly ["Checking the release version", "Verified the release version"];
+    readonly verify: readonly ["Verifying the payload", "Verified the payload"];
+    readonly install: readonly ["Installing the product", "Installed the product"];
+    readonly activate: readonly ["Activating surfaces", "Activated surfaces"];
+    readonly doctor: readonly ["Checking health", "Checked health"];
+};
+export type InstallerPhase = keyof typeof PHASES;
+export type InstallerChannel = 'stdout' | 'stderr' | 'spinner';
+export interface InstallerRunOptions {
+    operation?: 'install' | 'update';
+    tty?: boolean;
+    dryRun?: boolean;
+    color?: boolean;
+    columns?: number;
+    env?: Readonly<NodeJS.ProcessEnv>;
+    animate?: boolean;
+    write?: (text: string, channel: InstallerChannel) => void;
+}
+export interface InstallerFinish {
+    version?: string;
+    total: number;
+    updated: number;
+    failed: number;
+    retry?: string;
+    dryRun?: boolean;
+    installed?: boolean;
+    detail?: string;
+    deferred?: boolean;
+    operationFailed?: boolean;
+}
+export interface InstallerPhaseFacts {
+    state?: 'running' | StepKind;
+    seconds?: number;
+    measure?: StepMeasure;
+    detail?: string;
+}
+export interface InstallerSurfaceFacts {
+    id: string;
+    from?: string | null;
+    to?: string | null;
+    state: 'updated' | 'current' | 'failed' | 'skipped' | 'retry' | 'pending' | 'kept';
+    seconds?: number;
+    detail?: string;
+}
+/** One owner for the entire run. Callers supply measured facts, never terminal prose. */
+export declare function createInstallerRun(value: unknown, options?: InstallerRunOptions): {
+    start: () => void;
+    phase(id: InstallerPhase, facts?: InstallerPhaseFacts): void;
+    surface(facts: InstallerSurfaceFacts): void;
+    milestone({ step, state, ms }: {
+        step: string;
+        state: StepKind;
+        ms?: number;
+    }): void;
+    signIn({ url, code }: {
+        url: string;
+        code: string;
+    }): void;
+    relay(text: string, channel?: InstallerChannel, record?: boolean): void;
+    finish(facts: InstallerFinish): void;
+    stop(): void;
+};
+export type InstallerRun = ReturnType<typeof createInstallerRun>;
+export declare function runInstaller(value: unknown, operation: (run: InstallerRun) => Promise<InstallerFinish>, options?: InstallerRunOptions): Promise<InstallerFinish>;
+export {};

package/dist/spinner.d.ts

@@ -1,9 +1,9 @@
-import type { Face } from './face.js';
+import type { Face, StepMeasure } from './face.js';
 export interface Spinner {
-    /** Begin animating against this title. Safe to call again to restart. */
-    start(text: string): void;
-    /** Change the title without restarting the animation. */
-    say(text: string): void;
+    /** Begin animating against this title, optionally carrying the right-column measure. */
+    start(text: string, measure?: StepMeasure): void;
+    /** Change the title, and the measure, without restarting the animation. */
+    say(text: string, measure?: StepMeasure): void;
     /** Stop and CLEAR the line. Always call before writing the durable step line. */
     stop(): void;
 }
@@ -14,13 +14,10 @@ export interface SpinnerOptions {
     stream?: NodeJS.WritableStream;
     /** Frame interval in ms. */
     intervalMs?: number;
+    /** Default stderr lane records worker frames here without involving the main event loop. */
+    transcriptPath?: string;
 }
-/**
- * A spinner that occupies the STEP LINE's glyph column, so the durable line that replaces it lands
- * at the same place — one left edge, not two. It renders through `face.step(text, null, 'note')`
- * rather than composing a line of its own, which means it inherits TITLE_COLUMN and cannot drift
- * from it when the face changes.
- */
-export declare function createSpinner(face: Face, { animate, stream, intervalMs }: SpinnerOptions): Spinner;
+/** Shared formatting, with a worker for stderr and a timer for injected streams. */
+export declare function createSpinner(face: Face, { animate, stream, intervalMs, transcriptPath }: SpinnerOptions): Spinner;
 /** The frames, exported so a conformance check can recognise transient output. */
 export declare const SPINNER_FRAMES: readonly string[];

package/dist/transcript.d.ts

@@ -0,0 +1,3 @@
+import { type ConformanceOptions } from './conformance.js';
+/** Check durable output and optionally compare every captured record exactly. */
+export declare function assertInstallerTranscript(jsonl: string, options: ConformanceOptions, reference?: string): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/installer-face",
-  "version": "0.2.1",
+  "version": "0.4.1",
   "description": "The MM Terminal Line installer face: one renderer, the canonical product table, shell/PowerShell fragments for served one-liners, and the drift guard every surface runs.",
   "type": "module",
   "license": "UNLICENSED",