@mutmutco/installer-face 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# @mutmutco/installer-face
+
+The MM Terminal Line, once, for every surface that talks to a human.
+
+`docs/Guides/installer-guidebook.md` keeps the WHY. This package is the WHAT, and
+`assertFaceConformance` is the enforcement each repo runs against its own surfaces.
+
+**Scope** (owner ruling, 2026-09-20): the served one-liner scripts, the npm install path, `install`,
+`update`, bootstrap scripts and doctor receipts. A repo consumes this package. It does not keep a
+copy — and a "fallback" copy is just another copy.
+
+## Why it exists
+
+Jerv-Hub wrote this renderer, MM-Strategy copied it, and the copy immediately found the original
+breaking its own two-space rule. Four copies are four drifts waiting, and prose cannot stop drift;
+only shared code and a shared guard can.
+
+## Use
+
+```ts
+import { createFace, assertFaceConformance } from '@mutmutco/installer-face';
+
+const face = createFace({
+  product: 'jerv-hub',
+  color: Boolean(process.stdout.isTTY && !process.env.NO_COLOR && process.env.TERM !== 'dumb'),
+  columns: process.stdout.columns,
+});
+
+for (const line of face.welcome()) console.log(line);
+console.log(face.step('Registering MCP server', 2));
+console.log(face.relay(childOutput));          // another program's output, inside the rail
+for (const line of face.receipt([...])) console.log(line);
+console.log(face.signOff());
+```
+
+Colour is a DECISION the caller passes in, never sniffed here: the same face is used by processes
+whose stdout is a pipe, and a face drawn into a pipe is the bug this package exists to prevent.
+
+### Served one-liners
+
+A `curl … | sh` or `irm … | iex` script cannot import npm, so the package emits the block instead:
+
+```js
+import { renderShellFace, renderPowerShellFace } from '@mutmutco/installer-face';
+writeFileSync('install.sh', header + renderShellFace('jerv-hub') + body);
+writeFileSync('install.ps1', header + renderPowerShellFace('jerv-hub') + body);
+```
+
+The fragments carry the traps that already shipped as bugs: the stdout TTY gate (never stdin), the
+UTF-8 console encoding set before the first glyph, glyphs by code point so Windows PowerShell 5.1
+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.
+
+### The guard
+
+```ts
+import { assertFaceConformance, assertScriptConformance } from '@mutmutco/installer-face';
+
+assertFaceConformance(renderedLines, { product: 'jerv-hub', columns: 100 });
+assertFaceConformance(pipedLines, { product: 'jerv-hub', tty: false });  // plain lane: no glyphs, no colour
+assertScriptConformance(readFileSync('install.ps1', 'utf8'), { kind: 'ps1' });
+```
+
+It fails on every fault that reached a user on 2026-09-19/20: clack's corners, a single space after
+a glyph, two left edges, foreign output inside the face, a path in a step line, a ragged receipt, a
+reworded greeting, a face drawn into a pipe, a top-level `exit` in a served `.ps1`, and a literal
+glyph in a file `irm` will decode by code page.
+
+## The product table is the review gate
+
+`PRODUCTS` holds display name, accent and warm line per product. A new product is a pull request
+against this package — never a string typed into a repo.
+
+## Rendering, not reading
+
+Every fault this package guards was invisible in code review and obvious in one rendered run. The
+tests execute the shell fragment and measure the drawn columns rather than matching source text.

package/dist/conformance.d.ts

@@ -0,0 +1,21 @@
+export interface ConformanceOptions {
+    product: string;
+    /** The width the surface was rendered at; lines may not exceed it. */
+    columns?: number;
+    /** False asserts the PLAIN lane: no colour, and no glyphs or frames at all. */
+    tty?: boolean;
+}
+/**
+ * Assert a rendered surface against the contract. `lines` is what the surface actually printed,
+ * in order, colour included.
+ */
+export declare function assertFaceConformance(lines: readonly string[], options: ConformanceOptions): void;
+export interface ScriptConformanceOptions {
+    kind: 'sh' | 'ps1';
+    product?: string;
+}
+/**
+ * Assert a SERVED script — the thing `curl … | sh` and `irm … | iex` actually execute. These are
+ * source-level rules no rendered run can catch.
+ */
+export declare function assertScriptConformance(script: string, options: ScriptConformanceOptions): void;

