@bongos/core 1.20.1 → 1.20.3

package/tests/speciality_skills.mjs

@@ -58,6 +58,46 @@ await test('the real tree resolves: the core ships skills a speciality can offer
   assert.ok(got.has('recall') && got.has('status'), 'core skills are found in this checkout');
 });
 
+await test('a FOLDED description (`>-`) is read as its text, not as the fold marker (task 1004073)', () => {
+  const fm = skills.parseFrontmatter('---\nname: x\ndescription: >-\n  One line\n  and the next.\nrequires: [gh, droplet-ssh]\ncost: "Free."\n---\nbody');
+  assert.equal(fm.description, 'One line and the next.');
+  assert.deepEqual(fm.requires, ['gh', 'droplet-ssh']);
+  assert.equal(fm.cost, 'Free.');
+  assert.equal(skills.parseFrontmatter('---\ndescription: |\n  a\n  b\n---\n').description, 'a\nb', 'a literal block keeps its lines');
+  assert.deepEqual(skills.parseFrontmatter('no frontmatter'), {});
+});
+
+await test('every skill in the real tree reads a real description — none is a bare fold marker', () => {
+  const got = skills.installedSkills({ coreRoot: ROOT, isModuleEnabled: () => false });
+  const bad = [...got.values()].filter((s) => !s.description || /^[>|][+-]?$/.test(s.description)).map((s) => s.name);
+  assert.deepEqual(bad, [], `these would teach nothing in the walkthrough: ${bad.join(', ')}`);
+});
+
+await test('explainSkill splits a model-facing description into what it does, when, and what it costs', () => {
+  const e = skills.explainSkill({
+    name: 'goal-review', source: 'core',
+    description: 'Walk the review queue. Read-only. Metic+ only. Triggers: "/goal-review", "review goals", "confirm criteria", or a scheduled run.',
+    requires: ['gh'],
+  });
+  assert.equal(e.does, 'Walk the review queue. Read-only.', 'the trigger list and the rank note are not part of what it does');
+  assert.equal(e.rank, 'metic', 'the rank is kept apart: enabling a skill grants nothing');
+  assert.deepEqual(e.commands, ['/goal-review']);
+  assert.match(e.reachFor, /“review goals”, “confirm criteria”.*a scheduled run/);
+  assert.match(e.cost, /^Read-only/);
+  assert.deepEqual(e.needs, ['gh']);
+  assert.deepEqual(e.derived, { does: true, reachFor: true, cost: true });
+});
+
+await test('explainSkill prefers the author\'s people-facing words and says when it had to guess', () => {
+  const e = skills.explainSkill({ name: 'x', description: 'Model text. Triggers: "/x".', plain: 'Plain words.', cost: 'About a dollar.' });
+  assert.equal(e.does, 'Plain words.');
+  assert.equal(e.cost, 'About a dollar.');
+  assert.deepEqual(e.derived, { does: false, reachFor: true, cost: false });
+  const unknown = skills.explainSkill({ name: 'y', description: 'Does a thing.' });
+  assert.match(unknown.cost, /has not written down what it costs/, 'an unknown cost is said plainly, never invented');
+  assert.match(skills.explainSkill({ name: 'z', description: 'Read-only check. --probe runs a paid calibration.' }).cost, /paid option/);
+});
+
 await test('an unreadable root contributes nothing rather than throwing', () => {
   const got = skills.installedSkills({ coreRoot: path.join(os.tmpdir(), 'no-such-root-' + Date.now()), isModuleEnabled: () => { throw new Error('boom'); } });
   assert.equal(got.size, 0);
@@ -146,7 +186,12 @@ db.setEnabledSkills = async (b, s, list) => (store.adoption ? { ...store.adoptio
 db.createSpeciality = async (row) => { store.created = row; return { id: 10, ...row }; };
 db.updateSpeciality = async (id, patch) => { store.updated = patch; return { ...store.speciality, ...patch }; };
 db.countTraining = async () => ({ documentCount: 0, learningCount: 0 });
-skills.installedSkillsCached = () => new Map([['recall', {}], ['status', {}], ['costing', {}]]);
+skills.installedSkillsCached = () => new Map([
+  ['recall', { name: 'recall', description: 'Search what the project knows. Read-only. Triggers: "/recall", "what do we know about X".', source: 'core' }],
+  ['status', { name: 'status', description: 'Roll up a version.', source: 'core' }],
+  ['costing', { name: 'costing', description: 'Price a thing.', source: 'module:econ' }],
+]);
+db.listAdoptions = async () => (store.adoption ? [{ id: 9, active: store.adoption.active, enabled_skills: store.adoption.enabled_skills }] : []);
 api.requireBuilder = (req, res, next) => { req.builder = { id: 1, rank: 'metic' }; next(); };
 api.enabledDisciplines = () => ['ideator', 'engineer', 'artist'];
 
@@ -187,6 +232,36 @@ try {
     store.speciality.skills = ['recall', 'status'];
   });
 
+  await test('GET /specialities/:id/skills explains each OFFERED skill for the walkthrough, and the caller\'s own set', async () => {
+    store.adoption = null;
+    store.speciality.skills = ['recall', 'gone-now'];
+    const r = await call('GET', '/specialities/9/skills');
+    assert.equal(r.status, 200, JSON.stringify(r.body));
+    assert.equal(r.body.adopted, false);
+    assert.deepEqual(r.body.enabled, []);
+    assert.deepEqual(r.body.skills.map((s) => s.name), ['recall', 'gone-now'], 'the offered set, in its order — not every installed skill');
+    const recall = r.body.skills[0];
+    assert.equal(recall.installed, true);
+    assert.equal(recall.does, 'Search what the project knows. Read-only.');
+    assert.match(recall.reachFor, /what do we know about X/);
+    assert.match(recall.cost, /^Read-only/);
+    assert.deepEqual(r.body.skills[1], { name: 'gone-now', installed: false }, 'a skill removed since is named, not explained or offered');
+
+    store.adoption = { builder_id: 1, speciality_id: 9, active: true, enabled_skills: ['recall'] };
+    const held = await call('GET', '/specialities/9/skills');
+    assert.equal(held.body.adopted, true);
+    assert.deepEqual(held.body.enabled, ['recall']);
+    store.speciality.skills = ['recall', 'status'];
+  });
+
+  await test('GET /specialities/:id/skills is 404 for a speciality the caller cannot see', async () => {
+    const saved = store.speciality;
+    store.speciality = { ...saved, owner_builder_id: 2, visibility: 'private' };
+    const r = await call('GET', '/specialities/9/skills');
+    assert.equal(r.status, 404);
+    store.speciality = saved;
+  });
+
   await test('PUT /specialities/:id/skills needs an active adoption', async () => {
     store.adoption = null;
     const r = await call('PUT', '/specialities/9/skills', { enabled_skills: ['recall'] });

package/tests/speciality_walkthrough_ui.mjs

@@ -0,0 +1,218 @@
+// tests/speciality_walkthrough_ui.mjs — the skills walkthrough a person is taken
+// through when they adopt a speciality (task 1004073, part 2 of 3 of ADR 0310).
+//
+// The owner's ruling: an adopted speciality's skills start OFF, "and you should
+// walk through what comes with each, people need to learn the system". The task
+// names its own failure mode — "a settings page with eleven unchecked boxes
+// satisfies the letter and defeats the intent" — so these pin the SHAPE of the
+// flow, not just that a PUT happens: one skill at a time, the three answers on
+// every step, no control that decides without the person seeing each skill, and
+// nothing written until the recap is saved.
+//
+// This EXECUTES the real modules/hall-ui/public/settings-specialities.js in a vm
+// under a minimal DOM stub (the tests/goal_criterion_confirm_ui.mjs precedent —
+// there is no jsdom here), against a fake API, and drives real clicks through the
+// delegated handler the page wires.
+//
+// Run:  node tests/speciality_walkthrough_ui.mjs
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+import { makeRunner } from './helpers.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SRC = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/settings-specialities.js'), 'utf8');
+const { test, summary } = makeRunner();
+
+const explained = (name, extra = {}) => ({
+  name, installed: true, source: 'core',
+  does: `${name} does its one thing. And a second sentence.`,
+  reachFor: `When you would say something like “${name} please”.`,
+  cost: 'Read-only: it looks things up and changes nothing.',
+  commands: [`/${name}`], needs: [], rank: null,
+  derived: { does: true, reachFor: true, cost: true },
+  ...extra,
+});
+
+function speciality(over = {}) {
+  return {
+    id: 9, name: 'Economics', discipline: 'ideator', summary: 'Markets.', contract_md: '',
+    visibility: 'public', adoptable: true, mine: false, skills: ['recall', 'status', 'goal-review', 'gone'],
+    ...over,
+  };
+}
+
+const SKILLS_BODY = {
+  speciality: { id: 9, name: 'Economics', discipline: 'ideator' },
+  adopted: true,
+  enabled: [],
+  skills: [
+    explained('recall'),
+    explained('status'),
+    explained('goal-review', { rank: 'metic', needs: ['gh'] }),
+    { name: 'gone', installed: false },
+  ],
+};
+
+// Boot the page script and return a handle to drive it.
+async function boot({ catalog = [speciality()], skillsBody = SKILLS_BODY } = {}) {
+  const requests = [];
+  const toasts = [];
+  const els = new Map();
+  const handlers = new Map();
+  const makeEl = (id) => ({
+    id, hidden: id === 'specialities-scroll', innerHTML: '', textContent: '', elements: {},
+    addEventListener(type, fn) { handlers.set(`${id}:${type}`, fn); },
+  });
+  for (const id of ['specialities-scroll', 'specialities-rows', 'speciality-suggestions', 'specialities-status']) els.set(id, makeEl(id));
+  let focused = null;
+
+  const fetch = async (url, opts = {}) => {
+    const method = opts.method || 'GET';
+    const p = url.replace('/api/bongos', '');
+    requests.push({ method, path: p, body: opts.body ? JSON.parse(opts.body) : undefined });
+    let body = {};
+    if (method === 'GET' && p === '/specialities') body = { specialities: catalog };
+    else if (method === 'GET' && p === '/me/specialities') body = { adoptions: [] };
+    else if (method === 'GET' && p === '/specialities/offered') body = { suggestions: [] };
+    else if (method === 'GET' && /\/skills$/.test(p)) body = skillsBody;
+    else if (method === 'POST' && /\/adopt$/.test(p)) body = { adoption: { active: true } };
+    else if (method === 'PUT' && /\/skills$/.test(p)) body = { adoption: { enabled_skills: JSON.parse(opts.body).enabled_skills } };
+    return { ok: true, status: 200, json: async () => body };
+  };
+
+  const document = {
+    readyState: 'complete',
+    getElementById: (id) => els.get(id) || null,
+    addEventListener() {},
+    querySelector: (sel) => (sel.includes('data-walk-focus') ? { focus() { focused = 'walk-heading'; } } : null),
+  };
+  const window = {
+    OTB: {
+      escapeHtml: (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;'),
+      $: () => null,
+      toast: (m) => toasts.push(m),
+      roleAxisLabel: () => 'Role',
+    },
+    location: { assign() {} },
+  };
+  vm.runInNewContext(SRC, { window, document, fetch, JSON, Promise, Map, Set, String, Number, Array, Object, Math, RegExp, console });
+  const settle = () => new Promise((r) => setTimeout(r, 0));
+  for (let i = 0; i < 5; i++) await settle();
+
+  const rows = els.get('specialities-rows');
+  // A click through the delegated handler, on the first button whose attribute matches.
+  async function click(attr, value) {
+    const re = new RegExp(`<button[^>]*${attr}="${value}"[^>]*>`);
+    const tag = re.exec(rows.innerHTML);
+    assert.ok(tag, `no ${attr}="${value}" button in:\n${rows.innerHTML}`);
+    const dataset = {};
+    for (const [, k, v] of tag[0].matchAll(/data-([a-z]+)="([^"]*)"/g)) dataset[k] = v;
+    const btn = { dataset };
+    const target = { closest: (sel) => (sel === `button[${attr}]` ? btn : null) };
+    handlers.get('specialities-rows:click')({ target });
+    for (let i = 0; i < 6; i++) await settle();
+  }
+  const text = () => rows.innerHTML.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ');
+  return { els, rows, requests, toasts, click, text, focused: () => focused };
+}
+
+const writes = (h) => h.requests.filter((r) => r.method !== 'GET');
+
+await test('the specialities panel is revealed once its reads answer — it shipped hidden and nothing ever showed it', async () => {
+  const h = await boot();
+  assert.equal(h.els.get('specialities-scroll').hidden, false);
+});
+
+await test('adopting a speciality that offers skills opens the walkthrough on the FIRST skill, with nothing written yet', async () => {
+  const h = await boot();
+  await h.click('data-act', 'adopt');
+  assert.ok(h.requests.some((r) => r.method === 'GET' && r.path === '/specialities/9/skills'), 'the walkthrough read its skills');
+  assert.match(h.text(), /Skill 1 of 3 in Economics/, 'only INSTALLED skills are steps');
+  assert.equal(h.focused(), 'walk-heading', 'focus moves to the step, not left on a button that is gone');
+  assert.deepEqual(writes(h).map((r) => r.path), ['/specialities/9/adopt'], 'no enabled set was written by adopting');
+});
+
+await test('it is not a page of checkboxes: one skill per step, and no control decides for several at once', async () => {
+  const h = await boot();
+  await h.click('data-act', 'adopt');
+  assert.ok(!/type="checkbox"/.test(h.rows.innerHTML), 'no checkbox anywhere in the walkthrough');
+  assert.ok(!/(turn|enable|select) (them )?all/i.test(h.text()), 'no "turn them all on"');
+  assert.ok(h.text().includes('recall') && !h.text().includes('status does its one thing'), 'the next skill is not shown yet');
+});
+
+await test('every step answers what it does, when to reach for it, and what it costs', async () => {
+  const h = await boot();
+  await h.click('data-act', 'adopt');
+  for (let step = 0; step < 3; step++) {
+    const t = h.text();
+    for (const q of ['What it does', 'When to reach for it', 'What it costs']) assert.ok(t.includes(q), `step ${step + 1} is missing "${q}"`);
+    await h.click('data-walk', 'off');
+  }
+});
+
+await test('a rank-gated skill says so BEFORE the choice — turning it on grants nothing', async () => {
+  const h = await boot();
+  await h.click('data-act', 'adopt');
+  await h.click('data-walk', 'off');
+  await h.click('data-walk', 'off');
+  const t = h.text();
+  assert.match(t, /Skill 3 of 3/);
+  assert.match(t, /Metic rank or above.*does not change that/);
+  assert.match(t, /What it needs on your machine gh/);
+});
+
+await test('the recap names every skill with what it does and the choice made, then saves exactly the ones turned on', async () => {
+  const h = await boot();
+  await h.click('data-act', 'adopt');
+  await h.click('data-walk', 'on');
+  await h.click('data-walk', 'off');
+  await h.click('data-walk', 'on');
+  const t = h.text();
+  assert.match(t, /Your choices for Economics/);
+  assert.match(t, /2 of 3 turned on/);
+  for (const n of ['recall', 'status', 'goal-review']) assert.ok(t.includes(`${n} does its one thing.`), `the recap restates what ${n} does`);
+  assert.ok(!t.includes('And a second sentence'), 'one line each, not the whole description again');
+  assert.match(t, /no longer on this project.*gone/, 'an offered skill removed since is named, not offered');
+  assert.equal(writes(h).length, 1, 'still nothing written before Save');
+  await h.click('data-walk', 'save');
+  const put = writes(h).find((r) => r.method === 'PUT');
+  assert.ok(put, 'Save wrote the set');
+  assert.equal(put.path, '/specialities/9/skills');
+  assert.deepEqual(put.body, { enabled_skills: ['recall', 'goal-review'] });
+  assert.ok(h.toasts.some((m) => /2 of 3/.test(m)));
+});
+
+await test('Back revisits a decision and the new choice is the one saved', async () => {
+  const h = await boot();
+  await h.click('data-act', 'adopt');
+  await h.click('data-walk', 'on');
+  await h.click('data-walk', 'back');
+  assert.match(h.text(), /Skill 1 of 3/);
+  assert.match(h.rows.innerHTML, /data-walk="on" aria-pressed="true"/, 'the earlier choice shows when you step back to it');
+  await h.click('data-walk', 'off');
+  await h.click('data-walk', 'off');
+  await h.click('data-walk', 'off');
+  await h.click('data-walk', 'save');
+  assert.deepEqual(writes(h).find((r) => r.method === 'PUT').body, { enabled_skills: [] });
+});
+
+await test('finishing later writes nothing, so every skill stays off — the default the ruling asked for', async () => {
+  const h = await boot();
+  await h.click('data-act', 'adopt');
+  await h.click('data-walk', 'on');
+  await h.click('data-walk', 'close');
+  assert.ok(!/skill-walk/.test(h.rows.innerHTML), 'the walkthrough closed');
+  assert.ok(!writes(h).some((r) => r.method === 'PUT'), 'a half-finished walk saves nothing');
+});
+
+await test('a speciality that offers no skills adopts without a walkthrough', async () => {
+  const h = await boot({ catalog: [speciality({ skills: [] })] });
+  await h.click('data-act', 'adopt');
+  assert.ok(!h.requests.some((r) => /\/skills$/.test(r.path)), 'no skills read for a speciality with none');
+  assert.ok(!/skill-walk/.test(h.rows.innerHTML));
+});
+
+summary();