@appinternalleads/ui 0.2.0

package/tools/ask/serve.mjs

@@ -0,0 +1,217 @@
+/**
+ * **Holding an ask open from a process that cannot draw it.**
+ *
+ * `askInBrowser(block)` starts a one-shot loopback server, hands back the URL, and resolves with
+ * the `answer/1` envelope the page POSTs to `/answer`. Then it stops. It is deliberately not a
+ * long-lived server: an ask has one answer, and a listener outliving it is a socket nobody closed.
+ *
+ * ⚠ **Loopback only, and that is load-bearing.** The page is the answer path — anything that can
+ * reach it can answer for the user — so the server binds `127.0.0.1` and checks a token on both
+ * the page and the POST. It is not authentication; it is the difference between "this machine"
+ * and "this process".
+ */
+import { createServer } from 'node:http';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { staleAgainst } from './stale.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const DIST = resolve(here, 'dist');
+const REPO = resolve(here, '../..');
+
+/** `undefined` rather than a throw: an absent source is skipped, not treated as newer. */
+const mtime = (path) => { try { return statSync(path).mtimeMs; } catch { return undefined; } };
+
+/**
+ * Everything the page bundle is built from — **in the repository, and nowhere else.**
+ *
+ * ⚠ **An installed package has no meaningful timestamps and must not be checked.** `src/` ships,
+ * `dist/` ships, and the order npm happens to extract them in decides which looks newer. Measured
+ * in a fresh install: **all 100 source files landed 280ms after `dist/ask.js`**, so the guard
+ * refused to serve in every installed package — breaking the common case to protect against one
+ * that cannot arise, since nobody can edit a source they were never delivered.
+ *
+ * `page.tsx` is the marker because it is an input to the bundle and is deliberately not shipped.
+ * Its absence means this is not a working tree, and there is nothing to be stale against.
+ *
+ * `src/` is walked because the bundle **contains** the library — editing a widget and forgetting
+ * to rebuild shows the old widget, which is the same silence as the token bug and harder to spot.
+ */
+function pageSources() {
+  const own = ['page.tsx', 'index.html', 'vite.config.ts']
+    .map(f => ({ path: `tools/ask/${f}`, ms: mtime(resolve(here, f)) }));
+  if (own.every(o => o.ms === undefined)) return [];
+
+  let src = [];
+  try {
+    src = readdirSync(resolve(REPO, 'src'), { recursive: true })
+      .filter(f => /\.(tsx?|json)$/.test(String(f)))
+      .map(f => ({ path: `src/${f}`, ms: mtime(resolve(REPO, 'src', String(f))) }));
+  } catch { /* no sources beside us; the page's own inputs are enough */ }
+  return [...own, ...src];
+}
+
+function shell() {
+  let built;
+  try {
+    built = {
+      html: readFileSync(resolve(DIST, 'index.html'), 'utf8'),
+      js: readFileSync(resolve(DIST, 'ask.js'), 'utf8'),
+    };
+  } catch {
+    /* Two audiences, and the wrong instruction is worse than none: in the repo this is a
+       forgotten build step, and in an installed package it means `prepare` did not run — which
+       is what `--ignore-scripts` does, and it is not obvious from a missing file. */
+    throw new Error(
+      `The ask page is missing from ${DIST}.\n`
+      + '  In this repository: run `npm run ask:build`.\n'
+      + '  Installed as a package: `prepare` builds it, so this usually means the install ran '
+      + 'with --ignore-scripts. Reinstall without it.',
+    );
+  }
+  /**
+   * **Refused rather than served, because a stale page fails silently and blames something else.**
+   *
+   * Measured once already: `page.tsx` edited after a build produced a page that rendered, drew
+   * and submitted — and answered `could not send: bad token`, a message about authentication for
+   * a problem that was entirely a build step.
+   */
+  const stale = staleAgainst(mtime(resolve(DIST, 'ask.js')), pageSources());
+  if (stale) {
+    throw new Error(
+      `The ask page is older than ${stale.path}, so it would serve the previous build.\n`
+      + '  Run `npm run ask:build`.\n'
+      + '  Refused rather than served because a stale page does not look broken — it renders, it '
+      + 'submits, and it fails somewhere with nothing to do with the build.',
+    );
+  }
+
+  return built;
+}
+
+/**
+ * The block travels **in the document**, as a `<script type="application/json">` beside the
+ * bundle's own tag — one page load, no second fetch, and no cache to invalidate between two asks
+ * that differ only in their JSON.
+ *
+ * ⚠ **The bundle is a route, not an inline script, and the reason is not size.** Inlining it
+ * looked tidier and broke the page: `String.replace` with a *string* replacement expands `$&`,
+ * `` $` `` and `$'` inside the replacement, and a 600 kB bundle contains all three — `$'`
+ * re-inserted the rest of the document into itself. Measured: a 900px viewport rendered
+ * 8260 × 62207, the JS parsed as HTML tags, and the browser reported only
+ * `SyntaxError: missing ) after argument list`. A replacer function fixes the expansion; serving
+ * the file removes the class of bug.
+ */
+function page(html, payload) {
+  const json = JSON.stringify(payload).replace(/</g, '\\u003c');
+  return html.replace(
+    /<script type="module"[^>]*><\/script>/,
+    m => `<script id="comppack-ask" type="application/json">${json}</script>\n    ${m}`,
+  );
+}
+
+/**
+ * @param {object} block   a `question/1` block
+ * @param {{prompt?: string, options?: object, port?: number,
+ *          timeoutMs?: number}} opts
+ * @returns {{url: string, answer: Promise<object>, close: () => void}}
+ */
+export function askInBrowser(block, opts = {}) {
+  const built = shell();
+  const token = randomUUID();
+  const payload = {
+    block,
+    prompt: opts.prompt,
+    options: opts.options,
+  };
+  const body = page(built.html, payload);
+
+  let settle;
+  const answer = new Promise((res, rej) => { settle = { res, rej }; });
+
+  const server = createServer((req, res) => {
+    /**
+     * ⚠ **A throw in this handler takes down the whole process, ask and all.**
+     *
+     * `new URL('//', 'http://127.0.0.1')` is an `ERR_INVALID_URL`, and node has nowhere to put an
+     * exception raised inside a request listener — measured: the MCP server exited code 1 in the
+     * middle of an open ask, after announcing its URL, with the client left waiting on a call
+     * that would never answer. A malformed path is not exotic; a prefetch or a probe produces
+     * one, and this server exists to be pointed at by a browser.
+     */
+    let url;
+    try {
+      url = new URL(req.url, 'http://127.0.0.1');
+    } catch {
+      res.writeHead(400).end('bad request');
+      return;
+    }
+
+    if (req.method === 'GET' && url.pathname === '/') {
+      if (url.searchParams.get('t') !== token) { res.writeHead(403).end('bad token'); return; }
+      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' }).end(body);
+      return;
+    }
+
+    if (req.method === 'GET' && url.pathname === '/ask.js') {
+      /* Same token: the bundle is only interesting to the page this process served, and a route
+         that answers anyone is a route worth not having. */
+      if (req.headers.referer && !req.headers.referer.includes(token)) {
+        res.writeHead(403).end('bad token'); return;
+      }
+      res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8' }).end(built.js);
+      return;
+    }
+
+    if (req.method === 'POST' && url.pathname === '/answer') {
+      if (url.searchParams.get('t') !== token && req.headers['x-comppack-token'] !== token) {
+        res.writeHead(403).end('bad token'); return;
+      }
+      let raw = '';
+      req.on('data', c => { raw += c; if (raw.length > 4e6) req.destroy(); });
+      req.on('end', () => {
+        try {
+          const envelope = JSON.parse(raw);
+          res.writeHead(200, { 'content-type': 'application/json' }).end('{"ok":true}');
+          settle.res(envelope);
+          /* The 200 has to reach the page before the socket goes, or the browser shows a
+             network error for an ask that actually succeeded. */
+          setTimeout(() => server.close(), 150);
+        } catch (e) {
+          res.writeHead(400).end(String(e));
+        }
+      });
+      return;
+    }
+
+    res.writeHead(404).end();
+  });
+
+  /* Same reasoning one level up: a socket error — a tab closed mid-response, a client that hung
+     up — is an event with no handler, and an unhandled `error` on a server is a throw. */
+  server.on('clientError', (_e, socket) => socket.destroy());
+  server.on('error', e => settle.rej(e));
+
+  /* Port 0 — the OS picks. A fixed port is a collision the second ask of a session hits. */
+  server.listen(opts.port ?? 0, '127.0.0.1');
+
+  const ready = new Promise(r => server.once('listening', () => r(server.address().port)));
+
+  const ms = opts.timeoutMs ?? 10 * 60_000;
+  const timer = setTimeout(() => {
+    settle.rej(new Error(`No answer within ${Math.round(ms / 1000)}s — the ask timed out.`));
+    server.close();
+  }, ms);
+  timer.unref?.();
+  /* `.then(clear, clear)` rather than `.finally` — `finally` returns a promise that rejects with
+     the same reason, and nothing is attached to it, which is an unhandled rejection on timeout. */
+  answer.then(() => clearTimeout(timer), () => clearTimeout(timer));
+
+  return {
+    ready: ready.then(port => `http://127.0.0.1:${port}/?t=${token}`),
+    answer,
+    close: () => { clearTimeout(timer); server.close(); },
+  };
+}

