@web-my-money/studio-consumer 2.1.0 → 2.3.0

package/cli/provisioner.mjs

@@ -0,0 +1,102 @@
+// @ts-check
+
+/**
+ * The provisioning actions behind one interface (spec 2026-10-09 §6). This
+ * implementation runs the developer's own `gh` and `vercel` CLIs, so their
+ * sessions do the work and Studio holds no GitHub or Vercel credentials.
+ * Studio-driven provisioning (option 2) is another implementation of the same
+ * interface; nothing else changes.
+ *
+ * Flags checked against Vercel CLI 54 (2026-10-09): `env add` needs `--yes`
+ * (it otherwise asks to confirm, which hangs with the value on stdin), and has
+ * `--sensitive` and `--force`; `link` takes `--project`; `env ls` has `--format json`.
+ *
+ * @typedef {"production" | "preview"} EnvTarget
+ * @typedef {{
+ *   createRepoFromTemplate(name: string): Promise<void>,
+ *   createRepoFromSource(name: string): Promise<void>,
+ *   linkVercel(project: string): Promise<void>,
+ *   hasEnv(name: string): Promise<boolean>,
+ *   setEnv(name: string, value: string, targets: EnvTarget[], opts?: { sensitive?: boolean, force?: boolean }): Promise<void>,
+ * }} Provisioner
+ */
+
+/** @typedef {import("./run.mjs").Runner} Runner */
+
+/**
+ * @param {{ cwd: string, run: Runner, scope: string }} ctx
+ * @returns {Provisioner}
+ */
+export function cliProvisioner({ cwd, run, scope }) {
+  /**
+   * @param {string} cmd
+   * @param {string[]} args
+   * @param {{ input?: string, cwd?: string }} [opts]
+   * @param {string} [shown] what to tell the developer to run by hand (never contains a secret)
+   */
+  async function must(cmd, args, opts = {}, shown = `${cmd} ${args.join(" ")}`) {
+    const r = await run(cmd, args, { cwd: opts.cwd ?? cwd, input: opts.input });
+    if (r.code !== 0) {
+      const why = (r.stderr || r.stdout).trim().split(/\r?\n/).slice(-1)[0] ?? "";
+      throw new Error(`\`${shown}\` failed${why ? `: ${why}` : ""}`);
+    }
+    return r;
+  }
+
+  /** @type {Map<string, string[]> | null} read once per run: name → targets */
+  let envs = null;
+
+  return {
+    async createRepoFromTemplate(name) {
+      await must("gh", [
+        "repo",
+        "create",
+        `Web-My-Money/${name}`,
+        "--private",
+        "--template",
+        "Web-My-Money/wmm-app-template",
+        "--clone",
+      ]);
+    },
+    async createRepoFromSource(name) {
+      await must("gh", ["repo", "create", `Web-My-Money/${name}`, "--private", "--source", ".", "--remote", "origin"]);
+    },
+    async linkVercel(project) {
+      // --scope pins the WMM team (a personal Vercel login would otherwise link
+      // to the wrong account); --project names the project instead of guessing
+      // it from the folder name.
+      await must("vercel", ["link", "--yes", "--project", project, "--scope", scope]);
+      // `vercel link` usually connects the GitHub repo itself; then this answers
+      // "already connected", which is the state we want (seen in the real run).
+      const connect = await run("vercel", ["git", "connect", "--yes", "--scope", scope], { cwd });
+      if (connect.code !== 0 && !/already connected/i.test(`${connect.stderr}\n${connect.stdout}`)) {
+        const why = (connect.stderr || connect.stdout).trim().split(/\r?\n/).slice(-1)[0] ?? "";
+        throw new Error(`\`vercel git connect\` failed${why ? `: ${why}` : ""}`);
+      }
+    },
+    async hasEnv(name) {
+      if (!envs) {
+        const r = await must("vercel", ["env", "ls", "--format", "json", "--scope", scope]);
+        envs = new Map();
+        const parsed = /** @type {{ envs?: { key: string, target?: string[] | string }[] }} */ (JSON.parse(r.stdout || "{}"));
+        for (const e of parsed.envs ?? []) {
+          const targets = Array.isArray(e.target) ? e.target : e.target ? [e.target] : [];
+          envs.set(e.key, [...(envs.get(e.key) ?? []), ...targets]);
+        }
+      }
+      const targets = envs.get(name) ?? [];
+      return targets.includes("production") || targets.includes("preview");
+    },
+    async setEnv(name, value, targets, opts = {}) {
+      for (const target of targets) {
+        const args = ["env", "add", name, target, "--yes"];
+        if (opts.sensitive) args.push("--sensitive");
+        if (opts.force) args.push("--force");
+        args.push("--scope", scope);
+        // The value goes on stdin: never in the argument list, never on screen.
+        await must("vercel", args, { input: value }, `vercel env add ${name} ${target}`);
+      }
+      if (envs) envs.set(name, [...(envs.get(name) ?? []), ...targets]);
+    },
+  };
+}

