@mutmutco/installer-face 0.4.2 → 0.4.3

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+# 0.4.3
+
+- Resolve freshly installed npm commands outside the inherited PATH.
+- Preserve typed engine phases, safe authentication relay and product JSON through shared maintenance.
+- Own quiet output, cancellation and failure diagnostics in the shared lifecycle.
+- Preserve mid-run authentication handoff, measured progress timing and terminal routing.
+- Use ASCII plain labels without changing Unicode paths, names or authorization URLs.
+
 # 0.4.2
 
 - Preserve rollback and log facts, including retry guidance for early failures.

package/README.md

@@ -20,6 +20,15 @@ only shared code and a shared guard can.
 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.
+Engines receive `onPhaseEvent({ id, state, detail?, measure?, measured? })` for phase facts.
+Repeated running progress retains the original start time; the package measures elapsed time.
+Typed `measured` facts carry percent, bytes, or a count with an optional total. Unknown totals stay unknown.
+Each completed phase needs its own verdict: starting another phase does not imply success.
+`relay(text, channel?, record?)` defaults to live-only output, keeping authorization URLs out of transcripts.
+Optional `jsonResult(summary, schedule)` preserves product machine output while the shared owner serializes it.
+`safeErrorDetail(error)` supplies an actionable, non-sensitive failure message; the default is generic.
+Scheduling and self-handoff callbacks are optional, but a requested handoff without an implementation fails.
+Return `cancelled: true` to end without readiness. The package also owns `--quiet` output selection.
 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? }`.
@@ -27,6 +36,7 @@ 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.
+The npm mode resolves that command from the global prefix after installation; it never relies on a refreshed PATH.
 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.
@@ -44,17 +54,24 @@ 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.
+Use the shared maintenance handoff for self-reexec. For a mid-engine authentication retry,
+`withCustody` pauses the shared output and supplies completed `faceContinues` phases to the product
+operation. Return `{ kind: "resume", value }` to continue, or `{ kind: "reexec", code }` when the
+child owns the final result. The shared owner resumes timing or transfers receipt ownership.
 
 `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.
+Maintenance callers can declare `render: { tty, color, columns, env, animate }` without supplying
+a writer or constructing a run. `--no-color`, `NO_COLOR`, and `TERM=dumb` disable color.
+The lower-level owner also accepts an output observer for tests.
 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.
+The shared plain lane uses ASCII labels and separators while preserving dynamic Unicode data.
+Do not transliterate paths or authorization URLs through a consumer output callback.
 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.

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export type { InstallerProduct, InstallerRun, InstallerRunOptions, InstallerPhas
 export { renderPayloadEntry } from './payload.js';
 export type { PayloadEntryOptions } from './payload.js';
 export { runMaintenance } from './maintenance.js';
-export type { MaintenanceArm, MaintenanceSummary } from './maintenance.js';
+export type { MaintenanceArm, MaintenanceSummary, MaintenancePhaseEvent, MaintenanceCustodyResult, MaintenanceEngineOptions, MaintenanceSchedule } from './maintenance.js';
 export { validateInstallerOutcome, readInstallerOutcome, writeInstallerOutcome } from './outcome.js';
 export type { InstallerOutcome } from './outcome.js';
 export { assertInstallerTranscript } from './transcript.js';

package/dist/index.js

@@ -655,7 +655,7 @@ function assertFaceConformance(lines, options) {
     }
   }
   if (rendered.length === 0) fail("R7 render before you ship", "no rendered lines were given to the guard");
