@bongos/core 1.19.418 → 1.19.420

package/modules/provisioning/routes/provisioning.js

@@ -86,6 +86,30 @@ function ownerFromTargetRef(ref) {
   return m ? m[1] : null;
 }
 
+// The project-detail answers, validated LOUDLY (task 1002334). `detail` arrives as
+// a nested object, and the strict body validator only reaches top-level fields — so
+// without this a typo'd answer key would be dropped by normalizeProjectDetail and
+// the caller would be told nothing, which is exactly the silent-drop failure the
+// strict validator exists to prevent (and that a re-request's type_ignored receipt
+// was written to avoid). Returns null when clean, or a { code, message } to fail
+// with. Both the create route and PATCH …/detail run it, so they cannot drift.
+function badProjectDetail(detail) {
+  if (detail === undefined || detail === null) return null;
+  if (typeof detail !== 'object' || Array.isArray(detail)) {
+    return { code: 'bad_detail', message: 'detail must be an object of answers.' };
+  }
+  const vocab = provisioning.PROJECT_DETAIL_VOCAB;
+  for (const [key, value] of Object.entries(detail)) {
+    if (!Object.prototype.hasOwnProperty.call(vocab, key)) {
+      return { code: 'bad_detail', message: `Unknown detail answer "${key}" — the interview asks: ${Object.keys(vocab).join(', ')}.` };
+    }
+    if (!vocab[key].includes(value)) {
+      return { code: 'bad_detail', message: `"${key}" must be one of: ${vocab[key].join(', ')}.` };
+    }
+  }
+  return null;
+}
+
 // Minimal HTML escaper for the callback landing page (no template engine here).
 function esc(s) {
   return String(s == null ? '' : s).replace(/[&<>"']/g, (c) => (
@@ -388,8 +412,16 @@ module.exports = function provisioningRoutes() {
       onboard_mode: { type: 'string', maxLength: 20 },
       // the declared project Type (task 1002772) — optional, closed vocabulary
       type: { type: 'string', enum: [...provisioning.PROJECT_TYPES] },
+      // The optional project-detail step (task 1002334) — "tell us about your
+      // project", skippable everywhere. Absent means SKIPPED, which is a supported
+      // default: the project simply stays dark-matter until a description exists
+      // (ADR 0182 D4), and PATCH …/detail is the way back.
+      description: { type: 'string', maxLength: provisioning.DESCRIPTION_MAX },
+      detail: { type: 'object' },
     })) return;
     const body = req.body || {};
+    const detailFault = badProjectDetail(body.detail);
+    if (detailFault) return res.fail(detailFault.code, { status: 400, message: detailFault.message });
     const slug = String(body.slug || '').trim().toLowerCase();
     if (!provisioning.isValidSlug(slug)) {
       return res.fail('bad_slug', 400, { reason: 'lowercase, 2–40 chars of [a-z0-9-], no leading/trailing/double dash' });
@@ -472,6 +504,9 @@ module.exports = function provisioningRoutes() {
         targetRef: body.target_ref, hostingShape: shape,
         domain, tier: body.tier, onboardMode,
         type: body.type,
+        // The optional detail step's answers (task 1002334) — absent means the
+        // owner skipped it, which is the supported default, not an error.
+        description: body.description, detail: body.detail,
       });
       // Slug already taken by ANOTHER builder — refuse (never reassign ownership).
       if (!created && String(instance.owner_builder_id) !== String(req.builder.id)) {
@@ -525,6 +560,16 @@ module.exports = function provisioningRoutes() {
           hint: "a re-request never changes an existing instance's declared type",
         };
       }
+      // …and the same for the detail answers (task 1002334). Unlike type this one
+      // HAS a mutation route, so the receipt names it instead of just refusing —
+      // otherwise an owner who came back to fill in the description they skipped
+      // would be told nothing and left dark-matter with no idea why.
+      let detailIgnored;
+      if (!created && (body.description !== undefined || body.detail !== undefined)) {
+        detailIgnored = {
+          hint: `a re-request never changes an existing instance's project detail — PATCH /provisioning/instances/${instance.id}/detail instead`,
+        };
+      }
       res.status(created ? 201 : 200).json({
         instance: provisioning.publicInstance(instance),
         open_intent: intent ? { action: intent.action, state: intent.state } : null,
@@ -533,6 +578,7 @@ module.exports = function provisioningRoutes() {
         ...(domainIgnored ? { domain_ignored: domainIgnored } : {}),
         ...(noAddressIgnored ? { no_address_ignored: noAddressIgnored } : {}),
         ...(typeIgnored ? { type_ignored: typeIgnored } : {}),
+        ...(detailIgnored ? { detail_ignored: detailIgnored } : {}),
       });
     } catch (err) {
       log.error('[provisioning] POST /provisioning/instances', err);
@@ -644,6 +690,65 @@ module.exports = function provisioningRoutes() {
     }
   });
 
