@bongos/core 1.25.17 → 1.25.19

package/tests/app_host.mjs

@@ -0,0 +1,413 @@
+// tests/app_host.mjs — where the project's app runs, in the hall's options menu (task 1004571).
+//
+// The whole chain, DB-free and with no Render call anywhere:
+//   1. the provisioning port (projectAppStatus) — the row, by both halves of the projection,
+//      read through app-status.js's own shape;
+//   2. the hub route (POST /sso/app-status) — only an authenticated project, only its own row;
+//   3. the core asker (readAppStatusFromHub) — the project's credentials, never throws;
+//   4. the hall route (GET /app-host) — each state, owner vs everyone else, new fields kept;
+//   5. the module switch — the panel's script is injected only while the module is on, and
+//      loads before settings.js the way settings.js loads;
+//   6. the panel itself — what a builder reads in each state.
+//
+// Run:  node --test tests/app_host.mjs
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const express = require('express');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+
+// The doorway with a quiet logger and a stand-in sign-in gate, BEFORE any route file loads.
+const apiPath = require.resolve('../src/module-api.js');
+const realApi = require(apiPath);
+let viewer = { id: 7 };
+const fakeApi = {
+  ...realApi,
+  logger: () => ({ error() {}, warn() {}, info() {} }),
+  requireBuilder: (req, _res, next) => { req.builder = viewer; next(); },
+};
+require.cache[apiPath].exports = fakeApi;
+
+async function serve(router) {
+  const app = express();
+  app.use(express.json());
+  app.use(attachFail);
+  app.use('/api/bongos', router);
+  const server = await new Promise((r) => { const s = app.listen(0, '127.0.0.1', () => r(s)); });
+  const base = `http://127.0.0.1:${server.address().port}/api/bongos`;
+  const call = (method, route, body) => new Promise((resolve, reject) => {
+    const payload = body ? JSON.stringify(body) : '';
+    const req = http.request(`${base}${route}`, {
+      method, headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) },
+    }, (res) => {
+      let raw = '';
+      res.on('data', (c) => { raw += c; });
+      res.on('end', () => resolve({ status: res.statusCode, headers: res.headers, body: raw ? JSON.parse(raw) : null }));
+    });
+    req.on('error', reject);
+    req.end(payload);
+  });
+  return { call, close: () => server.close() };
+}
+
+// ── 1. the provisioning port ─────────────────────────────────────────────────
+
+const { projectAppStatus } = require('../modules/provisioning/seams.js');
+
+function rowDb(row) {
+  const seen = [];
+  return { seen, async query(sql, params) { seen.push({ sql: String(sql), params }); return { rows: row ? [row] : [] }; } };
+}
+
+test('port: the project is named by slug AND host, the host lowercased', async () => {
+  const db = rowDb(null);
+  assert.equal(await projectAppStatus(db, { slug: 'mercury', host: 'Mercury.Test' }), null);
+  assert.deepEqual(db.seen[0].params, ['mercury', 'mercury.test']);
+  assert.match(db.seen[0].sql, /i\.slug = \$1 AND lower\(i\.domain\) = \$2/);
+});
+
+test('port: a half-named project is no answer, and no query runs', async () => {
+  const db = rowDb({ app_host: null, waiting: false });
+  assert.equal(await projectAppStatus(db, { slug: 'mercury' }), null);
+  assert.equal(await projectAppStatus(db, { host: 'mercury.test' }), null);
+  assert.equal(db.seen.length, 0);
+});
+
+test('port: no platform yet is { app: null }; Render reads through app-status.js', async () => {
+  assert.deepEqual(await projectAppStatus(rowDb({ app_host: null, waiting: false }), { slug: 'm', host: 'm.test' }), { app: null, sandbox: null });
+  const live = await projectAppStatus(rowDb({
+    app_host: { platform: 'render', state: 'live', serviceUrl: 'https://mercury-app.onrender.com', serviceId: 'srv-abcdefgh12' },
+    waiting: false,
+  }), { slug: 'm', host: 'm.test' });
+  assert.equal(live.app.stage, 'live');
+  assert.equal(live.app.url, 'https://mercury-app.onrender.com');
+  assert.equal(live.app.links.service, 'https://dashboard.render.com/web/srv-abcdefgh12');
+  const failed = await projectAppStatus(rowDb({ app_host: { platform: 'render', state: 'failed', error: 'the build command failed' }, waiting: false }), { slug: 'm', host: 'm.test' });
+  assert.equal(failed.app.state, 'failed');
+  assert.equal(failed.app.error, 'The build command failed.');
+  const waiting = await projectAppStatus(rowDb({ app_host: { platform: 'render', state: 'requested' }, waiting: true }), { slug: 'm', host: 'm.test' });
+  assert.equal(waiting.app.waiting, true);
+  assert.equal(waiting.app.stage, 'creating');
+});
+
+// ── 2. the hub route ─────────────────────────────────────────────────────────
+
+const pi = require('../modules/platform-identity/platform-identity.js');
+const SECRET = 'project-secret';
+const CLIENTS = {
+  mercury: { client_id: 'mercury', secret_hash: pi.sha256hex(SECRET), status: 'active', origin: 'https://Mercury.test' },
+  frozen: { client_id: 'frozen', secret_hash: pi.sha256hex(SECRET), status: 'suspended', origin: 'https://frozen.test' },
+  shell: { client_id: 'shell', secret_hash: '', status: 'active', origin: 'https://shell.test' },
+};
+const clientDb = { async query(_sql, params) { return { rows: CLIENTS[params[0]] ? [CLIENTS[params[0]]] : [] }; } };
+const buildHubRoute = require('../modules/platform-identity/routes/sso-app-status.js');
+
+test('hub: a wrong secret, a suspended client and a catalog-only row are all refused, and the port is never asked', async () => {
+  const asked = [];
+  const hub = await serve(buildHubRoute({ db: clientDb, resolvePort: () => async (t) => { asked.push(t); return { app: null }; } }));
+  try {
+    for (const body of [
+      { client_id: 'mercury', client_secret: 'nope' },
+      { client_id: 'frozen', client_secret: SECRET },
+      { client_id: 'shell', client_secret: '' },
+      { client_id: 'nobody', client_secret: SECRET },
+    ]) {
+      const r = await hub.call('POST', '/sso/app-status', body);
+      assert.equal(r.status, 401, JSON.stringify(body));
+    }
+    assert.equal(asked.length, 0);
+  } finally { hub.close(); }
+});
+
+test('hub: the project reads ITS OWN row — slug from the client, host from its registered origin', async () => {
+  const asked = [];
+  const app = { platform: 'render', state: 'live', stage: 'live', url: 'https://m.onrender.com', sandbox: { url: 'https://m-sandbox.onrender.com' } };
+  const hub = await serve(buildHubRoute({ db: clientDb, resolvePort: (n) => (n === 'provisioning.projectAppStatus' ? async (t) => { asked.push(t); return { app }; } : null) }));
+  try {
+    const r = await hub.call('POST', '/sso/app-status', { client_id: 'mercury', client_secret: SECRET });
+    assert.equal(r.status, 200);
+    assert.deepEqual(asked, [{ slug: 'mercury', host: 'mercury.test' }]);
+    assert.deepEqual(r.body, { ok: true, known: true, app, sandbox: null }, 'the shape passes through, new fields and all');
+    const extra = await hub.call('POST', '/sso/app-status', { client_id: 'mercury', client_secret: SECRET, slug: 'venus' });
+    assert.equal(extra.status, 400, 'nothing in the body can name another project');
+  } finally { hub.close(); }
+});
+
+test('hub: no provisioning, or no row, is known:false', async () => {
+  for (const resolvePort of [() => null, () => async () => null]) {
+    const hub = await serve(buildHubRoute({ db: clientDb, resolvePort }));
+    try {
+      const r = await hub.call('POST', '/sso/app-status', { client_id: 'mercury', client_secret: SECRET });
+      assert.deepEqual(r.body, { ok: true, known: false, app: null, sandbox: null });
+    } finally { hub.close(); }
+  }
+});
+
+// ── 3. the core asker ────────────────────────────────────────────────────────
+
+const pin = (rel, exports) => {
+  const p = require.resolve(rel);
+  require.cache[p] = { id: p, filename: p, loaded: true, exports };
+};
+const IDP = { origin: 'https://hub.test', clientId: 'mercury', clientSecret: SECRET };
+function loadAsker(idp) {
+  pin('../src/bongos/auth-config.js', { ...require('../src/bongos/auth-config.js'), loadIdpConfig: () => idp });
+  delete require.cache[require.resolve('../src/bongos/auth-admission.js')];
+  return require('../src/bongos/auth-admission.js').readAppStatusFromHub;
+}
+async function withFetch(impl, fn) {
+  const real = globalThis.fetch;
+  const sent = [];
+  globalThis.fetch = async (url, init) => { sent.push({ url, init }); return impl(url, init); };
+  try { await fn(sent); } finally { globalThis.fetch = real; }
+}
+const MANAGE = { manage_url: 'https://hub.test/projects?view=manage&project=mercury', hub_host: 'hub.test' };
+
+test('asker: no hub answers hub:false and sends nothing', async () => {
+  const ask = loadAsker(null);
+  await withFetch(async () => ({ ok: true }), async (sent) => {
+    assert.deepEqual(await ask(), { hub: false });
+    assert.equal(sent.length, 0);
+  });
+});
+
+test('asker: it sends only this project\'s credentials, bounded, and returns the hub\'s answer with the manage page', async () => {
+  const ask = loadAsker(IDP);
+  const app = { platform: 'render', state: 'creating', stage: 'creating' };
+  await withFetch(async () => ({ ok: true, json: async () => ({ ok: true, known: true, app }) }), async (sent) => {
+    assert.deepEqual(await ask(), { hub: true, reachable: true, known: true, app, sandbox: null, manage: MANAGE });
+    assert.equal(sent[0].url, 'https://hub.test/api/bongos/sso/app-status');
+    assert.deepEqual(JSON.parse(sent[0].init.body), { client_id: 'mercury', client_secret: SECRET });
+    assert.ok(sent[0].init.signal);
+  });
+});
+
+test('asker: a hub that is down or older never throws — reachable:false', async () => {
+  const ask = loadAsker(IDP);
+  await withFetch(async () => { throw new Error('ECONNREFUSED'); }, async () => {
+    assert.deepEqual(await ask(), { hub: true, reachable: false, manage: MANAGE });
+  });
+  await withFetch(async () => ({ ok: false, status: 404, json: async () => ({}) }), async () => {
+    assert.deepEqual(await ask(), { hub: true, reachable: false, manage: MANAGE });
+  });
+});
+
+// ── 4. the hall route ────────────────────────────────────────────────────────
+
+const buildHall = require('../modules/app-host/routes/app-host.js');
+const { viewFor } = buildHall;
+const RENDER_LIVE = {
+  platform: 'render', state: 'live', stage: 'live', url: 'https://m.onrender.com',
+  links: { service: 'https://dashboard.render.com/web/srv-abcdefgh12' }, workspace: 'tea-x', retry: null,
+  sandbox: { url: 'https://m-sandbox.onrender.com', stage: 'live' },
+};
+
+test('hall: each state, as the owner and as everyone else', () => {
+  const read = (app, extra = {}) => ({ hub: true, reachable: true, known: true, app, manage: MANAGE, ...extra });
+  // no platform yet
+  let v = viewFor(read(null), { owner: true });
+  assert.equal(v.app, null);
+  assert.equal(v.connect_url, `${MANAGE.manage_url}#mAppCard`);
+  v = viewFor(read(null), { owner: false });
+  assert.equal(v.connect_url, null, 'no action a non-owner cannot complete');
+  assert.equal(v.owner, false);
+  // live, owner: links kept; non-owner: owner-only fields gone, the rest (and new fields) kept
+  v = viewFor(read(RENDER_LIVE), { owner: true });
+  assert.ok(v.app.links);
+  assert.equal('retry' in v.app, false);
+  v = viewFor(read(RENDER_LIVE), { owner: false });
+  for (const k of buildHall.OWNER_ONLY) assert.equal(k in v.app, false, k);
+  assert.equal(v.app.url, RENDER_LIVE.url);
+  assert.deepEqual(v.app.sandbox, RENDER_LIVE.sandbox, 'a field the hub adds later arrives untouched');
+  // failed: the sentence reaches everyone; only the owner gets where to retry
+  const failed = { platform: 'render', state: 'failed', stage: null, error: 'The build command failed.', retry: { owner_id: 'tea-x' } };
+  assert.equal(viewFor(read(failed), { owner: false }).app.error, 'The build command failed.');
+  assert.equal(viewFor(read(failed), { owner: false }).connect_url, null);
+  assert.ok(viewFor(read(failed), { owner: true }).connect_url);
+  // not reachable, not known, no hub
+  assert.equal(viewFor({ hub: true, reachable: false, manage: MANAGE }, { owner: true }).reachable, false);
+  assert.equal(viewFor(read(null, { known: false }), { owner: true }).known, false);
+  assert.deepEqual(viewFor({ hub: false }, { owner: true }), { hub: false, reachable: false, known: false, app: null, sandbox: null, owner: false, connect_url: null, hub_host: null });
+});
+
+test('hall: GET /app-host decides owner on the server, never from the request', async () => {
+  const read = async () => ({ hub: true, reachable: true, known: true, app: RENDER_LIVE, manage: MANAGE });
+  let ownerIds = new Set([1]);
+  const hall = await serve(buildHall({ readHub: read, isOwner: async (req) => ownerIds.has(req.builder.id) }));
+  try {
+    viewer = { id: 1 };
+    let r = await hall.call('GET', '/app-host?owner=1');
+    assert.equal(r.status, 200);
+    assert.equal(r.body.owner, true);
+    assert.ok(r.body.app.links);
+    assert.equal(r.headers['cache-control'], 'no-store');
+    viewer = { id: 2 };
+    r = await hall.call('GET', '/app-host?owner=1');
+    assert.equal(r.body.owner, false);
+    assert.equal(r.body.connect_url, null);
+    assert.equal(r.body.app.links, undefined);
+  } finally { hall.close(); viewer = { id: 7 }; }
+});
+
+test('hall: the owner atom is core.pin.move, and an unreadable authority is no', async () => {
+  // The default isOwner, through the government port.
+  const realResolve = fakeApi.resolveOptional;
+  const read = async () => ({ hub: true, reachable: true, known: true, app: null, manage: MANAGE });
+  try {
+    for (const [gov, expected] of [
+      [{ resolveBuilderPermissions: async () => ['core.pin.move'] }, true],
+      [{ resolveBuilderPermissions: async () => ['task.claim'] }, false],
+      [{ resolveBuilderPermissions: async () => { throw new Error('db down'); } }, false],
+      [null, false],
+    ]) {
+      fakeApi.resolveOptional = (n) => (n === 'government' ? gov : null);
+      const hall = await serve(buildHall({ readHub: read }));
+      try { assert.equal((await hall.call('GET', '/app-host')).body.owner, expected); } finally { hall.close(); }
+    }
+  } finally { fakeApi.resolveOptional = realResolve; }
+});
+
+// ── 5. the module switch ─────────────────────────────────────────────────────
+
+const { hallWidgetScripts } = require('../src/module-loader/loader.js');
+const { injectModuleHallWidgets } = require('../src/bongos/serve-internal.js');
+
+test('module: on, its panel script is listed for the options menu; off, it is not', () => {
+  const on = hallWidgetScripts({ isEnabled: () => true, file: 'settings-widget.js' });
+  assert.ok(on.some((s) => s.key === 'app-host' && s.src === '/modules/app-host/public/settings-widget.js'));
+  const off = hallWidgetScripts({ isEnabled: (k) => k !== 'app-host', file: 'settings-widget.js' });
+  assert.equal(off.some((s) => s.key === 'app-host'), false);
+  const manifest = JSON.parse(fs.readFileSync(path.join(ROOT, 'modules/app-host/module.json'), 'utf8'));
+  assert.equal(manifest.default, true);
+  assert.deepEqual(manifest.contributes.routes, ['app-host']);
+});
+
+test('module: the panel script lands before settings.js and loads the way it does (not deferred)', () => {
+  const html = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/settings.html'), 'utf8');
+  const out = injectModuleHallWidgets(html, [{ key: 'app-host', src: '/modules/app-host/public/settings-widget.js' }], 'settings');
+  const at = out.indexOf('<script src="/modules/app-host/public/settings-widget.js"></script>');
+  assert.ok(at > 0, 'injected as a plain script');
+  assert.ok(at < out.indexOf('<script src="/builders/settings.js'));
+  assert.ok(at > out.indexOf('<script src="/builders/dom-utils.js'), 'after the seam exists');
+  assert.equal(injectModuleHallWidgets(html, [], 'settings'), html, 'off: the page is unchanged');
+  // The hall index keeps its deferred widgets.
+  const idx = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/index.html'), 'utf8');
+  assert.match(injectModuleHallWidgets(idx, [{ key: 'x', src: '/modules/x/public/hall-widget.js' }]), /hall-widget\.js" defer><\/script>/);
+});
+
+// ── 6. the panel ─────────────────────────────────────────────────────────────
+
+function loadPanel() {
+  const panels = [];
+  // The hall's shared escaper, as window.OTB carries it (dom-utils.js).
+  const { escapeHtml } = require('../src/html-escape.js');
+  const window = { OTB: { escapeHtml, contributeSettingsPanel: (p) => panels.push(p) } };
+  vm.runInNewContext(fs.readFileSync(path.join(ROOT, 'modules/app-host/public/settings-widget.js'), 'utf8'), { window });
+  return { panels, render: window.OTBAppHost.render };
+}
+
+test('panel: registers one options-menu panel', () => {
+  const { panels } = loadPanel();
+  assert.equal(panels.length, 1);
+  assert.equal(panels[0].id, 'app-host');
+  assert.equal(panels[0].title, 'Where the app runs');
+});
+
+test('panel: what a builder reads in each state', () => {
+  const { render } = loadPanel();
+  const base = { hub: true, reachable: true, known: true, hub_host: 'hub.test' };
+  const owner = { ...base, owner: true, connect_url: `${MANAGE.manage_url}#mAppCard` };
+  const member = { ...base, owner: false, connect_url: null };
+
+  let h = render({ ...owner, app: null });
+  assert.match(h, /No platform yet/);
+  assert.match(h, /href="https:\/\/hub\.test\/projects\?view=manage&amp;project=mercury#mAppCard">Connect Render</);
+  h = render({ ...member, app: null });
+  assert.match(h, /No platform yet/);
+  assert.doesNotMatch(h, /<a /, 'no action a non-owner cannot complete');
+  assert.match(h, /owner can connect Render/);
+
+  assert.match(render({ ...member, app: { platform: 'render', state: 'creating', stage: 'creating' } }), /creating.*Step 1 of 3|Step 1 of 3[\s\S]*creating/);
+  assert.match(render({ ...member, app: { platform: 'render', state: 'deploying', stage: 'building' } }), /Step 2 of 3/);
+  assert.match(render({ ...member, app: { platform: 'render', state: 'deploying', stage: 'quiet', quiet: true } }), /hasn’t answered/);
+  h = render({ ...member, app: { platform: 'render', state: 'live', stage: 'live', url: 'https://m.onrender.com' } });
+  assert.match(h, /status-pill--ok">live/);
+  assert.match(h, /href="https:\/\/m\.onrender\.com"/);
+  assert.doesNotMatch(render({ ...member, app: { platform: 'render', state: 'live', stage: 'live', url: 'https://evil.example' } }), /evil/, 'only an onrender.com address is linked');
+
+  h = render({ ...owner, app: { platform: 'render', state: 'failed', stage: null, error: 'The build command <b>failed</b>.' } });
+  assert.match(h, /status-pill--danger">failed/);
+  assert.match(h, /The build command &lt;b&gt;failed&lt;\/b&gt;\./, 'the setup\'s own words, escaped');
+  assert.match(h, />Retry on the project page</);
+  h = render({ ...member, app: { platform: 'render', state: 'failed', stage: null, error: 'The build command failed.' } });
+  assert.match(h, /owner can retry it from this project's page on hub\.test/);
+  assert.doesNotMatch(h, /<a /);
+
+  assert.match(render({ ...owner, reachable: false }), /Check again/);
+  assert.match(render({ ...owner, known: false }), /isn’t set up through hub\.test/);
+  assert.match(render({ hub: false }), /runs on its own server/);
+});
+
+// ── 7. the sandbox beside the app (task 1005289's shape, carried as is) ──────────
+
+test('sandbox: the port reads it from the same row, only for a Render app', async () => {
+  const row = {
+    status: 'active', waiting: false,
+    app_host: {
+      platform: 'render', state: 'live', serviceUrl: 'https://m.onrender.com', serviceId: 'srv-abcdefgh12',
+      sandbox: { state: 'live', serviceId: 'srv-sandbox1234', serviceUrl: 'https://m-sandbox.onrender.com' },
+    },
+  };
+  const got = await projectAppStatus(rowDb(row), { slug: 'm', host: 'm.test' });
+  assert.equal(got.sandbox.stage, 'live');
+  assert.equal(got.sandbox.url, 'https://m-sandbox.onrender.com');
+  assert.equal((await projectAppStatus(rowDb({ app_host: null, status: 'active', waiting: false }), { slug: 'm', host: 'm.test' })).sandbox, null);
+});
+
+test('sandbox: the hub and the asker pass it through; an older hub sends none', async () => {
+  const sandbox = { state: 'live', stage: 'live', url: 'https://m-sandbox.onrender.com' };
+  const hub = await serve(buildHubRoute({ db: clientDb, resolvePort: () => async () => ({ app: { platform: 'render', stage: 'live' }, sandbox }) }));
+  try {
+    const r = await hub.call('POST', '/sso/app-status', { client_id: 'mercury', client_secret: SECRET });
+    assert.deepEqual(r.body.sandbox, sandbox);
+  } finally { hub.close(); }
+  const ask = loadAsker(IDP);
+  await withFetch(async () => ({ ok: true, json: async () => ({ ok: true, known: true, app: null }) }), async () => {
+    assert.equal((await ask()).sandbox, null);
+  });
+});
+
+test('sandbox: everyone sees it, only the owner gets its links, and "none" is not drawn', () => {
+  const app = { platform: 'render', state: 'live', stage: 'live' };
+  const sandbox = { state: 'live', stage: 'live', url: 'https://m-sandbox.onrender.com', links: { service: 'https://dashboard.render.com/web/srv-sandbox1234' }, can_add: false, plan: 'free' };
+  const read = (sb) => ({ hub: true, reachable: true, known: true, app, sandbox: sb, manage: MANAGE });
+  assert.ok(viewFor(read(sandbox), { owner: true }).sandbox.links);
+  const other = viewFor(read(sandbox), { owner: false }).sandbox;
+  assert.equal(other.links, undefined);
+  assert.equal(other.can_add, undefined);
+  assert.equal(other.url, sandbox.url);
+  assert.equal(other.plan, 'free', 'other fields pass through');
+  assert.equal(viewFor(read({ state: 'none', message: 'This project has no sandbox yet.', can_add: true }), { owner: true }).sandbox, null);
+});
+
+test('sandbox: the panel draws a second row with its own stage and address', () => {
+  const { render } = loadPanel();
+  const d = { hub: true, reachable: true, known: true, hub_host: 'hub.test', owner: false, connect_url: null,
+    app: { platform: 'render', state: 'live', stage: 'live', url: 'https://m.onrender.com' } };
+  let h = render({ ...d, sandbox: { state: 'live', stage: 'live', url: 'https://m-sandbox.onrender.com' } });
+  assert.match(h, /Sandbox[\s\S]*href="https:\/\/m-sandbox\.onrender\.com"/);
+  h = render({ ...d, sandbox: { state: 'requested', stage: 'creating', message: 'Your sandbox is set up right after your app.' } });
+  assert.match(h, /Sandbox[\s\S]*set up right after your app[\s\S]*creating/);
+  h = render({ ...d, sandbox: { state: 'failed', stage: null, error: 'The free plan is full.' } });
+  assert.match(h, /Setting up the sandbox stopped\. The free plan is full\./);
+  assert.doesNotMatch(render({ ...d, sandbox: null }), /Sandbox/);
+});

package/tests/first_read.mjs

@@ -41,10 +41,16 @@ function fakePool() {
     if (/^SELECT ref, kind, entity_id FROM lifecycle_repo_map_filed/.test(q)) {
       return { rows: p[0].filter((r) => s.filed.has(r)).map((r) => ({ ref: r, ...s.filed.get(r) })) };
     }
+    if (/^INSERT INTO lifecycle_repo_map_filed .*'dismissed', NULL/.test(q)) {
+      // the owner's no: ON CONFLICT DO NOTHING
+      for (const ref of p[0]) if (!s.filed.has(ref)) s.filed.set(ref, { kind: 'dismissed', entity_id: null, map_id: p[1] });
+      return { rows: [] };
+    }
     if (/^INSERT INTO lifecycle_repo_map_filed .* unnest/.test(q)) {
       s.filedWrites = (s.filedWrites || 0) + 1;
       p[0].forEach((ref, i) => {
-        if (s.filed.has(ref)) throw Object.assign(new Error('duplicate key'), { code: '23505' });
+        // ON CONFLICT ... DO UPDATE ... WHERE kind = 'dismissed': only a dismissed row is replaced
+        if (s.filed.has(ref) && s.filed.get(ref).kind !== 'dismissed') throw Object.assign(new Error('filed twice'), { code: '23505' });
         s.filed.set(ref, { kind: p[1][i], entity_id: p[2][i], map_id: p[3] });
       });
       return { rows: [] };
@@ -74,12 +80,13 @@ test('the prompt sends the owner\'s own session to read locally, map in the defi
   for (const must of [
     'own AI session', 'Bongos itself never reads this repository', 'Do not upload, paste or send any source code',
     fr.MAP_FILE, fr.SCHEMA, '"goals"', '"next"', '"why"', '"seen_at"', 'errors or mishaps',
-    'first-read check', 'first-read submit', 'first-read accept', 'first-read reject', 'Never accept on your own',
+    'first-read check', 'first-read submit', 'first-read accept', 'first-read reject', 'first-read dismiss', 'Never accept or dismiss on your own',
     'not filed twice',
   ]) assert.ok(p.includes(must), `the prompt says: ${must}`);
   // The example it prints is itself a valid map, so a session that copies it is on the shape.
   assert.equal(fr.validateRepoMap(fr.exampleMap()).ok, true);
-  const printed = JSON.parse(p.slice(p.indexOf('{'), p.lastIndexOf('}') + 1));
+  const from = p.indexOf('Use exactly this shape:') + 'Use exactly this shape:'.length;
+  const printed = JSON.parse(p.slice(p.indexOf('{', from), p.indexOf('\n   - Optional', from)));
   assert.deepEqual(printed, fr.exampleMap());
 });
 
@@ -107,11 +114,11 @@ test('a good map validates into a flat review list with stable refs', () => {
   assert.equal(v.items[3].goal_ref, fr.NEXT_GOAL.ref, 'a next item naming no goal lands under the fix-what-was-found goal');
 });
 
-test('a later section (recommended modules) rides along without breaking the shape', () => {
-  const raw = { ...fr.exampleMap(), recommended_modules: [{ key: 'payments', why: 'a checkout exists' }] };
+test('a section this version does not read rides along without breaking the shape', () => {
+  const raw = { ...fr.exampleMap(), later_section: [{ key: 'x', why: 'room to grow' }] };
   const v = fr.validateRepoMap(raw);
   assert.equal(v.ok, true);
-  assert.deepEqual(v.map.recommended_modules, raw.recommended_modules);
+  assert.deepEqual(v.map.later_section, raw.later_section);
 });
 
 test('a prototype-shaped key in the map is never copied onto it', () => {
@@ -253,7 +260,7 @@ api.requirePermission = (...p) => { perms.push(p.join(',')); return (_req, _res,
 api.requireActAlone = (area) => { perms.push('act-alone:' + area); return (_req, _res, next) => next(); };
 
 const route = fakePool();
-for (const fn of ['submitMap', 'reviewMap', 'acceptMap', 'rejectMap']) {
+for (const fn of ['submitMap', 'reviewMap', 'acceptMap', 'rejectMap', 'dismissItems']) {
   storeModule[fn] = (a) => store[fn](a, route.deps);
 }
 const app = express();
@@ -277,7 +284,8 @@ test('the routes: filing is gated like creating a goal, and the flow runs end to
   assert.ok(perms.includes('act-alone:planning'));
   const prompt = await call('GET', '/first-read/prompt');
   assert.equal(prompt.status, 200);
-  assert.equal(prompt.body.prompt, fr.firstReadPrompt());
+  // No module list is registered in this test, so the prompt says so (task 1005281).
+  assert.equal(prompt.body.prompt, fr.firstReadPrompt({ catalog: null }));
 
   const bad = await call('POST', '/first-read/maps', { map: { schema: fr.SCHEMA, summary: 'x', goals: [{ title: 'A' }] } });
   assert.equal(bad.status, 400);
@@ -301,3 +309,171 @@ test('the routes: filing is gated like creating a goal, and the flow runs end to
   assert.equal((await call('GET', '/first-read/maps/999')).status, 404);
   assert.equal((await call('POST', `/first-read/maps/${ok.body.map_id}/reject`)).status, 409, 'an accepted map is not then rejected');
 });
+
+// ── recommended modules (task 1005281) ───────────────────────────────────────
+//
+// The owner's own session compares what the code does with this project's live module
+// list and may recommend from it. Only keys on that list are accepted; a recommendation
+// is a suggestion the owner accepts (a draft task to switch it on) or dismisses.
+
+const fc = require('../modules/lifecycle/first-read-catalog.js');
+
+const LISTED = [
+  { key: 'lifecycle', title: 'Lifecycle', description: 'Tasks and claims.', enabled: true },
+  { key: 'billing', title: 'Billing (internal name)', description: 'Takes card payments through the processor and keeps the ledger. Engineers: see ADR.', enabled: false },
+  { key: 'raise', title: 'Raise', description: 'A fundraising page.', enabled: false },
+];
+const PICKER = { optional: [{ key: 'billing', label: 'Billing', summary: 'Take payments and send receipts.' }] };
+const CATALOG = fc.buildCatalog(LISTED, PICKER);
+
+// A repository whose billing code keeps failing: a known weak area.
+function weakBillingMap() {
+  return {
+    schema: fr.SCHEMA,
+    summary: 'A shop whose own card-payment code keeps failing.',
+    next: [{ title: 'Payments fail at checkout', kind: 'error', why: 'Half the test charges fail with a timeout.', seen_at: ['src/billing/charge.js:30'] }],
+    recommended_modules: [{
+      module: 'billing', title: 'Session-chosen words, ignored',
+      found: 'The hand-written billing code retries forever and loses receipts.',
+      why: 'The Billing module takes payments and sends receipts, so this code can go.',
+      seen_at: ['src/billing/'],
+    }],
+  };
+}
+
+test('the catalog is this project\'s modules not yet on, in the picker\'s words where it has them', () => {
+  assert.deepEqual(CATALOG.map((m) => m.key), ['billing', 'raise'], 'an enabled module is not offered');
+  assert.equal(CATALOG[0].title, 'Billing');
+  assert.equal(CATALOG[0].summary, 'Take payments and send receipts.');
+  assert.equal(CATALOG[1].summary, 'A fundraising page.', 'otherwise the module\'s own first sentence');
+  assert.equal(fc.buildCatalog(null, null).length, 0);
+});
+
+test('the catalog is read live from the kernel port, and is null when no list can be read', async () => {
+  const seams = require('../src/module-seams.js');
+  assert.equal(await fc.switchOnCatalog(), null, 'no port, no list: nothing may be recommended');
+  // Left registered: the route test below reads the same list.
+  seams.registerProvider('modules.catalog', () => LISTED);
+  assert.deepEqual((await fc.switchOnCatalog()).map((m) => m.key), ['billing', 'raise']);
+});
+
+test('the prompt carries the live list; the Genesis copy tells the session how to get it', () => {
+  const p = fr.firstReadPrompt({ catalog: CATALOG });
+  assert.ok(p.includes('- billing: Billing. Take payments and send receipts.'));
+  assert.ok(p.includes('"recommended_modules"') && p.includes('Recommend only from the list'));
+  assert.ok(p.includes('no recommendation is a good answer'));
+  assert.ok(fr.firstReadPrompt().includes('first-read catalog'), 'the fixed Genesis text names the live list');
+  assert.ok(fr.firstReadPrompt({ catalog: null }).includes('could not be read'));
+});
+
+test('a repository with a known weak area gets the matching module, with its reason', async () => {
+  const v = fr.validateRepoMap(weakBillingMap(), { catalog: CATALOG });
+  assert.equal(v.ok, true, JSON.stringify(v.errors));
+  const mod = v.items.find((i) => i.type === 'module');
+  assert.equal(mod.ref, 'module:billing');
+  assert.equal(mod.title, 'Billing', 'the catalog\'s words, never the session\'s');
+  assert.match(mod.found, /retries forever/);
+  assert.match(mod.why, /takes payments/);
+  assert.deepEqual(v.map.recommended_modules[0].title, 'Billing');
+
+  const { deps, s } = fakePool();
+  const { map_id } = await store.submitMap({ raw: weakBillingMap(), catalog: CATALOG }, deps);
+  const out = await store.acceptMap({ mapId: map_id, select: 'all' }, deps);
+  assert.equal(out.ok, true);
+  assert.ok(s.goals.some((g) => g.title === fr.MODULES_GOAL.title));
+  const task = s.tasks.find((t) => t.sourceRef === 'module:billing');
+  assert.equal(task.title, 'Switch on the Billing module');
+  assert.equal(task.status, 'backlog', 'a draft: nothing is switched on, nothing is claimable');
+  assert.match(task.description, /Found: The hand-written billing code/);
+  assert.match(task.description, /Why the Billing module/);
+  assert.match(task.description, /Seen at: src\/billing\//);
+});
+
+test('a repository with nothing to replace gets no recommendation', async () => {
+  const raw = { ...fr.exampleMap() };
+  const v = fr.validateRepoMap(raw, { catalog: CATALOG });
+  assert.equal(v.ok, true);
+  assert.equal(v.items.filter((i) => i.type === 'module').length, 0);
+  assert.equal(v.map.recommended_modules, undefined);
+  const { deps, s } = fakePool();
+  const { map_id } = await store.submitMap({ raw, catalog: CATALOG }, deps);
+  await store.acceptMap({ mapId: map_id, select: 'all' }, deps);
+  assert.ok(!s.goals.some((g) => g.title === fr.MODULES_GOAL.title), 'no modules goal is filed for an empty section');
+  assert.ok(!s.tasks.some((t) => /^Switch on the/.test(t.title)));
+});
+
+test('an unknown module, a repeated one, or any module when no list can be read, is refused', async () => {
+  const unknown = weakBillingMap();
+  unknown.recommended_modules[0].module = 'stripe-magic';
+  let v = fr.validateRepoMap(unknown, { catalog: CATALOG });
+  assert.equal(v.ok, false);
+  assert.ok(v.errors.some((e) => /"stripe-magic" is not a module this project can switch on/.test(e)));
+
+  const on = weakBillingMap();
+  on.recommended_modules[0].module = 'lifecycle';
+  assert.equal(fr.validateRepoMap(on, { catalog: CATALOG }).ok, false, 'a module already on is not on the list');
+
+  const twice = weakBillingMap();
+  twice.recommended_modules.push({ ...twice.recommended_modules[0] });
+  assert.ok(fr.validateRepoMap(twice, { catalog: CATALOG }).errors.some((e) => /repeats a module/.test(e)));
+
+  v = fr.validateRepoMap(weakBillingMap(), { catalog: null });
+  assert.ok(v.errors.some((e) => /could not be read here/.test(e)));
+
+  const missing = weakBillingMap();
+  delete missing.recommended_modules[0].found;
+  assert.ok(fr.validateRepoMap(missing, { catalog: CATALOG }).errors.some((e) => /recommended_modules\[0\]\.found is missing/.test(e)));
+
+  const { deps, s } = fakePool();
+  const out = await store.submitMap({ raw: unknown, catalog: CATALOG }, deps);
+  assert.equal(out.ok, false);
+  assert.equal(s.maps.length, 0, 'a refused map is not stored');
+});
+
+test('dismissing a recommendation files nothing, and a re-run does not raise it again unless named', async () => {
+  const { deps, s } = fakePool();
+  const first = await store.submitMap({ raw: weakBillingMap(), catalog: CATALOG }, deps);
+  const d = await store.dismissItems({ mapId: first.map_id, refs: ['module:billing'] }, deps);
+  assert.equal(d.ok, true);
+  assert.deepEqual(d.dismissed, ['module:billing']);
+  assert.equal(s.tasks.length, 0, 'a no files nothing');
+  assert.equal((await store.dismissItems({ mapId: first.map_id, refs: ['module:nope'] }, deps)).code, 'unknown_items');
+
+  const second = await store.submitMap({ raw: weakBillingMap(), catalog: CATALOG }, deps);
+  const review = await store.reviewMap(second.map_id, deps);
+  assert.equal(review.items.find((i) => i.ref === 'module:billing').filed.kind, 'dismissed');
+  const all = await store.acceptMap({ mapId: second.map_id, select: 'all' }, deps);
+  assert.ok(all.skipped.some((x) => x.ref === 'module:billing' && x.reason === 'dismissed'));
+  assert.ok(!s.tasks.some((t) => t.sourceRef === 'module:billing'));
+
+  const named = await store.acceptMap({ mapId: second.map_id, select: ['module:billing'] }, deps);
+  assert.equal(named.filed.tasks.length, 1, 'naming a dismissed item files it: the owner changed their mind');
+  assert.equal(s.filed.get('module:billing').kind, 'task');
+  const again = await store.dismissItems({ mapId: second.map_id, refs: ['module:billing'] }, deps);
+  assert.ok(again.skipped.some((x) => x.reason === 'already_filed'), 'a filed item is not un-filed by a dismiss');
+});
+
+test('the routes: the catalog route, a submit checked against the live list, and dismiss', async () => {
+  const seams = require('../src/module-seams.js');
+  if (!seams.hasProvider('modules.catalog')) seams.registerProvider('modules.catalog', () => LISTED);
+  const cat = await call('GET', '/first-read/catalog');
+  assert.equal(cat.status, 200);
+  assert.equal(cat.body.available, true);
+  assert.deepEqual(cat.body.modules.map((m) => m.key), ['billing', 'raise']);
+  const prompt = await call('GET', '/first-read/prompt');
+  assert.ok(prompt.body.prompt.includes('- billing: Billing (internal name). Takes card payments through the processor and keeps the ledger.'));
+
+  const bad = weakBillingMap();
+  bad.recommended_modules[0].module = 'stripe-magic';
+  const refused = await call('POST', '/first-read/maps', { map: bad });
+  assert.equal(refused.status, 400);
+  assert.ok(refused.body.errors.some((e) => /stripe-magic/.test(e)));
+
+  const ok = await call('POST', '/first-read/maps', { map: weakBillingMap() });
+  assert.equal(ok.status, 201);
+  assert.ok(ok.body.items.some((i) => i.ref === 'module:billing' && i.type === 'module'));
+  const dismissed = await call('POST', `/first-read/maps/${ok.body.map_id}/dismiss`, { items: ['module:billing'] });
+  assert.equal(dismissed.status, 200);
+  assert.equal((await call('POST', `/first-read/maps/${ok.body.map_id}/dismiss`, { items: 'all' })).status, 400);
+  assert.ok(perms.filter((x) => x === 'goal.create').length >= 4, 'dismiss is gated like the rest of the review');
+});