@bongos/core 1.25.12 → 1.25.13

package/tests/front_door_guide_plan.mjs

@@ -0,0 +1,344 @@
+// tests/front_door_guide_plan.mjs — where the start-a-project chat ends (task 1005273): a
+// plan from structured output that names only modules in the live catalog, saved and
+// readable again after a browser restart, attached to the account at sign-up, and swept
+// away when nobody signs up.
+//
+// The REAL routers over an in-memory db and a mocked Claude client (no key, no network, no
+// spend), with the catalog served by the REAL provisioning port, so "only modules in the
+// catalog" is checked against the list the project-creation picker actually offers.
+// The SQL itself (the migration, the sweep, the attach rule) is in
+// tests/front_door_guide_db.mjs, against a real Postgres.
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+
+const require = createRequire(import.meta.url);
+const api = require('../src/module-api.js');
+const db = require('../modules/front-door-guide/db.js');
+const claude = require('../modules/front-door-guide/claude.js');
+const G = require('../modules/front-door-guide/guide.js');
+const P = require('../modules/front-door-guide/plan.js');
+const sweep = require('../modules/front-door-guide/pollers/retention-sweep.js');
+const { optionalModules } = require('../modules/provisioning/starter-bundles.js');
+
+const ENV = 'BONGOS_FRONT_DOOR_GUIDE_';
+
+// ---- the live catalog: the provisioning module's own port --------------------------------
+
+require('../modules/provisioning/seams.js').registerProvisioningSeams();
+const CATALOG_KEYS = optionalModules().map((m) => m.key);
+
+// ---- an in-memory db with the SQL's rules ------------------------------------------------
+
+const convs = new Map();
+let calls = [];
+let seq = 0;
+const copy = (c) => c && JSON.parse(JSON.stringify(c));
+const nowIso = () => new Date().toISOString();
+Object.assign(db, {
+  createConversation: async (tokenHash, visitorHash) => {
+    const c = { id: String(++seq), token_hash: tokenHash, visitor_hash: visitorHash, messages: [], visitor_messages: 0, spend_micro: 0, status: 'open', end_reason: null, created_at: new Date(Date.now() - 10_000).toISOString(), updated_at: nowIso(), plan: null, planned_at: null, builder_id: null, attached_at: null };
+    convs.set(c.id, c);
+    return copy(c);
+  },
+  getConversation: async (id, tokenHash) => { const c = convs.get(String(id)); return c && c.token_hash === tokenHash ? copy(c) : null; },
+  siteSpendMicro: async () => calls.reduce((s, r) => s + r.cost_micro, 0),
+  visitorUsage: async (v) => {
+    const mine = calls.filter((r) => r.visitor_hash === v);
+    return { messages: mine.filter((r) => r.kind === 'reply').length, spendMicro: mine.reduce((s, r) => s + r.cost_micro, 0) };
+  },
+  recordTurn: async (id, { messages, status, endReason }, call) => {
+    calls.push({ conversation_id: String(id), visitor_hash: call.visitorHash, cost_micro: call.costMicro, kind: 'reply' });
+    const c = convs.get(String(id));
+    Object.assign(c, { messages, status, end_reason: endReason, visitor_messages: c.visitor_messages + 1, updated_at: nowIso() });
+    return copy(c);
+  },
+  endConversation: async (id, reason) => Object.assign(convs.get(String(id)), { status: 'ended', end_reason: reason }),
+  savePlan: async (id, plan, call) => {
+    calls.push({ conversation_id: String(id), visitor_hash: call.visitorHash, cost_micro: call.costMicro, kind: 'plan' });
+    const c = convs.get(String(id));
+    Object.assign(c, { plan: c.plan || plan, planned_at: c.planned_at || nowIso(), status: 'ended', end_reason: 'planned', updated_at: nowIso() });
+    return copy(c);
+  },
+  recordPlanSpend: async (id, call) => { calls.push({ conversation_id: String(id), visitor_hash: call.visitorHash, cost_micro: call.costMicro, kind: 'plan' }); },
+  attachToBuilder: async (id, tokenHash, builderId) => {
+    const c = convs.get(String(id));
+    if (!c || c.token_hash !== tokenHash || (c.builder_id != null && c.builder_id !== builderId)) return null;
+    Object.assign(c, { builder_id: builderId, attached_at: c.attached_at || nowIso() });
+    return copy(c);
+  },
+  latestForBuilder: async (builderId) => copy([...convs.values()].filter((c) => c.builder_id === builderId).pop() || null),
+});
+
+// ---- the mocked Claude client --------------------------------------------------------
+
+let requests = [];
+let planReply = null;
+const chatReply = () => ({ model: 'claude-opus-5-5', stop_reason: 'end_turn', content: [{ type: 'text', text: 'Who is it for?' }], usage: { input_tokens: 700, output_tokens: 150 } });
+const goodPlan = (modules) => JSON.stringify({
+  summary: 'A booking site for a small yoga studio.',
+  project_type: 'business',
+  how_it_works: ['You describe what you want.', 'AI builders do small tasks.'],
+  modules,
+  steps: [{ title: 'Sign up', detail: 'Create your account.' }, { title: 'Create the project', detail: 'Name it.' }],
+  needs: [{ item: 'A payments account', detail: 'To take bookings.' }],
+  open_questions: ['Do classes repeat weekly?'],
+});
+claude.createClient = () => ({ messages: { create: async (req) => {
+  requests.push(req);
+  if (req.output_config && req.output_config.format) {
+    return planReply ? planReply(req) : { model: 'claude-opus-5-5', stop_reason: 'end_turn', content: [{ type: 'text', text: goodPlan([{ key: CATALOG_KEYS[0], why: 'It fits.' }]) }], usage: { input_tokens: 2000, output_tokens: 600 } };
+  }
+  return chatReply();
+} } });
+
+// ---- a stand-in sign-in: x-test-builder is the signed-in account --------------------------
+
+api.requireBuilder = (req, res, next) => {
+  const id = req.get('x-test-builder');
+  if (!id) return res.status(401).json({ error: 'unauthenticated' });
+  req.builder = { id: Number(id) };
+  return next();
+};
+
+const express = require('express');
+const app = express();
+app.set('trust proxy', true);
+app.use(express.json({ limit: '64kb' }));
+app.use('/api/bongos', require('../modules/front-door-guide/routes/front-door-guide.js')());
+app.use('/api/bongos', require('../modules/front-door-guide/routes/front-door-guide-plan.js')());
+const server = app.listen(0);
+await new Promise((r) => server.once('listening', r));
+const PORT = server.address().port;
+test.after(() => server.close());
+
+let ipSeq = 0;
+function call(method, path, { body, ip, headers = {} } = {}) {
+  return new Promise((resolve, reject) => {
+    const data = body === undefined ? null : JSON.stringify(body);
+    const h = { 'content-type': 'application/json', 'user-agent': 'Mozilla/5.0 (test browser)', 'x-forwarded-for': ip || `10.9.0.${++ipSeq}`, ...headers };
+    const req = http.request({ host: '127.0.0.1', port: PORT, method, path: `/api/bongos${path}`, headers: h }, (res) => {
+      let buf = '';
+      res.on('data', (c) => { buf += c; });
+      res.on('end', () => resolve({ status: res.statusCode, body: buf ? JSON.parse(buf) : null }));
+    });
+    req.on('error', reject);
+    if (data) req.write(data);
+    req.end();
+  });
+}
+
+function reset(over = {}) {
+  for (const k of Object.keys(process.env)) if (k.startsWith(ENV)) delete process.env[k];
+  const all = { ANTHROPIC_API_KEY: 'sk-ant-TEST-ONLY-0123456789abcdef', MIN_FIRST_MESSAGE_MS: '1', STARTS_PER_HOUR: '1000', MESSAGES_PER_MINUTE: '1000', ...over };
+  for (const [k, v] of Object.entries(all)) if (v !== null) process.env[ENV + k] = String(v);
+  convs.clear(); calls = []; requests = []; planReply = null;
+}
+
+async function chatWithOneMessage(ip) {
+  const st = await call('POST', '/front-door-guide/conversations', { body: {}, ip });
+  const conv = st.body.conversation;
+  await call('POST', `/front-door-guide/conversations/${conv.id}/messages`, { body: { token: conv.token, text: 'A booking site for my yoga studio.' }, ip });
+  return { conv, start: st.body };
+}
+const askPlan = (conv, ip) => call('POST', `/front-door-guide/conversations/${conv.id}/plan`, { body: { token: conv.token }, ip });
+
+// ---- the plan -----------------------------------------------------------------------------
+
+test('the catalog the plan reads is the provisioning picker\'s own list', async () => {
+  const port = api.resolveOptional('provisioning.moduleCatalog');
+  assert.equal(typeof port, 'function');
+  const c = await port();
+  assert.deepEqual(c.optional.map((m) => m.key), CATALOG_KEYS);
+  assert.ok(CATALOG_KEYS.length > 0);
+  for (const m of c.optional) assert.ok(m.label && m.summary, `${m.key} carries owner-facing words`);
+});
+
+test('the plan is structured output and names only catalog modules, in the catalog\'s words', async () => {
+  reset();
+  const ip = '10.8.0.1';
+  const { conv } = await chatWithOneMessage(ip);
+  planReply = () => ({
+    model: 'claude-opus-5-5', stop_reason: 'end_turn', usage: { input_tokens: 2000, output_tokens: 600 },
+    content: [{ type: 'text', text: goodPlan([
+      { key: CATALOG_KEYS[0], why: 'Fits.' },
+      { key: 'made-up-module', why: 'Invented.' },
+      { key: 'lifecycle', why: 'Core, not optional.' },
+      { key: CATALOG_KEYS[0], why: 'Twice.' },
+    ]) }],
+  });
+  const r = await askPlan(conv, ip);
+  assert.equal(r.status, 200);
+  assert.equal(r.body.mode, 'plan');
+  assert.deepEqual(r.body.next, { action: 'sign_up', label: 'Sign up and get started' });
+  const real = optionalModules().find((m) => m.key === CATALOG_KEYS[0]);
+  assert.deepEqual(r.body.plan.modules, [{ key: real.key, label: real.label, summary: real.summary, why: 'Fits.' }]);
+  assert.equal(r.body.plan.project_type, 'business');
+  assert.equal(r.body.plan.cost_and_time, P.COST_AND_TIME, 'cost and time are named, never estimated');
+  assert.ok(r.body.plan.steps.length && r.body.plan.needs.length);
+
+  // The request asked for JSON against a schema whose module keys ARE the catalog.
+  const req = requests.find((q) => q.output_config && q.output_config.format);
+  assert.equal(req.output_config.format.type, 'json_schema');
+  assert.deepEqual(req.output_config.format.schema.properties.modules.items.properties.key.enum, CATALOG_KEYS);
+  assert.equal(req.max_tokens, 4000);
+  for (const k of CATALOG_KEYS) assert.ok(req.system.includes(`- ${k}:`), `the instructions list ${k}`);
+  assert.equal(calls.filter((c) => c.kind === 'plan').length, 1, 'the plan call is recorded as spend');
+});
+
+test('a plan is written once: asking again re-reads it, and the chat now ends with sign-up', async () => {
+  reset();
+  const ip = '10.8.0.2';
+  const { conv } = await chatWithOneMessage(ip);
+  const first = await askPlan(conv, ip);
+  const again = await askPlan(conv, ip);
+  assert.deepEqual(again.body.plan, first.body.plan);
+  assert.equal(requests.filter((q) => q.output_config.format).length, 1);
+  const more = await call('POST', `/front-door-guide/conversations/${conv.id}/messages`, { body: { token: conv.token, text: 'one more thing' }, ip });
+  assert.equal(more.body.mode, 'ended');
+  assert.equal(more.body.reason, 'planned');
+  assert.equal(more.body.next_step, 'sign_up');
+});
+
+test('no plan before the visitor has said anything; a plan does not use up a message', async () => {
+  reset({ MAX_MESSAGES: 2 });
+  const ip = '10.8.0.3';
+  const st = await call('POST', '/front-door-guide/conversations', { body: {}, ip });
+  assert.equal((await askPlan(st.body.conversation, ip)).status, 409);
+  const { conv } = await chatWithOneMessage(ip);
+  await askPlan(conv, ip);
+  const used = await db.visitorUsage(convs.get(conv.id).visitor_hash);
+  assert.equal(used.messages, 1, 'only the reply counts as a message');
+});
+
+test('a plan that cannot be used (refused, cut off, not JSON) costs what it cost and offers the form', async () => {
+  for (const reply of [
+    { stop_reason: 'refusal', content: [] },
+    { stop_reason: 'max_tokens', content: [{ type: 'text', text: '{"summary": "half' }] },
+    { stop_reason: 'end_turn', content: [{ type: 'text', text: 'not json' }] },
+  ]) {
+    reset();
+    const ip = `10.8.1.${calls.length + Math.floor(Math.random() * 200)}`;
+    const { conv } = await chatWithOneMessage(ip);
+    planReply = () => ({ model: 'claude-opus-5-5', usage: { input_tokens: 2000, output_tokens: 50 }, ...reply });
+    const r = await askPlan(conv, ip);
+    assert.deepEqual(r.body, G.formAnswer('unavailable'));
+    assert.equal(convs.get(conv.id).plan, null);
+    assert.equal(calls.filter((c) => c.kind === 'plan').length, 1, `${reply.stop_reason}: the spend is recorded`);
+  }
+});
+
+test('the plan is held to the site budget like a reply', async () => {
+  reset({ DAILY_BUDGET_CENTS: 1 });
+  const ip = '10.8.0.4';
+  const st = await call('POST', '/front-door-guide/conversations', { body: {}, ip });
+  convs.get(st.body.conversation.id).visitor_messages = 1; // as if they had talked
+  const r = await askPlan(st.body.conversation, ip);
+  assert.deepEqual(r.body, G.formAnswer('daily_budget'));
+  assert.equal(requests.length, 0);
+});
+
+// ---- saved, resumed, attached --------------------------------------------------------------
+
+test('the visitor is told the chat is saved, and after a browser restart it all comes back', async () => {
+  reset({ RETENTION_DAYS: 21 });
+  const ip = '10.8.0.5';
+  const { conv, start } = await chatWithOneMessage(ip);
+  assert.deepEqual(start.saved, G.savedNotice(21));
+  assert.match(start.saved.message, /saved/);
+  assert.match(start.saved.message, /21 days/);
+  await askPlan(conv, ip);
+
+  // A new browser session: nothing but the id and token the page kept, from a new address.
+  const back = await call('GET', `/front-door-guide/conversations/${conv.id}`, { ip: '10.8.200.1', headers: { 'x-guide-token': conv.token } });
+  assert.equal(back.status, 200);
+  assert.equal(back.body.transcript.length, 2);
+  assert.equal(back.body.plan.summary, 'A booking site for a small yoga studio.');
+  assert.deepEqual(back.body.next, P.NEXT_STEP);
+  assert.equal(back.body.attached, false);
+  assert.equal(back.body.saved.keep_days, 21);
+});
+
+test('at sign-up the chat and plan move onto the new account, and only that account', async () => {
+  reset();
+  const ip = '10.8.0.6';
+  const { conv } = await chatWithOneMessage(ip);
+  await askPlan(conv, ip);
+  const attach = (builder, token = conv.token) => call('POST', `/front-door-guide/conversations/${conv.id}/attach`,
+    { body: { token }, headers: builder ? { 'x-test-builder': String(builder) } : {} });
+
+  assert.equal((await attach(null)).status, 401, 'attaching needs a signed-in account');
+  assert.equal((await attach(77, 'Z'.repeat(32))).status, 404, 'and the chat\'s token');
+  const ok = await attach(77);
+  assert.equal(ok.status, 200);
+  assert.equal(ok.body.conversation.plan.summary, 'A booking site for a small yoga studio.');
+  assert.ok(!('visitor_hash' in ok.body.conversation));
+  assert.equal((await attach(77)).status, 200, 'attaching again is harmless');
+  assert.equal((await attach(88)).status, 404, 'another account cannot take it');
+
+  const mine = await call('GET', '/front-door-guide/mine', { headers: { 'x-test-builder': '77' } });
+  assert.equal(mine.body.conversation.id, conv.id);
+  assert.deepEqual(mine.body.conversation.next, P.NEXT_STEP);
+  assert.equal(mine.body.conversation.transcript[0].role, 'visitor');
+  const theirs = await call('GET', '/front-door-guide/mine', { headers: { 'x-test-builder': '88' } });
+  assert.equal(theirs.body.conversation, null);
+  assert.equal((await call('GET', '/front-door-guide/mine')).status, 401);
+});
+
+// ---- the retention sweep ---------------------------------------------------------------
+
+test('the retention sweep deletes after the owner\'s number of days, and only unclaimed chats', async () => {
+  reset({ RETENTION_DAYS: 14 });
+  const DAY = 86_400_000;
+  const rows = [
+    { id: 'old', builder_id: null, updated_at: Date.now() - 15 * DAY },
+    { id: 'recent', builder_id: null, updated_at: Date.now() - 13 * DAY },
+    { id: 'attached', builder_id: 5, updated_at: Date.now() - 400 * DAY },
+  ];
+  const spend = [{ conversation_id: 'old', cost_micro: 9000 }];
+  let askedDays = null;
+  // The same rule as db.deleteAbandoned's SQL, over the rows above.
+  const deleteAbandoned = async (days) => {
+    askedDays = days;
+    const gone = rows.filter((r) => r.builder_id == null && r.updated_at < Date.now() - days * DAY);
+    for (const g of gone) {
+      rows.splice(rows.indexOf(g), 1);
+      for (const s of spend) if (s.conversation_id === g.id) s.conversation_id = null;
+    }
+    return gone.length;
+  };
+  const r = await sweep.tick({ deleteAbandoned });
+  assert.deepEqual(r, { deleted: 1 });
+  assert.equal(askedDays, 14, 'the sweep reads the retention setting');
+  assert.deepEqual(rows.map((x) => x.id), ['recent', 'attached']);
+  assert.deepEqual(spend, [{ conversation_id: null, cost_micro: 9000 }], 'the money stays on the books');
+  assert.equal(sweep.TICK_MS, 3_600_000);
+
+  const failed = await sweep.tick({ deleteAbandoned: async () => { throw new Error('connection lost'); } });
+  assert.equal(failed.skipped, 'error');
+
+  // db.deleteAbandoned sends the setting as the day count and spares claimed chats.
+  let sent = null;
+  await db.deleteAbandoned.call(null, 14, async (sql, params) => { sent = { sql, params }; return { rowCount: 0 }; });
+  assert.deepEqual(sent.params, [14]);
+  assert.match(sent.sql, /builder_id IS NULL/);
+});
+
+test('plan sanitising: strings trimmed and capped, lists capped, an unknown type is not-sure', () => {
+  const catalog = { optional: [{ key: 'discord', label: 'Discord', summary: 'Chat.' }] };
+  const plan = P.sanitizePlan({
+    summary: `  ${'x'.repeat(2000)}  `, project_type: 'casino',
+    how_it_works: Array(20).fill('point'), modules: [{ key: 'discord', why: 'yes' }],
+    steps: Array(30).fill({ title: 't', detail: 'd' }), needs: [{ item: '', detail: 'dropped' }], open_questions: [],
+  }, catalog);
+  assert.equal(plan.summary.length, 600);
+  assert.equal(plan.project_type, 'not-sure');
+  assert.equal(plan.how_it_works.length, 6);
+  assert.equal(plan.steps.length, 10);
+  assert.deepEqual(plan.needs, []);
+  assert.equal(P.sanitizePlan({ summary: '' }, catalog), null);
+  const noCatalog = P.planSchema([]);
+  assert.equal(noCatalog.properties.modules.items.properties.key.enum, undefined);
+});