@bongos/core 1.20.43 → 1.20.45

package/tests/hall_commands.mjs

@@ -0,0 +1,162 @@
+// tests/hall_commands.mjs — the hall's Commands page (task 1004473): one table
+// of every skill and one of every bongos CLI verb, read from live sources.
+//
+// The done-when pins: every SKILL.md the instance has, and every bin/bongos.js
+// VERBS entry, appears on the page EXACTLY once. They are checked against the
+// real tree — the same installedSkills()+explainSkill() the
+// /specialities/installed-skills route serves, and the same cliCommands() the
+// /cli/commands route serves — rendered through the page's own lib.
+//
+// Run:  node --test tests/hall_commands.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const lib = require('../modules/hall-ui/public/commands-lib.js');
+const kit = require('../modules/hall-ui/public/hall-kit.js');
+const skills = require('../modules/specialities/skills.js');
+const { VERBS, GROUPS } = require('../bin/bongos.js');
+const esc = kit.esc;
+
+// Every SKILL.md on disk, by name: core .claude/skills/ plus every module's skills/.
+function skillDirsOnDisk({ modules = () => true } = {}) {
+  const out = [];
+  const scan = (dir) => {
+    let names = [];
+    try { names = fs.readdirSync(dir); } catch { return; }
+    for (const n of names) if (fs.existsSync(path.join(dir, n, 'SKILL.md'))) out.push({ name: n, md: path.join(dir, n, 'SKILL.md') });
+  };
+  scan(path.join(ROOT, '.claude', 'skills'));
+  for (const key of fs.readdirSync(path.join(ROOT, 'modules'))) if (modules(key)) scan(path.join(ROOT, 'modules', key, 'skills'));
+  return out;
+}
+
+// What the route hands the page: installedSkills() explained, exactly as
+// GET /specialities/installed-skills builds it.
+function servedSkills(isModuleEnabled) {
+  return [...skills.installedSkills({ coreRoot: ROOT, isModuleEnabled })]
+    .map(([name, entry]) => skills.explainSkill({ name, ...entry }));
+}
+
+const count = (html, attr, value) => html.split(`${attr}="${value}"`).length - 1;
+
+test('every SKILL.md in the tree appears on the page exactly once (every module on)', () => {
+  const html = lib.skillsTableHtml(lib.groupSkills(servedSkills(() => true)), { esc });
+  const onDisk = skillDirsOnDisk();
+  assert.ok(onDisk.length >= 48, `expected the real skill tree, found ${onDisk.length}`);
+  for (const { name } of onDisk) assert.equal(count(html, 'data-skill', name), 1, `/${name} should appear exactly once`);
+  assert.equal(count(html, 'data-skill', ''), 0, 'no nameless row');
+  assert.equal(html.split('data-skill="').length - 1, new Set(onDisk.map((s) => s.name)).size, 'no row that is not a SKILL.md');
+});
+
+test('a default instance shows its enabled modules\' skills and NOT a disabled module\'s', () => {
+  const defaults = (key) => {
+    try { return JSON.parse(fs.readFileSync(path.join(ROOT, 'modules', key, 'module.json'), 'utf8')).default === true; } catch { return false; }
+  };
+  const html = lib.skillsTableHtml(lib.groupSkills(servedSkills(defaults)), { esc });
+  for (const { name } of skillDirsOnDisk({ modules: defaults })) assert.equal(count(html, 'data-skill', name), 1, `/${name} should appear exactly once`);
+  for (const { name } of skillDirsOnDisk({ modules: (k) => k === 'pixel-art' || k === 'design-styles' })) {
+    if (fs.existsSync(path.join(ROOT, '.claude', 'skills', name, 'SKILL.md'))) continue;
+    assert.equal(count(html, 'data-skill', name), 0, `/${name} ships in a default-off module, so it must not be listed`);
+  }
+});
+
+test('each row carries the SKILL.md plain / reach-for / cost words', () => {
+  const served = servedSkills(() => true);
+  const html = lib.skillsTableHtml(lib.groupSkills(served), { esc });
+  const ship = served.find((s) => s.name === 'builder-ship');
+  const fm = skills.parseFrontmatter(fs.readFileSync(path.join(ROOT, '.claude/skills/builder-ship/SKILL.md'), 'utf8'));
+  assert.equal(ship.does, fm.plain);
+  assert.equal(ship.reachFor, fm['reach-for']);
+  assert.equal(ship.cost, fm.cost);
+  for (const v of [fm.plain, fm['reach-for'], fm.cost]) assert.ok(html.includes(esc(v)), `page shows: ${v}`);
+});
+
+test('the "type it yourself" marker follows disable-model-invocation, skill by skill', () => {
+  const served = servedSkills(() => true);
+  const html = lib.skillsTableHtml(lib.groupSkills(served), { esc });
+  let typed = 0;
+  for (const { name, md } of skillDirsOnDisk()) {
+    const hidden = skills.parseFrontmatter(fs.readFileSync(md, 'utf8'))['disable-model-invocation'] === 'true';
+    if (hidden) typed++;
+    const row = html.slice(html.indexOf(`data-skill="${name}"`)).split('</tr>')[0];
+    assert.match(row, hidden ? /cmd-how--typed/ : /cmd-how--listed/, `/${name}: ${hidden ? 'typed-only' : 'shown to Claude'}`);
+  }
+  assert.ok(typed > 0, 'the tree has typed-only skills (task 1004471), so the marker is exercised');
+});
+
+test('a skill no group names still gets a row, under Everything else', () => {
+  const groups = lib.groupSkills([{ name: 'brand-new-skill', source: 'core', does: 'x' }, { name: 'builder-ship', source: 'core' }]);
+  assert.deepEqual(groups.map((g) => g.key), ['loop', 'other']);
+  assert.equal(lib.groupKeyOf({ name: 'otb-tile-generate', source: 'module:pixel-art' }), 'design', 'a module\'s skills land in its group');
+  const loop = lib.groupSkills([{ name: 'builder-ship' }, { name: 'builder-claim' }, { name: 'builder-start' }].map((x) => ({ ...x, source: 'core' })));
+  assert.deepEqual(loop[0].skills.map((x) => x.name), ['builder-start', 'builder-claim', 'builder-ship'], 'the loop reads in the order you work it');
+});
+
+test('row text is escaped — a skill cannot inject markup into the hall', () => {
+  const html = lib.skillsTableHtml(lib.groupSkills([{ name: 'x', source: 'core', does: '<img src=x onerror=alert(1)>' }]), { esc });
+  assert.ok(!html.includes('<img'), html);
+});
+
+const { cliCommands } = require('../src/bongos/routes/cli-commands.js');
+
+test('every bin/bongos.js VERBS entry appears exactly once, grouped like `bongos --help`', () => {
+  const groups = cliCommands();
+  const html = lib.cliTableHtml(groups, { esc });
+  for (const verb of Object.keys(VERBS)) assert.equal(count(html, 'data-verb', verb), 1, `bongos ${verb} should appear exactly once`);
+  assert.equal(html.split('data-verb="').length - 1, Object.keys(VERBS).length, 'no row that is not a verb');
+  assert.deepEqual(groups.map((g) => g.label), GROUPS.map(([, label]) => label), 'the help\'s group order');
+  for (const g of groups) for (const c of g.commands) assert.equal(c.summary, VERBS[c.verb].summary, `${c.verb}: the help line, verbatim`);
+});
+
+test('a verb in a group GROUPS does not name is still listed', () => {
+  const groups = cliCommands({ GROUPS: [['work', 'Work']], VERBS: { a: { group: 'work', summary: 'A' }, b: { group: 'new', summary: 'B' } } });
+  assert.deepEqual(groups.map((g) => [g.key, g.commands.map((c) => c.verb)]), [['work', ['a']], ['other', ['b']]]);
+});
+
+test('GET /cli/commands serves the verbs to a signed-in builder and refuses a stranger', async () => {
+  const auth = require('../src/bongos/auth.js');
+  const express = require('express');
+  const build = require('../src/bongos/routes/cli-commands.js');
+  const serve = async (app, fn) => {
+    const server = http.createServer(app);
+    await new Promise((r) => server.listen(0, '127.0.0.1', r));
+    try { return await fn(`http://127.0.0.1:${server.address().port}`); } finally { server.close(); }
+  };
+
+  const saved = auth.requireBuilder;
+  auth.requireBuilder = (req, _res, next) => { req.builder = { id: 1, rank: 'xenos' }; next(); };
+  let signedIn;
+  try {
+    const app = express();
+    app.use(build());
+    signedIn = await serve(app, async (base) => { const r = await fetch(`${base}/cli/commands`); return { status: r.status, body: await r.json() }; });
+  } finally { auth.requireBuilder = saved; }
+  assert.equal(signedIn.status, 200);
+  assert.deepEqual(signedIn.body.groups.flatMap((g) => g.commands.map((c) => c.verb)).sort(), Object.keys(VERBS).sort());
+
+  const gated = express();
+  gated.use((req, res, next) => { res.fail = (code, st) => res.status(typeof st === 'number' ? st : 401).json({ error: code }); next(); });
+  gated.use(build());
+  const stranger = await serve(gated, async (base) => (await fetch(`${base}/cli/commands`)).status);
+  assert.ok(stranger === 401 || stranger === 403, `no session → refused (got ${stranger})`);
+});
+
+test('the page is wired: nav entry in Docs, sign-in gated, both reads, no hand-typed command', () => {
+  const page = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/commands.html'), 'utf8');
+  const js = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/commands.js'), 'utf8');
+  assert.match(js, /\/api\/bongos\/specialities\/installed-skills/);
+  assert.match(js, /\/api\/bongos\/cli\/commands/);
+  assert.ok(!/data-skill=|data-verb=|\/builder-ship|bongos claim/.test(page), 'the HTML names no command — the rows are generated');
+  const shell = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/shell.js'), 'utf8');
+  assert.match(shell, /id: 'commands', label: 'Commands', icon: 'docs', href: '\/commands', gate: 'signed'/);
+  const serveInternal = fs.readFileSync(path.join(ROOT, 'src/bongos/serve-internal.js'), 'utf8');
+  assert.match(serveInternal.match(/const SIGNEDIN_BUILDERS_PAGE_RE =\s*(\/.*\/);/)[1], /\|commands\)/);
+});