+  // ── The optional project detail (task 1002334, goal 1000046) ──────────────
+  // PATCH /provisioning/instances/:id/detail — answer (or re-answer) the
+  // "tell us about your project" step after creation. Body: any subset of
+  // { description, detail }. rank: any authenticated builder (own resource;
+  // archon may change any — same gate as settings).
+  //
+  // THIS ROUTE IS WHAT MAKES THE STEP SKIPPABLE. Skipping at creation leaves the
+  // project dark-matter — off the map and un-joinable (ADR 0182 D4) — and that is
+  // a supported default only because there is a way back. Without this route
+  // "optional" would mean "permanently unpublishable", i.e. a dead end, which is
+  // precisely what criterion `proj-detail-interview` refuses.
+  //
+  // Deliberately NOT a settings-apply: nothing here is a policy the running
+  // instance obeys, so there is no web.env to patch and no restart to queue. The
+  // answers live on the platform row until a catalog row materializes (the
+  // provisioning_007 `type` precedent), and R16 (task 1002335) is the surface that
+  // reads `description` to compute publishability and name what is still missing.
+  router.patch('/provisioning/instances/:id/detail', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
+    if (!id) return;
+    if (validateOrRespond(req, res, {
+      description: { type: 'string', maxLength: provisioning.DESCRIPTION_MAX },
+      detail: { type: 'object' },
+    })) return;
+    const body = req.body || {};
+    const detailFault = badProjectDetail(body.detail);
+    if (detailFault) return res.fail(detailFault.code, { status: 400, message: detailFault.message });
+    if (body.description === undefined && body.detail === undefined) {
+      return res.fail('bad_detail', { status: 400,
+        message: 'The body carries nothing to change — send description, detail, or both.' });
+    }
+    try {
+      const inst = await provisioning.getInstanceById(pool, id);
+      if (instanceAccessDenied(inst, req.builder)) return res.fail('instance_not_found', 404);
+      const actor = String(inst.owner_builder_id) === String(req.builder.id) ? 'api:self' : `api:archon:${req.builder.id}`;
+      // An empty description is CLEARING it, not a no-op string: normalize here so
+      // the column never holds '' — a blank string would read as answered to a
+      // `description IS NOT NULL` publish check and put an empty husk on the map.
+      const patch = {};
+      if (body.description !== undefined) patch.description = provisioning.normalizeDescription(body.description);
+      if (body.detail !== undefined) patch.detail = body.detail;
+      const updated = await provisioning.updateInstanceDetail(pool, id, patch);
+      await provisioning.recordEvent(pool, {
+        instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'detail',
+        detail: `project detail changed: ${Object.keys(patch).join(', ')}`,
+        actor,
+      }).catch(() => {});
+      res.json({
+        ok: true,
+        description: updated.description || null,
+        detail: provisioning.projectDetail(updated),
+        options: provisioning.PROJECT_DETAIL_VOCAB,
+      });
+    } catch (err) {
+      log.error('[provisioning] PATCH /provisioning/instances/:id/detail', err);
+      res.fail('detail_update_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // ── Per-project settings (task 1003040, goal 1000058) ─────────────────────
   // The foundation the manage-page wave hangs off: effective settings are the
   // DEFAULTS (today's behavior — public surfaces, apply-to-join) overlaid with

package/modules/provisioning/tests/provisioning.mjs

@@ -298,5 +298,89 @@ await ta('updateInstanceSettings: jsonb MERGE (||) + updated_at, parameterized,
   assert.deepEqual(params, [18, JSON.stringify({ joinability: 'open' })]);
 });
 
+console.log('');
+console.log('the optional project-detail interview (BV1.R15, task 1002334):');
+
+t('normalizeDescription: collapses whitespace, caps, and empty means ABSENT (never an empty string)', () => {
+  const NL = String.fromCharCode(10);
+  assert.equal(P.normalizeDescription('  A co-op   farming' + NL + '  game.  '), 'A co-op farming game.');
+  // null, not '' — the publish gate reads `description IS NOT NULL`, so a blank
+  // string stored in a nullable column would publish an empty husk (ADR 0182 D4)
+  assert.equal(P.normalizeDescription('   '), null);
+  assert.equal(P.normalizeDescription(''), null);
+  assert.equal(P.normalizeDescription(null), null);
+  assert.equal(P.normalizeDescription(42), null);
+  assert.equal(P.normalizeDescription('x'.repeat(P.DESCRIPTION_MAX + 50)).length, P.DESCRIPTION_MAX);
+});
+
+t('normalizeProjectDetail: on-vocabulary keys only — an unknown key or value is DROPPED, never defaulted', () => {
+  assert.deepEqual(P.normalizeProjectDetail({ team_shape: 'community' }), { team_shape: 'community' });
+  assert.deepEqual(P.normalizeProjectDetail({ team_shape: 'enormous' }), {}, 'an off-vocabulary answer is not stored');
+  assert.deepEqual(P.normalizeProjectDetail({ favourite_colour: 'blue' }), {}, 'an unknown question is not stored');
+  // skipping is the supported default, so every not-an-object shape reads as {}
+  for (const skipped of [undefined, null, 'solo', ['solo'], 7]) {
+    assert.deepEqual(P.normalizeProjectDetail(skipped), {}, 'a skipped interview stores {}');
+  }
+});
+
+t('projectDetail: a stored value that has since LEFT the vocabulary never leaks out of the read surface', () => {
+  assert.deepEqual(P.projectDetail({ detail: { team_shape: 'solo' } }), { team_shape: 'solo' });
+  assert.deepEqual(P.projectDetail({ detail: { team_shape: 'guild' } }), {});
+  assert.deepEqual(P.projectDetail({}), {}, 'a row predating the migration reads as skipped');
+  assert.deepEqual(P.projectDetail(null), {});
+});
+
+t('PROJECT_DETAIL_VOCAB carries NO defaults — an unanswered question stays unanswered', () => {
+  // The deliberate asymmetry with SETTINGS_VOCAB: a setting is a policy the
+  // instance must obey, so it needs a default; a detail answer is something the
+  // owner SAID, and a default would feed R17 a recommendation nobody asked for.
+  assert.equal(P.DEFAULT_PROJECT_DETAIL, undefined, 'there is no defaults table to drift from');
+  for (const vocab of Object.values(P.PROJECT_DETAIL_VOCAB)) {
+    assert.ok(Array.isArray(vocab) && vocab.length, 'every question has a closed answer list');
+  }
+});
+
+t('publicInstance surfaces both halves, and both are legitimately empty when skipped', () => {
+  const answered = P.publicInstance({ id: 1, slug: 'mercury', description: 'A thing.', detail: { team_shape: 'solo' } });
+  assert.equal(answered.description, 'A thing.');
+  assert.deepEqual(answered.detail, { team_shape: 'solo' });
+  const skipped = P.publicInstance({ id: 2, slug: 'venus' });
+  assert.equal(skipped.description, null, 'no description is null — what keeps the project dark-matter');
+  assert.deepEqual(skipped.detail, {}, 'and a skipped interview reads as {}, never undefined');
+});
+
+await ta('createInstance: the answers ride the INSERT, and a skipped interview inserts null + {}', async () => {
+  let params = null;
+  const db = { query: async (q, p) => { params = p; return { rows: [{ id: 3 }] }; } };
+  await P.createInstance(db, {
+    ownerBuilderId: 1, slug: 'mercury', description: '  A co-op  game. ',
+    detail: { team_shape: 'community', bogus: 'x' },
+  });
+  assert.equal(params[11], 'A co-op game.', 'the description is normalized before it is stored');
+  assert.equal(params[12], JSON.stringify({ team_shape: 'community' }), 'and off-vocabulary keys never reach the column');
+  await P.createInstance(db, { ownerBuilderId: 1, slug: 'venus' });
+  assert.equal(params[11], null, 'a skipped interview stores null — not an empty string');
+  assert.equal(params[12], '{}');
+});
+
+await ta('updateInstanceDetail: detail MERGES, description REPLACES, and neither is written unasked', async () => {
+  let sql = '', params = null;
+  const db = { query: async (q, p) => { sql = q; params = p; return { rows: [{ id: 18 }] }; } };
+
+  await P.updateInstanceDetail(db, 18, { detail: { team_shape: 'small-team' } });
+  assert.ok(sql.includes('detail = detail || $2::jsonb'), 'one answer does not erase the others');
+  assert.ok(!sql.includes('description ='), 'an unsent description is left alone, never nulled');
+  assert.deepEqual(params, [18, JSON.stringify({ team_shape: 'small-team' })]);
+
+  await P.updateInstanceDetail(db, 18, { description: 'Filled in later.' });
+  assert.ok(sql.includes('description = $2'), 'the way back for a skipped step');
+  assert.ok(!sql.includes('detail = detail'), 'and it touches no answers it was not given');
+
+  // clearing is allowed and un-publishes — the honest consequence of deleting
+  // half the identity gate, not a bug to guard against
+  await P.updateInstanceDetail(db, 18, { description: null });
+  assert.deepEqual(params, [18, null]);
+});
+
 console.log(`\nprovisioning module: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.418",
+  "version": "1.19.420",
   "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",