@mutmutco/installer-face 0.1.0 → 0.2.0

package/README.md

@@ -51,6 +51,33 @@ UTF-8 console encoding set before the first glyph, glyphs by code point so Windo
 cannot mojibake them, a rule built by repetition rather than `tr` (byte-oriented, emits mojibake),
 and receipt widths measured in columns rather than `${#var}` bytes.
 
+### Transient status
+
+```js
+import { createSpinner } from '@mutmutco/installer-face';
+
+const spinner = createSpinner(face, { animate: Boolean(process.stderr.isTTY && !process.env.NO_COLOR) });
+spinner.start('Downloading the launcher');
+spinner.say('Downloading the launcher (12 MB)');
+spinner.stop();                       // ALWAYS before the durable line
+console.log(face.step('Downloaded the launcher', 12));
+```
+
+Status goes to stderr, results to stdout, so a relayed or redirected run never receives frames. The
+frame occupies the step line's glyph column and is rendered through `face.step(text, null, 'note')`
+rather than composed, so it inherits `TITLE_COLUMN` and the width cap, and the durable line replaces
+it exactly. Off a TTY it writes nothing at all — no frames, no escape codes, no cleared lines. The
+interval is `unref`'d, so a throw before `stop()` cannot hold a process open.
+
+clack cannot provide this: its `spinner().stop()` always prints a line carrying its own glyph, which
+is one of the three defects that made us draw the face ourselves.
+
+Served scripts get the same lane from the generated fragments: `face_status` / `face_status_clear`
+in sh (gated on `[ -t 2 ]`), and `Write-FaceStatus` / `Clear-FaceStatus` in PowerShell, with frames
+emitted BY CODE POINT because `irm` hands the file to `iex` decoded by the console code page. Both
+advance the frame per CALL rather than on a timer: drive them from the work — a byte count, a retry,
+a phase change.
+
 ### The guard
 
 ```ts

package/dist/index.d.ts

@@ -3,5 +3,9 @@ export type { Face, FaceOptions, StepKind } from './face.js';
 export { PRODUCTS, identityFor } from './products.js';
 export type { ProductIdentity } from './products.js';
 export { renderShellFace, renderPowerShellFace } from './shell.js';
+export { renderRows } from './rows.js';
+export type { Row } from './rows.js';
+export { createSpinner, SPINNER_FRAMES } from './spinner.js';
+export type { Spinner, SpinnerOptions } from './spinner.js';
 export { assertFaceConformance, assertScriptConformance } from './conformance.js';
 export type { ConformanceOptions, ScriptConformanceOptions } from './conformance.js';

package/dist/index.js

@@ -192,7 +192,7 @@ face_rule() {
   face_r=''
   face_i=0
   while [ "$face_i" -lt "$1" ]; do
-    face_r="$face_r\u2500"
+    face_r="\${face_r}\u2500"
     face_i=$((face_i + 1))
   done
   printf '%s' "$face_r"
@@ -220,6 +220,29 @@ face_receipt() {
 face_refusal() {
   printf '%s  %s  %s\\n' "$(paint "$FACE_MUTED" '\u2502')" "$(paint "$FACE_ACCENT" '\u2716')" "$1" >&2
 }
+
+# face_status <text> \u2014 transient status, redrawn in place on STDERR (0.2.0). A served script has no
+# timer and no background job worth the complexity, so the frame advances on each CALL: drive it from
+# the work (a byte count, a retry, a phase change) rather than from a clock. Gated on stderr being a
+# TTY, so a piped or logged run receives nothing and stays byte-stable.
+FACE_FRAME=0
+face_status() {
+  [ -t 2 ] || return 0
+  FACE_FRAME=$(( (FACE_FRAME + 1) % 4 ))
+  case "$FACE_FRAME" in
+    0) face_f='\u25D2' ;;
+    1) face_f='\u25D0' ;;
+    2) face_f='\u25D3' ;;
+    *) face_f='\u25D1' ;;
+  esac
+  printf '\\r\\033[2K%s  %s  %s' "$(paint "$FACE_MUTED" '\u2502')" "$(paint "$FACE_MUTED" "$face_f")" "$1" >&2
+}
+
+# Always call before writing the durable line, or the finished step lands on a half-drawn frame.
+face_status_clear() {
+  [ -t 2 ] || return 0
+  printf '\\r\\033[2K' >&2
+}
 # <<< installer-face:end
 `;
 }
