@bongos/core 1.21.127 → 1.21.129

package/tests/howto_moments.mjs

@@ -0,0 +1,136 @@
+// tests/howto_moments.mjs — the right unread how-to step at the right moment, never twice (task 1004635)
+//
+// The done-when: on a fresh project the first session is walked through the starting
+// step, the first ship triggers the shipping walkthrough, and neither repeats once read.
+// Held here at three layers: the pure picker (modules/onboarding/howto-moments.js), the
+// Conductor advisory built from it (.claude/hooks/conductor.js howtoAdvisory), and the
+// non-Claude path (the `npx bongos howto` verb + the instance CLAUDE.md lines naming it).
+//
+// Run:  node tests/howto_moments.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const guide = require('../modules/onboarding/howto-guide.js');
+const m = require('../modules/onboarding/howto-moments.js');
+const { howtoAdvisory, evaluateTriggers } = require('../.claude/hooks/conductor.js');
+const { VERBS } = require('../bin/bongos.js');
+const { renderInstanceClaudeMd } = require('../scripts/gds/claude-md-template.js');
+const { readIds } = require('../scripts/gds/howto.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.message}`); }
+}
+const ids = (pick) => (pick ? pick.steps.map((s) => s.id) : []);
+
+console.log('the picker:');
+
+test('a fresh project: the first prompt walks through what Bongos is and where to start', () => {
+  const pick = m.pickSteps({ firstPrompt: true, prompt: 'hello', claims: [], read: [] });
+  assert.equal(pick.moment.id, 'first_open');
+  assert.deepEqual(ids(pick), ['welcome', 'where_to_start']);
+});
+
+test('once read, the starting step never comes back — the next session moves on', () => {
+  const pick = m.pickSteps({ firstPrompt: true, prompt: 'hello', claims: [], read: ['welcome', 'where_to_start'] });
+  assert.ok(!ids(pick).includes('where_to_start'));
+  assert.ok(!ids(pick).includes('welcome'));
+});
+
+test('an ordinary later prompt with nothing claimed says nothing', () => {
+  assert.equal(m.pickSteps({ firstPrompt: false, prompt: 'rename the button', claims: [], read: [] }), null);
+});
+
+test('the first ship triggers the shipping walkthrough, ahead of the claim steps', () => {
+  const pick = m.pickSteps({ prompt: 'ship it', claims: [{ task_id: 1 }], read: [] });
+  assert.equal(pick.moment.id, 'first_ship');
+  assert.deepEqual(ids(pick), ['what_ship_does', 'review_findings']);
+});
+
+test('the shipping walkthrough does not repeat once read', () => {
+  const read = ['what_ship_does', 'review_findings', 'claim_a_task', 'give_a_task_back', 'preview_before_ship'];
+  assert.equal(m.pickSteps({ prompt: 'ship it', claims: [{ task_id: 1 }], read }), null);
+});
+
+test('holding a claim opens the first-claim steps', () => {
+  assert.equal(m.pickSteps({ prompt: 'go on', claims: [{ task_id: 1 }], read: [] }).moment.id, 'first_claim');
+});
+
+test('after a ship (no claim, shipping walkthrough read) comes what happens next', () => {
+  const pick = m.pickSteps({ prompt: 'ok', claims: [], read: ['what_ship_does', 'review_findings'] });
+  assert.equal(pick.moment.id, 'after_ship');
+});
+
+test('unknown claim state never guesses a claim moment', () => {
+  assert.equal(m.pickSteps({ prompt: 'ship it', claims: null, read: [] }), null);
+});
+
+test('short: never more than two steps, all from one moment', () => {
+  for (const firstPrompt of [true, false]) {
+    for (const prompt of ['ship it', 'I am stuck', 'make a goal', 'invite my teammate', 'what can I work on?']) {
+      const pick = m.pickSteps({ firstPrompt, prompt, claims: [{ task_id: 1 }], read: [] });
+      if (!pick) continue;
+      assert.ok(pick.steps.length <= m.MAX_STEPS);
+      assert.ok(pick.steps.every((s) => s.moment === pick.moment.id));
+    }
+  }
+});
+
+test('every moment the picker can open is a moment the guide defines', () => {
+  const opened = new Set();
+  for (const prompt of ['ship it', 'stuck', 'set up', 'goal', 'make a task', "what's next", 'invite', 'settings']) {
+    for (const claims of [[], [{}], null]) {
+      for (const id of m.openMoments({ firstPrompt: true, prompt, claims, read: [] })) opened.add(id);
+    }
+  }
+  for (const id of opened) assert.ok(guide.MOMENT_IDS.has(id), id);
+});
+
+test('the AI is told to say it once, briefly, and that it is marked read', () => {
+  const text = m.renderForAi(m.pickSteps({ firstPrompt: true, claims: [], read: [] }));
+  assert.match(text, /Where to start/);
+  assert.match(text, /once/);
+  assert.match(text, /marked read/);
+});
+
+console.log('\nthe Conductor:');
+
+test('no read state (offline, signed out, no onboarding module) → no how-to advisory', () => {
+  assert.equal(howtoAdvisory({ howto: null, firstPrompt: true, activeClaims: [] }), null);
+});
+
+test('the advisory names the steps it shows, so main() can mark exactly those read', () => {
+  const a = howtoAdvisory({ howto: { read: [] }, firstPrompt: true, activeClaims: [] });
+  assert.deepEqual(a.howtoSteps, ['welcome', 'where_to_start']);
+  assert.equal(a.id, 'howto:welcome,where_to_start');
+});
+
+test('evaluateTriggers carries the how-to advisory on a first prompt, and not once read', () => {
+  const first = evaluateTriggers({ prompt: 'hi', activeClaims: [], howto: { read: [] }, firstPrompt: true });
+  assert.ok(first.some((a) => a.howtoSteps));
+  const all = guide.STEPS.map((s) => s.id);
+  const later = evaluateTriggers({ prompt: 'ship it', activeClaims: [{ task_id: 1 }], howto: { read: all }, firstPrompt: true });
+  assert.ok(!later.some((a) => a.howtoSteps));
+});
+
+console.log('\nother AI tools:');
+
+test('`bongos howto` is a verb, run by scripts/gds/howto.js', () => {
+  assert.equal(VERBS.howto.script, 'howto.js');
+});
+
+test('the instance CLAUDE.md names the three moment commands', () => {
+  const md = renderInstanceClaudeMd({});
+  for (const id of ['first_open', 'first_claim', 'first_ship']) assert.ok(md.includes(`npx bongos howto moment ${id}`), id);
+});
+
+test('the CLI counts read and skipped steps as done', () => {
+  assert.deepEqual(readIds({ steps: [{ id: 'a', state: 'read' }, { id: 'b', state: 'skipped' }, { id: 'c', state: 'unread' }] }), ['a', 'b']);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed) process.exitCode = 1;

package/tests/howto_state.mjs

@@ -0,0 +1,178 @@
+// tests/howto_state.mjs — per-person read/unread state for the how-to steps (task 1004634)
+//
+// Two halves. The DB-free half drives howto-state.js against an in-memory pool that
+// honours the three statements it issues, so the contract runs everywhere: unread by
+// default, mark read, skip all, a read upgrades a skip (never the reverse), the first
+// read time is kept, reset some or all, and an id the guide does not name is refused.
+// The DB half applies the real migration and runs the same calls against Postgres; it
+// skips when no Postgres is reachable (DATABASE_URL), like copy_desk_flags_db.mjs.
+//
+// Run:  node tests/howto_state.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+
+const require = createRequire(import.meta.url);
+const hs = require('../modules/onboarding/howto-state.js');
+const guide = require('../modules/onboarding/howto-guide.js');
+const ROOT = path.resolve(path.dirname(url.fileURLToPath(import.meta.url)), '..');
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.stack || err.message}`); }
+}
+
+// An in-memory stand-in for the three statements howto-state.js runs.
+function fakePool() {
+  const rows = new Map(); // `${b}|${step}` → { builder_id, step_id, how, read_at }
+  let clock = 0;
+  return {
+    rows,
+    async query(sql, params) {
+      if (/^SELECT step_id/.test(sql)) {
+        return { rows: [...rows.values()].filter((r) => r.builder_id === params[0]) };
+      }
+      if (/^INSERT INTO onboarding_howto_reads/.test(sql)) {
+        const [b, ids, how] = params;
+        for (const s of ids) {
+          const k = `${b}|${s}`;
+          const cur = rows.get(k);
+          if (!cur) rows.set(k, { builder_id: b, step_id: s, how, read_at: new Date(1e12 + ++clock * 1000) });
+          else if (cur.how === 'skipped' && how === 'read') cur.how = 'read';
+        }
+        return { rows: [] };
+      }
+      if (/^DELETE FROM onboarding_howto_reads WHERE builder_id = \$1 AND/.test(sql)) {
+        for (const s of params[1]) rows.delete(`${params[0]}|${s}`);
+        return { rows: [] };
+      }
+      if (/^DELETE FROM onboarding_howto_reads WHERE builder_id = \$1$/.test(sql)) {
+        for (const [k, r] of rows) if (r.builder_id === params[0]) rows.delete(k);
+        return { rows: [] };
+      }
+      throw new Error(`unexpected SQL: ${sql}`);
+    },
+  };
+}
+
+async function contract(label, deps, A, B) {
+  const first = guide.STEPS[0].id;
+  const second = guide.STEPS[1].id;
+
+  await test(`${label}: a new person has every step unread, next is the first`, async () => {
+    const s = await hs.readState(A, deps);
+    assert.equal(s.total, guide.STEPS.length);
+    assert.equal(s.unread, s.total);
+    assert.equal(s.next_unread, first);
+    assert.ok(s.steps.every((x) => x.state === 'unread' && x.read_at === null));
+  });
+
+  await test(`${label}: mark one read → it is read, next moves on, other people untouched`, async () => {
+    const r = await hs.markRead(A, { steps: [first] }, deps);
+    assert.equal(r.ok, true);
+    assert.equal(r.state.read, 1);
+    assert.equal(r.state.next_unread, second);
+    assert.equal(r.state.steps[0].state, 'read');
+    assert.ok(r.state.steps[0].read_at);
+    const other = await hs.readState(B, deps);
+    assert.equal(other.read, 0, 'per person');
+  });
+
+  await test(`${label}: re-marking keeps the first read time (idempotent)`, async () => {
+    const before = (await hs.readState(A, deps)).steps[0].read_at;
+    await hs.markRead(A, { steps: [first] }, deps);
+    assert.equal((await hs.readState(A, deps)).steps[0].read_at, before);
+  });
+
+  await test(`${label}: an unknown step id is refused and nothing is stored`, async () => {
+    const r = await hs.markRead(A, { steps: [second, 'not_a_step'] }, deps);
+    assert.equal(r.ok, false);
+    assert.equal(r.reason, 'unknown_step');
+    assert.deepEqual(r.unknown, ['not_a_step']);
+    assert.equal((await hs.readState(A, deps)).read, 1);
+    assert.equal((await hs.markRead(A, { steps: [] }, deps)).reason, 'no_steps');
+    assert.equal((await hs.markRead(A, { steps: [second], how: 'seen' }, deps)).reason, 'bad_how');
+  });
+
+  await test(`${label}: skip all marks every other step skipped; nothing left unread`, async () => {
+    const r = await hs.markRead(A, { all: true, how: 'skipped' }, deps);
+    assert.equal(r.state.unread, 0);
+    assert.equal(r.state.next_unread, null);
+    assert.equal(r.state.read, 1, 'the step already read stays read');
+    assert.equal(r.state.skipped, guide.STEPS.length - 1);
+  });
+
+  await test(`${label}: reading a skipped step upgrades it; skipping a read one does not downgrade`, async () => {
+    await hs.markRead(A, { steps: [second] }, deps);
+    let s = await hs.readState(A, deps);
+    assert.equal(s.steps[1].state, 'read');
+    await hs.markRead(A, { steps: [second], how: 'skipped' }, deps);
+    s = await hs.readState(A, deps);
+    assert.equal(s.steps[1].state, 'read');
+  });
+
+  await test(`${label}: reset some steps, then reset everything`, async () => {
+    let r = await hs.reset(A, { steps: [first] }, deps);
+    assert.equal(r.state.steps[0].state, 'unread');
+    assert.equal(r.state.next_unread, first);
+    assert.equal((await hs.reset(A, { steps: ['nope_nope'] }, deps)).reason, 'unknown_step');
+    r = await hs.reset(A, {}, deps);
+    assert.equal(r.state.unread, guide.STEPS.length);
+  });
+}
+
+await test('shapeState ignores a stored mark for a step the guide no longer has', async () => {
+  const s = hs.shapeState([{ step_id: 'retired_step', how: 'read', read_at: new Date() }]);
+  assert.equal(s.read, 0);
+  assert.equal(s.total, guide.STEPS.length);
+});
+
+await test('the module declares its migration and the routes are mounted', async () => {
+  const mod = JSON.parse(fs.readFileSync(path.join(ROOT, 'modules/onboarding/module.json'), 'utf8'));
+  assert.equal(mod.contributes.migrations, true);
+  assert.ok(fs.existsSync(path.join(ROOT, 'modules/onboarding/migrations/onboarding_001_howto_reads.sql')));
+  const src = fs.readFileSync(path.join(ROOT, 'modules/onboarding/routes/onboarding.js'), 'utf8');
+  for (const r of ["router.get('/me/howto'", "router.post('/me/howto/read'", "router.post('/me/howto/reset'"]) assert.ok(src.includes(r), r);
+});
+
+await contract('in-memory', { pool: fakePool() }, 1, 2);
+
+// ── the real database ────────────────────────────────────────────────────────
+const { Pool } = require('pg');
+const pool = new Pool({ connectionString: process.env.DATABASE_URL || undefined });
+let dbUp = true;
+try { await pool.query('SELECT 1'); } catch (e) {
+  dbUp = false;
+  console.log(`  (db half SKIPPED — no reachable Postgres: ${e.code || e.message}. Set DATABASE_URL to run.)`);
+}
+if (dbUp) {
+  await pool.query(`
+    CREATE TABLE IF NOT EXISTS schema_migrations (version text PRIMARY KEY);
+    CREATE TABLE IF NOT EXISTS builders (id bigserial PRIMARY KEY, github_login text);
+  `);
+  await pool.query(fs.readFileSync(path.join(ROOT, 'modules/onboarding/migrations/onboarding_001_howto_reads.sql'), 'utf8'));
+  await pool.query(fs.readFileSync(path.join(ROOT, 'modules/onboarding/migrations/onboarding_001_howto_reads.sql'), 'utf8')); // idempotent
+  const A = 910000001;
+  const B = 910000002;
+  await pool.query('INSERT INTO builders (id, github_login) VALUES ($1, $2), ($3, $4) ON CONFLICT (id) DO NOTHING', [A, 'howto-a', B, 'howto-b']);
+  await pool.query('DELETE FROM onboarding_howto_reads WHERE builder_id IN ($1, $2)', [A, B]);
+  try {
+    await contract('postgres', { pool }, A, B);
+    await test('postgres: the CHECK refuses a malformed step id and a bad how', async () => {
+      await assert.rejects(pool.query("INSERT INTO onboarding_howto_reads (builder_id, step_id) VALUES ($1, 'Bad Id')", [A]));
+      await assert.rejects(pool.query("INSERT INTO onboarding_howto_reads (builder_id, step_id, how) VALUES ($1, 'welcome', 'seen')", [A]));
+    });
+  } finally {
+    await pool.query('DELETE FROM onboarding_howto_reads WHERE builder_id IN ($1, $2)', [A, B]).catch(() => {});
+    await pool.query('DELETE FROM builders WHERE id IN ($1, $2)', [A, B]).catch(() => {});
+  }
+}
+await pool.end().catch(() => {});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);

package/tests/module_release_channels.mjs

@@ -0,0 +1,58 @@
+// tests/module_release_channels.mjs — the release-channel schema a module version
+// sits on (task 1003815, ADR 0344; migration core_276). No database: the migration
+// is read as text and its shape pinned. The integration lane applies it to a real
+// Postgres with every other migration.
+//
+// Run:  node tests/module_release_channels.mjs
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SQL = fs.readFileSync(path.join(ROOT, 'migrations', 'core_276_module_release_channels.sql'), 'utf8');
+const DDL = SQL.replace(/--.*$/gm, '');
+
+test('core_276 is additive and idempotent', () => {
+  // the project's own migration linter, so this tracks its unsafe-pattern list as it grows
+  const lint = require('../scripts/gds/lint-migrations.js');
+  assert.deepEqual(lint.scanMigrationSql(SQL).unsafe || [], [], 'additive only');
+  for (const m of DDL.matchAll(/CREATE (TABLE|INDEX)\s+(?!IF NOT EXISTS\b)(\w+)/g)) {
+    assert.fail(`CREATE ${m[1]} ${m[2]} without IF NOT EXISTS is not safe to re-run`);
+  }
+  assert.match(DDL, /ON CONFLICT \(channel\) DO NOTHING/, 're-running does not duplicate the channel rows');
+  assert.match(DDL, /WHERE NOT EXISTS \(SELECT 1 FROM store_module_version_channels c WHERE c\.version_id = v\.id\)/,
+    're-running does not add a second backfill row');
+  assert.match(SQL, /INSERT INTO schema_migrations \(version\) VALUES \('core_276_module_release_channels'\)/);
+});
+
+test('channels are rows, so a fourth needs no schema change; tester, general and withdrawn ship', () => {
+  assert.match(DDL, /CREATE TABLE IF NOT EXISTS store_release_channels \(\s*channel\s+text PRIMARY KEY/);
+  const seeded = [...DDL.matchAll(/\('(\w+)',\s+'[^']*',\s+(true|false),\s+\d+\)/g)].map((m) => [m[1], m[2]]);
+  assert.deepEqual(seeded, [['tester', 'true'], ['general', 'true'], ['withdrawn', 'false']],
+    'two channels serve installs; withdrawn never does');
+  assert.doesNotMatch(DDL, /channel\s+text[^,\n]*CHECK \(channel IN/, 'no closed list of channels in a CHECK');
+  assert.doesNotMatch(DDL, /\bis_tester\b|\btester\s+boolean/, 'not a boolean');
+});
+
+test('a channel belongs to a version, as history: the newest row is current', () => {
+  const t = DDL.match(/CREATE TABLE IF NOT EXISTS store_module_version_channels \(([\s\S]*?)\n\);/);
+  assert.ok(t, 'the history table exists');
+  const body = t[1];
+  assert.match(body, /version_id\s+bigint NOT NULL REFERENCES store_module_versions\(id\)/, 'keyed by version, not module');
+  assert.doesNotMatch(body, /\bmodule_key\b/, 'never by module');
+  assert.match(body, /channel\s+text NOT NULL REFERENCES store_release_channels\(channel\)/);
+  assert.match(body, /reason\s+text NOT NULL CHECK \(reason ~ '\^\[a-z\]\[a-z0-9_\]\{0,39\}\$'\)/, 'a short code, never free text');
+  assert.match(body, /set_by\s+bigint REFERENCES builders\(id\),/, 'nullable: the system can move a version');
+  assert.doesNotMatch(body, /UNIQUE \(version_id\)/, 'a version can move more than once');
+  assert.match(DDL, /ON store_module_version_channels \(version_id, set_at DESC, id DESC\)/, 'current-channel lookup is indexed');
+});
+
+test('versions published before staged rollout stay offered to everyone', () => {
+  assert.match(DDL, /SELECT v\.id, 'general', 'predates_staged_rollout'\s+FROM store_module_versions v/);
+});

package/tests/own_scope_guard.mjs

@@ -164,6 +164,12 @@ const OWN_SCOPED_SURFACES = [
       },
     ],
   },
+  {
+    file: 'modules/onboarding/routes/onboarding.js',
+    why: "the how-to read state (task 1004634). GET /me/howto and POST /me/howto/read|reset read and write the CALLER's own marks, keyed on req.builder.id; the body names step ids, never a builder. The rest of the router is /founding/*, whose one path param names a founding STAGE, not a builder.",
+    minOwnScoped: 1,
+    crossOwner: [],
+  },
 ];
 
 // Floors that keep this guard from going quietly vacuous (a regex that stops