viewable-one 0.0.0-stage → 0.12.1

package/lib/cli-output.mjs

@@ -0,0 +1,176 @@
+/** Human CLI presentation only. Never use on the MCP JSON-RPC stream. */
+const clean = value => String(value ?? '').replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').replace(/[\x00-\x1f\x7f-\x9f]/g, ' ');
+export function colorEnabled({ env = process.env, isTTY = process.stdout.isTTY } = {}) {
+  if (Object.hasOwn(env, 'NO_COLOR') || env.FORCE_COLOR === '0' || env.TERM === 'dumb') return false;
+  return Boolean(isTTY || (env.FORCE_COLOR && env.FORCE_COLOR !== '0'));
+}
+const paint = (text, code, color) => color ? `\x1b[${code}m${text}\x1b[0m` : text;
+export function heading(title, { color = colorEnabled() } = {}) {
+  return paint(clean(title), '1;36', color);
+}
+// ---------------------------------------------------------------------------
+// THE PAINT BOX (brief 31, Move 7, 2026-09-12). The ruling: "make sure you
+// format the terminal stuff properly, use colors and make it look good to
+// work in terminal for user."
+//
+// NO DEPENDENCY. `chalk`/`kleur` buy nothing here: four colours and bold is
+// `paint` above, and every helper below goes through `colorEnabled` and
+// `clean`, so NO_COLOR / TERM=dumb / a pipe all get plain text and the
+// first-line rule of this file - never on the MCP JSON-RPC stream - holds
+// for the new helpers exactly as it does for `heading`.
+//
+// WIDTH IS `wrap`'s JOB, not each caller's. `step`, `hint` and `bullets` all
+// go through it, so an 80-column terminal is the floor everything is built
+// against rather than something remembered per line.
+
+/** Secondary text: a URL to paste, a "press ^C to cancel". */
+export function dim(text, { color = colorEnabled() } = {}) {
+  return paint(clean(text), '2', color);
+}
+
+/** The one line that says which thing is asking. */
+export function bold(text, { color = colorEnabled() } = {}) {
+  return paint(clean(text), '1', color);
+}
+
+/** A result that landed. */
+export function ok(text, { color = colorEnabled() } = {}) {
+  return paint(clean(text), '32', color);
+}
+
+/** A result that was skipped, or landed with something left to do. */
+export function warn(text, { color = colorEnabled() } = {}) {
+  return paint(clean(text), '33', color);
+}
+
+/** A result that did not land. `die` paints its FIRST line with this and
+ *  leaves the rest plain, so a pasted error is still readable in an issue. */
+export function fail(text, { color = colorEnabled() } = {}) {
+  return paint(clean(text), '31', color);
+}
+
+/** "Step 2 of 4 · Connect this project" - the walk `viewable init` became.
+ *  Same bold cyan as `heading`, because it IS the heading of that step. */
+export function step(n, total, text, { color = colorEnabled(), width = process.stdout.columns || 88 } = {}) {
+  const title = `Step ${Number(n)} of ${Number(total)} \u00b7 ${clean(text)}`;
+  const lines = wrap(title, Math.max(32, Math.min(100, width)), '');
+  return lines.map((line) => paint(line, '1;36', color)).join('\n');
+}
+
+/** Dim, indented, wrapped: the URL under a browser hand-off, the next step
+ *  under a row. Returns one string so a caller can `say(hint(...))`. */
+export function hint(text, { color = colorEnabled(), width = process.stdout.columns || 88, indent = '  ' } = {}) {
+  const w = Math.max(32, Math.min(100, width));
+  return wrap(text, w, indent).map((line) => paint(line, '2', color)).join('\n');
+}
+
+/** A short list under a heading. Returns LINES, like `checkSections`, because
+ *  a list is many lines and joining them is the caller's choice. */
+export function bullets(items, { color = colorEnabled(), width = process.stdout.columns || 88 } = {}) {
+  const w = Math.max(32, Math.min(100, width));
+  const lines = [];
+  for (const item of items ?? []) {
+    const wrapped = wrap(item, w, '    ');
+    if (!wrapped.length) continue;
+    lines.push(`  ${paint('\u2022', '2', color)} ${wrapped[0].trimStart()}`);
+    lines.push(...wrapped.slice(1));
+  }
+  return lines;
+}
+
+// ---------------------------------------------------------------------------
+// THE DOCTOR-SHAPED ROW (brief 31 review, 2026-09-12). `{key, label, ok,
+// state, detail, action?}` plus the `warn` variant (`ok:true, warn:true`,
+// ruling 8B: a warning is green) is the one shape lib/doctor.mjs,
+// lib/uninstall.mjs and lib/uninstall-project.mjs all print - three
+// byte-identical copies of these two constructors were found on review.
+// Homed here rather than in doctor.mjs because this is the module that
+// already knows how to PAINT a row (`renderRow` below), and every caller of
+// `row`/`warnRow` needs that too.
+export const row = (key, label, ok, state, detail = '', action) =>
+  action ? { key, label, ok, state, detail, action } : { key, label, ok, state, detail };
+
+/** A row that is neither ok nor FAIL: something is missing, the install
+ * still works, and what it costs is said out loud. `ok:true` on purpose -
+ * ruling 8B counts a warning as green. */
+export const warnRow = (key, label, state, detail = '') => ({ key, label, ok: true, warn: true, state, detail });
+
+/** One row, painted: the STATUS/label line plus its wrapped detail. Shared by
+ * `checkSections` (which groups rows under headings first) and `printedRows`
+ * in lib/uninstall.mjs (which has no groups) - both used to keep their own
+ * copy of exactly this rendering, found identical on review 2026-09-12. The
+ * `beat` label override is `checkSections`' own special case; a row from
+ * anywhere else never carries that key, so it is harmless to apply here for
+ * everyone. */
+export function renderRow(row, { color = colorEnabled(), width = process.stdout.columns || 88 } = {}) {
+  const w = Math.max(32, Math.min(100, width));
+  const status = row.warn ? 'WARN' : row.ok ? 'OK' : 'FAIL';
+  const code = row.warn ? '33' : row.ok ? '32' : '31';
+  const label = row.key === 'beat' ? 'Runner heartbeat' : clean(row.label);
+  const state = row.state ? ` — ${clean(row.state)}` : '';
+  const wrapped = wrap(`${label}${state}`, w - 7, '');
+  const lines = [`  ${paint(status.padEnd(4), code, color)} ${wrapped[0] ?? label}`];
+  lines.push(...wrapped.slice(1).map(line => `       ${line}`));
+  if (row.detail) lines.push(...wrap(row.detail, w, '       '));
+  return lines;
+}
+
+export function wrap(text, width = 80, indent = '      ') {
+  const available = Math.max(12, width - indent.length);
+  const words = clean(text).trim().split(/\s+/);
+  const lines = []; let line = '';
+  for (let word of words) {
+    if (line && line.length + word.length + 1 > available) { lines.push(indent + line); line = ''; }
+    while (word.length > available) { lines.push(indent + word.slice(0, available)); word = word.slice(available); }
+    if (word) line += (line ? ' ' : '') + word;
+  }
+  if (line) lines.push(indent + line);
+  return lines;
+}
+export function checkSections(rows, { color = colorEnabled(), width = process.stdout.columns || 88 } = {}) {
+  width = Math.max(32, Math.min(100, width));
+  const groups = [
+    ['Project', ['registry', 'mirror', 'mcp', 'opencode', 'codex']],
+    ['Runner', ['plist', 'daemonVersion', 'daemon', 'beat', 'boardAuth']],
+    ['Coding agents', ['agents', 'login']],
+    ['System', ['platform', 'git', 'version']],
+  ];
+  const known = new Set(groups.flatMap(([, keys]) => keys));
+  groups.push(['Other checks', rows.filter(r => !known.has(r.key)).map(r => r.key)]);
+  const lines = [];
+  for (const [title, keys] of groups) {
+    const selected = rows.filter(row => keys.includes(row.key));
+    if (!selected.length) continue;
+    lines.push('', heading(title, { color }));
+    for (const row of selected) lines.push(...renderRow(row, { color, width }));
+  }
+  const actions = new Set(rows.filter(row => !row.ok).map(row => {
+    // A row that came with its own next step knows better than the default
+    // below: "run glytch init" is a loop when init is what was refused.
+    if (row.action) return clean(row.action);
+    if (row.key === 'mirror') return 'Open your board and link the project folder shown above.';
+    if (row.key === 'beat') return 'Wait a few seconds, then run viewable doctor from this project. If the heartbeat stays missing, run viewable init.';
+    if (row.key === 'login') return 'Run claude once and sign in.';
+    if (row.key === 'agents') return 'Install a selected coding agent, or run viewable init to change your selection.';
+    return 'Run viewable init from this project folder to refresh its setup, then viewable doctor.';
+  }));
+  if (actions.size) {
+    lines.push('', heading('Next steps', { color }));
+    for (const action of actions) lines.push(...wrap(action, width, '  '));
+  }
+  return lines;
+}
+export function summary(rows, { color = colorEnabled() } = {}) {
+  const failures = rows.filter(row => !row.ok).length;
+  const warnings = rows.filter(row => row.warn).length;
+  const message = failures
+    ? `${failures} check${failures === 1 ? ' needs' : 's need'} attention. Follow the instructions under FAIL.`
+    : warnings ? `No failed checks. ${warnings} warning${warnings === 1 ? '' : 's'} to review.` : 'All checks passed.';
+  return paint(message, failures ? '1;31' : warnings ? '1;33' : '1;32', color);
+}
+export function homeNotice(root, home, options) {
+  if (root !== home) return [];
+  return ['', heading('Check your project folder', options),
+    ...wrap('You are in your home folder. Run project commands inside the folder linked to your board.', 88, '  '),
+    '  Example: cd ~/Projects/your-project', ''];
+}

