@bongos/core 1.20.24 → 1.20.25

package/tests/provisioning_wizard_create_xenos.mjs

@@ -0,0 +1,381 @@
+// tests/provisioning_wizard_create_xenos.mjs — a brand-new user presses "Create my
+// project" (task 1004412, ADR 0354).
+//
+// The hub's create wizard (modules/public-landing/public/projects.html) ends in one
+// request: POST /provisioning/instances with the wizard's hosting shape. A new hub
+// signup is a Xenos (migrations/029_rank_three_live.sql). So the question this file
+// answers is the one a stranger actually asks: when a Xenos sends the wizard's own
+// request, what comes back, and what does the wizard then say?
+//
+// Until task 1004412 the answer was 403 permission_forbidden for EVERY new user, shown as
+// the generic "We couldn't file the request". Task 1003370 had gated cloud-host outright,
+// before ADR 0345 made it the free front door. The owner's ruling (2026-09-30): a
+// builder's first live hosted project needs no permission, and a further one needs
+// provisioning.fleet.manage.
+//
+// It is asked as close to production as a DB-free test can get:
+//   • the shape is READ from projects.html, not typed here, so the test follows the
+//     wizard if the wizard ever changes what it sends;
+//   • the permission gate is the REAL requirePermission (src/bongos/auth.js), not a
+//     fake. The builder's grants are the catalog's own seed for their rank
+//     (seedForRank), which is what governance_002 wrote into role_permissions, fed
+//     through the real resolver's effectivePermissions on the session-fold path;
+//   • the error envelope is the real attachFail, and the wizard's copy is the real
+//     friendlyCreateError, handed the route's real response body.
+// Only the database is stubbed: the row writes, the caller's project list, and the box's
+// slot count.
+//
+// Run:  node tests/provisioning_wizard_create_xenos.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+let passed = 0, failed = 0;
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// ── what the wizard sends and says, read from the wizard ─────────────────────────
+// LF-normalised: a Windows checkout hands back CRLF.
+const HUB = fs.readFileSync(path.join(ROOT, 'modules', 'public-landing', 'public', 'projects.html'), 'utf8').replace(/\r\n/g, '\n');
+// The create click's handler, from its listener to the end of that listener. The scan is
+// guarded below: a regex that quietly matches nothing would test nothing.
+const CREATE = (() => {
+  const start = HUB.indexOf("$('doCreate').addEventListener('click'");
+  if (start < 0) return '';
+  const end = HUB.indexOf('\n    });\n', start);
+  return end < 0 ? '' : HUB.slice(start, end);
+})();
+const WIZARD_SHAPES = [...CREATE.matchAll(/hosting_shape:\s*'([a-z-]+)'/g)].map((m) => m[1]);
+const WIZARD_SHAPE = WIZARD_SHAPES[0];
+
+// The wizard's own error copy, evaluated. It is self-contained (it reads only its
+// argument), so its text runs as it is; the caller hands it `{ data: <response body> }`
+// exactly as the create click does (`e.data = data`).
+const friendlyCreateError = (() => {
+  const start = HUB.indexOf('function friendlyCreateError(err) {');
+  const end = HUB.indexOf('\n    function createFailureMarkup', start);
+  assert.ok(start >= 0 && end > start, 'friendlyCreateError() exists in projects.html');
+  return new Function(`${HUB.slice(start, end)}\nreturn friendlyCreateError;`)();
+})();
+
+// The request a stranger's first project sends: a fresh repo, the default address.
+function wizardBody(slug) {
+  return { slug, hosting_shape: WIZARD_SHAPE, target_ref: `newcomer/${slug}`, onboard_mode: 'greenfield' };
+}
+
+// ── stubs: the database, and only the database ────────────────────────────────────
+const provisioning = require('../modules/provisioning/provisioning.js');
+let created = [];
+let createDelay = null; // a promise the next createInstance waits on, for the race case
+provisioning.createInstance = async (_db, args) => {
+  if (createDelay) await createDelay;
+  created.push(args);
+  return { instance: { id: 42, owner_builder_id: 7, slug: args.slug, hosting_shape: args.hostingShape, status: 'requested', domain: args.domain || null }, created: true };
+};
+// Whether the builder's free-place lock was still held when the intent was queued —
+// the step right after the insert — so the lock's early release can be asserted.
+let lockHeldAtEnqueue = null;
+provisioning.enqueueIntent = async (_db, _id) => { lockHeldAtEnqueue = heldLocks.has('7'); return { intent: { id: 1, action: 'provision', state: 'pending' }, created: true }; };
+provisioning.getOpenIntent = async () => null;
+provisioning.recordEvent = async () => {};
+provisioning.getInstanceBySlug = async () => null;
+provisioning.getInstanceByDomain = async () => null;
+// The caller's own projects, flipped per case. The gate counts these.
+let owned = [];
+provisioning.listInstancesForOwner = async () => owned;
+require('../modules/provisioning/catalog-bridge.js').publishInstanceToCatalog = async () => {};
+// The free-place lock, with the real one's semantics and none of its database: a
+// try-lock per builder, released when the gate's release function runs. The real
+// function's SQL and client handling are proved separately below (holdFreePlace cases).
+const freePlace = require('../modules/provisioning/free-place-lock.js');
+const realHoldFreePlace = freePlace.holdFreePlace;
+const heldLocks = new Set();
+freePlace.holdFreePlace = async (_db, builderId) => {
+  const key = String(builderId);
+  if (heldLocks.has(key)) return null;
+  heldLocks.add(key);
+  return async () => { heldLocks.delete(key); };
+};
+// The box's slot count. `placed` is flipped per case; 15 is the 2 GB box's ceiling.
+const capacity = require('../modules/provisioning/capacity.js');
+let placed = 3;
+capacity.fleetCapacity = async () => ({ box: 'control-plane', placed, ceiling: 15, source: 'measured' });
+
+// ── auth: a session for a builder of the given rank, holding that rank's real grants ─
+const catalog = require('../modules/government/catalog.js');
+const resolver = require('../modules/government/resolver.js');
+const seams = require('../src/module-seams.js');
+let rank = 'xenos';
+// true → the session carries no grant keys and the resolver throws, so authority cannot
+// be established at all (the kernel then denies with held: null).
+let authorityUnreadable = false;
+seams.registerProvider('government', {
+  // The session-fold path: requirePermission runs this over the raw grant keys the
+  // session query carried. The DB path below answers the same set, so either path
+  // resolves to the rank's seed.
+  effectivePermissions: resolver.effectivePermissions,
+  resolveBuilderPermissions: async () => {
+    if (authorityUnreadable) throw new Error('resolver down');
+    return catalog.seedForRank(rank);
+  },
+  permissionFloor: (key) => (catalog.byKey(key) || {}).floor || null,
+  isOwnershipScoped: catalog.isOwnershipScoped,
+});
+const api = require('../src/module-api.js');
+api.requireBuilder = (req, _res, next) => {
+  req.builder = { id: 7, github_login: 'newcomer', rank };
+  req.rawPermissionKeys = authorityUnreadable ? undefined : catalog.seedForRank(rank);
+  next();
+};
+
+const express = require('express');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+const provisioningRoutes = require('../modules/provisioning/routes/provisioning.js');
+const app = express();
+app.use(express.json());
+app.use(attachFail);
+app.use('/api/bongos', provisioningRoutes());
+
+const server = app.listen(0);
+await new Promise((r) => server.once('listening', r));
+const base = `http://127.0.0.1:${server.address().port}/api/bongos`;
+
+function post(body) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify(body);
+    const req = http.request(`${base}/provisioning/instances`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },
+    }, (res) => {
+      let d = '';
+      res.on('data', (c) => { d += c; });
+      res.on('end', () => { let j = null; try { j = JSON.parse(d); } catch { /* non-JSON */ } resolve({ status: res.statusCode, body: j, raw: d }); });
+    });
+    req.on('error', reject);
+    req.end(payload);
+  });
+}
+
+function reset({ as = 'xenos', projects = [], slots = 3 } = {}) {
+  rank = as; owned = projects; placed = slots; created = []; createDelay = null; authorityUnreadable = false;
+}
+const hosted = (slug, status = 'active') => ({ id: 9, owner_builder_id: 7, slug, hosting_shape: 'cloud-host', status });
+
+// ── the harness is real ───────────────────────────────────────────────────────────
+
+await ta('the wizard sends exactly one hosting shape, and it is cloud-host', () => {
+  // If this scan found nothing, every case below would post an undefined shape — which
+  // defaults to the open byo-host and passes for the wrong reason.
+  assert.ok(CREATE.includes("'/provisioning/instances'"), 'found the create click and its POST');
+  assert.deepEqual(WIZARD_SHAPES, ['cloud-host'], `the create request's hosting_shape literals: ${JSON.stringify(WIZARD_SHAPES)}`);
+});
+
+await ta('a Xenos holds the catalog seed for its rank, and that seed has no fleet permission', () => {
+  const xenos = catalog.seedForRank('xenos');
+  assert.ok(xenos.length > 0 && xenos.includes('task.ship'), 'the seed is the real one, not an empty list');
+  assert.ok(!xenos.includes('provisioning.fleet.manage'));
+  assert.ok(catalog.seedForRank('metic').includes('provisioning.fleet.manage'), 'a Metic does hold it');
+});
+
+// ── the first project (task 1004412) ──────────────────────────────────────────────
+
+await ta('a Xenos\'s FIRST hosted project is created from the wizard\'s exact request', async () => {
+  // The finding: before task 1004412 this was 403 permission_forbidden, for every new user.
+  reset();
+  const res = await post(wizardBody('first-light'));
+  assert.equal(res.status, 201, `got ${res.status} ${res.raw}`);
+  assert.equal(created.length, 1);
+  assert.equal(created[0].hostingShape, 'cloud-host', 'stored as the hosted shape the wizard asked for');
+});
+
+await ta('only a project taken offline gives the free place back; byo-host projects never use it', async () => {
+  reset({ projects: [hosted('old-one', 'torn_down'), { ...hosted('own-box'), hosting_shape: 'byo-host' }] });
+  const res = await post(wizardBody('first-light'));
+  assert.equal(res.status, 201, `got ${res.status} ${res.raw}`);
+});
+
+await ta('asking again for your OWN project is that project, not a second one', async () => {
+  // A retry of a snagged standup, or a revive, re-sends the same slug. It must not be
+  // counted against the place it already holds.
+  reset({ projects: [hosted('first-light', 'error')] });
+  const res = await post(wizardBody('first-light'));
+  assert.equal(res.status, 201, `got ${res.status} ${res.raw}`);
+});
+
+// ── a second project ──────────────────────────────────────────────────────────────
+
+await ta('a Xenos who already hosts a project is refused a second, and nothing is created', async () => {
+  for (const status of ['active', 'requested', 'provisioning', 'error', 'tearing_down']) {
+    reset({ projects: [hosted('first-light', status)] });
+    const res = await post(wizardBody('second-sun'));
+    assert.equal(res.status, 403, `with a ${status} project: got ${res.status} ${res.raw}`);
+    assert.equal(res.body.error.code, 'permission_forbidden');
+    assert.deepEqual(res.body.error.details.required, ['provisioning.fleet.manage']);
+    assert.deepEqual(created, [], `with a ${status} project: no row`);
+  }
+});
+
+await ta('the wizard tells that person why, in plain words, and not the raw permission', async () => {
+  reset({ projects: [hosted('first-light')] });
+  const res = await post(wizardBody('second-sun'));
+  const said = friendlyCreateError({ data: res.body });
+  assert.match(said, /one project for free, and yours already has one/, said);
+  assert.match(said, /take the old one offline/, 'it names the way out, in the project page\'s own words');
+  assert.match(said, /Trusted builders can host more than one/, 'and the other way out: the permission lifts the limit (the owner\'s wording, 2026-09-30)');
+  assert.doesNotMatch(said, /provisioning\.fleet\.manage|permission|metic/i, 'no wire vocabulary in the headline');
+});
+
+await ta('when authority cannot be checked at all, the wizard does not blame the person\'s project', async () => {
+  // held: null is the kernel's fail-closed denial — the permission system could not
+  // answer. That is a blip, not "you already have one", so the wizard's copy falls to its
+  // generic sentence (an empty string here) with the raw text under Technical details.
+  reset({ projects: [hosted('first-light')] });
+  authorityUnreadable = true;
+  const res = await post(wizardBody('second-sun'));
+  assert.equal(res.status, 403, `got ${res.status} ${res.raw}`);
+  assert.equal(res.body.error.code, 'permission_forbidden');
+  assert.equal(res.body.error.details.held, null, 'the fail-closed shape');
+  assert.equal(friendlyCreateError({ data: res.body }), '');
+});
+
+await ta('a Metic may host more than one — the permission lifts the limit', async () => {
+  reset({ as: 'metic', projects: [hosted('first-light'), hosted('second-sun')] });
+  const res = await post(wizardBody('third-star'));
+  assert.equal(res.status, 201, `got ${res.status} ${res.raw}`);
+});
+
+await ta('two creates sent at once cannot both take the free place', async () => {
+  // The count and the insert are two steps. Hold the first request inside the insert and
+  // send a second: it must be refused, not counted against a list that has not changed yet.
+  reset();
+  let release;
+  createDelay = new Promise((r) => { release = r; });
+  const first = post(wizardBody('first-light'));
+  await new Promise((r) => setTimeout(r, 50)); // the first is now waiting inside createInstance
+  // A refused second answers at once. One that got through would wait on the same held
+  // insert, so it is given half a second and then the first is released either way —
+  // otherwise a broken guard would hang this file instead of failing it.
+  const pending = post(wizardBody('second-sun'));
+  const early = await Promise.race([pending, new Promise((r) => setTimeout(() => r(null), 500))]);
+  release();
+  const second = early || await pending;
+  const firstRes = await first;
+  assert.equal(firstRes.status, 201, `first: ${firstRes.status} ${firstRes.raw}`);
+  assert.equal(second.status, 409, `second: ${second.status} ${second.raw}`);
+  assert.equal(second.body.error.code, 'create_in_progress');
+  assert.deepEqual(created.map((a) => a.slug), ['first-light'], 'exactly one project');
+  // …and once the first has answered, the mark is gone: the next request is counted again.
+  createDelay = null; owned = [hosted('first-light')];
+  const third = await post(wizardBody('second-sun'));
+  assert.equal(third.status, 403, `after the first answered: ${third.status} ${third.raw}`);
+});
+
+await ta('a project list that cannot be read refuses, and never counts as zero', async () => {
+  reset();
+  provisioning.listInstancesForOwner = async () => { throw new Error('db down'); };
+  try {
+    const res = await post(wizardBody('first-light'));
+    assert.equal(res.status, 500, `got ${res.status} ${res.raw}`);
+    assert.equal(res.body.error.code, 'request_failed');
+    assert.deepEqual(created, [], 'no row');
+    assert.match(friendlyCreateError({ data: res.body }), /couldn’t file the request/);
+  } finally {
+    provisioning.listInstancesForOwner = async () => owned;
+  }
+});
+
+// ── the box is full ───────────────────────────────────────────────────────────────
+
+await ta('a full server is said plainly in the wizard, never as the operator\'s sentence', async () => {
+  reset({ slots: 15 });
+  const res = await post(wizardBody('first-light'));
+  assert.equal(res.status, 409, `got ${res.status} ${res.raw}`);
+  assert.equal(res.body.error.code, 'box_full');
+  assert.deepEqual(created, [], 'no row');
+  const said = friendlyCreateError({ data: res.body });
+  assert.match(said, /server is full/, said);
+  assert.doesNotMatch(said, /ADR|task \d|slots/i, 'the server\'s own reason is written for operators');
+});
+
+await ta('the lock is let go as soon as the row exists, not at the end of the request', async () => {
+  reset();
+  lockHeldAtEnqueue = null;
+  const res = await post(wizardBody('first-light'));
+  assert.equal(res.status, 201, `got ${res.status} ${res.raw}`);
+  assert.equal(lockHeldAtEnqueue, false, 'released right after createInstance, before the intent is queued');
+  assert.equal(heldLocks.size, 0);
+});
+
+await ta('a lock that cannot be taken refuses, and never admits', async () => {
+  reset();
+  const saved = freePlace.holdFreePlace;
+  freePlace.holdFreePlace = async () => { throw new Error('db down'); };
+  try {
+    const res = await post(wizardBody('first-light'));
+    assert.equal(res.status, 500, `got ${res.status} ${res.raw}`);
+    assert.equal(res.body.error.code, 'request_failed');
+    assert.deepEqual(created, [], 'no row');
+  } finally {
+    freePlace.holdFreePlace = saved;
+  }
+});
+
+// ── the real lock: one per builder across processes, held on its own client ───────
+
+function fakeDb({ held = true, lockThrows = false, unlockThrows = false } = {}) {
+  const log = { queries: [], released: [] };
+  const client = {
+    query: async (sql, params) => {
+      log.queries.push({ sql, params });
+      if (/pg_try_advisory_lock/.test(sql)) { if (lockThrows) throw new Error('lock failed'); return { rows: [{ held }] }; }
+      if (/pg_advisory_unlock/.test(sql)) { if (unlockThrows) throw new Error('unlock failed'); return { rows: [{ pg_advisory_unlock: true }] }; }
+      throw new Error(`unexpected SQL: ${sql}`);
+    },
+    release: (destroy) => { log.released.push(destroy === true ? 'destroyed' : 'returned'); },
+  };
+  return { db: { connect: async () => client }, log };
+}
+
+await ta('holdFreePlace: a TRY lock keyed on the builder, released by unlocking and returning the client', async () => {
+  const { db, log } = fakeDb();
+  const release = await realHoldFreePlace(db, 1000025);
+  assert.equal(typeof release, 'function', 'held → a release function');
+  assert.match(log.queries[0].sql, /pg_try_advisory_lock\(hashtext\('provisioning\.one-free-hosted-project'\), \$1::int\)/,
+    'try (never waits), namespaced so it cannot collide with another lock on a builder id');
+  assert.deepEqual(log.queries[0].params, [1000025]);
+  assert.deepEqual(log.released, [], 'the client is HELD for the request — a session lock dies with its connection');
+  await release();
+  await release();
+  assert.match(log.queries[1].sql, /pg_advisory_unlock/);
+  assert.equal(log.queries.length, 2, 'a second release is a no-op');
+  assert.deepEqual(log.released, ['returned']);
+});
+
+await ta('holdFreePlace: someone else holds it → null, and the client goes straight back', async () => {
+  const { db, log } = fakeDb({ held: false });
+  assert.equal(await realHoldFreePlace(db, 7), null);
+  assert.deepEqual(log.released, ['returned']);
+});
+
+await ta('holdFreePlace: a failed lock or unlock DESTROYS the client, which ends the session and its lock', async () => {
+  const failing = fakeDb({ lockThrows: true });
+  await assert.rejects(() => realHoldFreePlace(failing.db, 7), /lock failed/);
+  assert.deepEqual(failing.log.released, ['destroyed']);
+  const stuck = fakeDb({ unlockThrows: true });
+  const release = await realHoldFreePlace(stuck.db, 7);
+  await release();
+  assert.deepEqual(stuck.log.released, ['destroyed'], 'a lock we could not let go of must not go back into the pool');
+});
+
+server.close();
+console.log(`\nprovisioning_wizard_create_xenos: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);