@bongos/core 1.19.1081 → 1.20.1

package/tests/npm_release_preview_proxy.mjs

@@ -0,0 +1,162 @@
+// tests/npm_release_preview_proxy.mjs — forwarding a request to the preview and putting the
+// "You are viewing Bongos X" banner on every page that comes back (task 1004300).
+//
+// WHAT IS AT RISK. The proxy sits in front of a whole hall. It must be transparent (the Host
+// header, method, path, query and body reach the preview unchanged, because the hall routes
+// on Host), it must not buffer a live event stream, and it must put the banner on every HTML
+// page, including a page from a version too old to know about banners. The upstream is
+// injected: no socket is opened.
+//
+// Run:  node --test tests/npm_release_preview_proxy.mjs
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { Readable, Writable, PassThrough } from 'node:stream';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { createProxy, injectBanner, bannerHtml, withoutPreviewCookie } = require('../modules/npm-release/preview/proxy.js');
+
+// A stand-in for node:http whose request() records what it was asked and answers from `respond`.
+function fakeHttp(respond) {
+  const seen = [];
+  return {
+    seen,
+    request(opts, cb) {
+      const chunks = [];
+      const rec = { opts, body: '' };
+      seen.push(rec);
+      return new Writable({
+        write(c, _e, n) { chunks.push(c); n(); },
+        final(n) {
+          rec.body = Buffer.concat(chunks).toString('utf8');
+          const r = respond(opts, rec.body);
+          if (r instanceof Error) { this.destroy(r); n(); return; }
+          const res = r.stream || Readable.from(r.body === undefined ? [] : [Buffer.from(r.body)]);
+          res.statusCode = r.status || 200;
+          res.headers = r.headers || {};
+          cb(res);
+          n();
+        },
+      });
+    },
+  };
+}
+
+class FakeRes extends Writable {
+  constructor() { super(); this.parts = []; this.headersSent = false; }
+  writeHead(status, headers) { this.status = status; this.headers = headers; this.headersSent = true; }
+  _write(chunk, _e, n) { this.parts.push(Buffer.from(chunk)); n(); }
+  get text() { return Buffer.concat(this.parts).toString('utf8'); }
+}
+
+function request(over = {}) {
+  const r = Readable.from(over.body ? [Buffer.from(over.body)] : []);
+  r.method = over.method || 'GET';
+  r.originalUrl = over.url || '/builders/tasks?x=1&y=2';
+  r.headers = { host: 'builders.example.test', cookie: 'sid=abc; bongos_preview=1.19.1000; theme=dark', 'accept-encoding': 'gzip', connection: 'keep-alive', ...(over.headers || {}) };
+  return r;
+}
+
+const banner = () => ({ viewing: '1.19.1000', running: '1.19.1050' });
+const make = (http) => createProxy({ port: () => 3190, banner, exitHref: '/api/bongos/npm-release/preview/exit', httpImpl: http });
+const finish = (res) => new Promise((r) => (res.writableFinished ? r() : res.on('finish', r)));
+const tick = () => new Promise((r) => setImmediate(r));
+
+test('the request goes to the loopback preview port with Host, method, path, query and body unchanged', async () => {
+  const http = fakeHttp(() => ({ headers: { 'content-type': 'application/json' }, body: '{}' }));
+  const res = new FakeRes();
+  make(http)(request({ method: 'POST', url: '/api/bongos/thing?a=1&b=2', body: '{"hello":1}' }), res);
+  await finish(res);
+  const { opts, body } = http.seen[0];
+  assert.equal(opts.host, '127.0.0.1');
+  assert.equal(opts.port, 3190);
+  assert.equal(opts.method, 'POST');
+  assert.equal(opts.path, '/api/bongos/thing?a=1&b=2');
+  assert.equal(opts.headers.host, 'builders.example.test', 'the hall is routed on Host');
+  assert.equal(body, '{"hello":1}');
+});
+
+test('the steering cookie is not passed on; every other cookie is', async () => {
+  const http = fakeHttp(() => ({ body: 'x' }));
+  const res = new FakeRes();
+  make(http)(request(), res);
+  await finish(res);
+  assert.equal(http.seen[0].opts.headers.cookie, 'sid=abc; theme=dark');
+  assert.equal(withoutPreviewCookie('bongos_preview=1.2.3'), '');
+});
+
+test('hop-by-hop headers are dropped and the preview is asked for an uncompressed body', async () => {
+  const http = fakeHttp(() => ({ body: 'x' }));
+  const res = new FakeRes();
+  make(http)(request(), res);
+  await finish(res);
+  const h = http.seen[0].opts.headers;
+  assert.equal(h.connection, undefined);
+  assert.equal(h['accept-encoding'], 'identity');
+});
+
+test('an HTML page gets the banner right after the opening body tag, and a fresh content length', async () => {
+  const page = '<!doctype html><html><head><title>t</title></head><body class="hall"><main>hi</main></body></html>';
+  const http = fakeHttp(() => ({ headers: { 'content-type': 'text/html; charset=utf-8', 'content-length': String(page.length), etag: 'W/"x"' }, body: page }));
+  const res = new FakeRes();
+  make(http)(request(), res);
+  await finish(res);
+  assert.equal(res.status, 200);
+  assert.match(res.text, /<body class="hall"><div id="bongos-preview-banner"/);
+  assert.match(res.text, /You are viewing Bongos 1\.19\.1000 &mdash; this hall runs 1\.19\.1050/);
+  assert.match(res.text, /href="\/api\/bongos\/npm-release\/preview\/exit"/);
+  assert.match(res.text, /<main>hi<\/main>/);
+  assert.equal(res.headers['content-length'], undefined, 'the old length no longer fits');
+  assert.equal(res.headers.etag, undefined);
+  assert.equal(res.headers['cache-control'], 'no-store');
+});
+
+test('a very old page with no banner code of its own still shows the banner (it is added here)', () => {
+  const out = injectBanner('<html><BODY><p>1.0 hall</p></BODY></html>', bannerHtml({ viewing: '1.0.1', running: '1.19.9', exitHref: '/x' }));
+  assert.match(out, /<BODY><div id="bongos-preview-banner"/);
+});
+
+test('a document with no body tag is left as it was', () => {
+  assert.equal(injectBanner('{"not":"html"}', 'BANNER'), '{"not":"html"}');
+});
+
+test('the banner escapes what it is given', () => {
+  const b = bannerHtml({ viewing: '<script>1</script>', running: 'a"b', exitHref: '/x' });
+  assert.doesNotMatch(b, /<script>/);
+  assert.match(b, /&lt;script&gt;/);
+});
+
+test('JSON and other non-page answers pass through untouched, headers included', async () => {
+  const http = fakeHttp(() => ({ status: 201, headers: { 'content-type': 'application/json', 'content-length': '11', etag: 'abc' }, body: '{"ok":true}' }));
+  const res = new FakeRes();
+  make(http)(request(), res);
+  await finish(res);
+  assert.equal(res.status, 201);
+  assert.equal(res.text, '{"ok":true}');
+  assert.equal(res.headers['content-length'], '11');
+  assert.doesNotMatch(res.text, /banner/);
+});
+
+test('an event stream is streamed, not held: the first chunk arrives before the stream ends', async () => {
+  const stream = new PassThrough();
+  const http = fakeHttp(() => ({ headers: { 'content-type': 'text/event-stream' }, stream }));
+  const res = new FakeRes();
+  make(http)(request(), res);
+  await tick();
+  stream.write('data: one\n\n');
+  await tick();
+  assert.equal(res.text, 'data: one\n\n', 'delivered while the upstream is still open');
+  assert.equal(res.writableFinished, false);
+  stream.end();
+  await finish(res);
+  assert.doesNotMatch(res.text, /banner/);
+});
+
+test('a preview that is not answering is a plain 502, not a crash', async () => {
+  const http = fakeHttp(() => new Error('ECONNREFUSED'));
+  const res = new FakeRes();
+  make(http)(request(), res);
+  await finish(res);
+  assert.equal(res.status, 502);
+  assert.match(res.text, /not answering/);
+});

