@bongos/core 1.19.1081 → 1.20.1

package/modules/lifecycle/task-visuals.js

@@ -82,11 +82,113 @@ const MAX_ALT_LENGTH = 300;        // the caption/alt text stored beside it.
 // ever opens a name that matches it.
 const NAME_RE = /^task-(\d{1,12})-[0-9a-f]{16}\.(png|jpg|gif|webp)$/;
 
-// Where visuals live. Outside the git tree (a `var/` dir) so a deploy's
-// `git reset --hard` / pull never wipes them; gitignored. Env override for tests.
+// Where visuals live: <INSTANCE ROOT>/var/task-visuals (task 1004381).
+//
+// THE BUG THIS FIXES. This used to be path.join(__dirname, '..', '..', 'var',
+// 'task-visuals') — the CORE root. Correct in a single checkout, where core root
+// and instance root are one directory. Wrong the day a site runs the consumer
+// layout: __dirname is then node_modules/@bongos/core/modules/lifecycle, so every
+// visual was written INSIDE the installed package, and every core upgrade (npm ci
+// replaces the package) silently erased them all. Seen live on cloudbongos.com:
+// eight page-tweak renders attached on 1.19.1076 were 404 five upgrades later.
+// The same failure the doorway's resolveInstanceRoot note records for
+// modules/government; the discord bug-attachments store (the sibling this lib
+// follows) was already moved for it.
+//
+// TASK_VISUALS_DIR stays the override (tests, or an operator who wants the
+// images on another disk). The directory is created on first write, by the
+// server process's own user, with a `*` .gitignore inside it: the instance root
+// is a git checkout whose tree `bongos upgrade` requires to be CLEAN, and an
+// instance's scaffolded .gitignore does not list var/. See ensureVisualsDir.
+let instanceRootCache;
+function instanceRoot() {
+  if (instanceRootCache === undefined) {
+    try {
+      // Through the published doorway (ADR 0083), lazily: the CLI requires this
+      // lib for readImageFile and must not pay for the doorway.
+      instanceRootCache = require('../../src/module-api').resolveInstanceRoot();
+    } catch (e) {
+      // A storage-path lookup must never take the server down: fall back to the
+      // historical location, which is right in a single checkout.
+      instanceRootCache = path.join(__dirname, '..', '..');
+    }
+  }
+  return instanceRootCache;
+}
+
+// The old, in-package location. Read only by migrateLegacyVisuals, so a site
+// that wrote visuals there before this fix keeps them.
+function legacyVisualsDir() {
+  return path.join(__dirname, '..', '..', 'var', 'task-visuals');
+}
+
+// PURE given its inputs — the store directory for an instance root. Split out so
+// the consumer-layout test can prove where it lands without faking a process.
+function visualsDirFor({ env = process.env, root } = {}) {
+  if (env.TASK_VISUALS_DIR) return env.TASK_VISUALS_DIR;
+  return path.join(root || instanceRoot(), 'var', 'task-visuals');
+}
+
 function visualsDir() {
-  return process.env.TASK_VISUALS_DIR
-    || path.join(__dirname, '..', '..', 'var', 'task-visuals');
+  return visualsDirFor();
+}
+
+// mkdir -p the store and, for the DEFAULT store under the instance root, drop a
+// `*` .gitignore in it, so the files never show as untracked in the instance's
+// git tree (an untracked path there halts the next `bongos upgrade` pre-flight).
+// A TASK_VISUALS_DIR override is the operator's own directory and is left bare.
+// Idempotent; the .gitignore write is best-effort.
+const DIR_GITIGNORE = '# Task visuals (task 1004381): runtime data, never committed.\n*\n';
+async function ensureVisualsDir(dir, { env = process.env } = {}) {
+  await fs.mkdir(dir, { recursive: true });
+  if (env.TASK_VISUALS_DIR) return;
+  try {
+    await fs.writeFile(path.join(dir, '.gitignore'), DIR_GITIGNORE, { flag: 'wx' });
+  } catch (err) { /* EEXIST is the steady state; anything else is non-fatal */ }
+}
+
+// One-time boot move: any stored visual still at the old in-package path is
+// moved into the new store, so a site that attached renders before upgrading to
+// this fix does not lose them on the upgrade after. A no-op when the two paths
+// are the same directory (a single checkout) or the old one is absent. Never
+// overwrites a file already in the new store, never throws: it returns
+// { moved, skipped, failed } for the caller to log.
+//
+// With TASK_VISUALS_DIR set (and no explicit `from`) there is nothing to move:
+// the old code honoured the same override, so no visual was ever written to the
+// legacy path. That also keeps a test that points the store at a temp dir from
+// sweeping a real checkout's var/task-visuals into it.
+async function migrateLegacyVisuals({ from, to = visualsDir(), env = process.env } = {}) {
+  const out = { moved: 0, skipped: 0, failed: 0 };
+  if (from === undefined) {
+    if (env.TASK_VISUALS_DIR) return out;
+    from = legacyVisualsDir();
+  }
+  if (path.resolve(from) === path.resolve(to)) return out;
+  let names;
+  try { names = await fs.readdir(from); } catch (err) { return out; }
+  names = names.filter(isSafeName);
+  if (!names.length) return out;
+  await ensureVisualsDir(to);
+  for (const name of names) {
+    const src = path.join(from, name);
+    const dest = path.join(to, name);
+    try {
+      try { await fs.access(dest); out.skipped += 1; continue; } catch (e) { /* absent: move it */ }
+      try {
+        await fs.rename(src, dest);
+      } catch (err) {
+        if (!err || err.code !== 'EXDEV') throw err;
+        // Another filesystem: copy, then remove the original.
+        await fs.copyFile(src, dest, fsSync.constants.COPYFILE_EXCL);
+        await fs.unlink(src);
+      }
+      out.moved += 1;
+    } catch (err) {
+      out.failed += 1;
+    }
+  }
+  return out;
 }
 
 // PURE — is this a well-formed, server-generated visual name?