package/tools/ask/stale.mjs

@@ -0,0 +1,30 @@
+/**
+ * **Is the built page older than what it was built from?**
+ *
+ * Pure, and its own module, because the bug it exists to catch is one nothing else could see — and
+ * because `serve.mjs` ships in the package, so this has to be plain JS rather than TypeScript.
+ *
+ * ⚠ **The failure it prevents, measured:** `page.tsx` was edited after `ask:build` ran, so the
+ * bundle in `dist/` was one revision behind. Nothing crashed. The page rendered, the widget drew,
+ * the submit worked — and the POST came back **`could not send: bad token`**, because the stale
+ * bundle predated the token the server had started sending. A message about authentication, for a
+ * problem that was entirely a build step, on a page that looked completely fine.
+ */
+
+/**
+ * The newest source that is newer than the build, or `undefined` when the build is current.
+ *
+ * Sources that do not exist are skipped rather than treated as new: an **installed package** ships
+ * `dist/` and none of its inputs, and refusing to serve there would break the common case to guard
+ * against one that cannot happen.
+ *
+ * @param {number | undefined} builtMs  when the bundle was written
+ * @param {{path: string, ms: number | undefined}[]} sources
+ * @returns {{path: string, ms: number} | undefined}
+ */
+export function staleAgainst(builtMs, sources) {
+  if (builtMs === undefined) return undefined;
+  return sources
+    .filter(s => s.ms !== undefined && s.ms > builtMs)
+    .sort((a, b) => b.ms - a.ms)[0];
+}