package/lib/cloudflared-release.json

@@ -0,0 +1,25 @@
+{
+  "version": "2026.8.3",
+  "assets": {
+    "darwin-x64": {
+      "name": "cloudflared-darwin-amd64.tgz",
+      "sha256": "61e1316266a00fd70ce40da011d612badc805367fb65293dd1925f938f704c99"
+    },
+    "darwin-arm64": {
+      "name": "cloudflared-darwin-arm64.tgz",
+      "sha256": "40c9144d86df8937c5b43293a1f7d2d2107029aa74725023dd46b1b27154352f"
+    },
+    "linux-x64": {
+      "name": "cloudflared-linux-amd64",
+      "sha256": "f29324fe934d1e100617484c78deef803c4dc2cd351d645bbde42e96b4fccc5e"
+    },
+    "linux-arm64": {
+      "name": "cloudflared-linux-arm64",
+      "sha256": "4bcfd35521a7cbc545ebfd5d57334a71ee180e2a64874981f374c81472118391"
+    },
+    "win32-x64": {
+      "name": "cloudflared-windows-amd64.exe",
+      "sha256": "83e726ed18ea78c5ad5213c4c3a3a27051393950d2bc8ed4de69bec12d14eaae"
+    }
+  }
+}

package/lib/cloudflared.mjs