package/dist/face.d.ts

@@ -0,0 +1,64 @@
+import { type ProductIdentity } from './products.js';
+/** The guidebook glyph set. Nothing outside this may appear in a face. */
+export declare const GLYPH: Readonly<{
+    diamond: "◆";
+    hollow: "◇";
+    bar: "│";
+    check: "✔";
+    cross: "✖";
+    dot: "●";
+    boxTop: "╭";
+    boxTopEnd: "╮";
+    boxBottom: "╰";
+    boxBottomEnd: "╯";
+    rule: "─";
+}>;
+/** MM Terminal Line tokens, as SGR parameters. */
+export declare const PALETTE: Readonly<{
+    green: "38;2;31;209;138";
+    ink: "38;2;237;237;237";
+    muted: "38;2;150;150;150";
+    line: "38;2;42;42;42";
+}>;
+/**
+ * Where a step's TITLE starts, counted from the bar: bar, two spaces, glyph, two spaces.
+ *
+ * Two spaces after the glyph, never one — the check is drawn double-width in several terminals, so a
+ * single space reads as no gap at all ("no spacing next to checkmarks", Jervaise, 2026-09-19).
+ * Wrapped continuations and relayed output share this column, which is what gives a run ONE left
+ * edge instead of three.
+ */
+export declare const TITLE_COLUMN = 6;
+/** Visible width: what the terminal draws, with colour removed. Counts CODE POINTS, never bytes. */
+export declare function visibleWidth(text: string): number;
+/** Strip every SGR sequence — the plain lane a pipe, a log or NO_COLOR must receive. */
+export declare function stripColor(text: string): string;
+/** The guidebook's width cap: no emitted line exceeds the terminal width, 100 by default. */
+export declare function faceWidth(columns?: number): number;
+/** Break at word boundaries, hard-slicing a token longer than the line itself. */
+export declare function wrapWords(text: string, width: number): string[];
+export type StepKind = 'ok' | 'fail' | 'note';
+export interface Face {
+    readonly identity: ProductIdentity;
+    readonly width: number;
+    /** `◆ <product> — Mutatis Mutandis` and the product's own warm line. */
+    welcome(): string[];
+    /** One durable line for one finished step: glyph, title, and a measured time when truthful. */
+    step(title: string, seconds?: number | null, kind?: StepKind): string;
+    /** Another program's output, kept inside the face at the step-title column. */
+    relay(text: string): string;
+    /** The closing box: what changed, and one suggested command. */
+    receipt(lines: string[] | string): string[];
+    /** The sign-off, in the product accent. */
+    signOff(): string;
+    /** A refusal that reads as a face line rather than a bare error string. */
+    refusal(message: string): string;
+    paint(sgr: string, text: string): string;
+}
+export interface FaceOptions {
+    product: string;
+    /** False emits no escape codes at all, so a piped or logged run is byte-stable plain text. */
+    color?: boolean;
+    columns?: number;
+}
+export declare function createFace({ product, color, columns }: FaceOptions): Face;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { createFace, faceWidth, stripColor, visibleWidth, wrapWords, GLYPH, PALETTE, TITLE_COLUMN } from './face.js';
+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 { assertFaceConformance, assertScriptConformance } from './conformance.js';
+export type { ConformanceOptions, ScriptConformanceOptions } from './conformance.js';

package/dist/index.js