package/tests/hall_lead_row_home.mjs

@@ -0,0 +1,21 @@
+// .ov-row--lead is rendered only by the Collab page, so its grid rule lives in
+// collab.css, not oversight.css (task 1003637).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+
+const read = (f) => readFileSync(new URL(`../modules/hall-ui/public/${f}`, import.meta.url), 'utf8');
+
+test('oversight.css no longer defines .ov-row--lead', () => {
+  assert.doesNotMatch(read('oversight.css'), /\.ov-row--lead/);
+});
+
+test('collab.css owns the base rule and its 640px companion', () => {
+  const css = read('collab.css');
+  assert.match(css, /^\.ov-row--lead \{ grid-template-columns: auto minmax\(0, 1fr\) auto; \}/m);
+  assert.match(css, /@media \(max-width: 640px\) \{\s*\.ov-row--lead \{[^}]*\}\s*\.ov-row--lead > \.ov-row__right \{ grid-column: 2; \}/);
+});
+
+test('collab.js still renders the class, so the rule is not dead', () => {
+  assert.match(read('collab.js'), /ov-row--lead/);
+});

package/tests/hall_nav.mjs

@@ -285,8 +285,10 @@ test('sidebar groups read by audience, in order', () => {
   // what made this group read as one real page plus a link into the home page.
   assert.deepEqual(nav[2].items.map((i) => i.id), ['collab', 'roster'], 'Community = everyone else, in this project');
   assert.ok(!nav.flatMap((g) => g.items).some((i) => /^\/people\b/.test(i.href)), 'no nav item points at the deleted /people');
+  // task 1004473: 'commands' — every skill and CLI verb, read live — is reference
+  // material that reads the same for every builder, so it joins Docs.
   assert.deepEqual(nav[3].items.map((i) => i.id),
-    ['primer', 'ranks', 'economy', 'diagrams', 'atlas', 'modules', 'apidocs'], 'Docs = reference material');
+    ['primer', 'ranks', 'economy', 'commands', 'diagrams', 'atlas', 'modules', 'apidocs'], 'Docs = reference material');
   // 'government' (the Permissions tab, BV1.R113) is the group's one archon-gated item.
   // 'project-settings' joins the Government group at the metic floor (task 1003280,
   // goal 1000072) — it sits before 'government', which is the one archon-only item.

package/tests/hall_page_gate_map.mjs

@@ -46,6 +46,9 @@ const ORACLE = {
   '/builders/settings': 'requireBuilderPage',
   '/builders/atlas': 'requireBuilderPage',
   '/builders/modules': 'requireBuilderPage',
+  // task 1004473: the Commands page — its two reads (installed skills, CLI verbs)
+  // are requireBuilder, so sign-in is the whole gate.
+  '/builders/commands': 'requireBuilderPage',
   '/builders/goals': 'requireBuilderPage',
   // task 1003479: the goal map, on the goal board's tier. task 1004232 (sky part 4):
   // the URL now serves THE PROJECT SKY (the same page as /thinking, in its whole-project

package/tests/hall_tweak_editor.mjs

@@ -635,7 +635,7 @@ try {
     assert.match(HTML, /<body data-page="tweak-editor"[^>]*data-fullscreen-switch/);
     assert.equal((HTML.match(/<h1\b/g) || []).length, 1);
     assert.ok(HTML.indexOf('tweak-editor-lib.js') < HTML.indexOf('tweak-editor.js?'), 'the lib loads first');
-    assert.match(HTML, /shell\.js\?v=2026-09-29-renderdeploy/);
+    assert.match(HTML, /shell\.js\?v=2026-09-30-commands/);
     assert.equal(/fonts\.googleapis\.com\/css/.test(HTML), false);
     for (const id of ['tw-bar', 'tw-counter', 'tw-open', 'tw-open-more', 'tw-divider', 'tw-openwrap', 'tw-open-menu', 'tw-open-tab', 'tw-open-split', 'tw-frame', 'tw-frame-view', 'tw-split-close', 'tw-download', 'tw-upload', 'tw-file', 'tw-submit', 'tw-paper', 'tw-doc', 'tw-notice', 'tw-done', 'tw-take', 'tw-pick', 'tw-picks', 'tw-refused', 'tw-refused-title', 'tw-refused-list', 'tw-refused-next', 'tw-refused-download', 'tw-refused-close']) {
       assert.ok(new RegExp(`id="${id}"`).test(HTML), `#${id} is in the markup`);

package/tests/module_manifest.mjs

@@ -370,3 +370,25 @@ test('every bundled module with a declarativeSeams block validates against its o
   }
   assert.deepEqual(bad, [], bad.join('\n'));
 });
+
+// --- howto.artifactUrl (ADR 0347 D3, task 1004365) ---
+
+test('howto.artifactUrl: optional, and an https claude.ai link is accepted', () => {
+  assert.equal(validateManifest(baseManifest()).valid, true);
+  for (const url of ['https://claude.ai/artifact/abc123', 'https://claude.ai/code/artifact/0b1c']) {
+    const r = validateManifest({ ...baseManifest(), howto: { artifactUrl: url } });
+    assert.equal(r.valid, true, `${url}: ${r.errors.join('; ')}`);
+  }
+});
+
+test('howto.artifactUrl: anything but an https claude.ai link is refused, as is an unknown key', () => {
+  for (const url of ['http://claude.ai/artifact/x', 'https://evil.example/claude.ai', 'https://claude.ai.evil.example/x',
+    'https://user:pw@claude.ai/x', 'javascript:alert(1)', '', 42]) {
+    const r = validateManifest({ ...baseManifest(), howto: { artifactUrl: url } });
+    assert.equal(r.valid, false, String(url));
+    assert.ok(r.errors.some((e) => e.startsWith('howto.artifactUrl')), r.errors.join('; '));
+  }
+  assert.ok(validateManifest({ ...baseManifest(), howto: { artifactURL: 'https://claude.ai/x' } }).errors
+    .some((e) => e.startsWith('howto.artifactURL: unknown key')));
+  assert.equal(validateManifest({ ...baseManifest(), howto: 'https://claude.ai/x' }).valid, false);
+});

package/tests/module_store_publish.mjs

@@ -27,12 +27,21 @@ function moduleJson(over = {}) {
   };
 }
 
-// A temp modules/ root holding one module. files: { relPath: content }.
+// A how-to with all five required sections (ADR 0347 D2).
+const HOWTO = [
+  '# Weather', '', '## What it does', 'Shows the weather.', '', '## Install and enable',
+  '`bongos module install weather`, then switch it on.', '', '## How to use it', 'Open /weather.', '',
+  '## Configuration', 'None.', '', '## Limits and known issues', 'None known.', '',
+].join('\n');
+
+// A temp modules/ root holding one module. files: { relPath: content }; a null
+// content leaves that file out.
 function fixture(files = {}, mj = moduleJson()) {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'mod-publish-'));
   const dir = path.join(root, mj.key);