@@ -242,7 +344,7 @@ async function persistImageBuffer(buf, { taskId, contentType, dir = visualsDir()
   const screened = screenImage(buf, contentType);
   if (!screened.ok) return screened;
   const file = `task-${id}-${crypto.randomBytes(8).toString('hex')}.${screened.ext}`;
-  await fs.mkdir(dir, { recursive: true });
+  await ensureVisualsDir(dir);
   await fs.writeFile(path.join(dir, file), buf, { mode: 0o640 });
   return { ok: true, file, url: urlForName(file), bytes: buf.length };
 }
@@ -278,6 +380,8 @@ module.exports = {
   MAX_BYTES,
   MAX_ALT_LENGTH,
   visualsDir,
+  visualsDirFor,
+  migrateLegacyVisuals,
   isSafeName,
   taskIdFromName,
   resolveSafe,

package/modules/npm-release/module.json

@@ -15,7 +15,8 @@
   "contributes": {
     "routes": [
       "work",
-      "task-where"
+      "task-where",
+      "preview"
     ],
     "uiSections": [
       "task-where"

package/modules/npm-release/preview/commands.js

@@ -0,0 +1,81 @@
+'use strict';
+
+// modules/npm-release/preview/commands.js — the shell commands a preview start runs, as data
+// (task 1004300). Each is `{ cmd, args, env?, cwd? }` for spawn WITHOUT a shell, so a version
+// string can never be parsed as anything but an argument. The supervisor runs them in order.
+//
+// THE COPY IS A DUMP AND A RESTORE, never a template copy. A template copy needs the source
+// database to have no other connections, and the live hall holds a pool open on it for as
+// long as it runs — the copy would fail, or worse, force the live pool off. pg_dump reads
+// under a snapshot and takes no lock the live hall notices.
+
+const path = require('node:path');
+const { PREVIEW_DB } = require('./env');
+
+const PACKAGE = '@bongos/core';
+// The strict shape of a published version. Anything else never reaches a command line.
+const VERSION_RE = /^\d+\.\d+\.\d+$/;
+
+function assertVersion(version) {
+  if (!VERSION_RE.test(String(version))) throw new TypeError(`not a version: ${JSON.stringify(version)}`);
+}
+
+/** Where a version's install lives: one directory per version, under the cache root. */
+function versionDir(cacheRoot, version) {
+  assertVersion(version);
+  return path.join(cacheRoot, version);
+}
+
+/** The installed core's server entry — what the preview process runs. */
+function entryPath(cacheRoot, version) {
+  return path.join(versionDir(cacheRoot, version), 'node_modules', '@bongos', 'core', 'src', 'platform-server.js');
+}
+
+/** Install one published core version into its own directory. Production dependencies only. */
+function installCommand({ cacheRoot, version }) {
+  return { cmd: 'npm', args: ['install', '--prefix', versionDir(cacheRoot, version), `${PACKAGE}@${version}`, '--omit=dev'] };
+}
+
+/** Drop the copy if one is left over — used before a start and on every stop. */
+function dropDbCommand() {
+  return { cmd: 'dropdb', args: ['--if-exists', PREVIEW_DB] };
+}
+
+/** An empty database for the copy. Deliberately no template (see the header). */
+function createDbCommand() {
+  return { cmd: 'createdb', args: [PREVIEW_DB] };
+}
+
+/** Snapshot the live database to a custom-format dump file. */
+function dumpCommand({ liveDb, dumpFile }) {
+  if (!liveDb) throw new TypeError('dumpCommand: the live database name is required');
+  if (liveDb === PREVIEW_DB) throw new Error('refusing to preview from the preview database itself');
+  return { cmd: 'pg_dump', args: ['-Fc', '-f', dumpFile, liveDb] };
+}
+
+/** Load the dump into the copy. --no-owner so it needs no role the copy does not have. */
+function restoreCommand({ dumpFile }) {
+  return { cmd: 'pg_restore', args: ['--no-owner', '-d', PREVIEW_DB, dumpFile] };
+}
+
+/**
+ * Run the INSTALLED version's migrations against the copy — the point of a preview: a
+ * version's migration meets real data here, before it meets the live hall. INIT_CWD names
+ * the install directory as the instance root (migrate.sh resolves it from there);
+ * DATABASE_URL is blanked because the pool prefers it to PGDATABASE, and PGDATABASE is
+ * pinned to the copy so nothing can be applied to the live database by mistake.
+ */
+function migrateCommand({ cacheRoot, version, env }) {
+  const dir = versionDir(cacheRoot, version);
+  return {
+    cmd: 'bash',
+    args: [path.join(dir, 'node_modules', '@bongos', 'core', 'scripts', 'migrate.sh')],
+    cwd: dir,
+    env: { ...env, INIT_CWD: dir, PGDATABASE: PREVIEW_DB, DATABASE_URL: '' },
+  };
+}
+
+module.exports = {
+  VERSION_RE, PACKAGE, versionDir, entryPath,
+  installCommand, dropDbCommand, createDbCommand, dumpCommand, restoreCommand, migrateCommand,
+};

package/modules/npm-release/preview/divert.js

@@ -0,0 +1,95 @@
+'use strict';
+
+// modules/npm-release/preview/divert.js — the provider for the kernel's optional
+// request.divert seam: it decides, per request, whether a request belongs to the live hall
+// or to the running version preview (task 1004300, ADR 0349).
+//
+// A browser is steered by a cookie, bongos_preview=<version>, set when its owner opens the
+// preview. Same origin, so sign-in and cookies just work and no second OAuth app is needed.
+// A request is forwarded only when EVERY one of these holds; otherwise it falls through to
+// the live hall untouched:
+//   - the cookie names a version, and that is the version now running
+//   - the path is not sign-in (/api/bongos/auth/*) and not this module's own preview routes,
+//     so signing in, and getting OUT of a preview, always reach the live hall
+//   - the request is not a CLI/API call (an Authorization header): those are never previews
+//   - the caller is signed in AND holds core.pin.move — checked on EVERY request, uncached,
+//     with the same gates a route would use, so a revoked permission ends the preview for
+//     that person on their next click
+// A failed permission check also clears the cookie, so nobody is left stranded in a loop.
+
+const { VERSION_RE } = require('./commands');
+const { COOKIE_NAME } = require('./proxy');
+
+// The API is served under every prefix the kernel mounts it at: /api/bongos, the /api/bongos/v1
+// versioned form, and the legacy /api/gds. An exclusion that named only one would let the same
+// sign-in or exit request through by another spelling, so each pattern allows the optional
+// version segment (src/bongos/api-prefix.js owns the list; a module cannot import it).
+const AUTH_PATH = /^\/api\/(?:bongos|gds)(?:\/v\d+)?\/auth(?:\/|$)/;
+const PREVIEW_PATH = /^\/api\/(?:bongos|gds)(?:\/v\d+)?\/npm-release\/preview(?:\/|$)/;
+
+function cookieVersion(header) {
+  for (const part of String(header || '').split(';')) {
+    const s = part.trim();
+    if (s.startsWith(`${COOKIE_NAME}=`)) {
+      const v = s.slice(COOKIE_NAME.length + 1);
+      return VERSION_RE.test(v) ? v : null;
+    }
+  }
+  return null;
+}
+
+function pathOf(req) {
+  const url = String(req.originalUrl || req.url || '');
+  const q = url.indexOf('?');
+  return q === -1 ? url : url.slice(0, q);
+}
+
+/** The Set-Cookie value that removes the steering cookie. */
+function clearCookie() {
+  return `${COOKIE_NAME}=; Path=/; Max-Age=0; HttpOnly; SameSite=Lax`;
+}
+
+// Run an express-style gate to its verdict without letting it write a response of its own:
+// the gates answer a refusal through res.fail, which does not exist this early in the
+// request, and a refusal here means "not yours to preview", not an error page.
+function passes(gate, req) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (ok) => { if (!settled) { settled = true; resolve(ok); } };
+    const res = { fail: () => done(false) };
+    Promise.resolve(gate(req, res, (err) => done(!err))).catch(() => done(false));
+  });
+}
+
+/**
+ * @param {object} o
+ * @param {object} o.supervisor
+ * @param {Function} o.forward   (req, res) => void — the proxy
+ * @param {Function} o.requireBuilder     the kernel sign-in gate
+ * @param {Function} o.requirePermission  the kernel permission gate factory
+ * @returns {(req, res, next) => Promise<void>}
+ */
+function createDivert({ supervisor, forward, requireBuilder, requirePermission }) {
+  const mayPreview = requirePermission('core.pin.move');
+  return async function divert(req, res, next) {
+    const wanted = cookieVersion(req.headers.cookie);
+    if (!wanted) return next();
+    const st = supervisor.status();
+    if (st.state !== 'running' || st.version !== wanted) {
+      // The preview this cookie pointed at is gone: drop the cookie and serve the live hall.
+      res.append('Set-Cookie', clearCookie());
+      return next();
+    }
+    const p = pathOf(req);
+    if (AUTH_PATH.test(p) || PREVIEW_PATH.test(p)) return next();
+    if (req.headers.authorization) return next();
+    if (!(await passes(requireBuilder, req)) || !(await passes(mayPreview, req))) {
+      res.append('Set-Cookie', clearCookie());
+      return next();
+    }
+    supervisor.touch();
+    return forward(req, res);
+  };
+}
+
+module.exports = { createDivert, cookieVersion, clearCookie, AUTH_PATH, PREVIEW_PATH };

package/modules/npm-release/preview/env.js

@@ -0,0 +1,78 @@
+'use strict';
+
+// modules/npm-release/preview/env.js — the environment a version preview runs in (task 1004300).
+//
+// A preview is another Bongos process on the same droplet, running an OLDER (or newer)
+// core against a COPY of the live database. Anything that process can reach, it can act
+// on: a Discord webhook, a GitHub token, an AI key, the cron pollers that post, pay and
+// email. So its environment is built FROM NOTHING — an allow-list of the few names a
+// process needs to boot and reach Postgres — and never as a copy of ours with a few
+// names deleted. A deny-list forgets the next secret someone adds; an allow-list cannot.
+//
+// The pollers and the modules that talk outward are then switched off by name, and HOME
+// is pointed at an empty scratch directory so a config file in the real home (the
+// Discord webhook file among them) is not found.
+
+// The only names carried over from the live process.
+//   PATH            so node, and the child's own tooling, resolve
+//   NODE_ENV        production behaviour, as the live hall runs it
+//   PGHOST/PGPORT   which Postgres server (the copy lives on the same one)
+//   PGUSER/PGPASSWORD  the role that connects — needed to open a pool at all
+// PORT and HOST are NOT carried: the preview binds its own, set below.
+const CARRIED = Object.freeze(['PATH', 'NODE_ENV', 'PGHOST', 'PGPORT', 'PGUSER', 'PGPASSWORD']);
+
+// The name of the copy database. Fixed, so a leftover from a crash is dropped by the next
+// start instead of piling up.
+const PREVIEW_DB = 'bongos_preview';
+
+// Every background poller the platform has, off. Each is read by name in modules/ or
+// src/platform-server.js; a poller that is not listed here would keep running in the copy.
+const POLLERS_OFF = Object.freeze([
+  'PUBLISH_RECONCILER_DISABLED',
+  'ROUTINE_TIMERS_DISABLED',
+  'BOARD_EXPIRY_DISABLED',
+  'SEARCH_INDEX_SWEEP_DISABLED',
+  'SESSION_UPLOAD_HEALTH_DISABLED',
+  'SESSION_REWARD_RECONCILE_DISABLED',
+  'PROVISIONING_LIVENESS_DISABLED',
+  'PROVISIONING_CATALOG_BACKFILL_DISABLED',
+  'CONFLICT_RESOLVE_DISABLED',
+]);
+
+// Modules that talk to the outside world, off. npm-release is off too: a preview must not
+// offer previews of its own.
+const MODULES_OFF = Object.freeze([
+  'BONGOS_MODULE_DISCORD',
+  'BONGOS_MODULE_AGENTS',
+  'BONGOS_MODULE_PROVISIONING',
+  'BONGOS_MODULE_NPM_RELEASE',
+]);
+
+/**
+ * Build the child's environment.
+ *
+ * @param {object} o
+ * @param {object} [o.env]   the live process's environment (only CARRIED names are read)
+ * @param {number|string} o.port   the loopback port the preview listens on
+ * @param {string} o.scratchHome   an empty directory to serve as HOME
+ * @returns {Record<string,string>} a fresh object, never `env` itself
+ */
+function buildPreviewEnv({ env = process.env, port, scratchHome } = {}) {
+  if (!port) throw new TypeError('buildPreviewEnv: port is required');
+  if (!scratchHome) throw new TypeError('buildPreviewEnv: scratchHome is required');
+  const out = {};
+  for (const name of CARRIED) {
+    if (env[name] !== undefined && env[name] !== '') out[name] = String(env[name]);
+  }
+  if (!out.NODE_ENV) out.NODE_ENV = 'production';
+  out.PORT = String(port);
+  out.HOST = '127.0.0.1';
+  out.HOME = scratchHome;
+  out.PGDATABASE = PREVIEW_DB;
+  out.CHAT_DRY_RUN = '1';
+  for (const name of POLLERS_OFF) out[name] = '1';
+  for (const name of MODULES_OFF) out[name] = '0';
+  return out;
+}
+
+module.exports = { buildPreviewEnv, PREVIEW_DB, CARRIED, POLLERS_OFF, MODULES_OFF };

package/modules/npm-release/preview/proxy.js

@@ -0,0 +1,107 @@
+'use strict';
+
+// modules/npm-release/preview/proxy.js — forwards one request to the running preview and
+// stamps every page that comes back with the "You are viewing Bongos X" banner
+// (task 1004300, ADR 0349).
+//
+// TRANSPARENT ON PURPOSE. The Host header is kept (the hall is routed on it), the method,
+// path, query and body go through as they came, and a response that is not a page — a JSON
+// answer, a script, an event stream — is piped straight back without being read, so a
+// server-sent-events connection stays open and unbuffered. Only a text/html answer is held
+// long enough to place the banner after its opening body tag; the preview is asked for an
+// uncompressed body so there is nothing to inflate. A version whose pages are older than
+// any banner code still shows it, because the banner is added HERE, never by the preview.
+
+const http = require('node:http');
+
+// Hop-by-hop headers are meant for one connection, not for the next.
+const HOP = new Set(['connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer', 'transfer-encoding', 'upgrade']);
+
+const COOKIE_NAME = 'bongos_preview';
+
+// The cookie that steers a browser into the preview is ours and stays with us: the preview
+// has no use for it, and a preview page must not be able to read what routed it there.
+function withoutPreviewCookie(cookieHeader) {
+  return String(cookieHeader || '')
+    .split(';')
+    .map((s) => s.trim())
+    .filter((s) => s && !s.startsWith(`${COOKIE_NAME}=`))
+    .join('; ');
+}
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+}
+
+/** The banner markup: which version this is, which one the hall runs, and the way out. */
+function bannerHtml({ viewing, running, exitHref }) {
+  return '<div id="bongos-preview-banner" role="status" style="position:sticky;top:0;z-index:2147483647;'
+    + 'display:flex;gap:12px;align-items:center;justify-content:center;flex-wrap:wrap;padding:8px 16px;'
+    + 'background:#1f2933;color:#fff;font:14px/1.4 system-ui,sans-serif;">'
+    + `<span>You are viewing Bongos ${escapeHtml(viewing)} &mdash; this hall runs ${escapeHtml(running)}. Changes here do not reach the live hall.</span>`
+    + `<a href="${escapeHtml(exitHref)}" style="color:#fff;text-decoration:underline;font-weight:600;">Back to the live hall</a>`
+    + '</div>';
+}
+
+/** Place the banner after the opening body tag. A document with no body tag is left alone. */
+function injectBanner(html, banner) {
+  const m = /<body\b[^>]*>/i.exec(html);
+  if (!m) return html;
+  const at = m.index + m[0].length;
+  return html.slice(0, at) + banner + html.slice(at);
+}
+
+/**
+ * @param {object} o
+ * @param {()=>number} o.port         the preview's loopback port
+ * @param {()=>{viewing:string,running:string}} o.banner   what the banner should say now
+ * @param {string} o.exitHref
+ * @param {object} [o.httpImpl]       node:http, swapped in tests
+ * @returns {(req, res) => void}
+ */
+function createProxy({ port, banner, exitHref, httpImpl = http } = {}) {
+  return function forward(req, res) {
+    const headers = {};
+    for (const [k, v] of Object.entries(req.headers)) {
+      if (HOP.has(k) || k === 'accept-encoding') continue;
+      headers[k] = v;
+    }
+    headers['accept-encoding'] = 'identity';
+    const cookie = withoutPreviewCookie(req.headers.cookie);
+    if (cookie) headers.cookie = cookie; else delete headers.cookie;
+
+    const up = httpImpl.request(
+      { host: '127.0.0.1', port: port(), method: req.method, path: req.originalUrl || req.url, headers },
+      (upRes) => {
+        const out = {};
+        for (const [k, v] of Object.entries(upRes.headers)) if (!HOP.has(k)) out[k] = v;
+        const isPage = /^text\/html\b/i.test(String(upRes.headers['content-type'] || ''));
+        if (!isPage) {
+          res.writeHead(upRes.statusCode, out);
+          upRes.pipe(res);
+          return;
+        }
+        const chunks = [];
+        upRes.on('data', (c) => chunks.push(c));
+        upRes.on('end', () => {
+          const html = injectBanner(Buffer.concat(chunks).toString('utf8'), bannerHtml({ ...banner(), exitHref }));
+          delete out['content-length'];
+          delete out.etag;
+          out['cache-control'] = 'no-store';
+          res.writeHead(upRes.statusCode, out);
+          res.end(html);
+        });
+        upRes.on('error', () => res.destroy());
+      },
+    );
+    up.on('error', () => {
+      if (res.headersSent) { res.destroy(); return; }
+      res.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' });
+      res.end('The preview is not answering. Go back to the live hall and start it again.');
+    });
+    res.on('close', () => { if (!res.writableFinished) up.destroy(); });
+    req.pipe(up);
+  };
+}
+
+module.exports = { createProxy, injectBanner, bannerHtml, withoutPreviewCookie, COOKIE_NAME };