@@ -0,0 +1,454 @@
+// src/products.ts
+var PRODUCTS = Object.freeze({
+  "mm-strategy": Object.freeze({
+    name: "MM Strategy",
+    accent: "38;2;249;115;22",
+    warm: "Welcome. Let's set up MM Strategy \u2014 about a minute."
+  }),
+  "mmi-hub": Object.freeze({
+    name: "mmi-hub",
+    accent: "38;2;125;211;252",
+    warm: "Welcome back. Checking your surfaces\u2026"
+  }),
+  "jerv-hub": Object.freeze({
+    name: "jerv-hub",
+    accent: "38;2;248;113;113",
+    warm: "Welcome back. Checking your surfaces\u2026"
+  }),
+  jervcode: Object.freeze({
+    name: "JervCode",
+    accent: "38;2;192;132;252",
+    warm: "Welcome back. Keeping JervCode current\u2026"
+  })
+});
+function identityFor(product) {
+  const identity = PRODUCTS[product];
+  if (!identity) {
+    throw new Error(`unknown product ${JSON.stringify(product)} \u2014 add it to installer/face/src/products.ts rather than composing a greeting locally (known: ${Object.keys(PRODUCTS).join(", ")})`);
+  }
+  return identity;
+}
+
+// src/face.ts
+var GLYPH = Object.freeze({
+  diamond: "\u25C6",
+  hollow: "\u25C7",
+  bar: "\u2502",
+  check: "\u2714",
+  cross: "\u2716",
+  dot: "\u25CF",
+  boxTop: "\u256D",
+  boxTopEnd: "\u256E",
+  boxBottom: "\u2570",
+  boxBottomEnd: "\u256F",
+  rule: "\u2500"
+});
+var PALETTE = Object.freeze({
+  green: "38;2;31;209;138",
+  ink: "38;2;237;237;237",
+  muted: "38;2;150;150;150",
+  line: "38;2;42;42;42"
+});
+var TITLE_COLUMN = 6;
+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));
+}
+function wrapWords(text, width) {
+  const limit = Math.max(8, Math.floor(width));
+  const lines = [];
+  let line = "";
+  for (const word of String(text).split(/\s+/u).filter(Boolean)) {
+    let token = word;
+    while (visibleWidth(token) > limit) {
+      if (line) {
+        lines.push(line);
+        line = "";
+      }
+      lines.push([...token].slice(0, limit).join(""));
+      token = [...token].slice(limit).join("");
+    }
+    if (!line) line = token;
+    else if (visibleWidth(line) + 1 + visibleWidth(token) <= limit) line += ` ${token}`;
+    else {
+      lines.push(line);
+      line = token;
+    }
+  }
+  if (line) lines.push(line);
+  return lines.length ? lines : [""];
+}
+function createFace({ product, color = false, columns }) {
+  const identity = identityFor(product);
+  const width = faceWidth(columns);
+  const paint = (sgr, text) => color ? `\x1B[${sgr}m${text}\x1B[0m` : String(text);
+  const bar = () => paint(PALETTE.muted, GLYPH.bar);
+  const indent = " ".repeat(TITLE_COLUMN - 1);
+  const welcome = () => [
+    `${paint(identity.accent, GLYPH.diamond)}  ${paint(identity.accent, identity.name)} \u2014 Mutatis Mutandis`,
+    bar(),
+    `${bar()}  ${identity.warm}`,
+    bar()
+  ];
+  const step = (title, seconds = null, kind = "ok") => {
+    const glyph = kind === "fail" ? paint(identity.accent, GLYPH.cross) : kind === "note" ? paint(PALETTE.muted, GLYPH.hollow) : paint(PALETTE.green, GLYPH.check);
+    const time = seconds === null || seconds === void 0 ? "" : paint(PALETTE.muted, `${Math.max(0, Math.round(seconds))}s`);
+    const column = Math.min(44, Math.max(0, width - 8));
+    const reserved = time ? 6 : 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 body = (Array.isArray(lines) ? lines : String(lines).split("\n")).flatMap((raw) => {
+      const line = String(raw);
+      if (visibleWidth(line) <= width - 6) return [line];
+      const lead = /^\s*/u.exec(line)?.[0] ?? "";
+      return wrapWords(line, width - 6 - lead.length).map((part) => `${lead}${part}`);
+    });
+    const content = Math.min(width - 6, Math.max(...body.map(visibleWidth)));
+    const rule = paint(identity.accent, GLYPH.rule.repeat(content + 4));
+    const frame = (left, right) => `${paint(identity.accent, left)}${rule}${paint(identity.accent, right)}`;
+    return [
+      frame(GLYPH.boxTop, GLYPH.boxTopEnd),
+      ...body.map((line) => `${paint(identity.accent, GLYPH.bar)}  ${line}${" ".repeat(Math.max(0, content - visibleWidth(line)))}  ${paint(identity.accent, GLYPH.bar)}`),
+      frame(GLYPH.boxBottom, GLYPH.boxBottomEnd)
+    ];
+  };
+  const signOff = () => `${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, step, relay, receipt, signOff, refusal, paint };
+}
+
+// src/shell.ts
+var RELAY_INDENT = " ".repeat(TITLE_COLUMN - 1);
+function renderShellFace(product) {
+  const identity = identityFor(product);
+  return `# >>> installer-face:begin (generated by @mutmutco/installer-face \u2014 do not edit by hand)
+# MMI-Hub docs/Guides/installer-guidebook.md, face A: branded welcome, one durable line per finished
+# step with a measured time, relayed output kept inside the face, and a closing receipt box.
+FACE_COLOR=0
+if [ -t 1 ] && [ -z "\${NO_COLOR:-}" ] && [ "\${TERM:-}" != 'dumb' ]; then
+  FACE_COLOR=1
+fi
+FACE_NAME='${identity.name}'
+FACE_ACCENT='${identity.accent}'
+FACE_WARM='${identity.warm.replace(/'/gu, "'\\''")}'
+FACE_MUTED='${PALETTE.muted}'
+FACE_GREEN='${PALETTE.green}'
+
+# paint <sgr> <text> -> the text, coloured only when colour is allowed.
+paint() {
+  if [ "$FACE_COLOR" = '1' ]; then
+    printf '\\033[%sm%s\\033[0m' "$1" "$2"
+  else
+    printf '%s' "$2"
+  fi
+}
+
+face_welcome() {
+  printf '%s  %s %s\\n' "$(paint "$FACE_ACCENT" '\u25C6')" "$(paint "$FACE_ACCENT" "$FACE_NAME")" '\u2014 Mutatis Mutandis'
+  printf '%s\\n' "$(paint "$FACE_MUTED" '\u2502')"
+  printf '%s  %s\\n' "$(paint "$FACE_MUTED" '\u2502')" "$FACE_WARM"
+  printf '%s\\n' "$(paint "$FACE_MUTED" '\u2502')"
+}
+
+# face_step <title> <start epoch seconds> \u2014 one durable line for a finished step, measured.
+face_step() {
+  face_secs=$(( $(date +%s) - $2 ))
+  [ "$face_secs" -ge 0 ] || face_secs=0
+  face_title="$1"
+  if [ \${#face_title} -gt 38 ]; then
+    face_title="$(printf '%.18s' "$face_title")\u2026$(printf '%s' "$face_title" | tail -c 19)"
+    face_pad=0
+  else
+    face_pad=$(( 38 - \${#face_title} ))
+  fi
+  printf '%s  %s  %s%*s%s\\n' \\
+    "$(paint "$FACE_MUTED" '\u2502')" "$(paint "$FACE_GREEN" '\u2714')" "$face_title" "$face_pad" '' "$(paint "$FACE_MUTED" "\${face_secs}s")"
+}
+
+# face_relay \u2014 read another program's output and keep it inside the face, at the step-title column.
+face_relay() {
+  while IFS= read -r face_l; do
+    if [ -n "$face_l" ]; then
+      printf '%s${RELAY_INDENT}%s\\n' "$(paint "$FACE_MUTED" '\u2502')" "$face_l"
+    else
+      printf '%s\\n' "$(paint "$FACE_MUTED" '\u2502')"
+    fi
+  done
+}
+
+face_rule() {
+  face_r=''
+  face_i=0
+  while [ "$face_i" -lt "$1" ]; do
+    face_r="$face_r\u2500"
+    face_i=$((face_i + 1))
+  done
+  printf '%s' "$face_r"
+}
+
+# face_receipt <headline> <next command> <location> \u2014 the closing box.
+face_receipt() {
+  face_text1="$1"
+  face_text2="    Installed into $3"
+  face_text3="    Check health any time:  $2"
+  face_w1=$(( \${#face_text1} + 3 ))
+  face_w=$face_w1
+  [ \${#face_text2} -gt "$face_w" ] && face_w=\${#face_text2}
+  [ \${#face_text3} -gt "$face_w" ] && face_w=\${#face_text3}
+  face_bar="$(paint "$FACE_ACCENT" '\u2502')"
+  face_line="$(face_rule $((face_w + 4)))"
+  printf '%s\\n' "$(paint "$FACE_ACCENT" "\u256D\${face_line}\u256E")"
+  printf '%s  %s  %*s%s\\n' "$face_bar" "$(paint "$FACE_GREEN" '\u2714')  $face_text1" "$((face_w - face_w1))" '' "$face_bar"
+  printf '%s  %s%*s  %s\\n' "$face_bar" "$face_text2" "$((face_w - \${#face_text2}))" '' "$face_bar"
+  printf '%s  %s%*s  %s\\n' "$face_bar" "$face_text3" "$((face_w - \${#face_text3}))" '' "$face_bar"
+  printf '%s\\n' "$(paint "$FACE_ACCENT" "\u2570\${face_line}\u256F")"
+  printf '%s  %s\\n' "$(paint "$FACE_ACCENT" '\u25C6')" "$(paint "$FACE_ACCENT" "$FACE_NAME \xB7 Mutatis Mutandis")"
+}
+
+face_refusal() {
+  printf '%s  %s  %s\\n' "$(paint "$FACE_MUTED" '\u2502')" "$(paint "$FACE_ACCENT" '\u2716')" "$1" >&2
+}
+# <<< installer-face:end
+`;
+}
+function renderPowerShellFace(product) {
+  const identity = identityFor(product);
+  return `# >>> installer-face:begin (generated by @mutmutco/installer-face \u2014 do not edit by hand)
+# MMI-Hub docs/Guides/installer-guidebook.md, face A. Glyphs are emitted by code point because this
+# file is decoded by the console code page when \`irm\` pipes it to \`iex\`.
+$FaceDiamond = [char] 0x25C6
+$FaceHollow = [char] 0x25C7
+$FaceBar = [char] 0x2502
+$FaceCheck = [char] 0x2714
+$FaceCross = [char] 0x2716
+$FaceDash = [char] 0x2014
+
+$FaceName = '${identity.name}'
+$FaceAccent = '${identity.accent}'
+$FaceWarm = '${identity.warm.replace(/'/gu, "''").replace(/\u2026/gu, "' + [char] 0x2026 + '")}'
+$FaceMuted = '${PALETTE.muted}'
+$FaceGreen = '${PALETTE.green}'
+
+$FaceColor = $false
+if ([string]::IsNullOrEmpty($env:NO_COLOR) -and -not [Console]::IsOutputRedirected) {
+    if ((-not [string]::IsNullOrEmpty($env:WT_SESSION)) -or $PSVersionTable.PSVersion.Major -ge 6) {
+        $FaceColor = $true
+    }
+}
+try {
+    [Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
+}
+catch {
+    # A console that refuses UTF-8 still gets the glyphs its code page can draw.
+}
+
+function Write-Paint {
+    param([string] $Sgr, [string] $Text)
+    if ($FaceColor) {
+        return ([char] 27) + '[' + $Sgr + 'm' + $Text + ([char] 27) + '[0m'
+    }
+    return $Text
+}
+
+function Write-FaceWelcome {
+    Write-Host ((Write-Paint $FaceAccent ([string] $FaceDiamond)) + '  ' + (Write-Paint $FaceAccent $FaceName) + ' ' + $FaceDash + ' Mutatis Mutandis')
+    Write-Host (Write-Paint $FaceMuted ([string] $FaceBar))
+    Write-Host ((Write-Paint $FaceMuted ([string] $FaceBar)) + '  ' + $FaceWarm)
+    Write-Host (Write-Paint $FaceMuted ([string] $FaceBar))
+}
+
+# A title longer than the step column is shortened in the middle: a path's start and tail identify it.
+function Get-FaceTitle {
+    param([string] $Title, [int] $Width = 38)
+    if ($Title.Length -le $Width) {
+        return $Title
+    }
+    $head = [Math]::Floor(($Width - 1) / 2)
+    $tail = $Width - 1 - $head
+    return $Title.Substring(0, $head) + [char] 0x2026 + $Title.Substring($Title.Length - $tail)
+}
+
+function Write-FaceStep {
+    param([string] $Title, [DateTime] $Started)
+    $seconds = [Math]::Max(0, [int] ([DateTime]::UtcNow - $Started).TotalSeconds)
+    Write-Host ((Write-Paint $FaceMuted ([string] $FaceBar)) + '  ' + (Write-Paint $FaceGreen ([string] $FaceCheck)) + '  ' + (Get-FaceTitle $Title).PadRight(38) + ' ' + (Write-Paint $FaceMuted ($seconds.ToString() + 's')))
+}
+
+# Another program's output, kept inside the face at the step-title column.
+function Write-FaceRelay {
+    param([string] $Line)
+    if ([string]::IsNullOrWhiteSpace($Line)) {
+        Write-Host (Write-Paint $FaceMuted ([string] $FaceBar))
+        return
+    }
+    Write-Host ((Write-Paint $FaceMuted ([string] $FaceBar)) + '${RELAY_INDENT}' + $Line)
+}
+
+function Write-FaceReceipt {
+    param([string] $Location, [string] $Next)
+    $first = [string] $FaceCheck + '  ' + $FaceName + ' is ready.'
+    $second = '    Installed into ' + $Location
+    $third = '    Check health any time:  ' + $Next
+    $inner = ($first.Length, $second.Length, $third.Length | Measure-Object -Maximum).Maximum
+    $rule = [string]::new([char] 0x2500, $inner + 4)
+    Write-Host (Write-Paint $FaceAccent ([string] [char] 0x256D + $rule + [char] 0x256E))
+    foreach ($text in @($first, $second, $third)) {
+        Write-Host ((Write-Paint $FaceAccent ([string] $FaceBar)) + '  ' + $text.PadRight($inner) + '  ' + (Write-Paint $FaceAccent ([string] $FaceBar)))
+    }
+    Write-Host (Write-Paint $FaceAccent ([string] [char] 0x2570 + $rule + [char] 0x256F))
+    Write-Host ((Write-Paint $FaceAccent ([string] $FaceDiamond)) + '  ' + (Write-Paint $FaceAccent ($FaceName + ' ' + [char] 0x00B7 + ' Mutatis Mutandis')))
+}
+
+function Write-FaceRefusal {
+    param([string] $Message)
+    [Console]::Error.WriteLine((Write-Paint $FaceMuted ([string] $FaceBar)) + '  ' + (Write-Paint $FaceAccent ([string] $FaceCross)) + '  ' + $Message)
+}
+# <<< installer-face:end
+`;
+}
+
+// src/conformance.ts
+var ALLOWED = new Set(Object.values(GLYPH));
+var FORBIDDEN = /* @__PURE__ */ new Map([
+  ["\u2713", "U+2713 is not in the guidebook glyph set; the check is U+2714"],
+  ["\u2717", "U+2717 is not in the guidebook glyph set; the cross is U+2716"],
+  ["\u21BB", "U+21BB is not in the guidebook glyph set; a retry uses the dot U+25CF"],
+  ["\u250C", "U+250C is clack's intro corner; the welcome opens with the branded diamond"],
+  ["\u251C", "U+251C is clack's note frame; a receipt box pairs U+256D/U+256E over U+2570/U+256F"],
+  ["\u2514", "U+2514 is clack's outro corner; the sign-off carries the diamond"]
+]);
+var EMOJI = /[\u{1f300}-\u{1faff}\u{2600}-\u{27bf}]/u;
+function fail(rule, detail) {
+  throw new Error(`installer face: ${rule} \u2014 ${detail}`);
+}
+function assertFaceConformance(lines, options) {
+  const identity = identityFor(options.product);
+  const width = options.columns ?? 100;
+  const rendered = lines.flatMap((line) => String(line).split("\n"));
+  const plain = rendered.map(stripColor);
+  if (rendered.length === 0) fail("R7 render before you ship", "no rendered lines were given to the guard");
+  if (options.tty === false) {
+    for (const line of plain) {
+      const glyph = [...line].find((char) => ALLOWED.has(char));
+      if (glyph) fail("non-TTY lane is plain", `a piped run emitted ${JSON.stringify(glyph)} in ${JSON.stringify(line)}`);
+    }
+    for (const line of rendered) {
+      if (line.includes("\x1B[")) fail("non-TTY lane is plain", `a piped run emitted colour in ${JSON.stringify(line)}`);
+    }
+    return;
+  }
+  for (const line of plain) {
+    if (/[\u25c6\u25c7\u2714\u2716\u25cf] (?! )/u.test(line)) {
+      fail("R4 two spaces after a glyph", `a single space follows the glyph in ${JSON.stringify(line)}`);
+    }
+  }
+  for (const line of plain) {
+    for (const [glyph, why] of FORBIDDEN) {
+      if (line.includes(glyph)) fail("glyph set", `${why} (in ${JSON.stringify(line)})`);
+    }
+    const emoji = [...line].find((char) => EMOJI.test(char) && !ALLOWED.has(char));
+    if (emoji) fail("glyph set", `emoji ${JSON.stringify(emoji)} in ${JSON.stringify(line)}`);
+  }
+  const top = plain.findIndex((line) => line.startsWith(GLYPH.boxTop));
+  if (top !== -1) {
+    const bottom = plain.findIndex((line, index) => index > top && line.startsWith(GLYPH.boxBottom));
+    if (bottom === -1) fail("R5 receipt frame", "the receipt box opens and never closes");
+    if (!plain[top].endsWith(GLYPH.boxTopEnd)) fail("R5 receipt frame", `the top row does not pair its corners: ${JSON.stringify(plain[top])}`);
+    if (!plain[bottom].endsWith(GLYPH.boxBottomEnd)) fail("R5 receipt frame", `the bottom row does not pair its corners: ${JSON.stringify(plain[bottom])}`);
+    const widths = new Set(plain.slice(top, bottom + 1).map(visibleWidth));
+    if (widths.size !== 1) fail("R5 receipt frame", `the box is ragged: widths ${[...widths].join(", ")}`);
+  }
+  const inReceipt = (index) => top !== -1 && index >= top && index <= plain.findIndex((line, at) => at > top && line.startsWith(GLYPH.boxBottom));
+  const welcomeEnd = (plain[0] ?? "").startsWith(GLYPH.diamond) ? 4 : 0;
+  for (const [index, line] of plain.entries()) {
+    if (index < welcomeEnd || inReceipt(index)) continue;
+    if (!line.startsWith(GLYPH.bar) || line.trim() === GLYPH.bar) continue;
+    const after = [...line.slice(1)];
+    const at = after.findIndex((char) => char !== " ");
+    const edge = at + 2;
+    if (edge === 4 && ALLOWED.has(after[at])) continue;
+    if (edge !== TITLE_COLUMN + 1) {
+      fail("R1 one rail, one left edge", `text starts at column ${edge} without a glyph there; a line that carries no glyph belongs at the title column (${TITLE_COLUMN + 1}): ${JSON.stringify(line)}`);
+    }
+  }
+  for (const line of plain) {
+    if (/\(node:\d+\)|DeprecationWarning|ExperimentalWarning/u.test(line)) {
+      fail("R2 no foreign output in the face", `a Node warning reached the face: ${JSON.stringify(line)} \u2014 fix the spawn, or run the child with --no-deprecation`);
+    }
+  }
+  const receiptStart = top === -1 ? plain.length : top;
+  for (const line of plain.slice(0, receiptStart)) {
+    if (/[\u2714\u2716\u25cf\u25c7]/u.test(line) && /([A-Za-z]:\\|\/(?:home|Users|opt|usr)\/)/u.test(line)) {
+      fail("R3 paths live in the receipt", `a step line carries a path: ${JSON.stringify(line)}`);
+    }
+  }
+  for (const line of plain) {
+    if (visibleWidth(line) > width) {
+      fail("width cap", `a line is ${visibleWidth(line)} columns wide, cap ${width}: ${JSON.stringify(line)}`);
+    }
+  }
+  const head = plain[0] ?? "";
+  if (head.startsWith(GLYPH.diamond)) {
+    const expected = `${GLYPH.diamond}  ${identity.name} \u2014 Mutatis Mutandis`;
+    if (head !== expected) fail("welcome is the product table's", `expected ${JSON.stringify(expected)}, got ${JSON.stringify(head)}`);
+    const warm = plain.slice(1, 4).find((line) => line.includes(identity.warm));
+    if (!warm) fail("welcome is the product table's", `the warm line for ${options.product} is missing or reworded`);
+  }
+  const painted = rendered.join("\n");
+  if (painted.includes("\x1B[")) {
+    if (!painted.includes(identity.accent) && !painted.includes(PALETTE.muted)) {
+      fail("accent", `${options.product} rendered colour that is neither its accent nor a neutral token`);
+    }
+  }
+}
+function assertScriptConformance(script, options) {
+  const text = String(script);
+  if (text.includes("%%")) fail("served script", "an unrendered placeholder survived");
+  if (options.kind === "ps1") {
+    const topLevelExit = text.split(/\r?\n/u).filter((line) => /^\s*exit\b/u.test(line));
+    if (topLevelExit.length > 0) {
+      fail("served script", "a top-level `exit` closes the user's terminal under `irm | iex`; report the outcome through $LASTEXITCODE");
+    }
+    for (const glyph of ALLOWED) {
+      if (text.includes(glyph)) {
+        fail("served script", `the glyph ${JSON.stringify(glyph)} is written literally; emit it by code point ([char] 0x25C6) or PowerShell 5.1 renders mojibake`);
+      }
+    }
+    if (!/IsOutputRedirected/u.test(text)) fail("served script", "colour must drop when output is redirected");
+    if (!/OutputEncoding/u.test(text)) fail("served script", "set [Console]::OutputEncoding to UTF-8 before writing or relaying any glyph");
+  } else {
+    if (!/\[ -t 1 \]/u.test(text)) fail("served script", "colour must be gated on stdout being a TTY (`[ -t 1 ]`), never on stdin");
+    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");
+    }
+  }
+  if (!/NO_COLOR/u.test(text)) fail("served script", "NO_COLOR must disable colour");
+}
+export {
+  GLYPH,
+  PALETTE,
+  PRODUCTS,
+  TITLE_COLUMN,
+  assertFaceConformance,
+  assertScriptConformance,
+  createFace,
+  faceWidth,
+  identityFor,
+  renderPowerShellFace,
+  renderShellFace,
+  stripColor,
+  visibleWidth,
+  wrapWords
+};

package/dist/products.d.ts

@@ -0,0 +1,12 @@
+export interface ProductIdentity {
+    /** The display name exactly as the guidebook writes it — `jerv-hub`, not `Jerv Hub`. */
+    readonly name: string;
+    /** Product accent as SGR parameters (truecolor). Callers degrade by dropping colour entirely. */
+    readonly accent: string;
+    /** The warm line under the welcome. Verbatim from the guidebook; never composed at a call site. */
+    readonly warm: string;
+}
+export declare const PRODUCTS: Readonly<Record<string, ProductIdentity>>;
+/** The identity for a product key. An unknown key is a caller bug, and failing here is cheaper than
+ *  shipping an installer that greets a user as the wrong product. */
+export declare function identityFor(product: string): ProductIdentity;

package/dist/shell.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The POSIX sh face block.
+ *
+ * Two traps are baked in rather than left to the caller, because both shipped as bugs first:
+ *  - `${#var}` counts BYTES in a POSIX shell, so a string containing the check measures three
+ *    columns too wide and tears the receipt frame open. Everything measured here is ASCII and the
+ *    glyph is accounted for by hand.
+ *  - a rule cannot be built with `tr ' ' '─'`: tr is byte-oriented, substitutes ONE byte of the
+ *    three-byte character and emits mojibake. It is built by repetition.
+ */
+export declare function renderShellFace(product: string): string;
+/**
+ * The Windows PowerShell 5.1 face block.
+ *
+ * Every glyph is emitted BY CODE POINT, never as a literal character: `irm` hands the file to `iex`
+ * as text decoded by the console's own code page, and Windows PowerShell 5.1 renders literal UTF-8
+ * glyphs as mojibake. Colour is opt-in to terminals that speak VT and is dropped when output is
+ * redirected, so a logged run stays byte-stable.
+ */
+export declare function renderPowerShellFace(product: string): string;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@mutmutco/installer-face",
+  "version": "0.1.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",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.28.1",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.0"
+  }
+}