@bongos/core 1.21.151 → 1.21.152

package/modules/ui-design/module.json

@@ -4,6 +4,7 @@
   "description": "The platform capability that lets any builder on any instance create and design good-looking, functional UIs in line with that instance's world (scoped with the owner 2026-08-28; task 1003324, ADR 0197). It ships METHOD and never a world: the neutral design contract of ADR 0081 with its tool adapters (Claude Design, Figma), their sync CLIs and the validator; the /design playbook for ui-discipline work; the look-before-you-ship kit (kit/) and the style library (styles/). The thirteen design-style skills that lived in skills/ are the opt-in design-styles module since task 1004470; /design reaches them when that module is on. The instance's world — its branding pack, config/design-tokens.*, config/design-sources.json and its DESIGN.md — stays in config/ and at the repo root as the host boundary this module reads and never owns (ADR 0062 §7). Cloud Bongos's own front door is this module's first customer, not its owner. default-on because every instance has a face. No routes, no migrations, no port: declaration-only like character-anim, so disabling it withdraws only the skills it contributes and touches no served surface.",
   "version": "1.0.0",
   "coreVersion": "^1.19.0",
+  "category": { "parent": "pages" },
   "default": true,
   "maintenance": { "status": "core-maintained" },
   "contributes": { "skills": ["design", "design-sync", "figma-design-sync"], "disciplines": ["ui"] },

package/package-lock.json

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

package/package.json

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

@@ -9920,5 +9920,11 @@
       "id": "1004739",
       "text": "The module test runner can now test against the private core: the server sends its own copy of the core into the private test repo, once per version."
     }
+  ],
+  "1.21.152": [
+    {
+      "id": "1003784",
+      "text": "Every module now says which of the eight categories it belongs to, and the module list in the terminal and the hall's Modules tab both show it and let you search by it."
+    }
   ]
 }

package/scripts/gds/module.js

@@ -452,14 +452,16 @@ function formatCatalog(rows, { catalogOnly = false, query = '', core = null, del
     return out.join('\n');
   }
 
-  out.push(`  ${pad('', 5)}${pad('KEY', 20)}${pad('VERSION', 9)}${pad('SOURCE', 10)}${pad('AUTHOR', 20)}${pad('ORIGIN', 26)}${pad('LICENSE', 12)}UPKEEP`);
+  out.push(`  ${pad('', 5)}${pad('KEY', 20)}${pad('VERSION', 9)}${pad('SOURCE', 10)}${pad('CATEGORY', 28)}${pad('AUTHOR', 20)}${pad('ORIGIN', 26)}${pad('LICENSE', 12)}UPKEEP`);
   for (const r of shown) {
     const mark = r.enabled ? '[x]' : '[ ]';
     // An inferred credit is marked so it never reads as something the author
     // typed — the catalog's whole job is honest attribution (ADR 0107 §2).
     const suffix = r.credit.inferred ? '*' : '';
     const upkeep = ((r.maintenance && r.maintenance.status) || 'undeclared') + (delisted.has(r.key) ? ' · DELISTED' : '');
-    out.push(`  ${pad(mark, 5)}${pad(clip(r.key, 19), 20)}${pad(clip(r.version || '—', 8), 9)}${pad(r.source, 10)}${pad(clip((r.credit.author || '—') + suffix, 19), 20)}${pad(clip((r.credit.origin || '—') + suffix, 25), 26)}${pad(clip(r.license || '—', 11), 12)}${upkeep}`);
+    // The parent key, plus the sub-category once one is approved (ADR 0342).
+    const cat = r.category ? r.category.parent + (r.category.sub ? `/${r.category.sub}` : '') : '—';
+    out.push(`  ${pad(mark, 5)}${pad(clip(r.key, 19), 20)}${pad(clip(r.version || '—', 8), 9)}${pad(r.source, 10)}${pad(clip(cat, 27), 28)}${pad(clip((r.credit.author || '—') + suffix, 19), 20)}${pad(clip((r.credit.origin || '—') + suffix, 25), 26)}${pad(clip(r.license || '—', 11), 12)}${upkeep}`);
   }
   out.push('');
   out.push('  [x] enabled here · [ ] available, not enabled');

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.151'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.152'; // 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/src/module-loader/catalog.js

@@ -30,6 +30,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { deriveProvenance } = require('./provenance');
+const { CATEGORY_PARENTS } = require('./manifest-schema');
 
 // The core's own published + source package names. A checkout whose package.json
 // says one of these IS the core, so its modules/ IS the catalog (see
@@ -99,6 +100,17 @@ function creditFor(manifest = {}, { source = 'instance', coreProjectName = CORE_
   };
 }
 
+// Where a module is browsed (ADR 0342): its parent key, that parent's label, and its
+// sub-category key — or null when the manifest declares none. The label is resolved
+// HERE so the hall and the CLI never keep their own copy of the parent list. A parent
+// outside the closed list cannot reach this (the validator refuses it), so an unknown
+// one is null rather than shown under a label nobody chose.
+function categoryFor(manifest = {}) {
+  const c = manifest.category;
+  if (!c || typeof c !== 'object' || !Object.hasOwn(CATEGORY_PARENTS, c.parent)) return null;
+  return { parent: c.parent, parentTitle: CATEGORY_PARENTS[c.parent], sub: c.sub || null };
+}
+
 // One catalog row per discovered module. `loaded` is the loader's
 // discoverModules().loaded ([{ key, dir, manifest }]); `enabled` is the resolved
 // enablement map (src/modules.js modules()).
@@ -138,6 +150,7 @@ function buildCatalog({
         license: manifest.license || null,
         maintainer: manifest.maintainer || null,
         maintenance: manifest.maintenance || null,
+        category: categoryFor(manifest),
       };
     })
     .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