-  const all = { 'module.json': JSON.stringify(mj, null, 2), 'routes/weather.js': 'module.exports = () => null;\n', ...files };
+  const all = { 'module.json': JSON.stringify(mj, null, 2), 'routes/weather.js': 'module.exports = () => null;\n', 'HOWTO.md': HOWTO, ...files };
   for (const [rel, body] of Object.entries(all)) {
+    if (body === null) continue;
     fs.mkdirSync(path.dirname(path.join(dir, rel)), { recursive: true });
     fs.writeFileSync(path.join(dir, rel), body);
   }
@@ -54,12 +63,12 @@ function retar(tgz, edit) {
 test('pack: the tarball is the core release format — package/ root, inner manifest, a tree pin', async () => {
   const { tgz, manifest, sidecar } = pack(fixture());
   const names = format.readTar(tgz).map((e) => e.name).sort();
-  assert.deepEqual(names, ['package/.bongos-module.json', 'package/module.json', 'package/routes/weather.js']);
+  assert.deepEqual(names, ['package/.bongos-module.json', 'package/HOWTO.md', 'package/module.json', 'package/routes/weather.js']);
   assert.equal(manifest.artifact, 'bongos-module');
   assert.equal(manifest.module_key, 'weather');
   assert.equal(manifest.module_version, '1.2.0');
   assert.equal(manifest.core_version, '^1.0.0');
-  assert.equal(manifest.file_count, 2);
+  assert.equal(manifest.file_count, 3);
   assert.equal(manifest.tree_sha256, format.canonicalTreeHash(manifest.files));
   assert.equal(sidecar.tarball.sha256, format.sha256hex(tgz));
   assert.equal(sidecar.tarball.name, 'bongos-module-weather-1.2.0.tgz');
@@ -302,6 +311,81 @@ test('cli: uploads the packed bytes, and a store refusal is a failure exit with
   assert.ok(out.lines.some((l) => /HTTP 409/.test(l) && /already published/.test(l)));
 });
 
+// ---- the how-to gate (ADR 0347, task 1004365) -----------------------------------
+
+test('howto: a complete how-to passes, headings in any order and any case', () => {
+  assert.deepEqual(artifact.checkHowto(HOWTO), { ok: true, problems: [] });
+  const reordered = HOWTO.replace('## Configuration\nNone.\n', '').replace('# Weather', '# Weather\n## CONFIGURATION\nNone.');
+  assert.equal(artifact.checkHowto(reordered).ok, true);
+});
+
+test('howto: a missing file, a missing section and an empty section are each refused by name', () => {
+  assert.deepEqual(artifact.checkHowto(null).problems, ['HOWTO.md is missing — every store module ships one (ADR 0347)']);
+  assert.deepEqual(artifact.checkHowto(HOWTO.replace('## Configuration\nNone.\n', '')).problems,
+    ['HOWTO.md: section "Configuration" is missing']);
+  assert.deepEqual(artifact.checkHowto(HOWTO.replace('Open /weather.', '')).problems,
+    ['HOWTO.md: section "How to use it" is empty']);
+});
+
+test('howto: a prompt in a comment, a sub-heading alone, or a heading inside a code fence does not count', () => {
+  assert.deepEqual(artifact.checkHowto(HOWTO.replace('None known.', '<!-- say what goes wrong -->')).problems,
+    ['HOWTO.md: section "Limits and known issues" is empty']);
+  assert.deepEqual(artifact.checkHowto(HOWTO.replace('None known.', '### Later')).problems,
+    ['HOWTO.md: section "Limits and known issues" is empty']);
+  const fenced = HOWTO.replace('## Configuration\nNone.\n', '').replace('Open /weather.', 'Open /weather.\n```\n## Configuration\n```');
+  assert.deepEqual(artifact.checkHowto(fenced).problems, ['HOWTO.md: section "Configuration" is missing']);
+});
+
+test('howto: the scaffold\'s template has every section but fails the gate until it is written', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'mod-howto-'));
+  moduleCli.scaffoldModule({ key: 'weather', modulesDir: root, core: '1.0.0' });
+  const text = fs.readFileSync(path.join(root, 'weather', 'HOWTO.md'), 'utf8');
+  const res = artifact.checkHowto(text);
+  assert.deepEqual(res.problems, artifact.HOWTO_SECTIONS.map((s) => `HOWTO.md: section "${s}" is empty`));
+});
+
+test('howto: the file is packed into the tarball, so its hash pins it to the version', async () => {
+  const v = await artifact.verifyModuleArtifact(pack(fixture()).tgz, { key: 'weather', requireHowto: true });
+  assert.equal(v.ok, true, v.message);
+  assert.ok(v.manifest.files.some((f) => f.path === 'HOWTO.md'));
+});
+
+test('howto: verify refuses an incomplete how-to only when asked, so older versions still install', async () => {
+  const tgz = pack(fixture({ 'HOWTO.md': null })).tgz;
+  assert.equal((await artifact.verifyModuleArtifact(tgz, { key: 'weather' })).ok, true, 'install/update verify is unchanged');
+  const v = await artifact.verifyModuleArtifact(tgz, { key: 'weather', requireHowto: true });
+  assert.equal(v.code, 'howto_incomplete');
+  assert.match(v.message, /HOWTO\.md is missing/);
+});
+
+test('cli: publish refuses a missing or incomplete how-to by name, before anything is uploaded', async () => {
+  for (const [files, re] of [
+    [{ 'HOWTO.md': null }, /HOWTO\.md is missing/],
+    [{ 'HOWTO.md': HOWTO.replace('## Configuration\nNone.\n', '') }, /section "Configuration" is missing/],
+    [{ 'HOWTO.md': HOWTO.replace('Shows the weather.', '') }, /section "What it does" is empty/],
+  ]) {
+    const out = sink();
+    let uploaded = false;
+    const code = await moduleCli.cmdPublish(['weather'], {
+      log: out.log, errlog: out.log, modulesDir: fixture(files), upload: async () => { uploaded = true; },
+    });
+    assert.equal(code, 1);
+    assert.equal(uploaded, false);
+    assert.ok(out.lines.some((l) => re.test(l)), out.lines.join('\n'));
+  }
+});
+
+test('cli: module check reports the how-to as advice and never fails an upstream check on it', () => {
+  const out = sink();
+  const code = moduleCli.cmdCheck(['weather'], {
+    log: out.log, errlog: out.log,
+    check: () => ({ ok: true, findings: [] }),
+    howtoCheck: () => artifact.checkHowto(null),
+  });
+  assert.equal(code, 0);
+  assert.ok(out.lines.some((l) => /HOWTO\.md is missing/.test(l) && /bongos module publish/.test(l)));
+});
+
 test('cli: no key is a usage error', async () => {
   assert.equal(await moduleCli.cmdPublish([], { log: () => {}, errlog: () => {} }), 2);
 });