package/tests/npm_release_preview_routes.mjs

@@ -0,0 +1,208 @@
+// tests/npm_release_preview_routes.mjs — the preview's routes and how they are gated (task 1004300).
+//
+// WHAT IS AT RISK. These routes start a process, copy the live database and set the cookie
+// that steers a browser off the live hall. Each must be behind sign-in AND core.pin.move (an
+// atom, never a rank), and a refused caller must move nothing: no supervisor call at all.
+// The kernel gates are stubbed (no database); the supervisor and the registry are stubs.
+//
+// Run:  node --test tests/npm_release_preview_routes.mjs
+import assert from 'node:assert/strict';
+import { test, before, after } from 'node:test';
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const express = require('express');
+const auth = require('../src/bongos/auth');
+const seams = require('../src/module-seams');
+
+// Replace the kernel gates BEFORE the router is built: the module reads them at build time.
+const asked = [];
+auth.requireBuilder = (req, res, next) => {
+  const sid = /sid=(\w+)/.exec(req.headers.cookie || '');
+  if (!sid) return res.status(401).json({ error: { code: 'unauthenticated' } });
+  req.builder = { id: 7, perms: sid[1] === 'good' ? ['core.pin.move'] : [] };
+  return next();
+};
+auth.requirePermission = (...atoms) => {
+  asked.push(atoms);
+  return (req, res, next) => (atoms.every((a) => req.builder.perms.includes(a)) ? next() : res.status(403).json({ error: { code: 'permission_forbidden' } }));
+};
+const buildRouter = require('../modules/npm-release/routes/preview.js');
+
+const published = {};
+for (let i = 0; i < 60; i++) published['1.19.' + (1000 + i)] = '2026-09-01T00:00:00Z';
+
+let state;
+const calls = [];
+const supervisor = {
+  status: () => ({ ...state, port: 3190, idle_ms: 1200000 }),
+  start(v) { calls.push(['start', v]); if (state.state === 'running' && state.version !== v) return { ok: false, code: 'preview_busy' }; state = { state: 'starting', version: v, stage: 'queued' }; return { ok: true }; },
+  async stop() { calls.push(['stop']); state = { state: 'idle', version: null }; },
+  touch() { calls.push(['touch']); },
+};
+let registry = published;
+
+let server;
+let base;
+before(async () => {
+  state = { state: 'idle', version: null };
+  const app = express();
+  app.use(express.json());
+  app.use('/api/bongos', buildRouter({ supervisor, listPublished: async () => registry, runningVersion: () => '1.19.1040' }));
+  server = http.createServer(app);
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  base = server.address().port;
+});
+after(() => new Promise((r) => server.close(r)));
+
+function call(method, url, { cookie = 'sid=good', body } = {}) {
+  return new Promise((resolve, reject) => {
+    const data = body === undefined ? null : JSON.stringify(body);
+    const headers = { host: 'builders.example.test' };
+    if (cookie) headers.cookie = cookie;
+    if (data) { headers['content-type'] = 'application/json'; headers['content-length'] = Buffer.byteLength(data); }
+    const r = http.request({ host: '127.0.0.1', port: base, path: '/api/bongos' + url, method, headers }, (res) => {
+      let t = '';
+      res.on('data', (c) => (t += c));
+      res.on('end', () => resolve({ status: res.statusCode, headers: res.headers, json: t && t[0] === '{' ? JSON.parse(t) : null }));
+    });
+    r.on('error', reject);
+    if (data) r.write(data);
+    r.end();
+  });
+}
+
+const ROUTES = [['GET', '/npm-release/preview'], ['POST', '/npm-release/preview', { version: '1.19.1030' }], ['DELETE', '/npm-release/preview'],
+  ['GET', '/npm-release/preview/enter?v=1.19.1030'], ['GET', '/npm-release/preview/exit']];
+
+test('every route is gated on core.pin.move, asked for as an atom and never as a rank', () => {
+  assert.ok(asked.length >= 1);
+  for (const a of asked) assert.deepEqual(a, ['core.pin.move']);
+  const src = fs.readFileSync(path.join(ROOT, 'modules/npm-release/routes/preview.js'), 'utf8');
+  assert.match(src, /api\.requirePermission\('core\.pin\.move'\)/);
+  assert.doesNotMatch(src, /requireRank/);
+});
+
+test('every route has the two gates before its handler, on the router itself', () => {
+  const router = buildRouter({ supervisor, listPublished: async () => published, registerDivert: false });
+  const layers = router.stack.filter((l) => l.route);
+  assert.equal(layers.length, 5);
+  for (const l of layers) assert.equal(l.route.stack.length, 3, l.route.path + ' has requireBuilder, the permission gate, then the handler');
+});
+
+test('a caller who is not signed in, or lacks the permission, moves nothing on any route', async () => {
+  for (const [method, url, body] of ROUTES) {
+    calls.length = 0;
+    const anon = await call(method, url, { cookie: '', body });
+    assert.equal(anon.status, 401, method + ' ' + url);
+    const weak = await call(method, url, { cookie: 'sid=weak', body });
+    assert.equal(weak.status, 403, method + ' ' + url);
+    assert.deepEqual(calls, [], 'the supervisor was never touched');
+  }
+});
+
+test('GET reports what is running and which version the hall runs', async () => {
+  state = { state: 'idle', version: null };
+  const r = await call('GET', '/npm-release/preview');
+  assert.equal(r.status, 200);
+  assert.equal(r.json.preview.state, 'idle');
+  assert.equal(r.json.running, '1.19.1040');
+});
+
+test('POST starts a preview of a published, recent version and answers 202', async () => {
+  state = { state: 'idle', version: null };
+  calls.length = 0;
+  const r = await call('POST', '/npm-release/preview', { body: { version: '1.19.1030' } });
+  assert.equal(r.status, 202);
+  assert.deepEqual(calls, [['start', '1.19.1030']]);
+  assert.equal(r.json.preview.state, 'starting');
+});
+
+test('POST refuses what may not be previewed, and starts nothing', async () => {
+  const cases = [
+    [{ version: 'not-a-version' }, 400, 'not_a_version'],
+    [{ version: '1.19.9999' }, 400, 'not_published'],
+    [{ version: '1.19.1005' }, 400, 'too_old'],
+    [{}, 400, 'validation_failed'],
+  ];
+  for (const [body, status, code] of cases) {
+    state = { state: 'idle', version: null };
+    calls.length = 0;
+    const r = await call('POST', '/npm-release/preview', { body });
+    assert.equal(r.status, status, JSON.stringify(body));
+    assert.equal((r.json.error || {}).code, code, JSON.stringify(body));
+    assert.deepEqual(calls, []);
+  }
+});
+
+test('POST does not start when the registry cannot be read', async () => {
+  state = { state: 'idle', version: null };
+  calls.length = 0;
+  registry = null;
+  try {
+    const r = await call('POST', '/npm-release/preview', { body: { version: '1.19.1030' } });
+    assert.equal(r.status, 502);
+    assert.deepEqual(calls, []);
+  } finally { registry = published; }
+});
+
+test('POST while a different version runs is a 409 and does not disturb it', async () => {
+  state = { state: 'running', version: '1.19.1031' };
+  calls.length = 0;
+  const r = await call('POST', '/npm-release/preview', { body: { version: '1.19.1030' } });
+  assert.equal(r.status, 409);
+  assert.equal(r.json.error.code, 'preview_busy');
+  assert.equal(state.version, '1.19.1031');
+});
+
+test('DELETE stops the preview', async () => {
+  state = { state: 'running', version: '1.19.1030' };
+  calls.length = 0;
+  const r = await call('DELETE', '/npm-release/preview');
+  assert.equal(r.status, 200);
+  assert.deepEqual(calls, [['stop']]);
+  assert.equal(r.json.preview.state, 'idle');
+});
+
+test('enter sets the steering cookie for the running version and goes to the hall', async () => {
+  state = { state: 'running', version: '1.19.1030' };
+  const r = await call('GET', '/npm-release/preview/enter?v=1.19.1030');
+  assert.equal(r.status, 302);
+  assert.equal(r.headers.location, '/');
+  const c = [].concat(r.headers['set-cookie'])[0];
+  assert.match(c, /^bongos_preview=1\.19\.1030; Path=\/; HttpOnly; SameSite=Lax/);
+});
+
+test('enter refuses a preview that is not the one running, and sets no cookie', async () => {
+  for (const [st, v] of [[{ state: 'idle', version: null }, '1.19.1030'], [{ state: 'starting', version: '1.19.1030' }, '1.19.1030'], [{ state: 'running', version: '1.19.1031' }, '1.19.1030'], [{ state: 'running', version: '1.19.1030' }, 'zzz']]) {
+    state = st;
+    const r = await call('GET', '/npm-release/preview/enter?v=' + v);
+    assert.equal(r.status, 409, JSON.stringify(st) + v);
+    assert.equal(r.headers['set-cookie'], undefined);
+  }
+});
+
+test('exit clears the cookie and returns to the deploy page', async () => {
+  const r = await call('GET', '/npm-release/preview/exit');
+  assert.equal(r.status, 302);
+  assert.equal(r.headers.location, '/deploy');
+  assert.match([].concat(r.headers['set-cookie'])[0], /^bongos_preview=; Path=\/; Max-Age=0/);
+});
+
+test('building the router registers the request.divert provider once, and a rebuild does not throw', () => {
+  buildRouter({ supervisor, listPublished: async () => published });
+  assert.equal(seams.hasProvider('request.divert'), true);
+  assert.equal(typeof seams.resolve('request.divert'), 'function');
+  assert.doesNotThrow(() => buildRouter({ supervisor, listPublished: async () => published }));
+});
+
+test('the module declares the preview route so the loader mounts it', () => {
+  const m = JSON.parse(fs.readFileSync(path.join(ROOT, 'modules/npm-release/module.json'), 'utf8'));
+  assert.ok(m.contributes.routes.includes('preview'));
+  assert.ok(fs.existsSync(path.join(ROOT, 'modules/npm-release/routes/preview.js')));
+});

