@mutmutco/installer-launcher 0.1.8 → 0.1.10

package/dist/launcher.js

@@ -1,32 +1,44 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { spawnSync as spawnSync2 } from "node:child_process";
-import { existsSync as existsSync4, readFileSync as readFileSync4, statSync } from "node:fs";
+import { spawn as spawn2, spawnSync as spawnSync2 } from "node:child_process";
+import { existsSync as existsSync4, readFileSync as readFileSync5, statSync, mkdtempSync, unlinkSync, rmdirSync } from "node:fs";
+import { tmpdir as tmpdir4 } from "node:os";
 import { dirname as dirname2, join as join4, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL as pathToFileURL2 } from "node:url";
 
-// node_modules/@mutmutco/installer-face/dist/index.js
+// ../face/src/face.ts
+import { writeSync } from "node:fs";
+
+// ../face/src/products.ts
 var PRODUCTS = Object.freeze({
   "mm-strategy": Object.freeze({
     name: "MM Strategy",
+    installWarm: "Welcome. Let's set up MM Strategy \u2014 about a minute.",
     accent: "38;2;249;115;22",
-    warm: "Welcome. Let's set up MM Strategy \u2014 about a minute."
+    warm: "Welcome. Let's set up MM Strategy \u2014 about a minute.",
+    doctor: "mm-strategy doctor"
   }),
   "mmi-hub": Object.freeze({
     name: "mmi-hub",
+    installWarm: "Welcome. Setting up mmi-hub \u2014 about a minute.",
     accent: "38;2;125;211;252",
-    warm: "Welcome back. Checking your surfaces\u2026"
+    warm: "Welcome back. Checking your surfaces\u2026",
+    doctor: "mmi doctor"
   }),
   "jerv-hub": Object.freeze({
     name: "jerv-hub",
+    installWarm: "Welcome. Setting up jerv-hub \u2014 about a minute.",
     accent: "38;2;248;113;113",
-    warm: "Welcome back. Checking your surfaces\u2026"
+    warm: "Welcome back. Checking your surfaces\u2026",
+    doctor: "jerv doctor"
   }),
   jervcode: Object.freeze({
     name: "JervCode",
+    installWarm: "Welcome. Setting up JervCode \u2014 about a minute.",
     accent: "38;2;192;132;252",
-    warm: "Welcome back. Keeping JervCode current\u2026"
+    warm: "Welcome back. Keeping JervCode current\u2026",
+    doctor: "jervcode doctor"
   })
 });
 function identityFor(product) {
@@ -36,6 +48,8 @@ function identityFor(product) {
   }
   return identity;
 }