@@ -0,0 +1,81 @@
+/** Pinned official binaries; no system package manager or administrator access. */
+import { createHash, randomUUID } from 'node:crypto';
+import { readFile, writeFile, mkdir, rename, rm, chmod } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { gunzipSync } from 'node:zlib';
+import release from './cloudflared-release.json' with { type: 'json' };
+
+const MAX_BYTES = 100 * 1024 * 1024;
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+export function cloudflaredAsset(platform = process.platform, arch = process.arch) {
+  const asset = release.assets[`${platform}-${arch}`];
+  if (!asset) throw new Error(`Automatic preview setup is not available for ${platform}/${arch}. Set PM_CLOUDFLARED_BIN to a compatible cloudflared executable.`);
+  return { ...asset, version: release.version };
+}
+
+// Read only the expected regular file from the verified archive; never extract paths.
+export function unpackCloudflared(bytes, name) {
+  if (!name.endsWith('.tgz')) return bytes;
+  const tar = gunzipSync(bytes, { maxOutputLength: MAX_BYTES });
+  for (let offset = 0; offset + 512 <= tar.length;) {
+    const header = tar.subarray(offset, offset + 512);
+    const file = header.subarray(0, 100).toString().replace(/\0.*$/s, '');
+    const size = parseInt(header.subarray(124, 136).toString().replace(/\0.*$/s, '').trim(), 8);
+    if (!file) break;
+    if (!Number.isSafeInteger(size) || size < 0 || offset + 512 + size > tar.length) break;
+    if ((file === 'cloudflared' || file === './cloudflared') && [0, 48].includes(header[156])) {
+      return tar.subarray(offset + 512, offset + 512 + size);
+    }
+    offset += 512 + Math.ceil(size / 512) * 512;
+  }
+  throw new Error('The verified cloudflared archive contains no executable.');
+}
+
+async function download(url, fetchImpl, signal) {
+  const response = await fetchImpl(url, { signal });
+  if (!response.ok || !response.body) throw new Error(`Preview setup download failed (${response.status}). Retry when online.`);
+  const chunks = []; let size = 0;
+  for await (const chunk of response.body) {
+    size += chunk.length;
+    if (size > MAX_BYTES) throw new Error('Preview setup download exceeds the size limit.');
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks);
+}
+
+export async function ensureCloudflared({
+  platform = process.platform, arch = process.arch,
+  cacheDir = join(homedir(), '.glytch', 'bin', 'cloudflared'),
+  fetchImpl = fetch, signal, asset = cloudflaredAsset(platform, arch),
+} = {}) {
+  const combinedSignal = signal ? AbortSignal.any([signal, AbortSignal.timeout(120_000)]) : AbortSignal.timeout(120_000);
+  combinedSignal.throwIfAborted();
+  const dir = join(cacheDir, asset.version, `${platform}-${arch}`);
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  const archive = join(dir, asset.name + '.download');
+  let bytes;
+  try { bytes = await readFile(archive); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (!bytes || hash(bytes) !== asset.sha256) {
+    bytes = await download(`https://github.com/cloudflare/cloudflared/releases/download/${asset.version}/${asset.name}`, fetchImpl, combinedSignal);
+    if (hash(bytes) !== asset.sha256) throw new Error('Preview setup checksum verification failed. No downloaded program was run.');
+    await atomicWrite(archive, bytes);
+  }
+  combinedSignal.throwIfAborted();
+  const executable = unpackCloudflared(bytes, asset.name);
+  const bin = join(dir, platform === 'win32' ? 'cloudflared.exe' : 'cloudflared');
+  let current;
+  try { current = await readFile(bin); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (!current || hash(current) !== hash(executable)) await atomicWrite(bin, executable);
+  if (platform !== 'win32') await chmod(bin, 0o700);
+  combinedSignal.throwIfAborted();
+  return bin;
+}
+
+async function atomicWrite(path, bytes) {
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, bytes, { flag: 'wx', mode: 0o700 });
+    await rename(temporary, path);
+  } finally { await rm(temporary, { force: true }); }
+}

