@mutmutco/installer-face 0.4.1 → 0.4.2

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+# 0.4.2
+
+- Preserve rollback and log facts, including retry guidance for early failures.
+- Isolate injected output observers while keeping terminal and filesystem failures visible.
+- Generate embedded-runtime convergence from a declaration without global npm installation.
+
 # 0.4.1
 
 - Capture bootstrap output and validate recorded installer transcripts.

package/README.md

@@ -27,12 +27,17 @@ URL, canonical doctor command, and a nonempty unique surface list
 `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.
+For an embedded-runtime product, supply `installedRuntime: { entry, package, installRootEnv }`;
+`converge` then contains entry arguments rather than a binary name. The shared entry resolves the
+installed product and re-enters it with `--payload` and `--installed`, without invoking npm.
 
 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.
+arm, verify-release and rollback. 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.
+total, updated, failed and optional retry, dryRun, installed, deferred, operationFailed and safe detail.
+Failure facts can include rollback (`completed`, `partial`, `not-needed`, `unknown`), logPath,
+or logState (`unavailable`, `omitted`). Early operation failures retain retry guidance even with zero surfaces.
 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”.
 
@@ -46,6 +51,9 @@ redacted in transcripts. `relay(text, channel)` and `milestone({step,state,ms})`
 child diagnostics: never pass authentication responses, credentials or raw provider errors.
 
 TTY, color, width, environment, animation and output sink can be injected through options.
+Omit `write` for production terminal output and worker animation during synchronous work.
+An injected `write` observer uses timer animation; its exceptions are retained in `run.errors`.
+Default terminal writes and transcript/outcome filesystem failures remain operation errors.
 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;

package/dist/index.js

@@ -794,7 +794,7 @@ import { appendFileSync as appendFileSync2 } from "node:fs";
 // src/outcome.ts
 import { readFileSync, writeFileSync } from "node:fs";
 var counts = ["total", "updated", "failed"];
-var strings = ["version", "retry", "detail"];
+var strings = ["version", "retry", "detail", "logPath"];
 var flags = ["dryRun", "installed", "deferred", "operationFailed"];
 function validateInstallerOutcome(value) {
   const invalid = () => {
@@ -802,12 +802,15 @@ function validateInstallerOutcome(value) {
   };
   if (!value || typeof value !== "object" || Array.isArray(value)) return invalid();
   const facts = value;
-  const allowed = [...counts, ...strings, ...flags];
+  const allowed = [...counts, ...strings, ...flags, "rollback", "logState"];
   if (Object.keys(facts).some((key) => !allowed.includes(key))) return invalid();
   for (const key of counts) if (!Number.isSafeInteger(facts[key]) || facts[key] < 0) return invalid();
   if (facts.updated + facts.failed > facts.total) return invalid();
   for (const key of strings) if (facts[key] !== void 0 && (typeof facts[key] !== "string" || facts[key].length > 4096)) return invalid();
   for (const key of flags) if (facts[key] !== void 0 && typeof facts[key] !== "boolean") return invalid();
+  if (facts.rollback !== void 0 && !["completed", "partial", "not-needed", "unknown"].includes(facts.rollback)) return invalid();
+  if (facts.logState !== void 0 && !["unavailable", "omitted"].includes(facts.logState)) return invalid();
+  if (facts.logPath !== void 0 && (!facts.logPath.trim() || /[\x00-\x1f\x7f]/u.test(facts.logPath))) return invalid();
   return { ...facts };
 }
 function writeInstallerOutcome(path, value) {
@@ -880,7 +883,8 @@ var PHASES = {
   verify: ["Verifying the payload", "Verified the payload"],
   install: ["Installing the product", "Installed the product"],
   activate: ["Activating surfaces", "Activated surfaces"],
-  doctor: ["Checking health", "Checked health"]
+  doctor: ["Checking health", "Checked health"],
+  rollback: ["Restoring the previous version", "Restored the previous version"]
 };
 function createInstallerRun(value, options = {}) {
   const declaration = validateInstallerProduct(value);
@@ -893,9 +897,16 @@ function createInstallerRun(value, options = {}) {
     env,
     color: tty && options.color !== false && env.NO_COLOR === void 0
   });
-  const write = options.write ?? ((text, channel) => {
+  const errors = [];
+  const write = options.write ? (text, channel) => {
+    try {
+      options.write(text, channel);
+    } catch (error) {
+      errors.push(`installer output observer: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  } : (text, channel) => {
     (channel === "stdout" ? process.stdout : process.stderr).write(text);
-  });
+  };
   const emit = (text, channel = "stdout", recorded = text) => {
     if (!text) return;
     write(text, channel);
@@ -930,6 +941,9 @@ function createInstallerRun(value, options = {}) {
     if (rendered) lines([tty ? rendered : `${kind === "fail" ? "Failed: " : ""}${title}${measure === null ? "" : ` (${typeof measure === "number" ? `${Math.max(0, Math.round(measure))}s` : measure})`}`]);
   };
   const run = {
+    get errors() {
+      return [...errors];
+    },
     start,
     phase(id, facts = {}) {
       if (finished) throw new Error("installer run already finished");
@@ -995,7 +1009,9 @@ function createInstallerRun(value, options = {}) {
         changed,
         ...facts.failed ? [`Failed ${facts.failed} of ${facts.total} surfaces.`] : [],
         ...facts.detail ? [facts.detail] : [],
-        facts.retry && facts.failed ? `Retry:  ${facts.retry}` : `Check health any time:  ${declaration.doctor}`
+        ...facts.rollback ? [`Rollback: ${facts.rollback}`] : [],
+        ...facts.logPath ? [`Log: ${facts.logPath}`] : facts.logState ? [`Log: ${facts.logState}`] : [],
+        facts.retry && (facts.failed > 0 || facts.operationFailed) ? `Retry:  ${facts.retry}` : `Check health any time:  ${declaration.doctor}`
       ];
       if (!face.nested || !env.MM_INSTALLER_OUTCOME_FILE && (facts.failed > 0 || facts.operationFailed)) {
         lines(tty ? face.receipt(body, { ready }) : body.map((row) => row.replace(/^[✔✖●]  /u, "")));
@@ -1021,7 +1037,7 @@ async function runInstaller(value, operation, options) {
 }
 
 // src/payload.ts
-function renderPayloadEntry({ tarballs, converge, shippedFlag }) {
+function renderPayloadEntry({ tarballs, converge, shippedFlag, installedRuntime }) {
   if (!Array.isArray(tarballs) || tarballs.length === 0 || tarballs.some((name) => typeof name !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*\.tgz$/u.test(name))) {
     throw new Error("installer payload: tarballs must be relative .tgz basenames");
   }
@@ -1031,6 +1047,47 @@ function renderPayloadEntry({ tarballs, converge, shippedFlag }) {
   if (shippedFlag !== void 0 && !/^--[a-z][a-z0-9-]*$/u.test(shippedFlag)) {
     throw new Error("installer payload: invalid shipped flag");
   }
+  if (installedRuntime !== void 0) {
+    if (!installedRuntime || typeof installedRuntime.entry !== "string" || typeof installedRuntime.package !== "string" || !/^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/u.test(installedRuntime.entry) || installedRuntime.entry.split("/").some((part) => part === "." || part === "..") || !/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/u.test(installedRuntime.package) || installedRuntime.package.split("/").some((part) => part === "." || part === "..") || !Array.isArray(installedRuntime.installRootEnv) || installedRuntime.installRootEnv.some((name) => !/^[A-Z][A-Z0-9_]*$/u.test(name))) {
+      throw new Error("installer payload: invalid installed runtime");
+    }
+    if (shippedFlag) throw new Error("installer payload: installed runtime reads its own payload manifest");
+    return String.raw`// Generated by @mutmutco/installer-face. Uses the installed product, never a registry.
+import { spawnSync } from 'node:child_process';
+import { statSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+
+const runtime = ${JSON.stringify(installedRuntime)};
+const argv = process.argv.slice(2);
+const at = argv.indexOf('--payload');
+const payloadDir = resolve(at >= 0 && argv[at + 1] ? argv[at + 1] : dirname(process.argv[1]));
+const productDir = dirname(payloadDir);
+const packaged = join('node_modules', runtime.package);
+const candidates = [
+  ...runtime.installRootEnv.map((name) => process.env[name]),
+  productDir, join(productDir, 'app'), join(productDir, 'current'),
+  join(productDir, packaged), payloadDir, join(payloadDir, packaged),
+];
+const root = candidates.find((candidate) => {
+  if (!candidate) return false;
+  try { return statSync(join(candidate, runtime.entry)).isFile(); }
+  catch (error) { if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return false; throw error; }
+});
+if (!root) {
+  process.stderr.write('Installer payload has no installed product to converge: ' + payloadDir + '\n');
+  process.exitCode = 1;
+} else {
+  const viaLauncher = !/^node(\.exe)?$/iu.test(basename(process.execPath));
+  const args = [...(viaLauncher ? ['--run'] : []), join(root, runtime.entry),
+    ...${JSON.stringify(converge)}, '--payload', payloadDir, '--installed', root];
+  const child = spawnSync(process.execPath, args, { cwd: root, stdio: 'inherit', windowsHide: true });
+  if (child.error) {
+    process.stderr.write('Installer could not re-enter the installed product: ' + child.error.message + '\n');
+    process.exitCode = 1;
+  } else process.exitCode = child.status === null ? 1 : child.status;
+}
+`;
+  }
   return String.raw`// Generated by @mutmutco/installer-face. Product code declares operations, never this program.
 import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';

package/dist/payload.d.ts

@@ -3,5 +3,12 @@ export interface PayloadEntryOptions {
     tarballs: string[];
     converge: string[];
     shippedFlag?: string;
+    /** Converge an already installed product through this launcher's embedded runtime.
+     *  In this mode converge contains the entry's arguments, without a binary name. */
+    installedRuntime?: {
+        entry: string;
+        package: string;
+        installRootEnv: string[];
+    };
 }
-export declare function renderPayloadEntry({ tarballs, converge, shippedFlag }: PayloadEntryOptions): string;
+export declare function renderPayloadEntry({ tarballs, converge, shippedFlag, installedRuntime }: PayloadEntryOptions): string;

package/dist/run.d.ts

@@ -24,6 +24,7 @@ declare const PHASES: {
     readonly install: readonly ["Installing the product", "Installed the product"];
     readonly activate: readonly ["Activating surfaces", "Activated surfaces"];
     readonly doctor: readonly ["Checking health", "Checked health"];
+    readonly rollback: readonly ["Restoring the previous version", "Restored the previous version"];
 };
 export type InstallerPhase = keyof typeof PHASES;
 export type InstallerChannel = 'stdout' | 'stderr' | 'spinner';
@@ -35,6 +36,8 @@ export interface InstallerRunOptions {
     columns?: number;
     env?: Readonly<NodeJS.ProcessEnv>;
     animate?: boolean;
+    /** Optional output observer. Exceptions are recorded in run.errors, never operation failures.
+     *  Omit for production terminal output: the default worker animates during synchronous work. */
     write?: (text: string, channel: InstallerChannel) => void;
 }
 export interface InstallerFinish {
@@ -48,6 +51,9 @@ export interface InstallerFinish {
     detail?: string;
     deferred?: boolean;
     operationFailed?: boolean;
+    rollback?: 'completed' | 'partial' | 'not-needed' | 'unknown';
+    logPath?: string;
+    logState?: 'unavailable' | 'omitted';
 }
 export interface InstallerPhaseFacts {
     state?: 'running' | StepKind;
@@ -65,6 +71,7 @@ export interface InstallerSurfaceFacts {
 }
 /** One owner for the entire run. Callers supply measured facts, never terminal prose. */
 export declare function createInstallerRun(value: unknown, options?: InstallerRunOptions): {
+    readonly errors: readonly string[];
     start: () => void;
     phase(id: InstallerPhase, facts?: InstallerPhaseFacts): void;
     surface(facts: InstallerSurfaceFacts): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/installer-face",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "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",