@@ -315,10 +338,110 @@ function Write-FaceRefusal {
     param([string] $Message)
     [Console]::Error.WriteLine((Write-Paint $FaceMuted ([string] $FaceBar)) + '  ' + (Write-Paint $FaceAccent ([string] $FaceCross)) + '  ' + $Message)
 }
+
+# Transient status, redrawn in place on STDERR (0.2.0). Frames are emitted BY CODE POINT for the same
+# reason the glyphs are: \`irm\` hands this file to \`iex\` decoded by the console code page, so a
+# literal UTF-8 frame arrives as mojibake on Windows PowerShell 5.1. The frame advances per CALL \u2014
+# drive it from the work, not from a timer.
+$FaceFrames = @([char] 0x25D2, [char] 0x25D0, [char] 0x25D3, [char] 0x25D1)
+$FaceFrame = 0
+function Write-FaceStatus {
+    param([string] $Text)
+    if ([Console]::IsErrorRedirected) {
+        return
+    }
+    $script:FaceFrame = ($script:FaceFrame + 1) % $FaceFrames.Length
+    $line = (Write-Paint $FaceMuted ([string] $FaceBar)) + '  ' + (Write-Paint $FaceMuted ([string] $FaceFrames[$script:FaceFrame])) + '  ' + $Text
+    [Console]::Error.Write([string] [char] 13 + ([char] 27) + '[2K' + $line)
+}
+
+# Always call before writing the durable line.
+function Clear-FaceStatus {
+    if ([Console]::IsErrorRedirected) {
+        return
+    }
+    [Console]::Error.Write([string] [char] 13 + ([char] 27) + '[2K')
+}
 # <<< installer-face:end
 `;
 }
 
+// src/rows.ts
+var SEPARATOR = "\xB7";
+var subjectOf = (row) => row.aspect ? `${row.surface} ${row.aspect}` : row.surface;
+var groupKey = (row) => `${subjectOf(row)}\0${row.state}\0${row.mark ?? ""}\0${row.note ?? ""}`;
+function renderRows(face, rows) {
+  if (rows.length === 0) return [];
+  const groups = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const key = groupKey(row);
+    const found = groups.get(key);
+    if (found) {
+      if (row.instance) found.instances.push(row.instance);
+    } else {
+      groups.set(key, { row, instances: row.instance ? [row.instance] : [] });
+    }
+  }
+  const subjects = [...groups.values()].map(({ row, instances }) => instances.length > 1 ? subjectOf(row) : [subjectOf(row), instances[0]].filter(Boolean).join(` ${SEPARATOR} `));
+  const column = Math.min(Math.max(...subjects.map(visibleWidth)), Math.max(12, face.width - 24));
+  const lines = [];
+  for (const [index, { row, instances }] of [...groups.values()].entries()) {
+    const subject = subjects[index];
+    const tail = instances.length > 1 ? `${row.state} ${SEPARATOR} ${instances.join(", ")}` : row.state;
+    const body = `${clip(subject, column).padEnd(column)}  ${row.mark ? `${markGlyph(face, row.mark)}  ` : ""}${tail}`;
+    lines.push(...face.relay(body).split("\n"));
+    if (row.note) {
+      for (const part of wrapWords(row.note, Math.max(16, face.width - column - 10))) {
+        lines.push(...face.relay(`${" ".repeat(column)}  ${part}`).split("\n"));
+      }
+    }
+  }
+  return lines;
+}
+function markGlyph(face, kind) {
+  const glyph = kind === "fail" ? GLYPH.cross : kind === "note" ? GLYPH.hollow : GLYPH.check;
+  return face.paint(kind === "fail" ? face.identity.accent : kind === "note" ? "38;2;150;150;150" : "38;2;31;209;138", glyph);
+}
+function clip(text, width) {
+  if (visibleWidth(text) <= width) return text;
+  return `\u2026${[...text].slice(-(width - 1)).join("")}`;
+}
+
+// src/spinner.ts
+var FRAMES = ["\u25D2", "\u25D0", "\u25D3", "\u25D1"];
+function createSpinner(face, { animate, stream = process.stderr, intervalMs = 90 }) {
+  let timer = null;
+  let text = "";
+  let frame = 0;
+  const clear = () => {
+    if (animate) stream.write("\r\x1B[2K");
+  };
+  const draw = () => {
+    if (!animate) return;
+    const line = face.step(text, null, "note").split("\n")[0].replace(GLYPH.hollow, FRAMES[frame % FRAMES.length]);
+    stream.write(`\r\x1B[2K${line}`);
+    frame += 1;
+  };
+  return {
+    start(next) {
+      text = next;
+      frame = 0;
+      draw();
+      if (animate && !timer) timer = setInterval(draw, intervalMs).unref();
+    },
+    say(next) {
+      text = next;
+      draw();
+    },
+    stop() {
+      if (timer) clearInterval(timer);
+      timer = null;
+      clear();
+    }
+  };
+}
+var SPINNER_FRAMES = Object.freeze([...FRAMES]);
+
 // src/conformance.ts
 var ALLOWED = new Set(Object.values(GLYPH));
 var FORBIDDEN = /* @__PURE__ */ new Map([
@@ -433,6 +556,8 @@ function assertScriptConformance(script, options) {
     if (/\btr\s+'\s'\s+'\u2500'/u.test(text)) {
       fail("served script", "a rule cannot be built with tr: it is byte-oriented and substitutes one byte of the three-byte character");
     }
+    const unbraced = text.match(/\$[A-Za-z_][A-Za-z0-9_]*[^\x00-\x7F]/u);
+    if (unbraced) fail("served script", `an unbraced $variable abuts a non-ASCII byte and macOS sh reads it as one variable name: ${JSON.stringify(unbraced[0])} \u2014 brace the expansion`);
   }
   if (!/NO_COLOR/u.test(text)) fail("served script", "NO_COLOR must disable colour");
 }
@@ -440,13 +565,16 @@ export {
   GLYPH,
   PALETTE,
   PRODUCTS,
+  SPINNER_FRAMES,
   TITLE_COLUMN,
   assertFaceConformance,
   assertScriptConformance,
   createFace,
+  createSpinner,
   faceWidth,
   identityFor,
   renderPowerShellFace,
+  renderRows,
   renderShellFace,
   stripColor,
   visibleWidth,

package/dist/rows.d.ts

@@ -0,0 +1,22 @@
+import type { Face, StepKind } from './face.js';
+export interface Row {
+    /** The thing being reported: `Hermes desktop`, `Claude Code`, `jerv-cli`. */
+    surface: string;
+    /** What about it: `skill`, `MCP`, `panel`. Omitted when the surface is the whole subject. */
+    aspect?: string;
+    /** Which copy: a Hermes profile, a host account. Omitted for machine-level work. */
+    instance?: string;
+    /** What happened: `registered`, `written`, `installed`, `2/3 profiles`. */
+    state: string;
+    /** Optional glyph for a health verdict; omit for a plain convergence row. */
+    mark?: StepKind;
+    /** A continuation hanging under this row, with no subject of its own. */
+    note?: string;
+}
+/**
+ * Render a batch of rows as durable lines, aligned in one column the package computes.
+ *
+ * Batch in, lines out: the column cannot be right for a row rendered alone, which is exactly how
+ * every hand-built version drifted.
+ */
+export declare function renderRows(face: Face, rows: readonly Row[]): string[];

package/dist/spinner.d.ts

@@ -0,0 +1,26 @@
+import type { Face } 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;
+    /** Stop and CLEAR the line. Always call before writing the durable step line. */
+    stop(): void;
+}
+export interface SpinnerOptions {
+    /** False writes nothing at all: no frames, no escape codes, no cleared lines. */
+    animate: boolean;
+    /** Defaults to stderr. Results belong on stdout; status never does. */
+    stream?: NodeJS.WritableStream;
+    /** Frame interval in ms. */
+    intervalMs?: number;
+}
+/**
+ * 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;
+/** The frames, exported so a conformance check can recognise transient output. */
+export declare const SPINNER_FRAMES: readonly string[];

package/package.json

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