@north-light/cli 0.0.0-stage → 0.3.413

package/bin/runtime-selector.mjs

@@ -0,0 +1,510 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { GENERATION_ID, contained, isValidPublishedGeneration, nodeVersionsCompatible, parseSelectionTarget, runtimeHome, validateManifestShape } from './runtime-generation-manifest.mjs';
+
+const ROOT = runtimeHome();
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const FEEDBACK_REPO = 'Northlight-Systems/crouter';
+const generationEntryLeases = new Map();
+
+/** Keep the selected generation observable to runtime GC for this process's lifetime. */
+function holdGenerationEntryLease(entryPath) {
+  if (!generationEntryLeases.has(entryPath)) generationEntryLeases.set(entryPath, openSync(entryPath, 'r'));
+}
+
+function isSourceCheckout() {
+  return existsSync(join(PACKAGE_ROOT, '.git'));
+}
+
+/**
+ * One line for a long first-run step. At a terminal it is an animated bar
+ * drawn by `bin/progress-painter.mjs` in its own process (the installer and
+ * the renderer provision both block this event loop), replaced by a `✓`/`✗`
+ * line when the step ends. Off a terminal it is the same one-time notice this
+ * shim has always printed, and nothing else.
+ *
+ * Both steps are indeterminate: neither the runtime installer nor `uv`
+ * reports a count this shim could fill a bar from, and a bar that invents one
+ * would be lying about progress it cannot see.
+ */
+function beginStep(command, notice) {
+  if (!process.stderr.isTTY) {
+    process.stderr.write(`${command}: ${notice}\n`);
+    return null;
+  }
+  let child;
+  try {
+    child = spawn(process.execPath, [join(dirname(fileURLToPath(import.meta.url)), 'progress-painter.mjs'), `${command}: ${notice}`], { stdio: ['pipe', 2, 'ignore'] });
+  } catch {
+    process.stderr.write(`${command}: ${notice}\n`);
+    return null;
+  }
+  let alive = true;
+  const exited = new Promise((resolve) => {
+    child.once('exit', () => { alive = false; resolve(); });
+    child.once('error', () => { alive = false; resolve(); });
+  });
+  return async (outcome) => {
+    if (alive) child.stdin.end();
+    await Promise.race([exited, new Promise((resolve) => setTimeout(() => { child.kill('SIGKILL'); resolve(); }, 1000).unref())]);
+    process.stderr.write(`\r\x1b[2K\x1b[?25h${command}: ${outcome}\n`);
+  };
+}
+
+// Set when the first-run self-install ran and failed, so the closing message
+// points at the installer's own error instead of a blanket "reinstall".
+let firstInstallFailed = false;
+
+function remediation() {
+  if (firstInstallFailed) return 'The one-time runtime install above failed. Fix the cause it names, then run `crtr` again — it retries the install.';
+  return isSourceCheckout()
+    ? 'Run `npm run build && npm run install-runtime` in the crouter source checkout, then retry.'
+    : 'Reinstall crouter, then retry.';
+}
+
+/**
+ * First-run self-install. A published install relies on npm running
+ * `scripts/postinstall.mjs` to stage the first runtime generation, and npm no
+ * longer does that for a global install (11.19 skips install scripts, and its
+ * own allow-scripts remediations skip them too). Upgrades never depended on
+ * npm — self-update calls install-runtime.mjs directly — so first install was
+ * the only path still trusting it. This closes that gap the same way: when no
+ * generation is selected at all and this shim sits in a published package
+ * tree, stage one from that tree and continue.
+ *
+ * Only the missing-selection case qualifies. A selection that exists but
+ * fails validation is a real defect to report, not something to paper over,
+ * and a source checkout keeps its explicit `npm run install-runtime` because
+ * its `dist/` may be stale or absent.
+ */
+async function installFirstGeneration(command) {
+  if (isSourceCheckout() || !existsSync(join(PACKAGE_ROOT, 'dist', 'index.js'))) return false;
+  const end = beginStep(command, 'first run — installing the runtime generation (one-time)');
+  const result = await runInstaller(end !== null);
+  if (end !== null) await end(result.ok ? '✓ runtime generation' : `✗ runtime generation — ${firstLine(result.output) ?? 'installer failed'}`);
+  if (!result.ok && result.output !== '') process.stderr.write(result.output.endsWith('\n') ? result.output : `${result.output}\n`);
+  if (!result.ok) firstInstallFailed = true;
+  return result.ok;
+}
+
+/** Run the runtime installer. Behind a bar its output is captured so installer
+ *  chatter cannot overwrite the bar line — the capture is printed in full if
+ *  the install fails. With no bar (no terminal) the installer keeps writing
+ *  through, exactly as it always has. */
+function runInstaller(capture) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [join(PACKAGE_ROOT, 'scripts', 'install-runtime.mjs'), PACKAGE_ROOT], { cwd: PACKAGE_ROOT, stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit' });
+    let output = '';
+    child.stdout?.setEncoding('utf8');
+    child.stderr?.setEncoding('utf8');
+    child.stdout?.on('data', (chunk) => { output += chunk; });
+    child.stderr?.on('data', (chunk) => { output += chunk; });
+    child.on('error', (error) => resolve({ ok: false, output: `${output}${errorMessage(error)}\n` }));
+    child.on('close', (status) => resolve({ ok: status === 0, output }));
+  });
+}
+
+function firstLine(text) {
+  return text.split(/\r?\n/).find((line) => line.trim() !== '')?.trim();
+}
+
+/**
+ * The other half of what postinstall did: provision the pinned termrender
+ * venv, from the generation that was just selected so the code that renders
+ * is the code that provisioned. Best-effort, exactly as postinstall was — a
+ * renderer that will not provision (no `uv`, no network) is reported and the
+ * command still runs; every render path re-attempts on first use.
+ */
+async function provisionFirstRenderer(command, entryPath) {
+  try {
+    const mod = await import(pathToFileURL(join(dirname(entryPath), 'core', 'termrender', 'termrender.js')).href);
+    if (mod.isRendererReady()) return;
+    const end = beginStep(command, 'first run — provisioning the markdown renderer (one-time)');
+    if (end === null) {
+      // No bar to protect: the provisioner's own diagnostics stream as they
+      // always have, before the outcome line.
+      mod.ensureRenderer();
+      if (!mod.isRendererReady()) process.stderr.write(`${command}: renderer not provisioned; it will be retried on first render.\n`);
+      return;
+    }
+    // Behind a bar the diagnostics are captured so they cannot overwrite the
+    // bar line; the first of them is the cause the ✗ line names.
+    let diagnostics = '';
+    mod.ensureRenderer((message) => { diagnostics += message; });
+    const ready = mod.isRendererReady();
+    await end(ready ? '✓ markdown renderer' : `✗ markdown renderer — ${firstLine(diagnostics) ?? 'not provisioned; it will be retried on first render'}`);
+    if (diagnostics !== '') process.stderr.write(diagnostics.endsWith('\n') ? diagnostics : `${diagnostics}\n`);
+  } catch (error) {
+    process.stderr.write(`${command}: renderer provisioning skipped: ${errorMessage(error)}\n`);
+  }
+}
+
+function fail(command, detail) {
+  process.stderr.write(`${command}: invalid runtime selection: ${detail}\n${remediation()}\n`);
+  process.exitCode = 1;
+  return null;
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function failure(error, code) {
+  return code === undefined ? { ok: false, error } : { ok: false, error, code };
+}
+
+function readSelection() {
+  const selected = join(ROOT, 'selected');
+  let target;
+  try {
+    target = readlinkSync(selected);
+  } catch {
+    return failure(`missing ${selected}`, 'missing-selection');
+  }
+  const id = parseSelectionTarget(target);
+  if (!id) return failure(`selected must target generations/<id>, got ${JSON.stringify(target)}`);
+
+  const generations = join(ROOT, 'generations');
+  const generation = resolve(ROOT, target);
+  if (!contained(generations, generation) || !existsSync(generation)) return failure(`selected target ${target} does not exist`);
+  try {
+    const slot = lstatSync(generation);
+    const physical = realpathSync(generation);
+    if (!slot.isDirectory() || slot.isSymbolicLink() || !contained(realpathSync(generations), physical)) {
+      return failure(`selected target ${target} is not a generation directory`);
+    }
+    return { ok: true, selection: { generation: physical, id } };
+  } catch (error) {
+    return failure(errorMessage(error));
+  }
+}
+
+/** Load + validate one generation directory's manifest/entry. Shared by the
+ *  primary `selected` resolution and the sibling fallback scan (Fix B) so
+ *  both apply the exact same compatibility + shape rules. */
+function loadRuntime(generationDir, id, entryName) {
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(join(generationDir, 'generation.json'), 'utf8'));
+  } catch (error) {
+    return failure(`cannot read generation manifest: ${errorMessage(error)}`);
+  }
+  const result = validateManifestShape(manifest, { id, entryName });
+  if (!result.ok) return failure(result.error, result.code);
+
+  try {
+    const entryPath = resolve(generationDir, result.entry);
+    if (!contained(generationDir, entryPath) || !lstatSync(entryPath).isFile()) {
+      return failure(`generation entry ${result.entry} is missing`);
+    }
+    return { ok: true, runtime: { manifest, entryPath, generationId: id } };
+  } catch (error) {
+    return failure(errorMessage(error));
+  }
+}
+
+/** All installed generation ids under `generations/`, best-effort (an
+ *  unreadable directory yields an empty list rather than throwing). */
+function listGenerationIds() {
+  const generationsRoot = join(ROOT, 'generations');
+  try {
+    return readdirSync(generationsRoot, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && GENERATION_ID.test(entry.name))
+      .map((entry) => entry.name);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Fix B fallback: when `selected` is incompatible with the running Node, scan
+ * every installed generation for the newest one whose `nodeVersion` is
+ * ABI-compatible (see `nodeVersionsCompatible`) and otherwise valid. Never
+ * touches the `selected` symlink on disk — `selected` stays the *preferred*
+ * generation; this only changes which generation THIS process loads.
+ */
+function findCompatibleSibling(entryName, excludeId) {
+  const generationsRoot = join(ROOT, 'generations');
+  let best = null;
+  for (const id of listGenerationIds()) {
+    if (id === excludeId) continue;
+    const dir = join(generationsRoot, id);
+    let manifestVersion;
+    try {
+      manifestVersion = JSON.parse(readFileSync(join(dir, 'generation.json'), 'utf8')).nodeVersion;
+    } catch {
+      continue;
+    }
+    if (!nodeVersionsCompatible(manifestVersion, process.version)) continue;
+    const runtime = loadRuntime(dir, id, entryName);
+    if (!runtime.ok) continue;
+    // Fix B must only ever fall back to a genuinely completed, published
+    // generation — never one mid-install, corrupt, or same-size-corrupted
+    // in the window between sealing and the installer's full-hash check
+    // finishing (renamed into `generations/` but not yet sealed/validated;
+    // see install-runtime.mjs's `seal()` + `validatePublished()` +
+    // `markPublished()`). A candidate with the atomic published marker
+    // passes on that alone; a markerless candidate (e.g. a legacy sibling
+    // installed before this PR added the marker) is instead full-hash
+    // validated on the spot — never rejected outright just for predating the
+    // marker, since that would defeat Fix B's whole purpose on exactly the
+    // upgrade it exists for. See `isValidPublishedGeneration`'s doc comment.
+    if (!isValidPublishedGeneration(dir, runtime.runtime.manifest.files, generationsRoot, id)) continue;
+    if (best === null || Date.parse(runtime.runtime.manifest.createdAt) > Date.parse(best.runtime.manifest.createdAt)) best = runtime;
+  }
+  return best;
+}
+
+/** Resolve a runtime without changing process state or writing output. Falls
+ *  back to the newest ABI-compatible sibling generation when `selected` is
+ *  incompatible with the running Node; only fails outright when no compatible
+ *  generation exists at all. */
+export function tryResolveRuntime(entryName) {
+  const selected = readSelection();
+  if (!selected.ok) return selected;
+
+  const primary = loadRuntime(selected.selection.generation, selected.selection.id, entryName);
+  if (primary.ok || primary.code !== 'node-version-mismatch') return primary;
+
+  const sibling = findCompatibleSibling(entryName, selected.selection.id);
+  if (sibling === null) return primary;
+  return {
+    ok: true,
+    runtime: {
+      ...sibling.runtime,
+      notice: `selected runtime generation ${selected.selection.id} is incompatible with node ${process.version}; using compatible generation ${sibling.runtime.generationId} instead`,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Fix C — escape hatch: `sys feedback` / `sys doctor` must stay runnable even
+// when NO compatible runtime generation exists at all, so the mandated
+// bug-report path is never gated behind the very failure it reports. This is
+// a tiny, generation-independent bootstrap — not the full commands — built
+// entirely from Node built-ins so it never needs to load a `dist/` generation.
+// ---------------------------------------------------------------------------
+
+const ESCAPE_HATCHES = new Map([
+  ['sys feedback', 'feedback'],
+  ['sys doctor', 'doctor'],
+]);
+
+/** Which escape hatch (if any) this argv shape matches. Pure + exported for
+ *  focused testing. */
+export function escapeHatchKind(argv) {
+  return ESCAPE_HATCHES.get(argv.slice(0, 2).join(' ')) ?? null;
+}
+
+/** Whether `args` requests help (`-h`/`--help`, in any position) — checked
+ *  BEFORE any hatch-specific arg parsing or dispatch, so a help flag can
+ *  never be misread as a positional message and can never reach an external
+ *  write (`gh issue create`, a local save, or the reduced doctor report). */
+function wantsHelp(args) {
+  return args.some((arg) => arg === '-h' || arg === '--help');
+}
+
+const FEEDBACK_HELP = `Usage: crtr sys feedback [--title <title>] <message>
+
+File a bug report describing what broke — available even when no compatible
+runtime generation is installed for this Node (the runtime-generation escape
+hatch), so the mandated bug-report path is never gated behind the very
+failure it reports.
+
+  --title <title>   Optional report title (derived from <message> otherwise)
+  -h, --help        Show this help and exit
+
+Filed to https://github.com/${FEEDBACK_REPO}/issues via \`gh\` when available,
+or saved locally under ~/.crouter/feedback/ otherwise.
+`;
+
+const DOCTOR_HELP = `Usage: crtr sys doctor
+
+Report the current runtime-generation state — available even when no
+compatible runtime generation is installed for this Node (the
+runtime-generation escape hatch). This is a reduced, generation-independent
+diagnostic, not the full \`sys doctor\` command.
+
+  -h, --help        Show this help and exit
+`;
+
+/** Parse `sys feedback [--title X] <message>`-shaped args without a full flag
+ *  parser — good enough for a degraded-mode bootstrap. Every `-`-prefixed
+ *  token that isn't the recognized `--title` flag (`-h`/`--help` are
+ *  intercepted earlier by `wantsHelp`) is an error, so an unknown short or
+ *  long option (e.g. `-x`) can never be silently read as the message body —
+ *  it must be rejected before any side effect (`gh` spawn or local save). */
+function parseFeedbackArgs(args) {
+  let message;
+  let title;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--title') {
+      title = args[i + 1];
+      i += 1;
+    } else if (arg.startsWith('-')) {
+      return { error: `unrecognized option ${JSON.stringify(arg)}` };
+    } else if (message === undefined) {
+      message = arg;
+    }
+  }
+  return { message, title };
+}
+
+/** Build the report title + body for the feedback escape hatch. Pure +
+ *  exported for focused testing. */
+export function buildFeedbackReport({ message, title, reason, nodeVersion = process.version, platform = `${process.platform} ${process.arch}` }) {
+  const trimmed = message.trim();
+  const explicitTitle = title !== undefined && title.trim() !== '' ? title.trim() : undefined;
+  const base = explicitTitle ?? trimmed.split('\n')[0].trim();
+  const finalTitle = `[feedback] ${base.length > 80 ? base.slice(0, 79) + '…' : base}`;
+  const body = [
+    trimmed,
+    '',
+    '---',
+    '_Filed via `crtr sys feedback` in the runtime-generation escape hatch — no compatible runtime generation was available, so this is a reduced report generated by the bootstrap selector, not the full CLI._',
+    '',
+    '### Environment',
+    '| | |',
+    '|---|---|',
+    `| node version | \`${nodeVersion}\` |`,
+    `| platform | ${platform} |`,
+    ...(reason !== undefined ? [`| escape-hatch reason | ${reason} |`] : []),
+    '',
+  ].join('\n');
+  return { title: finalTitle, body };
+}
+
+function defaultFeedbackDir() {
+  return join(homedir(), '.crouter', 'feedback');
+}
+
+function defaultSpawnGh(title, body) {
+  return spawnSync('gh', ['issue', 'create', '--repo', FEEDBACK_REPO, '--title', title, '--body-file', '-'], { input: body, encoding: 'utf8' });
+}
+
+/** Persist a report locally when gh can't file it, so nothing is lost.
+ *  Returns the absolute path written. */
+function saveFeedbackLocally(feedbackDir, title, body) {
+  mkdirSync(feedbackDir, { recursive: true });
+  const path = join(feedbackDir, `${new Date().toISOString().replace(/[:.]/g, '-')}.md`);
+  writeFileSync(path, `# ${title}\n\n${body}`, 'utf8');
+  return path;
+}
+
+/** The `sys feedback` escape hatch: file via `gh` when possible, else save
+ *  locally — never lost, and never dependent on a loadable runtime
+ *  generation. `reason` is the original resolution failure, embedded in the
+ *  report body so it documents the very bug it is reporting. */
+export function runEscapeHatchFeedback(args, reason, { feedbackDir = defaultFeedbackDir(), spawnGh = defaultSpawnGh, out = process.stdout, err = process.stderr } = {}) {
+  if (wantsHelp(args)) {
+    out.write(FEEDBACK_HELP);
+    return;
+  }
+  const parsed = parseFeedbackArgs(args);
+  if (parsed.error !== undefined) {
+    err.write(`sys feedback: ${parsed.error}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  const { message, title } = parsed;
+  if (message === undefined || message.trim() === '') {
+    err.write('sys feedback: feedback message is required: describe what broke.\n');
+    process.exitCode = 1;
+    return;
+  }
+  const report = buildFeedbackReport({ message, title, reason });
+  const res = spawnGh(report.title, report.body);
+  if (res.error === undefined && res.status === 0) {
+    const url = res.stdout.trim().split('\n').filter((line) => line.startsWith('http')).pop() ?? res.stdout.trim();
+    out.write(`filed: ${url}\n`);
+    return;
+  }
+  const path = saveFeedbackLocally(feedbackDir, report.title, report.body);
+  out.write(`saved-locally: ${path}\n`);
+}
+
+/** Summaries of every installed generation — exactly what's needed to
+ *  diagnose "no compatible runtime generation", which is the one scenario
+ *  where this escape hatch fires. Pure data gathering, exported for focused
+ *  testing. */
+export function listGenerationSummaries() {
+  const generationsRoot = join(ROOT, 'generations');
+  return listGenerationIds()
+    .map((id) => {
+      try {
+        const manifest = JSON.parse(readFileSync(join(generationsRoot, id, 'generation.json'), 'utf8'));
+        return `${id} node=${manifest.nodeVersion ?? '?'} pkg=${manifest.packageVersion ?? '?'} createdAt=${manifest.createdAt ?? '?'}`;
+      } catch {
+        return `${id} (unreadable manifest)`;
+      }
+    })
+    .sort();
+}
+
+/** `sys doctor` (the escape-hatch form) takes no arguments beyond `-h`/
+ *  `--help`, which `wantsHelp` intercepts earlier — so by the time this
+ *  runs, ANY remaining argument is unrecognized and must be rejected before
+ *  the doctor report runs, not silently ignored. */
+function parseDoctorArgs(args) {
+  return args.length === 0 ? { ok: true } : { ok: false, error: `unrecognized argument ${JSON.stringify(args[0])}` };
+}
+
+/** The `sys doctor` escape hatch: a reduced, generation-independent report of
+ *  exactly the state this defect leaves behind (no compatible generation) —
+ *  the full doctor command needs a loadable generation to run its checks. */
+export function runEscapeHatchDoctor(reason, { out = process.stdout, err = process.stderr } = {}, args = []) {
+  if (wantsHelp(args)) {
+    out.write(DOCTOR_HELP);
+    return;
+  }
+  const parsed = parseDoctorArgs(args);
+  if (!parsed.ok) {
+    err.write(`sys doctor: ${parsed.error}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  out.write(
+    [
+      `no runtime generation is compatible with the running node (${process.version}).`,
+      reason !== undefined ? `reason: ${reason}` : undefined,
+      `installed generations under ${join(ROOT, 'generations')}:`,
+      ...listGenerationSummaries().map((line) => `  - ${line}`),
+      '',
+      `remediation: ${remediation()}`,
+      '',
+    ]
+      .filter((line) => line !== undefined)
+      .join('\n'),
+  );
+}
+
+export function selectRuntime(command, entryName) {
+  const result = tryResolveRuntime(entryName);
+  return result.ok ? result.runtime : fail(command, result.error);
+}
+
+export async function runSelected(command, entryName) {
+  let result = tryResolveRuntime(entryName);
+  if (!result.ok && result.code === 'missing-selection' && await installFirstGeneration(command)) {
+    result = tryResolveRuntime(entryName);
+    if (result.ok) await provisionFirstRenderer(command, result.runtime.entryPath);
+  }
+  if (result.ok) {
+    holdGenerationEntryLease(result.runtime.entryPath);
+    if (result.runtime.notice !== undefined) process.stderr.write(`${command}: ${result.runtime.notice}\n`);
+    await import(pathToFileURL(result.runtime.entryPath).href);
+    return;
+  }
+
+  const argv = process.argv.slice(2);
+  const kind = entryName === 'cli' ? escapeHatchKind(argv) : null;
+  const hatchArgs = argv.slice(2);
+  if (kind === 'feedback') return runEscapeHatchFeedback(hatchArgs, result.error);
+  if (kind === 'doctor') return runEscapeHatchDoctor(result.error, undefined, hatchArgs);
+
+  fail(command, result.error);
+}