+
+// ../face/src/face.ts
 var GLYPH = Object.freeze({
   diamond: "\u25C6",
   hollow: "\u25C7",
@@ -60,6 +74,9 @@ var ANSI = /\u001b\[[0-9;]*m/g;
 function visibleWidth(text) {
   return [...String(text).replace(ANSI, "")].length;
 }
+function stripColor(text) {
+  return String(text).replace(ANSI, "");
+}
 function faceWidth(columns) {
   const raw = Number(columns);
   return Math.max(40, Math.min(100, Number.isFinite(raw) && raw > 0 ? raw : 100));
@@ -88,7 +105,14 @@ function wrapWords(text, width) {
   if (line) lines.push(line);
   return lines.length ? lines : [""];
 }
-function createFace({ product, color = false, columns, env = process.env }) {
+var PROGRESS_PROTOCOL = 1;
+function readProgressFd(env) {
+  const fd = Number.parseInt(String(env.MM_PROGRESS_FD ?? ""), 10);
+  if (!Number.isInteger(fd) || fd <= 0) return null;
+  const protocol = Number.parseInt(String(env.MM_PROGRESS_PROTOCOL ?? PROGRESS_PROTOCOL), 10);
+  return protocol === PROGRESS_PROTOCOL ? fd : null;
+}
+function createFace({ product, color = false, columns, env = process.env, operation }) {
   const identity = identityFor(product);
   const width = faceWidth(columns);
   const paint = (sgr, text) => color ? `\x1B[${sgr}m${text}\x1B[0m` : String(text);
@@ -96,28 +120,45 @@ function createFace({ product, color = false, columns, env = process.env }) {
   const indent = " ".repeat(TITLE_COLUMN - 1);
   const continuedPhases = new Set((env.MM_FACE_CONTINUES ?? "").split(",").map((phase) => phase.trim()).filter(Boolean));
   const continuesFace = continuedPhases.size > 0;
-  const welcome = () => continuesFace ? [] : [
+  const nested = env.MM_OUTER_CONSOLE === "1";
+  const progressFd = readProgressFd(env);
+  const emitMilestone = (title, measure, kind) => {
+    if (progressFd === null) return false;
+    const record = { v: PROGRESS_PROTOCOL, step: stripColor(title), state: kind };
+    if (typeof measure === "number") record.ms = Math.max(0, Math.round(measure * 1e3));
+    try {
+      writeSync(progressFd, `${JSON.stringify(record)}
+`);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const welcome = () => continuesFace || nested ? [] : [
     `${paint(identity.accent, GLYPH.diamond)}  ${paint(identity.accent, identity.name)} \u2014 Mutatis Mutandis`,
     bar(),
-    `${bar()}  ${identity.warm}`,
+    `${bar()}  ${operation === "install" ? identity.installWarm : identity.warm}`,
     bar()
   ];
   const continues = (phase, kind = "ok") => {
     const inherited = continuedPhases.delete(String(phase).trim());
     return kind === "fail" ? false : inherited;
   };
-  const step = (title, seconds = null, kind = "ok") => {
+  const step = (title, measure = null, kind = "ok") => {
+    if (emitMilestone(title, measure, kind)) return "";
     const glyph = kind === "fail" ? paint(identity.accent, GLYPH.cross) : kind === "note" ? paint(PALETTE.muted, GLYPH.dot) : paint(PALETTE.green, GLYPH.check);
-    const time = seconds === null || seconds === void 0 ? "" : paint(PALETTE.muted, `${Math.max(0, Math.round(seconds))}s`);
+    const measured = measure === null || measure === void 0 ? "" : paint(PALETTE.muted, typeof measure === "number" ? `${Math.max(0, Math.round(measure))}s` : String(measure).trim());
+    const time = measured;
     const column = Math.min(44, Math.max(0, width - 8));
-    const reserved = time ? 6 : 0;
+    const reserved = time ? Math.max(6, visibleWidth(time) + 2) : 0;
     const [first, ...rest] = wrapWords(title, width - TITLE_COLUMN - reserved);
     const head = `${bar()}  ${glyph}  ${first}`;
     const pad = Math.max(1, column - visibleWidth(head));
     return [time ? `${head}${" ".repeat(pad)}${time}` : head, ...rest.map((line) => `${bar()}${indent}${line}`)].join("\n");
   };
-  const relay = (text) => String(text).split("\n").map((line) => line.trim() === "" ? bar() : `${bar()}${indent}${line}`).join("\n");
-  const receipt = (lines) => {
+  const relay = (text) => String(text).split("\n").flatMap((line) => line.trim() === "" ? [bar()] : (visibleWidth(line) <= width - TITLE_COLUMN ? [line] : wrapWords(line, width - TITLE_COLUMN)).map((part) => `${bar()}${indent}${part}`)).join("\n");
+  const receipt = (lines, { ready = true } = {}) => {
+    if (ready && nested) return [];
     const body = (Array.isArray(lines) ? lines : String(lines).split("\n")).flatMap((raw) => {
       const line = String(raw);
       if (visibleWidth(line) <= width - 6) return [line];
@@ -133,18 +174,361 @@ function createFace({ product, color = false, columns, env = process.env }) {
       frame(GLYPH.boxBottom, GLYPH.boxBottomEnd)
     ];
   };
-  const signOff = () => `${paint(identity.accent, GLYPH.diamond)}  ${paint(identity.accent, `${identity.name} \xB7 Mutatis Mutandis`)}`;
+  const outcome = (changed, options = {}) => {
+    const fact = String(changed ?? "").trim();
+    if (!fact) {
+      throw new Error(`installer face: the receipt must say what changed \u2014 pass the one measured fact this run produced, such as "Updated 2 of 7 surfaces to 4.4.10." (${identity.name})`);
+    }
+    return receipt([
+      `${GLYPH.check}  ${identity.name} is ready.`,
+      fact,
+      `Check health any time:  ${identity.doctor}`
+    ], options);
+  };
+  const signOff = () => nested ? "" : `${paint(identity.accent, GLYPH.diamond)}  ${paint(identity.accent, `${identity.name} \xB7 Mutatis Mutandis`)}`;
   const refusal = (message) => `${bar()}  ${paint(identity.accent, GLYPH.cross)}  ${message}`;
-  return { identity, width, welcome, continues, step, relay, receipt, signOff, refusal, paint };
+  return { identity, width, nested, emitsProgress: progressFd !== null, welcome, continues, step, relay, receipt, outcome, signOff, refusal, paint };
 }
+
+// ../face/src/shell.ts
 var RELAY_INDENT = " ".repeat(TITLE_COLUMN - 1);
+
+// ../face/src/spinner.ts
+import { appendFileSync, writeSync as writeSync2 } from "node:fs";
+import { Worker } from "node:worker_threads";
 var FRAMES = ["\u25D2", "\u25D0", "\u25D3", "\u25D1"];
+var WORKER_SOURCE = `
+const { parentPort, workerData } = require('node:worker_threads');
+const { writeSync, appendFileSync } = require('node:fs');
+const control = new Int32Array(workerData.control);
+let frames = workerData.frames, frame = workerData.frame;
+function draw() {
+  if (Atomics.compareExchange(control, 1, 0, 1) !== 0) return;
+  try {
+    if (Atomics.load(control, 0) || Atomics.load(control, 2) || !frames.length) return;
+    const text = frames[frame++ % frames.length];
+    writeSync(2, text);
+    if (workerData.transcriptPath) appendFileSync(workerData.transcriptPath, JSON.stringify({ channel: 'spinner', text }) + '\\n');
+  } finally {
+    Atomics.store(control, 1, 0);
+    Atomics.notify(control, 1);
+  }
+}
+parentPort.on('message', (next) => {
+  if (Atomics.load(control, 2)) return;
+  frames = next.frames;
+  frame = next.frame;
+  Atomics.store(control, 0, 0);
+});
+setInterval(draw, workerData.intervalMs);
+`;
+function createSpinner(face, { animate, stream, intervalMs = 90, transcriptPath }) {
+  animate = animate && !face.nested && !face.emitsProgress;
+  let timer = null;
+  let worker = null;
+  let control = null;
+  let frames = [];
+  let frame = 0;
+  const write = (text) => {
+    if (stream) stream.write(text);
+    else {
+      writeSync2(2, text);
+      if (transcriptPath) appendFileSync(transcriptPath, `${JSON.stringify({ channel: "spinner", text })}
+`);
+    }
+  };
+  const render = (text, measure) => {
+    const line = face.step(text, measure, "note").split("\n")[0];
+    frames = line ? FRAMES.map((glyph) => `\r\x1B[2K${line.replace(GLYPH.dot, glyph)}`) : [];
+  };
+  const draw = () => {
+    if (animate && frames.length) write(frames[frame++ % frames.length]);
+  };
+  const pause = () => {
+    if (!control) return;
+    Atomics.store(control, 0, 1);
+    while (Atomics.load(control, 1)) Atomics.wait(control, 1, 1);
+  };
+  const halt = () => {
+    if (timer) clearInterval(timer);
+    timer = null;
+    if (control) Atomics.store(control, 2, 1);
+    pause();
+    if (worker) void worker.terminate();
+    worker = null;
+    control = null;
+  };
+  return {
+    start(text, measure = null) {
+      if (!animate) return;
+      halt();
+      render(text, measure);
+      frame = 0;
+      draw();
+      if (!frames.length) return;
+      if (stream) timer = setInterval(draw, intervalMs).unref();
+      else {
+        control = new Int32Array(new SharedArrayBuffer(12));
+        try {
+          worker = new Worker(WORKER_SOURCE, { eval: true, workerData: {
+            control: control.buffer,
+            frames,
+            frame,
+            intervalMs,
+            transcriptPath
+          } });
+          const active = worker;
+          worker.on("error", () => {
+            if (worker === active) halt();
+          });
+          worker.unref();
+        } catch {
+          halt();
+        }
+      }
+    },
+    say(text, measure = null) {
+      if (!animate) return;
+      pause();
+      render(text, measure);
+      draw();
+      worker?.postMessage({ frames, frame });
+    },
+    stop() {
+      halt();
+      if (animate) write("\r\x1B[2K");
+    }
+  };
+}
 var SPINNER_FRAMES = Object.freeze([...FRAMES]);
+
+// ../face/src/conformance.ts
 var ALLOWED = new Set(Object.values(GLYPH));
 
+// ../face/src/run.ts
+import { appendFileSync as appendFileSync2 } from "node:fs";
+
+// ../face/src/outcome.ts
+import { readFileSync, writeFileSync } from "node:fs";
+var counts = ["total", "updated", "failed"];
+var strings = ["version", "retry", "detail"];
+var flags = ["dryRun", "installed", "deferred", "operationFailed"];
+function validateInstallerOutcome(value) {
+  const invalid = () => {
+    throw new Error("installer outcome: invalid child result");
+  };
+  if (!value || typeof value !== "object" || Array.isArray(value)) return invalid();
+  const facts = value;
+  const allowed = [...counts, ...strings, ...flags];
+  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();
+  return { ...facts };
+}
+function writeInstallerOutcome(path, value) {
+  writeFileSync(path, JSON.stringify(validateInstallerOutcome(value)), { encoding: "utf8", mode: 384 });
+}
+function readInstallerOutcome(path) {
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  }
+  if (text.length > 16384) throw new Error("installer outcome: child result is too large");
+  try {
+    return validateInstallerOutcome(JSON.parse(text));
+  } catch {
+    throw new Error("installer outcome: invalid child result");
+  }
+}
+
+// ../face/src/run.ts
+function validateInstallerProduct(value) {
+  const fail = (field2) => {
+    throw new Error(`installer product: invalid ${field2}`);
+  };
+  if (!value || typeof value !== "object" || Array.isArray(value)) return fail("declaration");
+  const input = value;
+  const text = (value2, field2) => typeof value2 === "string" && value2.trim() && !/[\r\n\x00-\x1f]/u.test(value2) ? value2 : fail(field2);
+  const key = text(input.product, "product");
+  const product = { mmi: "mmi-hub", jerv: "jerv-hub" }[key] ?? key;
+  const identity = identityFor(product);
+  const gate = text(input.gate, "gate");
+  let gateUrl;
+  try {
+    gateUrl = new URL(gate);
+  } catch {
+    return fail("gate");
+  }
+  if (!["https:", "http:"].includes(gateUrl.protocol) || gateUrl.username || gateUrl.password) return fail("gate");
+  const doctor = text(input.doctor, "doctor");
+  if (doctor !== identity.doctor) return fail("doctor");
+  if (!Array.isArray(input.surfaces) || input.surfaces.length === 0) return fail("surfaces");
+  const ids = /* @__PURE__ */ new Set();
+  const surfaces = input.surfaces.map((raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return fail("surface");
+    const source = raw;
+    const id = text(source.id, "surface.id");
+    if (ids.has(id)) return fail("duplicate surface.id");
+    ids.add(id);
+    const surface = { id };
+    for (const field2 of ["npm", "bin", "kind", "activation"]) {
+      if (source[field2] !== void 0) surface[field2] = text(source[field2], `surface.${field2}`);
+    }
+    if (Boolean(surface.npm) !== Boolean(surface.bin)) return fail("surface npm/bin pair");
+    if (surface.kind !== void 0 && !["agent-home", "payload"].includes(surface.kind)) return fail("surface.kind");
+    if (!surface.npm && !surface.kind) return fail("surface implementation");
+    return surface;
+  });
+  return { product, gate, doctor, surfaces };
+}
+var PHASES = {
+  preflight: ["Checking prerequisites", "Checked prerequisites"],
+  resolve: ["Resolving the release", "Resolved the release"],
+  download: ["Downloading the payload", "Downloaded the payload"],
+  "sign-in": ["Signing in", "Signed in"],
+  check: ["Checking surfaces", "Checked surfaces"],
+  arm: ["Scheduling updates", "Armed hourly updates"],
+  "verify-release": ["Checking the release version", "Verified the release version"],
+  verify: ["Verifying the payload", "Verified the payload"],
+  install: ["Installing the product", "Installed the product"],
+  activate: ["Activating surfaces", "Activated surfaces"],
+  doctor: ["Checking health", "Checked health"]
+};
+function createInstallerRun(value, options = {}) {
+  const declaration = validateInstallerProduct(value);
+  const env = options.env ?? process.env;
+  const tty = options.tty ?? Boolean(process.stdout.isTTY);
+  const face = createFace({
+    operation: options.operation,
+    product: declaration.product,
+    columns: options.columns,
+    env,
+    color: tty && options.color !== false && env.NO_COLOR === void 0
+  });
+  const write = options.write ?? ((text, channel) => {
+    (channel === "stdout" ? process.stdout : process.stderr).write(text);
+  });
+  const emit = (text, channel = "stdout", recorded = text) => {
+    if (!text) return;
+    write(text, channel);
+    if (env.MM_FACE_TRANSCRIPT) {
+      appendFileSync2(env.MM_FACE_TRANSCRIPT, `${JSON.stringify({ channel, text: recorded })}
+`, "utf8");
+    }
+  };
+  const lines = (rows, channel = "stdout") => {
+    for (const row of rows.flatMap((row2) => row2.split("\n"))) if (row) emit(`${row}
+`, channel);
+  };
+  const spinner = createSpinner(face, {
+    animate: tty && env.TERM !== "dumb" && (options.animate ?? Boolean(process.stderr.isTTY)),
+    ...options.write ? { stream: { write: (text) => {
+      emit(String(text), "spinner");
+      return true;
+    } } } : { transcriptPath: env.MM_FACE_TRANSCRIPT }
+  });
+  let started = false;
+  let finished = false;
+  const start = () => {
+    if (started || finished) return;
+    started = true;
+    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]);
+  };
+  const durable = (title, measure, kind) => {
+    spinner.stop();
+    const rendered = face.step(title, measure, kind);
+    if (rendered) lines([tty ? rendered : `${kind === "fail" ? "Failed: " : ""}${title}${measure === null ? "" : ` (${typeof measure === "number" ? `${Math.max(0, Math.round(measure))}s` : measure})`}`]);
+  };
+  const run2 = {
+    start,
+    phase(id, facts = {}) {
+      if (finished) throw new Error("installer run already finished");
+      if (!Object.hasOwn(PHASES, id)) throw new Error("installer run: unknown phase");
+      start();
+      const state = facts.state ?? "ok";
+      const title = PHASES[id][state === "ok" ? 1 : 0];
+      if (state === "running") {
+        spinner.start(title, facts.measure ?? null);
+        return;
+      }
+      if (!face.continues(id, state)) durable(title, facts.seconds ?? facts.measure ?? null, state);
+      if (facts.detail) run2.relay(facts.detail);
+    },
+    surface(facts) {
+      if (finished) throw new Error("installer run already finished");
+      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 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 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");
+      if (facts.detail) run2.relay(facts.detail);
+    },
+    milestone({ step, state, ms }) {
+      start();
+      durable(step, ms === void 0 ? null : ms / 1e3, state);
+    },
+    signIn({ url, code }) {
+      start();
+      spinner.stop();
+      for (const text of [`Open ${url}`, `Enter code: ${code}`]) {
+        const rendered = `${tty ? face.relay(text) : text}
+`;
+        emit(rendered, "stdout", rendered.replace(code, "[redacted]"));
+      }
+    },
+    // Only pass safe diagnostic text, never authentication output or credentials.
+    relay(text, channel = "stdout", record = true) {
+      spinner.stop();
+      const rendered = tty ? face.relay(text) : stripColor(text);
+      for (const row of rendered.split("\n")) if (row) {
+        emit(`${row}
+`, channel, record ? `${row}
+` : `${tty ? face.relay("[external output omitted]") : "[external output omitted]"}
+`);
+      }
+    },
+    finish(facts) {
+      if (finished) return;
+      validateInstallerOutcome(facts);
+      if (env.MM_INSTALLER_OUTCOME_FILE) writeInstallerOutcome(env.MM_INSTALLER_OUTCOME_FILE, facts);
+      start();
+      spinner.stop();
+      finished = true;
+      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 = [
+        `${ready ? GLYPH.check : facts.dryRun ? GLYPH.dot : GLYPH.cross}  ${face.identity.name}${ready ? " is ready." : facts.dryRun ? " preview complete." : facts.deferred ? " update deferred." : " is not ready yet."}`,
+        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}`
+      ];
+      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, "")));
+      }
+      if (tty) lines([face.signOff()]);
+    },
+    stop() {
+      spinner.stop();
+    }
+  };
+  return run2;
+}
+
 // src/autoupdate.ts
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync as readFileSync2, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 function schedulePlatform(override) {
@@ -193,7 +577,7 @@ function enableSchedule(config, command, options = {}) {
     const dir2 = join(home, "Library", "LaunchAgents");
     mkdirSync(dir2, { recursive: true });
     const plist = join(dir2, `${label2}.plist`);
-    writeFileSync(plist, darwinPlist(label2, command));
+    writeFileSync2(plist, darwinPlist(label2, command));
     exec("launchctl", ["bootout", `gui/${process.getuid?.() ?? 501}/${label2}`]);
     const result2 = exec("launchctl", ["bootstrap", `gui/${process.getuid?.() ?? 501}`, plist]);
     if (result2.code !== 0) {
@@ -204,8 +588,8 @@ function enableSchedule(config, command, options = {}) {
   const label = scheduleLabel(config);
   const dir = join(home, ".config", "systemd", "user");
   mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, `${label}.service`), linuxService(command));
-  writeFileSync(join(dir, `${label}.timer`), linuxTimer(label));
+  writeFileSync2(join(dir, `${label}.service`), linuxService(command));
+  writeFileSync2(join(dir, `${label}.timer`), linuxTimer(label));
   const reload = exec("systemctl", ["--user", "daemon-reload"]);
   if (reload.code !== 0) {
     throw new Error(`could not turn autoupdate on: ${firstLine(reload.stderr || reload.stdout) || `exit ${reload.code}`}`);
@@ -318,7 +702,7 @@ function firstLine(text) {
 }
 
 // src/config.ts
-import { readFileSync as readFileSync2 } from "node:fs";
+import { readFileSync as readFileSync3 } from "node:fs";
 import { getAsset } from "node:sea";
 
 // src/module-url.ts
@@ -340,10 +724,10 @@ function loadProductConfig(options = {}) {
   const explicit = options.configPath ?? process.env.LAUNCHER_CONFIG;
   const devFallback = new URL("../config/product.template.json", moduleUrl());
   if (explicit) {
-    return parseProductConfig(readFileSync2(explicit, "utf8"));
+    return parseProductConfig(readFileSync3(explicit, "utf8"));
   }
   try {
-    return parseProductConfig(readFileSync2(devFallback, "utf8"));
+    return parseProductConfig(readFileSync3(devFallback, "utf8"));
   } catch {
   }
   try {
@@ -462,7 +846,8 @@ async function loginGithub(config, options = {}) {
   const sleep = options.sleep ?? realSleep;
   const issued = await requestDeviceCode(config, fetchImpl);
   const openUrl = issued.verification_uri_complete ?? issued.verification_uri;
-  print(`To sign in, open ${issued.verification_uri} and enter the code ${issued.user_code}.`);
+  if (options.onDeviceCode) options.onDeviceCode({ url: issued.verification_uri, code: issued.user_code });
+  else print(`To sign in, open ${issued.verification_uri} and enter the code ${issued.user_code}.`);
   open(openUrl);
   const deadline = now() + issued.expires_in * 1e3;
   let intervalMs = Math.max(1, issued.interval) * 1e3;
@@ -632,7 +1017,7 @@ function page(title, body) {
 
 // src/payload.ts
 import { createHash as createHash2, createPublicKey, verify } from "node:crypto";
-import { mkdirSync as mkdirSync2, renameSync, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { mkdirSync as mkdirSync2, renameSync, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "node:fs";
 import { tmpdir as tmpdir2 } from "node:os";
 import { dirname, join as join2 } from "node:path";
 
@@ -784,7 +1169,7 @@ async function downloadAndUnpack(config, dir, manifest, accessToken, options = {
       }
       const dest = join2(staging, entry.path);
       mkdirSync2(dirname(dest), { recursive: true });
-      writeFileSync2(dest, bytes);
+      writeFileSync3(dest, bytes);
     }
     const target = join2(dir, "payload");
     mkdirSync2(dir, { recursive: true });
@@ -798,7 +1183,7 @@ async function downloadAndUnpack(config, dir, manifest, accessToken, options = {
 }
 
 // src/store.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync3, rmSync as rmSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync4, rmSync as rmSync3, writeFileSync as writeFileSync4 } from "node:fs";
 import { tmpdir as tmpdir3 } from "node:os";
 import { join as join3 } from "node:path";
 function defaultProductDir(product) {
@@ -823,7 +1208,7 @@ function payloadDir(dir) {
 }
 function readTokens(dir) {
   try {
-    const data = JSON.parse(readFileSync3(tokensPath(dir), "utf8"));
+    const data = JSON.parse(readFileSync4(tokensPath(dir), "utf8"));
     if (typeof data.accessToken !== "string" || !data.accessToken) return null;
     if (typeof data.expiresAt !== "number" || !Number.isFinite(data.expiresAt)) return null;
     const tokens = { accessToken: data.accessToken, expiresAt: data.expiresAt };
@@ -837,10 +1222,10 @@ function readTokens(dir) {
 function writeTokens(dir, tokens) {
   mkdirSync3(dir, { recursive: true });
   try {
-    writeFileSync3(tokensPath(dir), `${JSON.stringify(tokens)}
+    writeFileSync4(tokensPath(dir), `${JSON.stringify(tokens)}
 `, { mode: 384 });
   } catch {
-    writeFileSync3(tokensPath(dir), `${JSON.stringify(tokens)}
+    writeFileSync4(tokensPath(dir), `${JSON.stringify(tokens)}
 `);
   }
 }
@@ -849,7 +1234,7 @@ function clearTokens(dir) {
 }
 function readState(dir) {
   try {
-    const data = JSON.parse(readFileSync3(statePath(dir), "utf8"));
+    const data = JSON.parse(readFileSync4(statePath(dir), "utf8"));
     if (typeof data.version !== "string" || !data.version) return null;
     return { version: data.version, updatedAt: typeof data.updatedAt === "string" ? data.updatedAt : "" };
   } catch {
@@ -858,7 +1243,7 @@ function readState(dir) {
 }
 function writeState(dir, state) {
   mkdirSync3(dir, { recursive: true });
-  writeFileSync3(statePath(dir), `${JSON.stringify(state, null, 2)}
+  writeFileSync4(statePath(dir), `${JSON.stringify(state, null, 2)}
 `);
 }
 function wipeProductDir(dir) {
@@ -868,7 +1253,7 @@ function wipeProductDir(dir) {
 }
 
 // src/index.ts
-var LAUNCHER_VERSION = true ? "0.1.8" : readVersionFromPackage();
+var LAUNCHER_VERSION = true ? "0.1.10" : readVersionFromPackage();
 function defaultPrint(message) {
   process.stdout.write(`${message}
 `);
@@ -1004,11 +1389,16 @@ async function ensureFreshToken(config, dir, fetchImpl = fetch) {
   });
   return refreshed.accessToken;
 }
-async function doLogin(config, dir, options, print) {
+async function doLogin(config, dir, options, print, installer) {
   const fetchImpl = options.fetchImpl ?? fetch;
   const open = options.open ?? openBrowser;
   if (config.loginKind === "github") {
-    const tokens = await loginGithub(config, { fetchImpl, open, print });
+    const tokens = await loginGithub(config, {
+      fetchImpl,
+      open,
+      print,
+      ...installer ? { onDeviceCode: (prompt) => installer.signIn(prompt) } : {}
+    });
     writeTokens(dir, {
       accessToken: tokens.accessToken,
       refreshToken: tokens.refreshToken,
@@ -1023,20 +1413,20 @@ async function doLogin(config, dir, options, print) {
       clientId: tokens.clientId
     });
   }
-  print(`signed in to ${config.product}.`);
+  if (!installer) print(`signed in to ${config.product}.`);
 }
-async function fetchAccessTokenOrLogin(config, dir, options, print) {
+async function fetchAccessTokenOrLogin(config, dir, options, print, installer) {
   const fetchImpl = options.fetchImpl ?? fetch;
   const fresh = await ensureFreshToken(config, dir, fetchImpl);
   if (fresh) return fresh;
-  await doLogin(config, dir, options, print);
+  await doLogin(config, dir, options, print, installer);
   const after = readTokens(dir);
   if (!after) throw new Error("sign-in did not produce a token");
   return after.accessToken;
 }
 function readPayloadArgv(dir, key) {
   try {
-    const parsed = JSON.parse(readFileSync4(join4(payloadDir(dir), "payload.json"), "utf8"));
+    const parsed = JSON.parse(readFileSync5(join4(payloadDir(dir), "payload.json"), "utf8"));
     const entry = parsed[key];
     if (typeof entry === "string") {
       const parts = entry.trim().split(/\s+/).filter(Boolean);
@@ -1058,7 +1448,7 @@ function readPayloadRun(dir) {
 }
 function readPayloadVerbs(dir) {
   try {
-    const parsed = JSON.parse(readFileSync4(join4(payloadDir(dir), "payload.json"), "utf8"));
+    const parsed = JSON.parse(readFileSync5(join4(payloadDir(dir), "payload.json"), "utf8"));
     const verbs = parsed.verbs;
     if (verbs === "*") return "*";
     if (Array.isArray(verbs) && verbs.every((v) => typeof v === "string" && v.trim().length > 0)) {
@@ -1106,7 +1496,7 @@ function defaultRunEntry(entry, cwd, env) {
   const [command, ...args] = entry;
   const shell = needsShell(command);
   const commandLine = shell ? [command, ...args].map(quoteForShell).join(" ") : command;
-  const spawn2 = (progress2) => spawnSync2(commandLine, shell ? [] : args, {
+  const spawnEntry = (progress2) => spawnSync2(commandLine, shell ? [] : args, {
     cwd,
     stdio: progress2 ? ["inherit", "inherit", "inherit", "pipe"] : "inherit",
     shell,
@@ -1115,12 +1505,12 @@ function defaultRunEntry(entry, cwd, env) {
   });
   let result;
   if (process.platform === "win32" && shell) {
-    result = spawn2(false);
+    result = spawnEntry(false);
   } else {
     try {
-      result = spawn2(true);
+      result = spawnEntry(true);
     } catch {
-      result = spawn2(false);
+      result = spawnEntry(false);
     }
   }
   if (result.error) return { ok: false, error: result.error.message };
@@ -1137,73 +1527,71 @@ function faceProduct(config) {
   const known = { mmi: "mmi-hub", jerv: "jerv-hub" };
   return known[config.product] ?? config.product;
 }
-function faceFor(config, options) {
-  const tty = options.tty ?? Boolean(process.stdout.isTTY);
-  if (!tty) return null;
+async function installOrUpdate(config, dir, options, print, update) {
+  const product = faceProduct(config);
+  const installer = createInstallerRun({
+    product,
+    gate: config.host,
+    doctor: identityFor(product).doctor,
+    surfaces: [{ id: config.product, kind: "payload" }]
+  }, {
+    operation: update ? "update" : "install",
+    tty: options.tty,
+    animate: !options.print && Boolean(process.stderr.isTTY),
+    write: (text, channel) => {
+      if (options.print) print(text.replace(/\n$/, ""));
+      else (channel === "stdout" ? process.stdout : process.stderr).write(text);
+    }
+  });
+  const fetchImpl = options.fetchImpl ?? fetch;
+  let version = readState(dir)?.version ?? "unknown";
+  installer.start();
   try {
-    return createFace({
-      product: faceProduct(config),
-      color: !process.env.NO_COLOR && process.env.TERM !== "dumb",
-      columns: process.stdout.columns
+    let started = Date.now();
+    installer.phase("sign-in", { state: "running" });
+    const accessToken = await fetchAccessTokenOrLogin(config, dir, options, print, installer);
+    installer.phase("sign-in", { seconds: (Date.now() - started) / 1e3 });
+    installer.phase("resolve", { state: "running" });
+    started = Date.now();
+    const manifest = await fetchVerifiedManifest(config, accessToken, fetchImpl);
+    version = manifest.version;
+    installer.phase("resolve", { seconds: (Date.now() - started) / 1e3 });
+    const current = readState(dir);
+    const unchanged = update && current?.version === version && existsSync4(payloadDir(dir));
+    if (!unchanged) {
+      installer.phase("download", { state: "running" });
+      started = Date.now();
+      await downloadAndUnpack(config, dir, manifest, accessToken, { fetchImpl });
+      writeState(dir, { version, updatedAt: (/* @__PURE__ */ new Date()).toISOString() });
+      installer.phase("download", { seconds: (Date.now() - started) / 1e3 });
+    }
+    installer.surface({
+      id: config.product,
+      from: current?.version,
+      to: version,
+      state: unchanged ? "current" : "updated"
     });
-  } catch {
-    return null;
-  }
-}
-function since(start) {
-  return (Date.now() - start) / 1e3;
-}
-function outerConsoleOwnsOutcome() {
-  return process.env.MM_OUTER_CONSOLE === "1";
-}
-function printReceipt(face, config, print, ready, lines) {
-  const name = face ? face.identity.name : config.product;
-  const headline = ready ? `${name} is ready.` : `${name} is installed, but not ready yet.`;
-  if (ready && outerConsoleOwnsOutcome()) return;
-  if (!face) {
-    print(headline);
-    for (const line of lines) print(line.trim());
-    return;
+    return await finishLastMile(config, dir, options, installer, version, unchanged);
+  } catch (error) {
+    const code = error instanceof NeedsLoginError ? 3 : 1;
+    installer.finish({
+      version,
+      total: 1,
+      updated: 0,
+      failed: 1,
+      detail: error.message,
+      retry: `${config.binName} ${update ? "update" : "install"}`
+    });
+    return code;
+  } finally {
+    installer.stop();
   }
-  const glyph = ready ? "\u2714" : "\u2716";
-  for (const line of face.receipt([`${glyph}  ${headline}`, ...lines])) print(line);
-  print(face.signOff());
-}
-function printStep(face, print, title, seconds, kind = "ok") {
-  print(face ? face.step(title, seconds, kind) : title);
 }
-function printProgress(face, print, progress) {
-  for (const message of progress ?? []) {
-    printStep(face, print, message.step, message.ms === void 0 ? null : message.ms / 1e3, message.state);
-  }
+function doInstall(config, dir, options, print) {
+  return installOrUpdate(config, dir, options, print, false);
 }
-async function doInstall(config, dir, options, print) {
-  const fetchImpl = options.fetchImpl ?? fetch;
-  const face = faceFor(config, options);
-  const accessToken = await fetchAccessTokenOrLogin(config, dir, options, print);
-  const started = Date.now();
-  const manifest = await fetchVerifiedManifest(config, accessToken, fetchImpl);
-  await downloadAndUnpack(config, dir, manifest, accessToken, { fetchImpl });
-  writeState(dir, { version: manifest.version, updatedAt: (/* @__PURE__ */ new Date()).toISOString() });
-  printStep(face, print, `installed ${config.product} ${manifest.version}`, since(started));
-  return finishLastMile(config, dir, options, print, face, manifest.version);
-}
-async function doUpdate(config, dir, options, print) {
-  const fetchImpl = options.fetchImpl ?? fetch;
-  const face = faceFor(config, options);
-  if (face && !outerConsoleOwnsOutcome()) for (const line of face.welcome()) print(line);
-  const accessToken = await fetchAccessTokenOrLogin(config, dir, options, print);
-  const started = Date.now();
-  const manifest = await fetchVerifiedManifest(config, accessToken, fetchImpl);
-  const current = readState(dir);
-  if (current && current.version === manifest.version && existsSync4(payloadDir(dir))) {
-    printStep(face, print, `${config.product} is already up to date at ${manifest.version}`, since(started));
-    return finishLastMile(config, dir, options, print, face, manifest.version);
-  }
-  await downloadAndUnpack(config, dir, manifest, accessToken, { fetchImpl });
-  writeState(dir, { version: manifest.version, updatedAt: (/* @__PURE__ */ new Date()).toISOString() });
-  printStep(face, print, `updated ${config.product} to ${manifest.version}`, since(started));
-  return finishLastMile(config, dir, options, print, face, manifest.version);
+function doUpdate(config, dir, options, print) {
+  return installOrUpdate(config, dir, options, print, true);
 }
 function payloadEnv(dir) {
   const stored = readTokens(dir);
@@ -1225,51 +1613,124 @@ function payloadFileAsCommand(entry, payload) {
     return null;
   }
 }
-function finishLastMile(config, dir, options, print, face, version) {
+async function finishLastMile(config, dir, options, installer, version, unchanged) {
   const entry = readPayloadEntry(dir);
   const payload = payloadDir(dir);
   if (!entry) {
-    printReceipt(face, config, print, true, [
-      `Installed ${version} into ${dir}`,
-      `next step: run ${join4(payload, config.binName)} to start ${config.product}.`
-    ]);
+    installer.finish({
+      version,
+      total: 1,
+      updated: unchanged ? 0 : 1,
+      failed: 0,
+      installed: true,
+      detail: `next step: run ${join4(payload, config.binName)} to start ${config.product}.`
+    });
     return 0;
   }
   const command = resolveEntry(entry);
   const dataFile = payloadFileAsCommand(entry, payload);
   if (dataFile) {
-    printStep(face, print, `The payload names ${dataFile} as its command, but that is a file, not a program`, null, "fail");
-    printReceipt(face, config, print, false, [
-      `Downloaded ${version} into ${dir}`,
-      `This payload was built wrong: its entry must be a command, not one of its own files.`,
-      `Nothing on this machine can finish it \u2014 report it to the ${config.product} maintainers.`
-    ]);
+    installer.finish({
+      version,
+      total: 1,
+      updated: 0,
+      failed: 1,
+      detail: `The payload names ${dataFile} as its command, but that is a file, not a program. This payload was built wrong: its entry must be a command.`
+    });
     return 2;
   }
+  installer.phase("activate", { state: "running" });
   const started = Date.now();
-  const result = (options.runEntry ?? defaultRunEntry)(command, payload, payloadEnv(dir));
-  printProgress(face, print, result.progress);
-  if (result.ok) {
-    printStep(face, print, "Armed this machine", since(started));
-    printReceipt(face, config, print, true, [
-      `Installed ${version} into ${dir}`,
-      `Check health any time:  ${config.binName} doctor`
-    ]);
-    return 0;
+  const env = { ...payloadEnv(dir) ?? process.env, MM_OUTER_CONSOLE: "1" };
+  const result = options.runEntry ? options.runEntry(command, payload, env) : await runInstallEntry(command, payload, env, installer, readTokens(dir));
+  for (const progress of result.progress ?? []) installer.milestone(progress);
+  const succeeded = result.ok && (result.code === void 0 || result.code === 0);
+  const outcome = result.outcome ? validateInstallerOutcome(result.outcome) : void 0;
+  installer.phase("activate", { state: succeeded ? "ok" : "fail", seconds: (Date.now() - started) / 1e3 });
+  installer.finish({
+    ...outcome ?? {
+      version,
+      total: 1,
+      updated: succeeded && !unchanged ? 1 : 0,
+      failed: succeeded ? 0 : 1,
+      installed: true
+    },
+    ...!succeeded ? {
+      operationFailed: true,
+      detail: result.code === void 0 ? `Arming this machine could not start: ${result.error ?? command[0]}` : `Arming this machine did not finish (exit code ${result.code})${result.error?.startsWith("installer outcome:") ? `: ${result.error}` : ""}`,
+      retry: `(cd ${payload} && ${command.join(" ")})`
+    } : {}
+  });
+  return succeeded ? outcome?.operationFailed || outcome?.failed ? 1 : 0 : result.code || 1;
+}
+async function runInstallEntry(entry, cwd, env, installer, tokens = null) {
+  const [command, ...args] = entry;
+  const shell = needsShell(command);
+  const progress = !(process.platform === "win32" && shell);
+  const outcomeDir = mkdtempSync(join4(tmpdir4(), "mm-installer-outcome-"));
+  const outcomeFile = join4(outcomeDir, "outcome.json");
+  const childEnv = { ...env, MM_INSTALLER_OUTCOME_FILE: outcomeFile };
+  delete childEnv.MM_FACE_TRANSCRIPT;
+  delete childEnv.MM_PROGRESS_FD;
+  delete childEnv.MM_PROGRESS_PROTOCOL;
+  if (progress) Object.assign(childEnv, { MM_PROGRESS_FD: "3", MM_PROGRESS_PROTOCOL: "1" });
+  const secrets = [tokens?.accessToken, tokens?.refreshToken].filter((value) => Boolean(value));
+  const redact = (text) => secrets.reduce((safe, value) => safe.replaceAll(value, "[redacted]"), text);
+  try {
+    const result = await new Promise((resolve2) => {
+      const child = spawn2(shell ? [command, ...args].map(quoteForShell).join(" ") : command, shell ? [] : args, {
+        cwd,
+        shell,
+        windowsHide: true,
+        env: childEnv,
+        stdio: progress ? ["inherit", "pipe", "pipe", "pipe"] : ["inherit", "pipe", "pipe"]
+      });
+      for (const [stream, channel2] of [[child.stdout, "stdout"], [child.stderr, "stderr"]]) {
+        let partial = "";
+        stream?.setEncoding("utf8").on("data", (text) => {
+          const safe = redact(partial + text);
+          let held = 0;
+          for (const secret of secrets) for (let length = 1; length < secret.length; length++) {
+            if (safe.endsWith(secret.slice(0, length))) held = Math.max(held, length);
+          }
+          partial = held ? safe.slice(-held) : "";
+          const visible = held ? safe.slice(0, -held) : safe;
+          if (visible) installer.relay(visible, channel2, false);
+        }).on("end", () => {
+          if (partial) installer.relay("[redacted]", channel2, false);
+        });
+      }
+      let pending = "";
+      const channel = child.stdio[3];
+      if (channel && "setEncoding" in channel) {
+        channel.setEncoding("utf8");
+        channel.on("data", (text) => {
+          pending += text;
+          const end = pending.lastIndexOf("\n");
+          if (end >= 0) {
+            for (const record of parseProgress(pending.slice(0, end))) installer.milestone({ ...record, step: redact(record.step) });
+            pending = pending.slice(end + 1);
+          }
+          if (pending.length > 65536) pending = "";
+        });
+      }
+      child.on("error", (error) => resolve2({ ok: false, error: error.message }));
+      child.on("close", (code) => resolve2({
+        ok: code === 0,
+        ...code !== null ? { code } : {},
+        ...code !== 0 ? { error: `exit code ${code}` } : {}
+      }));
+    });
+    try {
+      const outcome = readInstallerOutcome(outcomeFile);
+      return { ...result, ...outcome ? { outcome } : {} };
+    } catch {
+      return { ...result, ok: false, code: result.code || 1, error: "installer outcome: invalid child result" };
+    }
+  } finally {
+    if (existsSync4(outcomeFile)) unlinkSync(outcomeFile);
+    rmdirSync(outcomeDir);
   }
-  const code = result.code ?? 1;
-  printStep(
-    face,
-    print,
-    result.code === void 0 ? `Arming this machine could not start: ${result.error ?? `could not run ${command[0]}`}` : `Arming this machine did not finish (exit code ${code})`,
-    null,
-    "fail"
-  );
-  printReceipt(face, config, print, false, [
-    `Downloaded ${version} into ${dir}`,
-    `Finish it with:  (cd ${payload} && ${command.join(" ")})`
-  ]);
-  return code;
 }
 function doForward(config, dir, options, command, argv, print) {
   if (command && existsSync4(command)) {
@@ -1392,5 +1853,6 @@ export {
   readPayloadVerbs,
   resolveEntry,
   run,
-  runFile
+  runFile,
+  runInstallEntry
 };