package/tools/speak.mjs

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+/**
+ * **Cross-platform text-to-speech for a local MCP server — macOS, Linux and Windows.**
+ *
+ * Pairs with `src/speech/speakable.ts`, which turns `question/1` and `answer/1` into sentences.
+ * That file is pure and ships inside `@comppack/ui`; this one shells out and deliberately does
+ * NOT. `src/` never imports `node:child_process` — the component library has no business
+ * spawning processes, and `tests/peers.test.ts` is the shape of the rule that keeps it honest.
+ *
+ * **Why a local process may speak at all.** The MCP server runs over stdio on the user's own
+ * machine, launched by their editor. It is not a service; there is no other host to make noise
+ * on. That is the entire justification, and it does not extend one inch further — the moment a
+ * remote transport exists this file is wrong.
+ *
+ * ⚠ **Never a shell.** Every call is `execFile`/`spawn` with an argv array, and the text goes
+ * over **stdin** wherever the engine can read it. This is not a style preference: the text
+ * originates in `question/1` JSON that an agent wrote, so a `sh -c` string built by
+ * interpolation would be a command-injection hole with a model on the far end of it. The
+ * competitor teardown that started this work found exactly that pattern —
+ * `execSync('bunx ... add @spectrumui/' + name)` — and the only reason it was not reachable
+ * there was an accident of lookup order.
+ */
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { platform, env as processEnv, argv as processArgv, stdin as processStdin, exit } from 'node:process';
+import { Buffer } from 'node:buffer';
+import { clearTimeout, setTimeout } from 'node:timers';
+
+const execFileP = promisify(execFile);
+
+/** Longest utterance we hand an engine in one go. Deepgram's own per-request cap is 2000. */
+export const MAX_CHARS = 2000;
+
+/* ── Engines ──────────────────────────────────────────────────────────────────
+ *
+ * Each engine states how to invoke it and whether it can take text on stdin. Ordered by
+ * preference within a platform: built-in first, then the common installs.
+ */
+
+/** @typedef {{ id: string, cmd: string, args: (o: SpeakOpts) => string[], stdin: boolean, probe?: string[] }} Engine */
+
+/** macOS. `say` has shipped with every version and needs no install. */
+const MAC = [
+  {
+    id: 'say',
+    cmd: 'say',
+    stdin: true,
+    /* `-f -` reads the text from stdin; `-r` is words per minute; `-v` names one of 184 voices. */
+    args: o => [
+      ...(o.voice ? ['-v', o.voice] : []),
+      ...(o.rate ? ['-r', String(o.rate)] : []),
+      ...(o.outFile ? ['-o', o.outFile] : []),
+      '-f', '-',
+    ],
+  },
+];
+
+/**
+ * Linux. **Nothing is built in**, so all four are probed and the first present one wins.
+ *
+ * `spd-say` leads because speech-dispatcher is what a desktop Ubuntu already has running for
+ * Orca, so it is the one most likely to be installed and the one that respects the user's
+ * configured voice. `espeak-ng` is the most likely to be installed on a server.
+ */
+const LINUX = [
+  {
+    id: 'spd-say',
+    cmd: 'spd-say',
+    stdin: false,
+    /* `-e` waits for the utterance to finish, so our promise means what it says. */
+    args: o => ['-e', ...(o.rate ? ['-r', String(rateToSpd(o.rate))] : []), '--', o.text],
+  },
+  {
+    id: 'espeak-ng',
+    cmd: 'espeak-ng',
+    stdin: true,
+    args: o => [
+      ...(o.voice ? ['-v', o.voice] : []),
+      ...(o.rate ? ['-s', String(o.rate)] : []),
+      ...(o.outFile ? ['-w', o.outFile] : []),
+    ],
+  },
+  {
+    id: 'espeak',
+    cmd: 'espeak',
+    stdin: true,
+    args: o => [
+      ...(o.voice ? ['-v', o.voice] : []),
+      ...(o.rate ? ['-s', String(o.rate)] : []),
+      ...(o.outFile ? ['-w', o.outFile] : []),
+    ],
+  },
+  { id: 'festival', cmd: 'festival', stdin: true, args: () => ['--tts'] },
+];
+
+/**
+ * Windows. `System.Speech` is part of .NET and present on every supported Windows, so this
+ * needs no install either.
+ *
+ * The script reads the text from **stdin**, never from an argument. PowerShell quoting is its
+ * own dialect and an apostrophe in a question — *"What's the deadline?"* — is enough to break a
+ * naively-quoted `-Command` string. Reading the stream sidesteps quoting entirely.
+ */
+export const WINDOWS_PS = `
+$ErrorActionPreference = 'Stop'
+Add-Type -AssemblyName System.Speech
+$s = New-Object System.Speech.Synthesis.SpeechSynthesizer
+if ($env:COMPPACK_TTS_VOICE) { try { $s.SelectVoice($env:COMPPACK_TTS_VOICE) } catch {} }
+if ($env:COMPPACK_TTS_RATE)  { $s.Rate = [int]$env:COMPPACK_TTS_RATE }
+if ($env:COMPPACK_TTS_OUT)   { $s.SetOutputToWaveFile($env:COMPPACK_TTS_OUT) }
+$text = [Console]::In.ReadToEnd()
+$s.Speak($text)
+$s.Dispose()
+`.trim();
+
+/**
+ * **`-EncodedCommand`, not `-Command -`.**
+ *
+ * `-Command -` tells PowerShell to read *the script* from stdin — which is the same stream the
+ * script's own `[Console]::In.ReadToEnd()` wants the text on. The two would fight, and the
+ * failure mode is a hang rather than an error. `-EncodedCommand` takes base64 of UTF-16LE, so
+ * the script travels as an argument with no quoting dialect to get wrong, and **stdin stays free
+ * for the text** — which is the whole reason the text is not an argument.
+ */
+const psArgs = () => [
+  '-NoProfile', '-NonInteractive',
+  '-EncodedCommand', Buffer.from(WINDOWS_PS, 'utf16le').toString('base64'),
+];
+
+const WINDOWS = [
+  {
+    id: 'powershell',
+    cmd: 'powershell.exe',
+    stdin: true,
+    args: psArgs,
+    probe: ['-NoProfile', '-Command', 'exit 0'],
+  },
+  { id: 'pwsh', cmd: 'pwsh', stdin: true, args: psArgs, probe: ['-NoProfile', '-Command', 'exit 0'] },
+];
+
+/**
+ * `spd-say` takes -100..100, everything else takes words per minute. 175 wpm is its zero.
+ * Clamped rather than allowed to overflow, because speech-dispatcher rejects out-of-range and
+ * a rejected utterance is silence with an exit code nobody reads.
+ */
+const rateToSpd = wpm => Math.max(-100, Math.min(100, Math.round((wpm - 175) / 1.75)));
+
+export function enginesFor(os = platform) {
+  if (os === 'darwin') return MAC;
+  if (os === 'win32') return WINDOWS;
+  return LINUX;
+}
+
+/** Is this engine actually on the machine? Cached — a `which` per utterance is absurd. */
+const found = new Map();
+async function present(engine) {
+  if (found.has(engine.id)) return found.get(engine.id);
+  let ok = false;
+  try {
+    if (engine.probe) {
+      await execFileP(engine.cmd, engine.probe, { timeout: 10_000 });
+      ok = true;
+    } else {
+      const which = platform === 'win32' ? 'where' : 'which';
+      await execFileP(which, [engine.cmd], { timeout: 5_000 });
+      ok = true;
+    }
+  } catch {
+    /* Absent, or not runnable. Either way this engine is not a candidate. */
+  }
+  found.set(engine.id, ok);
+  return ok;
+}
+
+/**
+ * The first available engine for this platform, or `null`.
+ *
+ * **`null` is a real answer, not a failure to try.** A headless Linux box with no speech package
+ * is the common case, and the honest response is to say so once and carry on silently — the same
+ * ethic as the generator refusing a value it cannot resolve rather than snapping it to something
+ * close.
+ */
+export async function detectEngine(os = platform) {
+  for (const e of enginesFor(os)) if (await present(e)) return e;
+  return null;
+}
+
+/** The installed voice names, read once. Empty when the engine cannot enumerate them. */
+let voiceCache = null;
+async function listVoices() {
+  if (voiceCache) return voiceCache;
+  try {
+    const { stdout } = await execFileP('say', ['-v', '?'], { timeout: 10_000 });
+    /* Each line is `Name  locale  # sample`. The name runs to two-or-more spaces, so a
+       two-word voice like `Bad News` survives — splitting on one space would lose it. */
+    voiceCache = stdout.split('\n').map(l => l.split(/\s{2,}/)[0]?.trim()).filter(Boolean);
+  } catch {
+    voiceCache = [];
+  }
+  return voiceCache;
+}
+
+/** @typedef {{ text: string, voice?: string, rate?: number, outFile?: string, timeoutMs?: number }} SpeakOpts */
+
+/**
+ * **Speak `text`, resolving when the utterance has finished.**
+ *
+ * Resolves `{ spoken: false, reason }` rather than throwing when no engine exists. A missing
+ * `espeak` is not an error in the caller's logic — it is a machine without a speaker — and a
+ * throw here would take down a tool call whose actual job succeeded.
+ */
+export async function speak(opts) {
+  const o = typeof opts === 'string' ? { text: opts } : { ...opts };
+  const text = String(o.text ?? '').trim();
+  if (!text) return { spoken: false, reason: 'empty text' };
+
+  const engine = await detectEngine();
+  if (!engine) {
+    return {
+      spoken: false,
+      reason: platform === 'linux'
+        ? 'no speech engine found — install one of: speech-dispatcher, espeak-ng, espeak, festival'
+        : `no speech engine found for platform ${platform}`,
+    };
+  }
+
+  /* Truncate on a word boundary. A sentence cut mid-word sounds like a fault; a sentence cut
+     between words sounds like the end. */
+  const clipped = text.length <= MAX_CHARS
+    ? text
+    : `${text.slice(0, text.lastIndexOf(' ', MAX_CHARS)) || text.slice(0, MAX_CHARS)}…`;
+
+  /**
+   * **macOS `say` accepts an unknown voice and exits 0**, silently using the default. Measured:
+   * `say -v NotARealVoice "hi"` → exit 0. So a typo in `--voice` produces the wrong voice and no
+   * indication of it, which is the failure mode this repo refuses everywhere else. Checked here
+   * rather than left to surprise someone — a warning, not a refusal, because the utterance is
+   * still correct and only the timbre is wrong.
+   */
+  if (o.voice && engine.id === 'say') {
+    const known = await listVoices();
+    if (known.length && !known.includes(o.voice)) {
+      console.warn(`[speak] unknown voice "${o.voice}" — say will use the default. \`say -v '?'\` lists them.`);
+    }
+  }
+
+  const env = { ...processEnv };
+  if (engine.id === 'powershell' || engine.id === 'pwsh') {
+    if (o.voice) env.COMPPACK_TTS_VOICE = o.voice;
+    if (o.rate) env.COMPPACK_TTS_RATE = String(o.rate);
+    if (o.outFile) env.COMPPACK_TTS_OUT = o.outFile;
+  }
+
+  const args = engine.args({ ...o, text: clipped });
+
+  return new Promise(resolve => {
+    /* `shell: false` is the default and is load-bearing — see the header. Stated, not assumed. */
+    const child = spawn(engine.cmd, args, { shell: false, env, stdio: ['pipe', 'ignore', 'pipe'] });
+    let err = '';
+    const timer = setTimeout(() => child.kill('SIGKILL'), o.timeoutMs ?? 30_000);
+
+    child.stderr?.on('data', d => { err += String(d); });
+    child.on('error', e => {
+      clearTimeout(timer);
+      resolve({ spoken: false, engine: engine.id, reason: e.message });
+    });
+    child.on('close', code => {
+      clearTimeout(timer);
+      resolve(code === 0
+        ? { spoken: true, engine: engine.id, chars: clipped.length }
+        : { spoken: false, engine: engine.id, reason: err.trim() || `exit ${code}` });
+    });
+
+    /* Always the text. The PowerShell script now arrives as `-EncodedCommand`, not on stdin. */
+    if (engine.stdin) child.stdin.end(clipped);
+    else child.stdin.end();
+  });
+}
+
+/* ── CLI ──────────────────────────────────────────────────────────────────────
+ * `node tools/speak.mjs "some text"` — or pipe it: `echo hi | node tools/speak.mjs`
+ * `--detect` reports the engine without speaking, which is what CI runs.
+ */
+const isMain = import.meta.url === `file://${processArgv[1]}`;
+if (isMain) {
+  const argv = processArgv.slice(2);
+  const flag = n => { const i = argv.indexOf(n); return i === -1 ? undefined : argv[i + 1]; };
+
+  if (argv.includes('--detect')) {
+    const e = await detectEngine();
+    console.log(JSON.stringify({ platform, engine: e?.id ?? null, cmd: e?.cmd ?? null }, null, 2));
+    exit(e ? 0 : 1);
+  }
+
+  const positional = argv.filter((a, i) =>
+    !a.startsWith('--') && argv[i - 1] !== '--voice' && argv[i - 1] !== '--rate'
+    && argv[i - 1] !== '--out');
+
+  const text = positional.length
+    ? positional.join(' ')
+    : await new Promise(r => {
+      let b = ''; processStdin.setEncoding('utf8');
+      processStdin.on('data', d => { b += d; });
+      processStdin.on('end', () => r(b));
+    });
+
+  const result = await speak({
+    text,
+    voice: flag('--voice'),
+    rate: flag('--rate') ? Number(flag('--rate')) : undefined,
+    outFile: flag('--out'),
+  });
+  console.log(JSON.stringify(result));
+  exit(result.spoken ? 0 : 1);
+}