-  const greetings = plain.filter((line) => line.includes(`${identity.name} \u2014 Mutatis Mutandis`));
+  const greetings = plain.filter((line) => ["\u2014", "-"].some((separator) => line.includes(`${identity.name} ${separator} Mutatis Mutandis`)));
   if (greetings.length > 1) fail("R8 one welcome per run", "duplicate product greeting");
   if (plain.filter((line) => line.startsWith(GLYPH.boxTop)).length > 1) {
     fail("R8 one receipt per run", "duplicate receipt");
@@ -895,7 +895,7 @@ function createInstallerRun(value, options = {}) {
     product: declaration.product,
     columns: options.columns,
     env,
-    color: tty && options.color !== false && env.NO_COLOR === void 0
+    color: tty && options.color !== false && env.NO_COLOR === void 0 && env.TERM !== "dumb"
   });
   const errors = [];
   const write = options.write ? (text, channel) => {
@@ -931,9 +931,13 @@ function createInstallerRun(value, options = {}) {
   const start = () => {
     if (started || finished) return;
     started = true;
+    if (options.quiet) return;
     const welcome = face.welcome();
     if (tty) lines(welcome);
-    else if (welcome.length) lines([`${face.identity.name} \u2014 Mutatis Mutandis`, options.operation === "install" ? face.identity.installWarm : face.identity.warm]);
+    else if (welcome.length) {
+      const warm = options.operation === "install" ? face.identity.installWarm : face.identity.warm;
+      lines([`${face.identity.name} - Mutatis Mutandis`, warm.replaceAll("\u2014", "-").replaceAll("\u2026", "...")]);
+    }
   };
   const durable = (title, measure, kind) => {
     spinner.stop();
@@ -963,12 +967,13 @@ function createInstallerRun(value, options = {}) {
       const surface = declaration.surfaces.find((surface2) => surface2.id === facts.id);
       if (!surface) throw new Error("installer run: undeclared surface");
       start();
-      const versions = facts.to ? facts.from && facts.from !== facts.to ? ` ${facts.from} \u2192 ${facts.to}` : ` ${facts.to}` : "";
+      const versions = facts.to ? facts.from && facts.from !== facts.to ? ` ${facts.from} ${tty ? "\u2192" : "->"} ${facts.to}` : ` ${facts.to}` : "";
       const status = { updated: options.dryRun ? "would update" : "updated", current: "already current", failed: "failed", skipped: "skipped", retry: "retrying", pending: "pending", kept: "kept" }[facts.state];
       if (!status) throw new Error("installer run: unknown surface state");
-      const activation = facts.state === "updated" && surface.activation ? ` \xB7 ${surface.activation}` : "";
+      const separator = tty ? "\xB7" : "-";
+      const activation = facts.state === "updated" && surface.activation ? ` ${separator} ${surface.activation}` : "";
       const completed = ["updated", "current", "kept", "skipped"].includes(facts.state);
-      durable(`${facts.id}${versions} \xB7 ${status}${activation}`, completed ? facts.seconds ?? null : null, facts.state === "failed" ? "fail" : facts.state === "updated" ? "ok" : "note");
+      durable(`${facts.id}${versions} ${separator} ${status}${activation}`, completed ? facts.seconds ?? null : null, facts.state === "failed" ? "fail" : facts.state === "updated" ? "ok" : "note");
       if (facts.detail) run.relay(facts.detail);
     },
     milestone({ step, state, ms }) {
@@ -995,6 +1000,20 @@ function createInstallerRun(value, options = {}) {
 `);
       }
     },
+    cancel() {
+      if (finished) return;
+      if (env.MM_INSTALLER_OUTCOME_FILE) writeInstallerOutcome(
+        env.MM_INSTALLER_OUTCOME_FILE,
+        { total: 0, updated: 0, failed: 0, deferred: true, detail: "Operation cancelled." }
+      );
+      start();
+      spinner.stop();
+      finished = true;
+      if (!face.nested || !env.MM_INSTALLER_OUTCOME_FILE) {
+        lines(tty ? face.receipt(["Operation cancelled."], { ready: false }) : ["Operation cancelled."]);
+      }
+      if (tty) lines([face.signOff()]);
+    },
     finish(facts) {
       if (finished) return;
       validateInstallerOutcome(facts);
@@ -1002,6 +1021,7 @@ function createInstallerRun(value, options = {}) {
       start();
       spinner.stop();
       finished = true;
+      if (options.quiet && facts.updated === 0 && facts.failed === 0 && !facts.operationFailed) return;
       const changed = !facts.version ? "No release target is available." : facts.dryRun ? `Would update ${facts.updated} of ${facts.total} surfaces to ${facts.version}.` : facts.installed ? `Installed ${facts.version} across ${facts.total} surfaces.` : `Updated ${facts.updated} of ${facts.total} surfaces to ${facts.version}.`;
       const ready = facts.failed === 0 && !facts.dryRun && !facts.deferred && !facts.operationFailed && Boolean(facts.version);
       const body = [
@@ -1074,7 +1094,15 @@ const root = candidates.find((candidate) => {
   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');
+  const archives = ${JSON.stringify(tarballs)}.map((name) => '"' + join(payloadDir, name) + '"').join(' ');
+  const viaLauncher = !/^node(\.exe)?$/iu.test(basename(process.execPath));
+  process.stderr.write([
+    'Installer payload has no installed product to converge: ' + payloadDir,
+    'NOT READY — nothing was armed and no host projection was written.',
+    'Finish by installing the payload archive offline:',
+    '  npm install --global --offline ' + archives,
+    'Then retry: "' + process.execPath + '" ' + (viaLauncher ? '--run ' : '') + '"' + process.argv[1] + '" --payload "' + payloadDir + '"',
+  ].join('\n') + '\n');
   process.exitCode = 1;
 } else {
   const viaLauncher = !/^node(\.exe)?$/iu.test(basename(process.execPath));
@@ -1088,26 +1116,35 @@ if (!root) {
 }
 `;
   }
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(converge[0])) {
+    throw new Error("installer payload: npm converge command must be a bin name");
+  }
   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';
-import { dirname, join } from 'node:path';
+import { readFileSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
 
 const payloadDir = dirname(process.argv[1]);
 const tarballs = ${JSON.stringify(tarballs.map((name) => `./${name}`))};
 const converge = ${JSON.stringify(converge)};
 const shippedFlag = ${JSON.stringify(shippedFlag ?? null)};
 
-function step(command, args) {
-  const options = { cwd: payloadDir, stdio: 'inherit', windowsHide: true };
+function step(command, args, capture = false) {
+  const options = { cwd: payloadDir, stdio: capture ? 'pipe' : 'inherit', windowsHide: true, encoding: 'utf8' };
+  if (process.platform === 'win32' && [command, ...args].some((arg) => /[\x00-\x1f"%!]/u.test(arg))) {
+    process.stderr.write('Installer command contains unsupported Windows shell characters.\n');
+    process.exit(1);
+  }
   // One prequoted command and no argv avoids Node's args+shell warning for Windows .cmd shims.
   const result = process.platform === 'win32'
-    ? spawnSync([command, ...args].map((arg) => /\s/.test(arg) ? '"' + arg + '"' : arg).join(' '), [], { ...options, shell: true })
+    ? spawnSync([command, ...args].map((arg) => /[\s&|<>^()]/u.test(arg) ? '"' + arg + '"' : arg).join(' '), [], { ...options, shell: true })
     : spawnSync(command, args, options);
   if (result.error || result.status !== 0) {
+    if (capture && result.stderr) process.stderr.write(result.stderr);
     process.stderr.write('Installer operation failed.\n');
     process.exit(result.status === null || result.status === undefined ? 1 : result.status);
   }
+  return result.stdout ?? '';
 }
 
 step('npm', ['install', '--global', '--no-fund', '--no-audit', ...tarballs]);
@@ -1125,44 +1162,129 @@ if (shippedFlag) {
   }
   if (!shipped) process.stdout.write('Payload carries no shipped version; running the declared operation.\n');
 }
-step(converge[0], [...converge.slice(1), ...(shipped ? [shippedFlag, shipped] : [])]);
+// The new global bin directory may not be on this process's inherited PATH.
+const prefix = step('npm', ['prefix', '--global'], true).trim();
+if (!prefix || !isAbsolute(prefix)) {
+  process.stderr.write('Installer could not resolve the global npm prefix.\n');
+  process.exit(1);
+}
+const candidates = process.platform === 'win32'
+  ? [join(prefix, converge[0] + '.cmd'), join(prefix, converge[0])]
+  : [join(prefix, 'bin', converge[0]), join(prefix, converge[0])];
+const command = candidates.find((candidate) => {
+  try { return statSync(candidate).isFile(); }
+  catch (error) { if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return false; throw error; }
+});
+if (!command) {
+  process.stderr.write('Installer could not find the installed command: ' + converge[0] + '\n');
+  process.exit(1);
+}
+step(command, [...converge.slice(1), ...(shipped ? [shippedFlag, shipped] : [])]);
 `;
 }
 
 // src/maintenance.ts
 async function runMaintenance(product, args, dependencies) {
   const json = args.includes("--json");
+  const quiet = args.includes("--quiet");
   const dryRun = args.includes("--dry-run");
   const installed = args.includes("install");
+  const render = dependencies.render;
+  const env = render?.env ?? process.env;
+  const tty = render?.tty ?? Boolean(process.stdout.isTTY);
   const run = json ? null : dependencies.run ?? createInstallerRun(product, {
-    tty: Boolean(process.stdout.isTTY),
-    color: Boolean(process.stdout.isTTY) && !process.env.NO_COLOR,
-    columns: process.stdout.columns,
+    ...render,
+    tty,
+    env,
+    color: tty && render?.color !== false && !args.includes("--no-color") && env.TERM !== "dumb",
+    columns: render?.columns ?? process.stdout.columns,
     dryRun,
+    quiet,
     operation: installed ? "install" : "update"
   });
-  run?.start();
+  if (!quiet) run?.start();
   let mark = Date.now();
+  let active;
+  let activeFacts;
+  let handedOff;
+  const shown = new Set((env.MM_FACE_CONTINUES ?? "").split(",").map((value) => value.trim()).filter(Boolean));
+  if (!quiet && !json) shown.add("welcome");
+  let phaseFailed = false;
+  let armFailed = false;
+  let knownFailure;
+  const phaseStarted = /* @__PURE__ */ new Map();
+  const phase = (event) => {
+    if (handedOff !== void 0) return;
+    if (event.state === "fail") phaseFailed = true;
+    const started = phaseStarted.get(event.id);
+    if (event.state === "running") {
+      if (started === void 0) phaseStarted.set(event.id, Date.now());
+      active = event.id;
+    } else {
+      phaseStarted.delete(event.id);
+      if (active === event.id) active = void 0;
+    }
+    if (!quiet && event.state === "running" && event.detail) run?.relay(event.detail);
+    const measured = event.measured;
+    const measure = measured?.kind === "percent" ? `${Math.max(0, Math.min(100, Math.round(measured.percent)))}%` : measured?.kind === "bytes" ? `${measured.done}/${measured.total} B` : measured?.kind === "count" ? `${measured.done}${measured.total === void 0 ? "" : `/${measured.total}`}` : event.measure;
+    const facts = {
+      state: event.state,
+      detail: event.detail,
+      measure,
+      ...event.state !== "running" && started !== void 0 ? { seconds: (Date.now() - started) / 1e3 } : {}
+    };
+    if (event.state === "running") activeFacts = facts;
+    if (!quiet) {
+      run?.phase(event.id, facts);
+      if (event.state === "ok" && run) shown.add(event.id);
+    }
+  };
   const pending = [];
   let streaming = false;
   const emitArm = ({ arm, seconds }) => {
+    if (quiet) return;
     run?.surface({
       id: arm.surface,
       from: arm.from ?? void 0,
       to: arm.to ?? void 0,
       state: arm.verdict === "fail" ? "failed" : arm.verdict === "defer" ? "retry" : arm.verdict === "skip" ? "kept" : arm.from === arm.to && !arm.launchStaged ? "current" : "updated",
       seconds,
-      detail: dependencies.diagnose(arm)
+      detail: dependencies.diagnose?.(arm)
     });
   };
+  const writeJson = (summary, schedule) => {
+    process.stdout.write(JSON.stringify(dependencies.jsonResult ? dependencies.jsonResult(summary, schedule) : installed ? { convergence: summary, autoupdate: schedule } : summary, null, 2) + "\n");
+  };
   try {
     const summary = await dependencies.engine({
       dryRun,
+      withCustody: async (operation) => {
+        if (handedOff !== void 0) throw new Error("installer terminal ownership already transferred");
+        run?.stop();
+        const result = await operation({ faceContinues: [...shown] });
+        if (result.kind === "reexec") {
+          if (!Number.isSafeInteger(result.code) || result.code < 0) throw new Error("invalid handoff exit code");
+          handedOff = result.code;
+        } else if (result.kind === "resume") {
+          if (!quiet && active) run?.phase(active, activeFacts);
+        } else throw new Error("invalid terminal custody result");
+        return result;
+      },
       shippedTarget: installed ? dependencies.shippedTarget : void 0,
-      narrate: args.includes("--verbose") ? (text) => run?.relay(text, "stderr") : void 0,
-      onTargetResolved: (target) => run?.phase("verify-release", { detail: target, state: "ok" }),
-      onPhase: () => run?.phase("check", { state: "running" }),
+      narrate: !quiet && !json && args.includes("--verbose") ? (text) => {
+        if (handedOff === void 0) run?.relay(text, "stderr", false);
+      } : void 0,
+      relay: (text, channel = "stdout", record = false) => {
+        if (handedOff === void 0) run?.relay(text, channel, record);
+      },
+      onTargetResolved: (target) => phase({ id: "verify-release", detail: target, state: "ok" }),
+      onPhase: () => {
+        if (!quiet && handedOff === void 0) run?.phase("check", { state: "running" });
+      },
+      onPhaseEvent: phase,
       onArm: (arm) => {
+        if (handedOff !== void 0) return;
+        if (arm.verdict === "fail") armFailed = true;
         const seconds = (Date.now() - mark) / 1e3;
         mark = Date.now();
         pending.push({ arm, seconds });
@@ -1170,43 +1292,68 @@ async function runMaintenance(product, args, dependencies) {
         if (streaming) for (const result of pending.splice(0)) emitArm(result);
       }
     });
+    if (handedOff !== void 0) return handedOff;
     if (summary.reexec) {
+      if (!dependencies.handOff) {
+        knownFailure = "The updated version needs a handoff, but no handoff is configured.";
+        throw new Error(knownFailure);
+      }
       run?.stop();
-      return dependencies.handOff(summary.reexec, args, { ...process.env, MM_FACE_CONTINUES: "welcome" });
+      knownFailure = "The updated updater could not launch.";
+      return await dependencies.handOff(summary.reexec, args, { ...process.env, MM_FACE_CONTINUES: "welcome" });
+    }
+    const counts2 = dependencies.counts(summary);
+    validateInstallerOutcome({ total: counts2.total, updated: counts2.updated, failed: counts2.failed });
+    if (!Number.isSafeInteger(counts2.retry) || counts2.retry < 0 || counts2.retry > counts2.total) throw new Error("invalid retry count");
+    if (summary.cancelled && summary.exit === 0 && !phaseFailed && !armFailed && counts2.failed === 0 && counts2.updated === 0) {
+      if (json) writeJson(summary, null);
+      else run?.cancel();
+      return 0;
     }
     for (const arm of pending) emitArm(arm);
     const waiting = summary.surfaces.filter((surface) => surface.present && surface.action === "arm-pending");
-    for (const surface of waiting) run?.surface({ id: surface.id, state: "pending" });
+    if (!quiet) for (const surface of waiting) run?.surface({ id: surface.id, state: "pending" });
     let schedule = null;
-    if (installed && !dryRun) {
-      const started = Date.now();
+    if (installed && !dryRun && dependencies.schedule) {
+      phase({ id: "arm", state: "running" });
       schedule = dependencies.schedule();
-      run?.phase("arm", {
-        state: schedule.ok ? "ok" : "fail",
-        seconds: (Date.now() - started) / 1e3,
-        detail: schedule.ok ? void 0 : schedule.detail
-      });
+      if (schedule) phase({ id: "arm", state: schedule.ok ? "ok" : "fail", detail: schedule.ok ? void 0 : schedule.detail });
     }
-    const counts2 = dependencies.counts(summary);
+    const failed = phaseFailed || armFailed || counts2.failed > 0 || Boolean(schedule && !schedule.ok);
+    const exit = Math.max(summary.exit, failed ? 1 : 0);
     if (json) {
-      process.stdout.write(JSON.stringify(installed ? { convergence: summary, autoupdate: schedule } : summary, null, 2) + "\n");
+      writeJson({ ...summary, exit }, schedule);
     } else {
       run.finish({
         version: summary.target ?? void 0,
         total: counts2.total,
         updated: counts2.updated,
         failed: counts2.failed,
-        operationFailed: summary.exit !== 0 || Boolean(schedule && !schedule.ok),
-        deferred: Boolean(counts2.retry || waiting.length || summary.deferred || !summary.target),
+        operationFailed: exit !== 0,
+        deferred: !failed && Boolean(counts2.retry || waiting.length || summary.deferred || summary.cancelled || !summary.target),
         dryRun,
         installed,
-        detail: schedule && !schedule.ok ? schedule.detail : summary.detail
+        detail: schedule && !schedule.ok ? schedule.detail : summary.detail ?? (summary.cancelled ? "Operation cancelled." : void 0),
+        retry: summary.retry,
+        rollback: summary.rollback,
+        logPath: summary.logPath,
+        logState: summary.logState
       });
     }
-    return Math.max(summary.exit, schedule && !schedule.ok ? 1 : 0);
+    return exit;
   } catch (error) {
-    run?.finish({ total: 0, updated: 0, failed: 0, operationFailed: true, detail: error.message });
-    if (json) throw error;
+    if (handedOff !== void 0) throw error;
+    let detail = knownFailure ?? (active === "sign-in" ? "Sign-in did not complete." : installed ? "Installation did not complete." : "Update did not complete.");
+    if (!knownFailure && dependencies.safeErrorDetail) {
+      try {
+        detail = dependencies.safeErrorDetail(error);
+      } catch {
+      }
+    }
+    if (active) phase({ id: active, state: "fail" });
+    run?.relay(detail, "stderr");
+    run?.finish({ total: 0, updated: 0, failed: 0, operationFailed: true, detail });
+    if (json) process.stdout.write(JSON.stringify({ error: detail }) + "\n");
     return 1;
   } finally {
     run?.stop();

package/dist/maintenance.d.ts

@@ -1,4 +1,4 @@
-import { type InstallerRun } from './run.js';
+import { type InstallerChannel, type InstallerFinish, type InstallerPhase, type InstallerPhaseFacts, type InstallerRunOptions, type InstallerRun } from './run.js';
 /** Facts produced by a product's convergence engine. No terminal labels or layout. */
 export interface MaintenanceArm {
     surface: string;
@@ -19,34 +19,76 @@ export interface MaintenanceSummary {
     exit: number;
     detail?: string;
     deferred?: boolean;
+    cancelled?: boolean;
+    retry?: string;
+    rollback?: InstallerFinish['rollback'];
+    logPath?: string;
+    logState?: InstallerFinish['logState'];
     reexec: {
         dist: string;
         target: string;
         from: string | null;
     } | null;
 }
+export interface MaintenancePhaseEvent {
+    id: InstallerPhase;
+    state: 'running' | 'ok' | 'fail' | 'note';
+    detail?: string;
+    measure?: InstallerPhaseFacts['measure'];
+    measured?: {
+        kind: 'percent';
+        percent: number;
+    } | {
+        kind: 'bytes';
+        done: number;
+        total: number;
+    } | {
+        kind: 'count';
+        done: number;
+        total?: number;
+    };
+}
+export type MaintenanceCustodyResult<T> = {
+    kind: 'reexec';
+    code: number;
+} | {
+    kind: 'resume';
+    value: T;
+};
+export interface MaintenanceEngineOptions {
+    dryRun: boolean;
+    withCustody: <T>(operation: (context: {
+        faceContinues: readonly string[];
+    }) => Promise<MaintenanceCustodyResult<T>>) => Promise<MaintenanceCustodyResult<T>>;
+    shippedTarget?: string;
+    narrate?: (line: string) => void;
+    onTargetResolved?: (target: string, gate: string | null) => void;
+    /** Legacy engine notification; it does not imply a completed phase. */
+    onPhase?: (line: string) => void;
+    onPhaseEvent?: (event: MaintenancePhaseEvent) => void;
+    relay?: (text: string, channel?: InstallerChannel, record?: boolean) => void;
+    onArm?: (arm: MaintenanceArm) => void;
+}
+export type MaintenanceSchedule = {
+    ok: boolean;
+    detail: string;
+} | 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>;
+    engine: (options: MaintenanceEngineOptions) => 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;
+    diagnose?: (arm: MaintenanceArm) => string | undefined;
+    schedule?: () => MaintenanceSchedule;
+    handOff?: (next: NonNullable<S['reexec']>, args: string[], env: NodeJS.ProcessEnv) => number | Promise<number>;
+    jsonResult?: (summary: S, schedule: MaintenanceSchedule) => object;
+    /** Return a safe, actionable diagnosis, never raw authentication output. */
+    safeErrorDetail?: (error: unknown) => string;
     shippedTarget?: string;
     run?: InstallerRun;
+    render?: Pick<InstallerRunOptions, 'tty' | 'color' | 'columns' | 'env' | 'animate'>;
 }): Promise<number>;

package/dist/run.d.ts

@@ -32,6 +32,7 @@ export interface InstallerRunOptions {
     operation?: 'install' | 'update';
     tty?: boolean;
     dryRun?: boolean;
+    quiet?: boolean;
     color?: boolean;
     columns?: number;
     env?: Readonly<NodeJS.ProcessEnv>;
@@ -85,6 +86,7 @@ export declare function createInstallerRun(value: unknown, options?: InstallerRu
         code: string;
     }): void;
     relay(text: string, channel?: InstallerChannel, record?: boolean): void;
+    cancel(): void;
     finish(facts: InstallerFinish): void;
     stop(): void;
 };

package/package.json

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