package/tests/module_store_publish_route.mjs

@@ -66,13 +66,17 @@ async function invoke(handle, req) {
   return res;
 }
 
-function packed(version = '1.0.0') {
+// A how-to with all five required sections (ADR 0347 D2).
+const HOWTO = artifact.HOWTO_SECTIONS.map((h) => `## ${h}\nSome text.\n`).join('\n');
+
+function packed(version = '1.0.0', { howto = HOWTO } = {}) {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'mod-src-'));
   const dir = path.join(root, 'weather');
   fs.mkdirSync(dir);
   fs.writeFileSync(path.join(dir, 'module.json'), JSON.stringify({
     key: 'weather', title: 'Weather', description: 'd', version, coreVersion: '^1.0.0', contributes: {},
   }));
+  if (howto !== null) fs.writeFileSync(path.join(dir, 'HOWTO.md'), howto);
   return artifact.packModule('weather', { modulesDir: root, modeOf: () => '644' }).tgz;
 }
 
@@ -119,3 +123,18 @@ test('a tarball for another key, garbage, or no body is refused before the regis
   assert.equal((await invoke(route.handle, { params: { key: 'Bad_Key' }, body: packed(), builder: { id: 42 } })).body.error, 'bad_module_key');
   assert.equal(state.versions.length, before);
 });