package/cli/run.mjs

@@ -0,0 +1,89 @@
+// @ts-check
+import { spawn } from "node:child_process";
+
+/**
+ * Every external command the onboarding command runs goes through here: an
+ * argument array, never a shell string. Secrets travel on stdin (`input`), never
+ * as arguments, so they never show in a process list or a shell history.
+ *
+ * Windows: npm, vercel and other npm-installed CLIs are `.cmd` shims, which Node
+ * will only start through a shell. So a command that is not found as a real
+ * executable is retried through `cmd.exe` with every argument quoted, and an
+ * argument cmd could reinterpret (a double quote, %, a newline) is refused rather
+ * than escaped by guesswork. Our arguments are names, keys and messages we build.
+ */
+
+/**
+ * @typedef {{ code: number, stdout: string, stderr: string }} RunResult
+ * @typedef {{ cwd?: string, input?: string, inherit?: boolean }} RunOptions
+ * @typedef {(cmd: string, args: string[], opts?: RunOptions) => Promise<RunResult>} Runner
+ */
+
+/**
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {RunOptions} opts
+ * @param {boolean} viaShell
+ * @returns {Promise<RunResult & { notFound?: boolean }>}
+ */
+function once(cmd, args, opts, viaShell) {
+  return new Promise((resolve) => {
+    /** @type {import("node:child_process").ChildProcess} */
+    let child;
+    try {
+      if (viaShell) {
+        // The command NAME is passed bare: quoting it makes cmd.exe resolve a
+        // .cmd shim's own folder (%~dp0) to the cwd, which breaks npm on
+        // nvm-windows. So the name may only be a plain program name.
+        if (!/^[A-Za-z0-9_.-]+$/.test(cmd)) {
+          resolve({ code: 2, stdout: "", stderr: `refusing to run ${JSON.stringify(cmd)} through cmd.exe` });
+          return;
+        }
+        for (const a of args) {
+          if (/["%\r\n]/.test(a)) {
+            resolve({ code: 2, stdout: "", stderr: `refusing to pass ${JSON.stringify(a)} through cmd.exe` });
+            return;
+          }
+        }
+        const line = [cmd, ...args.map((a) => `"${a}"`)].join(" ");
+        child = spawn(line, { cwd: opts.cwd, shell: true, stdio: opts.inherit ? "inherit" : "pipe", windowsHide: true });
+      } else {
+        child = spawn(cmd, args, { cwd: opts.cwd, stdio: opts.inherit ? "inherit" : "pipe", windowsHide: true });
+      }
+    } catch {
+      resolve({ code: 127, stdout: "", stderr: "", notFound: true });
+      return;
+    }
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (d) => (stdout += String(d)));
+    child.stderr?.on("data", (d) => (stderr += String(d)));
+    child.on("error", (err) => {
+      const notFound = /** @type {NodeJS.ErrnoException} */ (err).code === "ENOENT";
+      resolve({ code: 127, stdout, stderr: stderr || err.message, notFound });
+    });
+    child.on("close", (code) => {
+      const notRecognised = viaShell && /is not recognized as an internal or external command/i.test(stderr);
+      resolve({ code: notRecognised ? 127 : (code ?? 1), stdout, stderr });
+    });
+    if (!opts.inherit && child.stdin) {
+      if (opts.input !== undefined) child.stdin.end(opts.input);
+      else child.stdin.end();
+    }
+  });
+}
+
+/** @returns {Runner} */
+export function createRunner() {
+  return async function run(cmd, args, opts = {}) {
+    if (/[&|<>^"%\r\n]/.test(cmd)) {
+      return { code: 2, stdout: "", stderr: `refusing to run ${JSON.stringify(cmd)}: not a plain program name` };
+    }
+    const first = await once(cmd, args, opts, false);
+    if (first.notFound && process.platform === "win32") {
+      const viaShell = await once(cmd, args, opts, true);
+      return { code: viaShell.code, stdout: viaShell.stdout, stderr: viaShell.stderr };
+    }
+    return { code: first.code, stdout: first.stdout, stderr: first.stderr };
+  };
+}

package/cli/state.mjs

@@ -0,0 +1,37 @@
+// @ts-check
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * Where the onboarding command keeps its progress, so a rerun resumes instead
+ * of starting over. Lives in `.wmm-onboarding/` (gitignored by this module).
+ * NEVER holds the ingest key: that goes straight into Vercel and nowhere else.
+ *
+ * @typedef {{
+ *   siteKey: string, siteName: string, studioUrl: string, manifestUrl: string,
+ *   revalidateUrl: string, modules: string[], readyToken: string, done: string[],
+ *   theme?: string, scope?: string, baseBranch?: string, siteHasKey?: boolean
+ * }} OnboardingState
+ */
+
+const DIR = ".wmm-onboarding";
+
+/** @param {string} cwd @returns {OnboardingState | null} */
+export function loadState(cwd) {
+  const file = path.join(cwd, DIR, "state.json");
+  if (!existsSync(file)) return null;
+  return JSON.parse(readFileSync(file, "utf8"));
+}
+
+/** @param {string} cwd @param {OnboardingState} state */
+export function saveState(cwd, state) {
+  const { ingestKey: _never, ...safe } = /** @type {OnboardingState & { ingestKey?: unknown }} */ (state);
+  mkdirSync(path.join(cwd, DIR), { recursive: true });
+  writeFileSync(path.join(cwd, DIR, "state.json"), `${JSON.stringify(safe, null, 2)}\n`);
+  const gitignore = path.join(cwd, ".gitignore");
+  const current = existsSync(gitignore) ? readFileSync(gitignore, "utf8") : "";
+  if (!current.split(/\r?\n/).includes(`${DIR}/`)) {
+    const sep = current === "" || current.endsWith("\n") ? "" : "\n";
+    writeFileSync(gitignore, `${current}${sep}${DIR}/\n`);
+  }
+}

package/cli/studio-api.mjs

@@ -0,0 +1,127 @@
+// @ts-check
+
+/**
+ * The two Studio calls the onboarding command makes, with every failure turned
+ * into a sentence a developer can act on.
+ */
+
+/** @typedef {(url: string, init: { method: string, headers: Record<string, string>, body: string }) => Promise<Response>} FetchLike */
+/** @typedef {{ ok: true, data: Record<string, unknown> } | { ok: false, message: string }} ApiResult */
+
+/**
+ * @param {FetchLike} fetchImpl
+ * @param {string} url
+ * @param {unknown} body
+ */
+async function post(fetchImpl, url, body) {
+  const res = await fetchImpl(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  /** @type {Record<string, unknown>} */
+  let json = {};
+  try {
+    json = /** @type {Record<string, unknown>} */ (await res.json());
+  } catch {
+    json = {};
+  }
+  return { status: res.status, json };
+}
+
+const unreachable = (/** @type {string} */ base) =>
+  `Could not reach Studio at ${base}. Check your internet connection, then run this again.`;
+
+/**
+ * @param {string} studioUrl
+ * @param {string} code
+ * @param {FetchLike} [fetchImpl]
+ * @returns {Promise<ApiResult>}
+ */
+export async function exchangeCode(studioUrl, code, fetchImpl = fetch) {
+  const base = studioUrl.replace(/\/+$/, "");
+  let r;
+  try {
+    r = await post(fetchImpl, `${base}/api/public/setup/exchange`, { code });
+  } catch {
+    return { ok: false, message: unreachable(base) };
+  }
+  if (r.status === 200) return { ok: true, data: r.json };
+  if (r.status === 429) {
+    return { ok: false, message: "Too many attempts from this network. Wait a minute, then run this again." };
+  }
+  if (r.status === 400) {
+    return {
+      ok: false,
+      message:
+        "That setup code has expired or was already used. Get a new one in Studio: open the site, Site settings, Get the setup command.",
+    };
+  }
+  return {
+    ok: false,
+    message:
+      typeof r.json.error === "string"
+        ? r.json.error
+        : "Studio could not finish the setup. Ask for a new code in Site settings.",
+  };
+}
+
+/**
+ * @param {string} studioUrl
+ * @param {string} readyToken
+ * @param {FetchLike} [fetchImpl]
+ * @returns {Promise<ApiResult>}
+ */
+export async function markReady(studioUrl, readyToken, fetchImpl = fetch) {
+  const base = studioUrl.replace(/\/+$/, "");
+  let r;
+  try {
+    r = await post(fetchImpl, `${base}/api/public/setup/ready`, { readyToken });
+  } catch {
+    return { ok: false, message: unreachable(base) };
+  }
+  if (r.status === 200) return { ok: true, data: r.json };
+  if (r.status === 429) {
+    return { ok: false, message: "Studio synced this site moments ago. Wait 30 seconds, then run this again." };
+  }
+  return {
+    ok: false,
+    message: typeof r.json.error === "string" ? r.json.error : "Studio could not sync the site. Run this again in a minute.",
+  };
+}
+
+/**
+ * The site's analytics key, asked for at the moment it is saved to Vercel.
+ * `inUse` means the site already has a key Studio will not replace.
+ *
+ * @param {string} studioUrl
+ * @param {string} readyToken
+ * @param {FetchLike} [fetchImpl]
+ * @returns {Promise<{ ok: true, ingestKey: string } | { ok: false, inUse: boolean, message: string }>}
+ */
+export async function requestKey(studioUrl, readyToken, fetchImpl = fetch) {
+  const base = studioUrl.replace(/\/+$/, "");
+  let r;
+  try {
+    r = await post(fetchImpl, `${base}/api/public/setup/key`, { readyToken });
+  } catch {
+    return { ok: false, inUse: false, message: unreachable(base) };
+  }
+  if (r.status === 200 && typeof r.json.ingestKey === "string") return { ok: true, ingestKey: r.json.ingestKey };
+  if (r.status === 409) {
+    return { ok: false, inUse: true, message: "This site already has an analytics key in use." };
+  }
+  if (r.status === 400) {
+    return {
+      ok: false,
+      inUse: false,
+      message: "This setup has expired (it lasts 24 hours). Get a new command in Studio's Site settings and run it.",
+    };
+  }
+  return {
+    ok: false,
+    inUse: false,
+    message: typeof r.json.error === "string" ? r.json.error : "Studio could not create the key. Run this again.",
+  };
+}
+

package/cli/templates.mjs

@@ -0,0 +1,134 @@
+// @ts-check
+
+/**
+ * The files `init` writes into a site, as functions of the values Studio handed
+ * over. They mirror docs/ONBOARD-A-SITE.md in wmm-studio; imports are relative
+ * so they work whether or not the app has an `@/` alias.
+ *
+ * Paths are relative to the app's code root (`.` or `src`), except the test,
+ * which lives at the repo root.
+ */
+
+const HEADER = "// Written by `npx @web-my-money/studio-consumer init`. Safe to edit.\n";
+
+/** @param {string} s */
+const q = (s) => JSON.stringify(s);
+
+/** @param {{ siteKey: string }} v */
+export const studioTs = (v) => `${HEADER}
+/**
+ * This site's key in WMM Studio. A constant on purpose, never an env var: every
+ * event and every content slot is filed under it, so it must not differ between
+ * environments.
+ */
+export const SITE_KEY = ${q(v.siteKey)};
+`;
+
+/** @param {{ theme: string, style: "flat" | "glass" }} v */
+export const brandTs = (v) => `${HEADER}import { defineSiteBrand } from "@web-my-money/studio-consumer/brand";
+
+/**
+ * The site's brand theme. Spread brandRootAttributes(brand) on <html> in the
+ * root layout. A missing or WMM-owned theme fails the build on purpose: a
+ * client site must never inherit WMM's look by accident.
+ */
+export const brand = defineSiteBrand({ theme: ${q(v.theme)}, style: ${q(v.style)} });
+`;
+
+export const contentManifestTs = () => `${HEADER}import { SITE_KEY } from "./studio";
+
+/**
+ * What Studio may edit on this site. Starts empty: the onboarding skill
+ * (\`/onboard-site\` in Claude Code) proposes the editable text and fills this
+ * in once you approve it.
+ */
+export async function getManifest() {
+  return {
+    siteKey: SITE_KEY,
+    generatedAt: new Date().toISOString(),
+    slots: [],
+  };
+}
+`;
+
+export const contentTs = () => `${HEADER}import "server-only";
+import { createContentClient, type StudioForm } from "@web-my-money/studio-consumer/content";
+import { getManifest } from "./content-manifest";
+import { SITE_KEY } from "./studio";
+
+// Built ONCE, at module scope: its methods share one cached fetch per render,
+// so every section of a page agrees on the content and the A/B arm.
+const client = createContentClient({
+  studioUrl: process.env.STUDIO_CONTENT_URL,
+  siteKey: SITE_KEY,
+  getManifest,
+});
+
+export type { StudioForm };
+export const getSlot = client.getSlot;
+export const getLocalizedSlot = client.getLocalizedSlot;
+export const applyDictOverrides = client.applyDictOverrides;
+export const activeVariant = client.activeVariant;
+export const getRunningExperiments = client.getRunningExperiments;
+export const getDecidedWinners = client.getDecidedWinners;
+export const getStudioForms = client.getStudioForms;
+`;
+
+/** @param {string} toLib relative path from the route file to the lib folder */
+export const manifestRouteTs = (toLib) => `${HEADER}import { createManifestHandler } from "@web-my-money/studio-consumer/content";
+import { getManifest } from "${toLib}/content-manifest";
+import { brand } from "${toLib}/brand";
+
+// Always answers from the live code (the handler waits for a request), so
+// Studio never syncs against a copy frozen at build time.
+export const GET = createManifestHandler(getManifest, brand);
+`;
+
+export const revalidateRouteTs = () => `${HEADER}import { createRevalidateHandler } from "@web-my-money/studio-consumer/content";
+
+// Built per request so the env is read at request time, not frozen at load.
+export function POST(request: Request): Promise<Response> {
+  return createRevalidateHandler({
+    studioUrl: process.env.STUDIO_CONTENT_URL,
+  })(request);
+}
+`;
+
+/**
+ * @param {string} toLib
+ * @param {boolean} withExperiments
+ */
+export const collectRouteTs = (toLib, withExperiments) => `${HEADER}import { createCollectHandler } from "@web-my-money/studio-consumer/analytics";
+import { SITE_KEY } from "${toLib}/studio";
+${withExperiments ? `import { getRunningExperiments } from "${toLib}/content";\n` : ""}
+// Built per request so the env is read at request time, not frozen at load.
+export function POST(request: Request): Promise<Response> {
+  return createCollectHandler({
+    siteKey: SITE_KEY,
+    ingestUrl: process.env.FUNNEL_INGEST_URL ?? "",
+    ingestKey: process.env.FUNNEL_INGEST_TOKEN ?? "",${withExperiments ? "\n    getRunningExperiments," : ""}
+  })(request);
+}
+`;
+
+export const frameAncestorsTestTs = () => `${HEADER}import { describe, expect, it } from "vitest";
+import nextConfig from "../next.config";
+
+type Rule = { source: string; headers: { key: string; value: string }[] };
+
+// Studio's click-to-edit frames this site's real pages. If this header is
+// lost, editing silently turns into a grey box in Studio while the site and its
+// build stay green. This test is what makes that loud.
+describe("Studio can frame this site, and nothing else can", () => {
+  it("every page sends frame-ancestors 'self' plus Studio, and no X-Frame-Options", async () => {
+    const config = nextConfig as unknown as { headers?: () => Promise<Rule[]> };
+    const rules = (await config.headers?.()) ?? [];
+    const all = rules.find((r) => r.source === "/:path*");
+    const csp = all?.headers.find((h) => h.key.toLowerCase() === "content-security-policy")?.value ?? "";
+    const frameAncestors = csp.split(";").map((p) => p.trim()).find((p) => p.startsWith("frame-ancestors")) ?? "";
+    expect(frameAncestors).toMatch(/^frame-ancestors 'self' https:\\/\\/studio\\.webmymoney\\.com/);
+    expect(frameAncestors).not.toContain("*");
+    for (const r of rules) for (const h of r.headers) expect(h.key.toLowerCase()).not.toBe("x-frame-options");
+  });
+});
+`;

package/cli/ui.mjs

@@ -0,0 +1,126 @@
+// @ts-check
+import { createInterface } from "node:readline";
+import { Writable } from "node:stream";
+
+/**
+ * How the onboarding command talks to a developer who has never done this
+ * (spec 2026-10-09 §3.0): numbered steps with one plain sentence each, a
+ * recommended default on every question, and every stop ending in the exact
+ * next command. `explain` mode answers no to everything and asks nothing.
+ */
+
+export class StopError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} [nextCommand]
+   */
+  constructor(message, nextCommand) {
+    super(message);
+    this.name = "StopError";
+    this.nextCommand = nextCommand;
+  }
+}
+
+/**
+ * @param {{ input: NodeJS.ReadableStream, output: NodeJS.WritableStream, explain?: boolean }} io
+ */
+export function createUi({ input, output, explain = false }) {
+  /** @type {string[]} */
+  const queued = [];
+  /** @type {((line: string) => void)[]} */
+  const waiting = [];
+  // Lines are read without echo from readline; a hidden answer is simply not
+  // written back. Interactive terminals echo typed characters themselves, so
+  // askSecret also turns raw mode on when it can.
+  const sink = new Writable({
+    write(_chunk, _enc, cb) {
+      cb();
+    },
+  });
+  const rl = createInterface({ input, output: sink, terminal: false });
+  rl.on("line", (line) => {
+    const next = waiting.shift();
+    if (next) next(line);
+    else queued.push(line);
+  });
+
+  /** @returns {Promise<string>} */
+  const readLine = () =>
+    new Promise((resolve) => {
+      const line = queued.shift();
+      if (line !== undefined) resolve(line);
+      else waiting.push(resolve);
+    });
+
+  /** @param {string} s */
+  const say = (s) => output.write(`${s}\n`);
+
+  return {
+    explain,
+    /** @param {number} n @param {number} total @param {string} title @param {string} why */
+    step(n, total, title, why) {
+      say("");
+      say(`Step ${n} of ${total}: ${title}`);
+      say(`  ${why}`);
+    },
+    /** @param {string} s */
+    info(s) {
+      say(`  ${s}`);
+    },
+    /** @param {string} question @param {string} def */
+    async ask(question, def) {
+      if (explain) return def;
+      output.write(`  ${question} (${def}): `);
+      const answer = (await readLine()).trim();
+      return answer === "" ? def : answer;
+    },
+    /** @param {string} question */
+    async askSecret(question) {
+      output.write(`  ${question} (it will not show as you paste): `);
+      const tty = /** @type {NodeJS.ReadStream} */ (input);
+      const canHide = typeof tty.setRawMode === "function" && tty.isTTY;
+      if (canHide) tty.setRawMode(true);
+      try {
+        const line = await readLine();
+        // In raw mode Ctrl+C arrives as a character instead of stopping the
+        // program; honour it.
+        if (line.includes("\u0003")) {
+          throw new StopError("Stopped. Run this again whenever you are ready; it continues from here.");
+        }
+        return line.trim();
+      } finally {
+        if (canHide) tty.setRawMode(false);
+        output.write("\n");
+      }
+    },
+    /** @param {string} question @param {boolean} [defYes] */
+    async confirm(question, defYes = true) {
+      if (explain) {
+        say(`  Would ask: ${question}`);
+        return false;
+      }
+      output.write(`  ${question} ${defYes ? "[Y/n]" : "[y/N]"}: `);
+      const a = (await readLine()).trim().toLowerCase();
+      if (a === "") return defYes;
+      return a === "y" || a === "yes";
+    },
+    /** @param {string} message @param {string} [nextCommand] @returns {never} */
+    stop(message, nextCommand) {
+      throw new StopError(message, nextCommand);
+    },
+    /** Hand the terminal to a child process (Claude Code, the app's checks). */
+    pause() {
+      rl.pause();
+      input.pause();
+    },
+    /** Take the terminal back after the child exits. */
+    resume() {
+      rl.resume();
+    },
+    close() {
+      rl.close();
+    },
+  };
+}
+
+/** @typedef {ReturnType<typeof createUi>} Ui */