package/lib/codex-rpc.mjs

@@ -0,0 +1,92 @@
+// Codex app-server JSON-RPC over newline-delimited stdio. No model turn is
+// started by connecting or querying model/list. Protocol checked against
+// codex-cli 0.153.4 and https://learn.chatgpt.com/docs/app-server (2026-09-08).
+import { spawn } from "node:child_process";
+import { runnableCommand } from "./windows-command.mjs";
+
+export function startCodex({ bin = "codex", args = ["app-server"], cwd, env = process.env, platform = process.platform } = {}) {
+  const command = runnableCommand(bin, args, { platform, env });
+  return spawn(command.file, command.args, { cwd, env, shell: command.shell, windowsHide: true, stdio: ["pipe", "pipe", "pipe"] });
+}
+
+export function codexRpc(child, { onNotification = () => {}, onRequest = () => { throw new Error("This client cannot answer this request; use the board ask_user tool."); }, timeoutMs = 15_000 } = {}) {
+  let nextId = 0;
+  let buffer = "";
+  let closed = false;
+  const pending = new Map();
+  const received = new Set();
+  const send = (message) => {
+    if (closed || child.stdin.destroyed || !child.stdin.writable) throw new Error("Codex connection closed");
+    child.stdin.write(`${JSON.stringify(message)}\n`);
+  };
+  const close = (error = new Error("Codex connection closed")) => {
+    closed = true;
+    for (const { reject, timer } of pending.values()) { clearTimeout(timer); reject(error); }
+    pending.clear();
+  };
+  child.stdin.on("error", close);
+  child.on("error", close);
+  child.on("close", () => close());
+  child.stdout.setEncoding("utf8");
+  child.stdout.on("data", (chunk) => {
+    buffer += chunk;
+    if (buffer.length > 2_000_000) { close(new Error("Codex protocol line exceeds limit")); child.kill(); return; }
+    let end;
+    while ((end = buffer.indexOf("\n")) >= 0) {
+      const line = buffer.slice(0, end); buffer = buffer.slice(end + 1);
+      let message;
+      try { message = JSON.parse(line); } catch { continue; }
+      if (!message || typeof message !== "object") continue;
+      if (message.method && message.id !== undefined) {
+        // A repeated server request must neither file another question nor
+        // receive a second answer. IDs are scoped to this connection.
+        if (received.has(message.id)) continue;
+        received.add(message.id);
+        Promise.resolve().then(() => onRequest(message.method, message.params ?? {}, message.id)).then(
+          (result) => { if (!closed) send({ id: message.id, result }); },
+          (error) => { if (!closed) send({ id: message.id, error: { code: -32601, message: error.message } }); },
+        ).catch(() => {});
+      } else if (message.method) onNotification(message.method, message.params ?? {});
+      else if (pending.has(message.id)) {
+        const call = pending.get(message.id); pending.delete(message.id); clearTimeout(call.timer);
+        if (message.error) call.reject(new Error(message.error.message ?? "Codex request failed"));
+        else call.resolve(message.result);
+      }
+    }
+  });
+  const request = (method, params = {}) => new Promise((resolve, reject) => {
+    const id = ++nextId;
+    const timer = setTimeout(() => { pending.delete(id); reject(new Error(`Codex ${method} timed out`)); }, timeoutMs);
+    pending.set(id, { resolve, reject, timer });
+    try { send({ id, method, params }); } catch (error) { clearTimeout(timer); pending.delete(id); reject(error); }
+  });
+  return { request, close, async initialize() {
+    await request("initialize", { clientInfo: { name: "glytch", title: "Viewable board runner", version: "0.2.0" }, capabilities: {} });
+    send({ method: "initialized", params: {} });
+  } };
+}
+
+export async function discoverCodex({ bin = "codex", args = ["app-server"], env = process.env, timeoutMs = 5000, spawnImpl = startCodex } = {}) {
+  const child = spawnImpl({ bin, args, env });
+  // Drain stderr, but never expose config/auth diagnostics in a runner mark.
+  child.stderr?.resume();
+  const rpc = codexRpc(child, { timeoutMs });
+  const deadline = setTimeout(() => { rpc.close(new Error("Codex discovery timed out")); child.kill(); }, timeoutMs);
+  try {
+    await rpc.initialize();
+    const account = await rpc.request("account/read", { refreshToken: false });
+    const models = [];
+    let cursor;
+    do {
+      const page = await rpc.request("model/list", { ...(cursor ? { cursor } : {}), limit: 100 });
+      for (const model of page.data ?? []) {
+        if (model.hidden || typeof model.model !== "string") continue;
+        models.push({ id: model.model, label: model.displayName || model.model,
+          efforts: (model.supportedReasoningEfforts ?? []).map((e) => e.reasoningEffort).filter((e) => typeof e === "string"),
+          defaultEffort: model.defaultReasoningEffort, isDefault: model.isDefault === true });
+      }
+      cursor = page.nextCursor;
+    } while (cursor && models.length < 200);
+    return { loggedIn: account.account != null || account.requiresOpenaiAuth === false, models };
+  } finally { clearTimeout(deadline); rpc.close(); child.stdin.end(); child.kill(); }
+}