+
+test('an upload that skipped the CLI\'s how-to check is refused by the store, and nothing is kept', async () => {
+  const before = state.versions.length;
+  const missing = await invoke(route.handle, { params: { key: 'weather' }, body: packed('3.0.0', { howto: null }), builder: { id: 42 } });
+  assert.equal(missing.statusCode, 422);
+  assert.equal(missing.body.error, 'howto_incomplete');
+  assert.match(missing.body.message, /HOWTO\.md is missing/);
+  const empty = await invoke(route.handle, {
+    params: { key: 'weather' }, body: packed('3.0.0', { howto: HOWTO.replace('## Configuration\nSome text.', '## Configuration\n') }), builder: { id: 42 },
+  });
+  assert.equal(empty.body.error, 'howto_incomplete');
+  assert.match(empty.body.message, /section "Configuration" is empty/);
+  assert.equal(state.versions.length, before);
+  assert.ok(!fs.existsSync(path.join(STORE, 'weather', 'weather-3.0.0.tgz')));
+});

package/tests/nav_permission_atoms.mjs

@@ -87,7 +87,7 @@ test('the hall-preview fixture carries every atom /me resolves', () => {
 // the file and left the query alone, so a returning browser kept the cached copy —
 // a fix that reaches nobody looks identical to a fix that does not work.
 
-const SHELL_SHA = 'dd33737d54dccbb4';
+const SHELL_SHA = '4e14115a3737db9a';
 
 test('shell.js has not changed without its cache-bust being bumped', () => {
   const actual = crypto.createHash('sha256').update(SHELL).digest('hex').slice(0, 16);