package/tests/npm_release_preview_supervisor.mjs

@@ -0,0 +1,203 @@
+// tests/npm_release_preview_supervisor.mjs — the version preview's lifecycle (task 1004300).
+//
+// WHAT IS AT RISK. A preview is a second process and a second database on the live droplet.
+// The supervisor must (a) run the steps in the order that makes the copy safe, (b) leave
+// NOTHING behind when any step fails, (c) allow only one preview and refuse a second, and
+// (d) stop and drop the copy when idle. Every process, database, network and clock is
+// injected; nothing here spawns, dumps, installs or sleeps.
+//
+// Run:  node --test tests/npm_release_preview_supervisor.mjs
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { createSupervisor, previewable, IDLE_MS, WINDOW } = require('../modules/npm-release/preview/supervisor.js');
+const { PREVIEW_DB } = require('../modules/npm-release/preview/env.js');
+
+function rig({ failOn, probeResults, env } = {}) {
+  const calls = [];
+  const rmCalls = [];
+  const fake = { clock: 1_000_000, spawned: [], killed: 0 };
+  const sup = createSupervisor({
+    run: async (cmd) => {
+      calls.push(cmd);
+      const tag = cmd.cmd === 'pg_dump' ? 'dump' : cmd.cmd;
+      if (failOn && failOn === tag) return { code: 3, stderr: 'boom from ' + tag };
+      return { code: 0, stderr: '' };
+    },
+    spawn: (bin, args, opts) => {
+      const handlers = {};
+      const child = { bin, args, opts, on: (ev, fn) => { handlers[ev] = fn; }, kill: () => { fake.killed += 1; }, emit: (ev, ...a) => handlers[ev] && handlers[ev](...a) };
+      fake.spawned.push(child);
+      return child;
+    },
+    probe: async () => (probeResults ? probeResults.shift() ?? false : true),
+    sleep: async () => {},
+    now: () => fake.clock,
+    fsImpl: { mkdtempSync: (p) => p + 'XYZ', mkdirSync() {}, rmSync: (p) => rmCalls.push(p) },
+    tmpdir: '/tmp',
+    liveDb: 'live_db',
+    cacheRoot: '/cache',
+    port: 3190,
+    env: env || { PATH: '/bin', GITHUB_TOKEN: 'ghp_secret' },
+  });
+  return { sup, calls, rmCalls, fake };
+}
+
+const fwd = (x) => String(x).split(String.fromCharCode(92)).join('/');
+const DROP = { cmd: 'dropdb', args: ['--if-exists', PREVIEW_DB] };
+
+test('a start runs install, copy, restore and migrate, in that order, then launches and waits for health', async () => {
+  const { sup, calls, fake } = rig();
+  const r = sup.start('1.19.1000');
+  assert.equal(r.ok, true);
+  assert.equal(r.status.state, 'starting');
+  await r.done;
+  assert.deepEqual(calls.map((c) => c.cmd), ['npm', 'dropdb', 'createdb', 'pg_dump', 'pg_restore', 'bash']);
+  assert.equal(fake.spawned.length, 1);
+  assert.match(fwd(fake.spawned[0].args[0]), /1\.19\.1000\/node_modules\/@bongos\/core\/src\/platform-server\.js$/);
+  assert.equal(sup.status().state, 'running');
+  assert.equal(sup.status().version, '1.19.1000');
+});
+
+test('the child is launched with the built environment, not the live one', async () => {
+  const { sup, fake } = rig();
+  await sup.start('1.19.1000').done;
+  const env = fake.spawned[0].opts.env;
+  assert.equal(env.GITHUB_TOKEN, undefined);
+  assert.equal(env.PGDATABASE, PREVIEW_DB);
+  assert.equal(env.PORT, '3190');
+  assert.equal(env.HOST, '127.0.0.1');
+});
+
+test('the install and the migrate get the built environment too, never the live one', async () => {
+  const { sup, calls } = rig();
+  await sup.start('1.19.1000').done;
+  const install = calls.find((c) => c.cmd === 'npm');
+  const migrate = calls.find((c) => c.cmd === 'bash');
+  for (const cmd of [install, migrate]) {
+    assert.equal(cmd.env.GITHUB_TOKEN, undefined, cmd.cmd);
+    assert.equal(cmd.env.PGDATABASE, PREVIEW_DB, cmd.cmd);
+  }
+  assert.equal(migrate.env.DATABASE_URL, '');
+});
+
+for (const failOn of ['npm', 'dropdb', 'createdb', 'dump', 'pg_restore', 'bash']) {
+  test('a failed ' + failOn + ' step leaves nothing behind: copy dropped, scratch removed, no child', async () => {
+    const { sup, calls, rmCalls, fake } = rig({ failOn });
+    await sup.start('1.19.1000').done;
+    const s = sup.status();
+    assert.equal(s.state, 'failed');
+    assert.match(s.error, /failed \(exit 3\)/);
+    assert.equal(fake.spawned.length, 0, 'no process was started');
+    assert.deepEqual(calls[calls.length - 1], DROP, 'the copy is dropped last');
+    assert.equal(rmCalls.length, 1, 'the scratch directory is removed');
+  });
+}
+
+test('a preview that never answers is stopped and cleaned up', async () => {
+  const { sup, fake, rmCalls } = rig({ probeResults: new Array(100).fill(false) });
+  await sup.start('1.19.1000').done;
+  assert.equal(sup.status().state, 'failed');
+  assert.match(sup.status().error, /did not answer/);
+  assert.equal(fake.killed, 1);
+  assert.equal(rmCalls.length, 1);
+});
+
+test('only one preview at a time: a second version is refused, the same version is not restarted', async () => {
+  const { sup, calls } = rig();
+  await sup.start('1.19.1000').done;
+  const before = calls.length;
+  const other = sup.start('1.19.1001');
+  assert.equal(other.ok, false);
+  assert.equal(other.code, 'preview_busy');
+  const same = sup.start('1.19.1000');
+  assert.equal(same.ok, true);
+  assert.equal(same.already, true);
+  assert.equal(calls.length, before, 'nothing ran');
+});
+
+test('a second start while the first is still starting is refused too', () => {
+  const { sup } = rig();
+  sup.start('1.19.1000');
+  const other = sup.start('1.19.1001');
+  assert.equal(other.code, 'preview_busy');
+});
+
+test('a version that is not a version is refused before anything runs', () => {
+  const { sup, calls } = rig();
+  const r = sup.start('1.19.1; rm -rf /');
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'not_a_version');
+  assert.equal(calls.length, 0);
+});
+
+test('stop kills the child, drops the copy, removes scratch and returns to idle', async () => {
+  const { sup, calls, fake, rmCalls } = rig();
+  await sup.start('1.19.1000').done;
+  await sup.stop();
+  assert.equal(fake.killed, 1);
+  assert.deepEqual(calls[calls.length - 1], DROP);
+  assert.equal(rmCalls.length, 1);
+  assert.equal(sup.status().state, 'idle');
+  assert.equal(sup.status().version, null);
+  assert.equal(sup.start('1.19.1001').ok, true, 'and a new one may start');
+});
+
+test('a running preview nobody touches for the idle window is stopped; touching keeps it', async () => {
+  const { sup, fake } = rig();
+  await sup.start('1.19.1000').done;
+  fake.clock += IDLE_MS - 1000;
+  assert.equal(await sup.reapIdle(), false, 'just inside the window');
+  sup.touch();
+  fake.clock += IDLE_MS - 1000;
+  assert.equal(await sup.reapIdle(), false, 'the touch restarted the window');
+  fake.clock += 2000;
+  assert.equal(await sup.reapIdle(), true);
+  assert.equal(sup.status().state, 'idle');
+  assert.equal(fake.killed, 1);
+});
+
+test('the idle window is twenty minutes', () => {
+  assert.equal(IDLE_MS, 20 * 60 * 1000);
+});
+
+test('reaping does nothing when nothing is running', async () => {
+  const { sup, calls } = rig();
+  assert.equal(await sup.reapIdle(), false);
+  assert.equal(calls.length, 0);
+});
+
+test('a child that dies on its own leaves the state failed and the copy dropped', async () => {
+  const { sup, fake, calls } = rig();
+  await sup.start('1.19.1000').done;
+  fake.spawned[0].emit('exit', 1);
+  await new Promise((r) => setImmediate(r));
+  assert.equal(sup.status().state, 'failed');
+  assert.deepEqual(calls[calls.length - 1], DROP);
+});
+
+// ---- which versions may be opened ----------------------------------------------------
+
+const published = {};
+for (let i = 0; i < 60; i++) published['1.19.' + (1000 + i)] = '2026-09-01T00:00:00Z';
+
+test('only a published version may be previewed', () => {
+  assert.deepEqual(previewable('1.19.1010', { published, running: '1.19.1040' }), { ok: true });
+  assert.deepEqual(previewable('1.19.9999', { published, running: '1.19.1040' }), { ok: false, reason: 'not_published' });
+  assert.deepEqual(previewable('nope', { published, running: '1.19.1040' }), { ok: false, reason: 'not_a_version' });
+});
+
+test('no older than the running version minus thirty published versions; newer is fine', () => {
+  const running = '1.19.1040';
+  assert.equal(WINDOW, 30);
+  assert.equal(previewable('1.19.1010', { published, running }).ok, true, 'exactly thirty back');
+  assert.deepEqual(previewable('1.19.1009', { published, running }), { ok: false, reason: 'too_old', oldest: '1.19.1010' });
+  assert.equal(previewable('1.19.1059', { published, running }).ok, true, 'a newer one may be tried');
+});
+
+test('when the running version is not in the list the window counts from the newest', () => {
+  assert.equal(previewable('1.19.1029', { published, running: '0.0.1' }).ok, true);
+  assert.equal(previewable('1.19.1028', { published, running: '0.0.1' }).ok, false);
+});