@bongos/core 1.25.12 → 1.25.13

package/modules/front-door-guide/routes/front-door-guide.js

@@ -7,6 +7,9 @@
 //   POST /front-door-guide/conversations/:id/messages send one message   { token, text, website? }
 //   GET  /front-door-guide/conversations/:id          read it back       header x-guide-token
 //
+// The plan, attaching a chat to an account at sign-up, and "my plan" are in
+// routes/front-door-guide-plan.js (task 1005273).
+//
 // rank: public — every route. The visitor has no account yet; that is the point. What
 // stands in for one: per-visitor rate limits, a bot check, a token per conversation, and
 // every money cap enforced here before a call is made (the per-visitor message count and
@@ -25,37 +28,16 @@ const db = require('../db');
 const claude = require('../claude');
 const { readSettings } = require('../settings');
 const L = require('../limits');
+const C = require('../context');
+const P = require('../plan');
 
 const log = api.logger('front-door-guide');
 const ID_RE = /^\d{1,18}$/;
 const TOKEN_RE = /^[A-Za-z0-9_-]{16,64}$/;
 
-function salt() {
-  let s;
-  try { s = api.resolveEnv('FRONT_DOOR_GUIDE_SALT'); } catch (_) { s = null; }
-  if (s) return s;
-  let name = 'bongos';
-  try { name = api.instanceDbName() || name; } catch (_) { /* the default salt still separates visitors */ }
-  return `front-door-guide:${name}`;
-}
-
-function productName() {
-  try { return api.branding().identity.productName || 'Cloud Bongos'; } catch (_) { return 'Cloud Bongos'; }
-}
-
-// Can the site afford a call of `extraMicro` right now? → null, or the form reason.
-async function siteBudgetReason(settings, extraMicro, reservations) {
-  const pending = reservations.siteMicro();
-  // Spent is spent (>=), and a call must also fit in what is left (>).
-  const over = (spent, cap) => spent + pending >= cap || spent + pending + extraMicro > cap;
-  if (over(await db.siteSpendMicro('day'), settings.dailyBudgetMicro)) return 'daily_budget';
-  if (over(await db.siteSpendMicro('month'), settings.monthlyBudgetMicro)) return 'monthly_budget';
-  return null;
-}
-
 module.exports = function buildFrontDoorGuideRouter() {
   const router = express.Router();
-  const reservations = L.makeReservations();
+  const { reservations, siteBudgetReason, salt, productName } = C;
   let current = readSettings();
   const knobs = () => current;
 
@@ -68,7 +50,7 @@ module.exports = function buildFrontDoorGuideRouter() {
   // rank: public — the landing asks before it offers the chat.
   router.get('/front-door-guide/status', fresh, statusLimit, api.asyncHandler('GET /front-door-guide/status', async (req, res) => {
     const s = knobs();
-    const reason = !s.apiKey ? 'no_key' : await siteBudgetReason(s, 0, reservations);
+    const reason = !s.apiKey ? 'no_key' : await siteBudgetReason(s, 0);
     res.json({
       ok: true,
       mode: reason ? 'form' : 'chat',
@@ -86,7 +68,7 @@ module.exports = function buildFrontDoorGuideRouter() {
       return res.json(G.formAnswer('check_failed'));
     }
     if (!s.apiKey) return res.json(G.formAnswer('no_key'));
-    const budget = await siteBudgetReason(s, 0, reservations);
+    const budget = await siteBudgetReason(s, 0);
     if (budget) return res.json(G.formAnswer(budget));
     const visitor = L.visitorHash(L.clientIp(req), salt());
     const used = await db.visitorUsage(visitor);
@@ -97,6 +79,7 @@ module.exports = function buildFrontDoorGuideRouter() {
       ok: true, mode: 'chat',
       conversation: { ...G.conversationView(conv, s), token },
       greeting: G.GREETING,
+      saved: G.savedNotice(s.retentionDays),
     });
   }));
 
@@ -122,7 +105,10 @@ module.exports = function buildFrontDoorGuideRouter() {
     const conv = await db.getConversation(req.params.id, L.tokenHash(body.token));
     if (!conv) return res.status(404).json({ ok: false, error: 'not_found' });
     const view = () => G.conversationView(conv, s);
-    const ended = (reason) => ({ ok: true, mode: 'ended', reason, message: G.END_REASONS[reason] || G.END_REASONS.message_cap, conversation: view() });
+    const ended = (reason) => ({
+      ok: true, mode: 'ended', reason, message: G.END_REASONS[reason] || G.END_REASONS.message_cap,
+      next_step: reason === 'planned' ? 'sign_up' : 'plan', conversation: view(),
+    });
     if (conv.status === 'ended') return res.json(ended(conv.end_reason));
 
     const bot = G.botCheck({
@@ -148,7 +134,7 @@ module.exports = function buildFrontDoorGuideRouter() {
       await db.endConversation(conv.id, 'visitor_budget');
       return res.json(ended('visitor_budget'));
     }
-    const budget = await siteBudgetReason(s, estimate, reservations);
+    const budget = await siteBudgetReason(s, estimate);
     if (budget) return res.json(G.formAnswer(budget));
 
     const release = reservations.take(visitor, estimate);
@@ -182,7 +168,7 @@ module.exports = function buildFrontDoorGuideRouter() {
     res.json({
       ok: true,
       mode: endReason ? 'ended' : 'chat',
-      ...(endReason ? { reason: endReason, message: G.END_REASONS[endReason] } : {}),
+      ...(endReason ? { reason: endReason, message: G.END_REASONS[endReason], next_step: 'plan' } : {}),
       ...(refused ? { declined: true } : {}),
       reply: { text: reply },
       conversation: G.conversationView(saved || { ...conv, visitor_messages: Number(conv.visitor_messages) + 1 }, s),
@@ -199,6 +185,10 @@ module.exports = function buildFrontDoorGuideRouter() {
       ok: true,
       conversation: { ...G.conversationView(conv, knobs()), status: conv.status, end_reason: conv.end_reason || null },
       transcript: G.transcriptView(conv.messages),
+      plan: conv.plan || null,
+      ...(conv.plan ? { next: P.NEXT_STEP } : {}),
+      saved: G.savedNotice(knobs().retentionDays),
+      attached: conv.builder_id != null,
     });
   }));
 

package/modules/front-door-guide/settings.js

@@ -25,6 +25,8 @@ const DEFAULTS = Object.freeze({
   STARTS_PER_HOUR: 5,            // new conversations per visitor per hour
   MESSAGES_PER_MINUTE: 6,        // messages per visitor per minute
   MIN_FIRST_MESSAGE_MS: 1500,    // a person takes longer than this to type a first line
+  MAX_PLAN_TOKENS: 4000,         // the plan, thinking included
+  RETENTION_DAYS: 30,            // a chat nobody signed up for is deleted after this
 });
 
 const EFFORTS = new Set(['low', 'medium', 'high', 'xhigh', 'max']);
@@ -62,6 +64,8 @@ function readSettings({ resolve = defaultResolve } = {}) {
     startsPerHour: intKnob(read, 'STARTS_PER_HOUR'),
     messagesPerMinute: intKnob(read, 'MESSAGES_PER_MINUTE'),
     minFirstMessageMs: intKnob(read, 'MIN_FIRST_MESSAGE_MS'),
+    maxPlanTokens: intKnob(read, 'MAX_PLAN_TOKENS'),
+    retentionDays: intKnob(read, 'RETENTION_DAYS'),
   };
 }
 

package/modules/provisioning/module.json

@@ -39,7 +39,8 @@
     "provisioning.projectPlanets",
     "provisioning.projectOwnedBy",
     "provisioning.projectPublishIdentity",
-    "provisioning.selfUpdateChannel"
+    "provisioning.selfUpdateChannel",
+    "provisioning.moduleCatalog"
   ],
   "consumes": []
 }

package/modules/provisioning/seams.js

@@ -7,6 +7,7 @@ const api = require('../../src/module-api');
 const { pool } = api;
 const provisioning = require('./provisioning');
 const { selfUpdateChannel } = require('./core-upgrade');
+const { ALWAYS_ON_CORE, optionalModules } = require('./starter-bundles');
 
 // The `provisioning.projectPublishIdentity` port (task 1003578, ADR 0247 D4): the name and
 // description the publish gate judges, for the control-plane project a hub catalog row was
@@ -44,6 +45,11 @@ async function projectPublishIdentity(db, { slug, host } = {}) {
 //     question names both halves of the ADR 0246 projection.
 //   • PROVIDES port `provisioning.projectPublishIdentity` ({ slug, host }) → { name,
 //     description } | null — see projectPublishIdentity above.
+//   • PROVIDES port `provisioning.moduleCatalog` () → { core: [key], optional: [{ key,
+//     label, summary }] } — the modules a NEW project gets and may opt into, with the
+//     owner-facing words the creation picker shows (task 1005273). The start-a-project
+//     guide recommends only from this list, so its plan can never name a module the
+//     picker does not offer. Read-only; no database.
 function registerProvisioningSeams() {
   if (api.hasProvider('provisioning.instanceState')) return;
   api.registerProvider('provisioning.instanceState', (slug) => provisioning.instanceStateForSlug(pool, slug));
@@ -51,6 +57,10 @@ function registerProvisioningSeams() {
   api.registerProvider('provisioning.projectOwnedBy', (target) => provisioning.projectOwnedBy(pool, target));
   api.registerProvider('provisioning.projectPublishIdentity', (target) => projectPublishIdentity(pool, target));
   api.registerProvider('provisioning.selfUpdateChannel', () => selfUpdateChannel(pool));
+  api.registerProvider('provisioning.moduleCatalog', () => ({
+    core: [...ALWAYS_ON_CORE],
+    optional: optionalModules().map(({ key, label, summary }) => ({ key, label, summary })),
+  }));
 }
 
 module.exports = { registerProvisioningSeams, projectPublishIdentity };

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.25.12",
+  "version": "1.25.13",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.25.12",
+      "version": "1.25.13",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.25.12",
+  "version": "1.25.13",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -11782,5 +11782,11 @@
       "id": "1005288",
       "text": "Decided how every project gets a sandbox: a free copy of the app that always shows the newest finished work, while the real site only changes when a person presses promote. Fake data and test keys by default. Costs the owner n"
     }
+  ],
+  "1.25.13": [
+    {
+      "id": "1005273",
+      "text": "The project guide now ends with a written plan (with recommended features drawn only from what Bongos really offers), saves the chat so visitors can come back to it, moves it onto their account when they sign up, and deletes i"
+    }
   ]
 }

package/scripts/bongos/run-unit-tests.js

@@ -100,6 +100,10 @@ const INTEGRATION = new Set([
   // task 1004941: a rules proposal round-trips to a new version the weekly run's loader
   // reads, on real SQL (the one-active index, the CHECKs). DB-free sibling: market_watch_rules.
   'market_watch_rules_db',
+  // tasks 1005272/1005273: the start-a-project guide's SQL on a real engine: the migrations,
+  // the one-account attach rule, and the retention sweep keeping spend on the books.
+  // DB-free siblings: front_door_guide, front_door_guide_plan.
+  'front_door_guide_db',
   // task 1004940: the weekly ask's SQL store — once per week by constraint, one pooled
   // proposal per similar answer, the project guard on an answer. DB-free sibling:
   // market_watch_ask.

package/src/bongos/module-scope-map.js

@@ -190,6 +190,7 @@ const MODULE_GLOBS = {
   // signed-out visitor. Its test sits at the repo root, listed by exact path.
   'front-door-guide': [
     'modules/front-door-guide/', 'tests/front_door_guide.mjs',
+    'tests/front_door_guide_plan.mjs', 'tests/front_door_guide_db.mjs',
   ],
   // The /raise investor page (task 1004847, ADR 0384): hub-only.
   raise: [

package/src/module-api.js

@@ -81,7 +81,7 @@ const { sleep } = require('./sleep');
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.25.12'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.25.13'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/front_door_guide_db.mjs

@@ -0,0 +1,110 @@
+// tests/front_door_guide_db.mjs — the start-a-project guide's SQL against a REAL Postgres
+// (tasks 1005272, 1005273).
+//
+// What only a real engine can say: both migrations apply, and apply again as no-ops; a
+// turn and a plan land in one statement each; only replies count as a visitor's messages;
+// a chat attaches to one account and is never moved to another; and the retention sweep
+// deletes an abandoned chat after the set number of days while its spend stays in the
+// daily and monthly sums.
+//
+// The module is default:false, so CI's migrate.sh does not apply its migrations; this
+// file applies them itself. Rows use a visitor hash and builder ids no real instance has,
+// and are deleted before and after. Self-skips without a reachable Postgres; in the
+// INTEGRATION set (scripts/bongos/run-unit-tests.js) so the DB-free lane never runs it.
+//
+// Run:  DATABASE_URL=... node tests/front_door_guide_db.mjs
+
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { strict as assert } from 'node:assert';
+import { insertTestBuilders } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const { Pool } = require('pg');
+const db = require('../modules/front-door-guide/db.js');
+const sql = (n) => readFileSync(new URL(`../modules/front-door-guide/migrations/${n}`, import.meta.url), 'utf8');
+const M1 = sql('front_door_guide_001_conversations.sql');
+const M2 = sql('front_door_guide_002_plan_and_account.sql');
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL || undefined });
+try {
+  await pool.query('SELECT 1');
+} catch (e) {
+  console.log(`front_door_guide_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+const x = (text, params) => pool.query(text, params);
+const V = 't1005273-visitor';
+const ALICE = 91005273, BOB = 91005274;
+
+async function cleanup() {
+  await x(`DELETE FROM front_door_guide_calls WHERE visitor_hash LIKE $1`, [`${V}%`]).catch(() => {});
+  await x(`DELETE FROM front_door_guide_conversations WHERE visitor_hash LIKE $1`, [`${V}%`]).catch(() => {});
+  await x('DELETE FROM builders WHERE id = ANY($1)', [[ALICE, BOB]]).catch(() => {});
+}
+
+const call = (over = {}) => ({ visitorHash: V, model: 'claude-opus-5-5', inputTokens: 800, outputTokens: 200, cacheReadTokens: 0, cacheWriteTokens: 0, costMicro: 9000, stopReason: 'end_turn', ...over });
+
+try {
+  for (const m of [M1, M2, M1, M2]) await x(m); // applies, then re-applies as a no-op
+  await cleanup();
+  await insertTestBuilders(pool, [{ id: ALICE, login: 't1005273-alice' }, { id: BOB, login: 't1005273-bob' }]);
+
+  const dayBefore = await db.siteSpendMicro('day', x);
+
+  // A turn and a plan.
+  const conv = await db.createConversation('hash-a-1005273', V, x);
+  const turned = await db.recordTurn(conv.id, { messages: [{ role: 'user', content: 'hi' }, { role: 'assistant', content: 'hello' }], status: 'open', endReason: null }, call(), x);
+  assert.equal(turned.visitor_messages, 1);
+  assert.equal(Number(turned.spend_micro), 9000);
+  const planned = await db.savePlan(conv.id, { summary: 'A plan' }, call({ costMicro: 20000 }), x);
+  assert.equal(planned.plan.summary, 'A plan');
+  assert.equal(planned.status, 'ended');
+  assert.equal(planned.end_reason, 'planned');
+  const again = await db.savePlan(conv.id, { summary: 'Overwrite?' }, call({ costMicro: 1 }), x);
+  assert.equal(again.plan.summary, 'A plan', 'a stored plan is never overwritten');
+  await db.recordPlanSpend(conv.id, call({ costMicro: 5 }), x);
+
+  const usage = await db.visitorUsage(V, x);
+  assert.equal(usage.messages, 1, 'only replies are messages');
+  assert.equal(usage.spendMicro, 9000 + 20000 + 1 + 5);
+
+  // Attach: the token holder's account, once; never moved to another.
+  assert.equal(await db.attachToBuilder(conv.id, 'wrong-hash', ALICE, x), null);
+  const mine = await db.attachToBuilder(conv.id, 'hash-a-1005273', ALICE, x);
+  assert.equal(Number(mine.builder_id), ALICE);
+  assert.ok(mine.attached_at);
+  assert.equal(await db.attachToBuilder(conv.id, 'hash-a-1005273', BOB, x), null);
+  assert.equal((await db.latestForBuilder(ALICE, x)).plan.summary, 'A plan');
+  assert.equal(await db.latestForBuilder(BOB, x), null);
+
+  // The sweep: an abandoned chat older than the setting goes; a recent one and an
+  // attached one stay; the abandoned chat's spend stays on the books.
+  const abandoned = await db.createConversation('hash-b-1005273', V, x);
+  await db.recordTurn(abandoned.id, { messages: [], status: 'open', endReason: null }, call({ costMicro: 7000 }), x);
+  const recent = await db.createConversation('hash-c-1005273', V, x);
+  await x(`UPDATE front_door_guide_conversations SET updated_at = now() - interval '15 days' WHERE id = ANY($1)`, [[abandoned.id, conv.id]]);
+  await x(`UPDATE front_door_guide_conversations SET updated_at = now() - interval '13 days' WHERE id = $1`, [recent.id]);
+  const before = await db.siteSpendMicro('day', x);
+
+  const deleted = await db.deleteAbandoned(14, x);
+  assert.ok(deleted >= 1);
+  const left = (await x(`SELECT id FROM front_door_guide_conversations WHERE visitor_hash = $1 ORDER BY id`, [V])).rows.map((r) => String(r.id));
+  assert.deepEqual(left, [String(conv.id), String(recent.id)], 'the abandoned chat is gone; the attached and the recent stay');
+  const orphan = await x(`SELECT conversation_id, cost_micro FROM front_door_guide_calls WHERE visitor_hash = $1 AND cost_micro = 7000`, [V]);
+  assert.equal(orphan.rows.length, 1);
+  assert.equal(orphan.rows[0].conversation_id, null);
+  assert.equal(await db.siteSpendMicro('day', x), before, 'the budgets still count the deleted chat\'s money');
+  assert.ok(before >= dayBefore + 9000 + 20000 + 1 + 5 + 7000);
+
+  // Refusals the schema owns.
+  await assert.rejects(x(`INSERT INTO front_door_guide_calls (visitor_hash, model, cost_micro, kind) VALUES ($1, 'm', 1, 'other')`, [V]));
+  await assert.rejects(x(`INSERT INTO front_door_guide_calls (visitor_hash, model, cost_micro) VALUES ($1, 'm', -1)`, [V]));
+
+  console.log('front_door_guide_db.mjs: all checks passed');
+} finally {
+  await cleanup();
+  await pool.end();
+}