package/modules/npm-release/preview/runtime.js

@@ -0,0 +1,83 @@
+'use strict';
+
+// modules/npm-release/preview/runtime.js — the real-world wiring of the preview supervisor
+// (task 1004300, ADR 0349): actual child processes, an actual health probe, an idle timer.
+// Everything the supervisor takes as a function is bound here to the operating system, so
+// supervisor.js itself stays free of it and the tests never need to come near this file.
+//
+// NOT EXERCISED BY THE UNIT TESTS, by design: it spawns npm, pg_dump and node. It is small
+// enough to read whole, and the droplet run recorded in the task's part B is what proves it.
+
+const os = require('node:os');
+const path = require('node:path');
+const http = require('node:http');
+const { spawn } = require('node:child_process');
+const { createSupervisor, DEFAULT_PORT } = require('./supervisor');
+
+const REAP_EVERY_MS = 60 * 1000;
+
+// The only programs a preview may run, by the name commands.js gives them. Each entry
+// spawns a LITERAL program name, so what runs is answerable by reading this table (the
+// exec-path guard, task 1003371, requires exactly that); a command not in it is refused.
+const PROGRAMS = Object.freeze({
+  npm: (args, o) => spawn('npm', args, o),
+  dropdb: (args, o) => spawn('dropdb', args, o),
+  createdb: (args, o) => spawn('createdb', args, o),
+  pg_dump: (args, o) => spawn('pg_dump', args, o),
+  pg_restore: (args, o) => spawn('pg_restore', args, o),
+  bash: (args, o) => spawn('bash', args, o),
+});
+
+/** Run one command to the end, keeping the tail of its error output for the failure message. */
+function runCommand({ cmd, args, env, cwd }) {
+  return new Promise((resolve) => {
+    let stderr = '';
+    let child;
+    if (!Object.prototype.hasOwnProperty.call(PROGRAMS, cmd)) {
+      resolve({ code: -1, stderr: 'not a program a preview may run: ' + cmd });
+      return;
+    }
+    try {
+      child = PROGRAMS[cmd](args, { env: env || process.env, cwd, stdio: ['ignore', 'ignore', 'pipe'] });
+    } catch (e) {
+      resolve({ code: -1, stderr: e.message });
+      return;
+    }
+    child.stderr.on('data', (d) => { stderr = (stderr + d).slice(-2000); });
+    child.on('error', (e) => resolve({ code: -1, stderr: e.message }));
+    child.on('close', (code) => resolve({ code: code === null ? -1 : code, stderr }));
+  });
+}
+
+/** Does something answer /healthz on the loopback port? */
+function probeHealth(port) {
+  return new Promise((resolve) => {
+    const req = http.get({ host: '127.0.0.1', port, path: '/healthz', timeout: 2000 }, (res) => {
+      res.resume();
+      resolve(res.statusCode === 200);
+    });
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+  });
+}
+
+/**
+ * Build the production supervisor: the port from NPM_RELEASE_PREVIEW_PORT (default 3190,
+ * loopback only), installs cached under ~/.cache/bongos-preview, and a timer that stops
+ * an idle preview and a hook that stops it when this process does.
+ */
+function createRuntime({ liveDb, log, env = process.env } = {}) {
+  const port = Number(env.NPM_RELEASE_PREVIEW_PORT) || DEFAULT_PORT;
+  const supervisor = createSupervisor({
+    run: runCommand, spawn, probe: probeHealth, liveDb, log, port, env,
+    cacheRoot: path.join(os.homedir(), '.cache', 'bongos-preview'),
+  });
+  const timer = setInterval(() => {
+    supervisor.reapIdle().catch((e) => log.warn(`preview idle check failed: ${e && e.message}`));
+  }, REAP_EVERY_MS);
+  timer.unref();
+  process.once('exit', () => { supervisor.stop().catch(() => {}); });
+  return supervisor;
+}
+
+module.exports = { createRuntime, runCommand, probeHealth };