@@ -160,7 +173,8 @@ function instanceRows(rows = []) {
 function searchCatalog(rows = [], query = '') {
   const q = String(query || '').trim().toLowerCase();
   if (!q) return rows;
-  return rows.filter((r) => [r.key, r.title, r.description, r.credit.author, r.credit.origin, r.license]
+  return rows.filter((r) => [r.key, r.title, r.description, r.credit.author, r.credit.origin, r.license,
+    r.category && r.category.parentTitle, r.category && r.category.sub]
     .some((f) => f && String(f).toLowerCase().includes(q)));
 }
 

package/src/module-loader/manifest-schema.js

@@ -53,6 +53,10 @@
 //                                       //   actually declares in `contributes`, and every entry must be
 //                                       //   one it actually lists there — a typo'd exemption is an error,
 //                                       //   never a silent pass.
+//     "category": {                     // OPTIONAL. Where the module is browsed and ranked (ADR 0342).
+//       "parent": "money",              //   REQUIRED in-block: one of the eight CATEGORY_PARENTS keys.
+//       "sub":    "stripe-payments"     //   OPTIONAL. An approved sub-category key — the comparable set
+//     },                                //   the store's cap of ten counts within; absent while pending.
 //     "howto": {                        // OPTIONAL. Extras beside the module's HOWTO.md (ADR 0347 D3).
 //       "artifactUrl": "https://claude.ai/…" //   A Claude page with the same how-to, shown as an extra,
 //     },                                //   never graded and never required — the file is the how-to.
@@ -106,6 +110,24 @@ const SPEND_KEYS = ['requiresPayer'];
 // The `howto` block (ADR 0347 D3) — closed for the same reason; not exported either.
 const HOWTO_KEYS = ['artifactUrl'];
 
+// The eight fixed parent categories (ADR 0342 D1), key → the label a catalog shows.
+// A parent is for browsing only: the cap of ten counts within a SUB-category, never a
+// parent (D2). The list is closed so a typo'd "monye" fails loud rather than filing
+// the module under a ninth parent nobody browses; changing it needs a new ADR.
+// `sub` is shape-checked only — which sub-categories are approved is ledger state
+// (task 1004355), not something a pure validator can know.
+const CATEGORY_PARENTS = Object.freeze({
+  work: 'Work & planning',
+  people: 'Team & people',
+  quality: 'Quality & review',
+  money: 'Money',
+  communication: 'Communication',
+  pages: 'Pages & design',
+  hosting: 'Hosting & deploy',
+  knowledge: 'Knowledge',
+});
+const CATEGORY_KEYS = ['parent', 'sub'];
+
 // An https link on claude.ai (or a subdomain). Shape only: the store never fetches it.
 function isClaudeArtifactUrl(v) {
   if (!isStr(v)) return false;
@@ -320,6 +342,23 @@ function validateManifest(obj) {
     }
   }
 
+  // --- optional category (ADR 0342) ---
+  if ('category' in obj) {
+    const c = obj.category;
+    const parents = Object.keys(CATEGORY_PARENTS);
+    if (!isObj(c)) E('category: must be an object (e.g. { "parent": "money", "sub": "stripe-payments" })');
+    else {
+      for (const k of Object.keys(c)) {
+        if (!CATEGORY_KEYS.includes(k)) E(`category.${k}: unknown key (allowed: ${CATEGORY_KEYS.join(', ')}) — a module has exactly one sub-category (ADR 0342 D4)`);
+      }
+      if (!isStr(c.parent)) E(`category.parent: required — one of ${parents.join(', ')}`);
+      else if (!parents.includes(c.parent)) E(`category.parent: "${c.parent}" is not one of ${parents.join(', ')} (ADR 0342 D1)`);
+      if ('sub' in c && (!isStr(c.sub) || !KEY_RE.test(c.sub))) {
+        E('category.sub: must be a sub-category key (lowercase kebab-case) when present — leave it out while a new one is pending approval');
+      }
+    }
+  }
+
   // --- optional how-to extras (ADR 0347 D3) ---
   if ('howto' in obj) {
     const h = obj.howto;
@@ -370,5 +409,5 @@ function assertValidManifest(obj, label = 'module.json') {
 
 module.exports = {
   validateManifest, assertValidManifest, declaredEntries, entryLabel, KEY_RE, ALLOWED_CONTRIBUTES, ARRAY_OF_STRING_KEYS, ATTRIBUTION_KEYS,
-  MAINTENANCE_STATUSES, MAINTENANCE_KEYS, SUNSET_STATUSES,
+  MAINTENANCE_STATUSES, MAINTENANCE_KEYS, SUNSET_STATUSES, CATEGORY_PARENTS,
 };

package/tests/hall_catalog_world.mjs

@@ -58,7 +58,7 @@ test('modules: the row is the oversight row — title with the mono key, clamped
   assert.match(js, /<span class="ov-row__title">\$\{escapeHtml\(m\.title \|\| m\.key\)\}<span class="ov-mono">\$\{escapeHtml\(m\.key\)\}<\/span>/, 'the key rides inside the title in mono');
   assert.match(js, /class="ov-row__sub mod-row__desc"/, 'the description is the sub line');
   assert.match(js, /<details class="mod-more"/, 'a details disclosure opens the rest');
-  assert.match(js, /<div class="ov-row__facts">\$\{provenancePill\(m\)\}\$\{attributionFacts\(m\)\}\$\{upkeepFact\(m\)\}\$\{howtoFact\(m\)\}\$\{delistedFact\(m\)\}\$\{restartFact\(m\)\}<\/div>/, 'provenance, credit, upkeep, (for a store version, task 1004366) the how-to link and (task 1003797) the delisted pill and (task 1004463) the waits-for-a-restart pill are the facts line');
+  assert.match(js, /<div class="ov-row__facts">\$\{provenancePill\(m\)\}\$\{categoryFact\(m\)\}\$\{attributionFacts\(m\)\}\$\{upkeepFact\(m\)\}\$\{howtoFact\(m\)\}\$\{delistedFact\(m\)\}\$\{restartFact\(m\)\}<\/div>/, 'provenance, (task 1003784) the category, credit, upkeep, (for a store version, task 1004366) the how-to link and (task 1003797) the delisted pill and (task 1004463) the waits-for-a-restart pill are the facts line');
   assert.match(js, /<div class="ov-row__right mod-row__right">\$\{rightHtml\(m\)\}<\/div>/, 'the right column is one function');
   const css = read('modules.css');
   assert.match(css, /\.mod-row__desc \{[^}]*-webkit-line-clamp: 2/, 'the description clamps to two lines');
@@ -84,6 +84,9 @@ test('modules: upkeep colours the exception — undeclared is the warn pill, mai
   assert.match(js, /<span class="ov-fact">upkeep <b>\$\{escapeHtml\(status\)\}<\/b><\/span>/, 'a maintained module reads as a plain fact');
   assert.match(js, /fact-pill fact-pill--info">core-loaded</, 'core-loaded is the info pill');
   assert.match(js, /<span class="fact-chip">\$\{escapeHtml\(m\.license\)\}<\/span>/, 'the licence is a chip');
+  assert.match(js, /<span class="ov-fact">in <b>\$\{escapeHtml\(c\.parentTitle\)\}<\/b>\$\{sub\}<\/span>/,
+    'the category is a plain fact, labelled from the server row (task 1003784)');
+  assert.match(js, /cat\.parentTitle, cat\.sub\]/, 'the hall search covers the category, as searchCatalog does');
 });
 
 test('modules: the kit filter bar carries the search and a state lens, and the empty state is the kit\'s', () => {

package/tests/module_catalog.mjs

@@ -330,3 +330,37 @@ test('detectRoots: an explicit root bypasses the memo in both directions', () =>
   // …nor poison the memo for every later caller that asks about this process.
   assert.equal(catalog.detectRoots(), cached);
 });
+
+// ---------------------------------------------------------------------------
+// category — the ADR 0342 field, carried by the ONE model to both surfaces (task 1003784)
+// ---------------------------------------------------------------------------
+
+const categorized = () => catalog.buildCatalog({
+  loaded: [
+    loadedIn(CORE, 'economy', { category: { parent: 'money' } }),
+    loadedIn(CORE, 'discord', { category: { parent: 'communication', sub: 'team-chat' } }),
+    loadedIn(INST, 'game'),
+  ],
+  coreRoot: CORE, instanceRoot: INST,
+});
+
+test('buildCatalog: a row carries its category with the parent label; none declared is null', () => {
+  const byKey = Object.fromEntries(categorized().map((r) => [r.key, r]));
+  assert.deepEqual(byKey.economy.category, { parent: 'money', parentTitle: 'Money', sub: null });
+  assert.deepEqual(byKey.discord.category, { parent: 'communication', parentTitle: 'Communication', sub: 'team-chat' });
+  assert.equal(byKey.game.category, null);
+});
+
+test('searchCatalog: finds a module by its category label or sub-category', () => {
+  const rows = categorized();
+  assert.deepEqual(catalog.searchCatalog(rows, 'money').map((r) => r.key), ['economy']);
+  assert.deepEqual(catalog.searchCatalog(rows, 'team-chat').map((r) => r.key), ['discord']);
+});
+
+test('formatCatalog: the CATEGORY column shows parent/sub, and a dash when none is declared', () => {
+  const out = mod.formatCatalog(categorized());
+  assert.match(out, /CATEGORY/);
+  assert.match(out, /discord\s+\S+\s+core\s+communication\/team-chat/);
+  assert.match(out, /economy\s+\S+\s+core\s+money\s/);
+  assert.match(out, /game\s+\S+\s+instance\s+—\s/);
+});

package/tests/module_manifest.mjs

@@ -392,3 +392,39 @@ test('howto.artifactUrl: anything but an https claude.ai link is refused, as is
     .some((e) => e.startsWith('howto.artifactURL: unknown key')));
   assert.equal(validateManifest({ ...baseManifest(), howto: 'https://claude.ai/x' }).valid, false);
 });
+
+// --- category (ADR 0342, task 1003784) ---
+
+test('category: optional; a known parent, with or without a sub-category, is accepted', () => {
+  assert.equal(validateManifest(baseManifest()).valid, true, 'a manifest with no category still validates');
+  for (const category of [{ parent: 'money' }, { parent: 'communication', sub: 'team-chat' }]) {
+    const r = validateManifest({ ...baseManifest(), category });
+    assert.equal(r.valid, true, `${JSON.stringify(category)}: ${r.errors.join('; ')}`);
+  }
+});
+
+test('category: a parent outside the eight, a missing parent, a bad sub or an unknown key fails loud', () => {
+  const errs = (category) => validateManifest({ ...baseManifest(), category }).errors;
+  assert.ok(errs({ parent: 'monye' }).some((e) => e.startsWith('category.parent: "monye" is not one of')), 'a typo names the list');
+  assert.ok(errs({ sub: 'stripe-payments' }).some((e) => e.startsWith('category.parent: required')));
+  assert.ok(errs({ parent: 'money', sub: 'Stripe Payments' }).some((e) => e.startsWith('category.sub:')));
+  assert.ok(errs({ parent: 'money', sub: '' }).some((e) => e.startsWith('category.sub:')));
+  assert.ok(errs({ parent: 'money', subs: ['a', 'b'] }).some((e) => e.startsWith('category.subs: unknown key')),
+    'one sub-category per module (D4) — a second field is a typo, not a list');
+  assert.equal(validateManifest({ ...baseManifest(), category: 'money' }).valid, false);
+});
+
+test('category: the eight parents are exactly ADR 0342 D1', () => {
+  const { CATEGORY_PARENTS } = require(path.join(ROOT, 'src', 'module-loader', 'manifest-schema.js'));
+  assert.deepEqual(Object.keys(CATEGORY_PARENTS),
+    ['work', 'people', 'quality', 'money', 'communication', 'pages', 'hosting', 'knowledge']);
+});
+
+test('category: every bundled module declares one (core modules get categories too, ADR 0342)', async () => {
+  const fs = await import('node:fs');
+  const dir = path.join(ROOT, 'modules');
+  const missing = fs.readdirSync(dir)
+    .filter((k) => fs.existsSync(path.join(dir, k, 'module.json')))
+    .filter((k) => !JSON.parse(fs.readFileSync(path.join(dir, k, 'module.json'), 'utf8')).category);
+  assert.deepEqual(missing, [], `declare "category": { "parent": … } in: ${missing.join(', ')}`);
+});