@bongos/core 1.19.315 → 1.19.317

package/tests/skill_preflight.mjs

@@ -0,0 +1,251 @@
+// tests/skill_preflight.mjs — G03, task 1003167, goal 1000077, criterion
+// guards-skill-declares-machine.
+//
+// THE INCIDENT. /merge-mode states in its own prose that it assumes the Archon's
+// Mac or the droplet. It was run on a dev box anyway — and ship.js ALREADY knew,
+// because strandNextStep() tells a box "/merge-mode is NOT available here". The
+// knowledge existed in two places and neither stopped the run: prose cannot
+// refuse, and the one executable copy sat on a different code path.
+//
+// So these tests care about two things: that the preflight actually REFUSES, and
+// that the scan behind the fitness check does not cry wolf. Both false-positive
+// classes below were real defects in my own first drafts.
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const sp = require('../scripts/gds/skill-preflight.js');
+
+// ---- the declaration ------------------------------------------------------
+test('parseRequires reads the inline form', () => {
+  const r = sp.parseRequires('---\nname: x\nrequires: [gh, main-checkout]\n---\nbody');
+  assert.deepEqual(r.requires, ['gh', 'main-checkout']);
+  assert.equal(r.declared, true);
+});
+
+test('parseRequires reads the dash-list form', () => {
+  const r = sp.parseRequires('---\nname: x\nrequires:\n  - gh\n  - tty\n---\nbody');
+  assert.deepEqual(r.requires, ['gh', 'tty']);
+});
+
+test('no requires: is "declared nothing", NOT "declared an empty list"', () => {
+  // The fitness check needs to tell those apart.
+  const r = sp.parseRequires('---\nname: x\n---\nbody');
+  assert.equal(r.declared, false);
+  assert.deepEqual(r.requires, []);
+});
+
+test('a malformed requires: is an ERROR, not silently zero requirements', () => {
+  // Reporting zero would read as "declared, needs nothing" — a scan that finds
+  // nothing must never be indistinguishable from a clean pass.
+  const r = sp.parseRequires('---\nname: x\nrequires: gh\n---\nbody');
+  assert.ok(r.error, 'a scalar requires: must be flagged');
+  assert.equal(r.declared, true);
+});
+
+// ---- the scan must not cry wolf -------------------------------------------
+test('PROSE that names a command is not an instruction to run it', () => {
+  // dev/SKILL.md FORBIDS `git push origin main`. An earlier draft flagged it for
+  // saying so — the scan read code spans and prose alike.
+  const md = '---\nname: dev\n---\n- never run raw `git push origin main` or `~/deploy.sh`; that is Bongos\'s job.\n';
+  assert.deepEqual(sp.inferRequired(md), [], 'a prohibition must not imply a requirement');
+});
+
+test('a FENCED command is an instruction, and is picked up', () => {
+  const md = '---\nname: x\n---\n```bash\nnode scripts/gds/push-main.js\n```\n';
+  assert.deepEqual(sp.inferRequired(md), ['push-credential']);
+});
+
+test('a shell COMMENT inside a fence is discussion, not an instruction', () => {
+  const md = '---\nname: x\n---\n```bash\n# node scripts/gds/push-main.js is the sanctioned push\necho hi\n```\n';
+  assert.deepEqual(sp.inferRequired(md), []);
+});
+
+test('"through" does not match the gh signal', () => {
+  // `gh ` is a substring of "throu(gh )". The first draft flagged
+  // priority-session for a comment containing the word "through".
+  // NOT in a comment: comment-stripping would remove it and the boundary would
+  // never be exercised. The first version of this test made exactly that mistake
+  // and stayed green when the boundary was deleted.
+  const md = '---\nname: x\n---\n```bash\necho "routed through the gateway"\n```\n';
+  assert.deepEqual(sp.inferRequired(md), [], 'a word containing "gh " is not the gh CLI');
+  const inComment = '---\nname: x\n---\n```bash\n# API through it rather than re-deriving the token\necho ok\n```\n';
+  assert.deepEqual(sp.inferRequired(inComment), [], 'and a comment is discussion regardless');
+  const real = '---\nname: y\n---\n```bash\ngh pr view 12 --json state\n```\n';
+  assert.deepEqual(sp.inferRequired(real), ['gh'], 'the real gh command still matches');
+});
+
+test('ssh and the deploy host both imply droplet-ssh', () => {
+  for (const cmd of ['ssh -o ConnectTimeout=10 someone@host "~/deploy.sh"', 'ssh someone@host "psql -d x"']) {
+    assert.deepEqual(sp.inferRequired(`---\nname: x\n---\n\`\`\`bash\n${cmd}\n\`\`\`\n`), ['droplet-ssh'], cmd);
+  }
+});
+
+// ---- the refusal ----------------------------------------------------------
+const caps = {
+  present: { what: 'a present thing', probe: () => true, missing: 'absent' },
+  absent: { what: 'an absent thing', probe: () => false, missing: 'go get it' },
+  unknowable: { what: 'an unprovable thing', probe: () => null, missing: 'unreachable' },
+  thrower: { what: 'a probe that dies', probe: () => { throw new Error('boom'); }, missing: 'never printed' },
+};
+
+test('a FALSE probe refuses, and names the remedy', () => {
+  const r = sp.preflight(['present', 'absent'], caps);
+  assert.equal(r.ok, false);
+  assert.equal(r.missing.length, 1);
+  assert.equal(r.missing[0].name, 'absent');
+  assert.match(r.missing[0].why, /go get it/);
+});
+
+test('the refusal names ONLY what is missing, not the whole list', () => {
+  // The task's wording: name the MISSING capability, not the list. A satisfied
+  // capability must not appear in `missing`.
+  const r = sp.preflight(['present', 'absent'], caps);
+  assert.ok(!r.missing.some((m) => m.name === 'present'));
+});
+
+test('a NULL probe warns and does NOT block', () => {
+  // Refusing on "could not tell" would block legitimate machines; passing it
+  // silently would rebuild the hole. So: warn, proceed.
+  const r = sp.preflight(['unknowable'], caps);
+  assert.equal(r.ok, true, 'unknown must not refuse');
+  assert.equal(r.unknown.length, 1);
+});
+
+test('a probe that THROWS degrades to unknown, never to a pass-as-satisfied', () => {
+  const r = sp.preflight(['thrower'], caps);
+  assert.equal(r.unknown.length, 1);
+  assert.equal(r.missing.length, 0);
+});
+
+test('an undeclared capability name is caught rather than ignored', () => {
+  // A typo in a skill's requires: would otherwise be a silent no-op.
+  const r = sp.preflight(['no-such-capability'], caps);
+  assert.equal(r.ok, false);
+  assert.match(r.missing[0].why, /unknown capability/);
+});
+
+// ---- the live tree --------------------------------------------------------
+test('every registry capability has a probe and a remedy sentence', () => {
+  for (const [name, cap] of Object.entries(sp.CAPABILITIES)) {
+    assert.equal(typeof cap.probe, 'function', `${name} needs a probe`);
+    assert.ok(cap.what && cap.missing, `${name} needs what/missing text`);
+    assert.ok(cap.missing.length > 40, `${name}'s remedy must be actionable, not a label`);
+  }
+});
+
+test('the live tree passes the declare-check', () => {
+  const r = sp.checkOpsSkillsDeclareMachine();
+  assert.equal(r.hardFail, false, `unexpected:\n  ${r.violations.join('\n  ')}`);
+});
+
+test('merge-mode really declares the machine it needs', () => {
+  // The skill at the centre of the incident.
+  const r = sp.preflightSkill('merge-mode', caps);
+  assert.ok(r.requires.includes('main-checkout'));
+  assert.ok(r.requires.includes('push-credential'));
+});
+
+test('an UNDECLARED fenced ops command is caught', () => {
+  // Injected names, so this exercises the real comparison rather than
+  // short-circuiting on an empty enumeration — the first version of this test
+  // passed a bad dir and therefore proved nothing about the undeclared path.
+  const r = sp.checkOpsSkillsDeclareMachine({
+    names: ['rogue'],
+    read: () => '---\nname: rogue\n---\n```bash\nnode scripts/gds/push-main.js\nssh me@host "~/deploy.sh"\n```\n',
+  });
+  assert.equal(r.hardFail, true, 'a skill fencing a main-push with no declaration must fail');
+  const text = r.violations.join('\n');
+  assert.match(text, /push-credential/);
+  assert.match(text, /droplet-ssh/);
+  assert.match(text, /requires:/, 'the violation must name the remedy');
+});
+
+test('a skill that DOES declare its fenced commands passes', () => {
+  const r = sp.checkOpsSkillsDeclareMachine({
+    names: ['good'],
+    read: () => '---\nname: good\nrequires: [push-credential]\n---\n```bash\nnode scripts/gds/skill-preflight.js good\nnode scripts/gds/push-main.js\n```\n',
+  });
+  assert.equal(r.hardFail, false, r.violations.join('\n'));
+});
+
+test('declaring MORE than the fences imply is allowed', () => {
+  // A human knows things the scan cannot see; punishing over-declaration would
+  // train people to declare less.
+  const r = sp.checkOpsSkillsDeclareMachine({
+    names: ['careful'],
+    read: () => '---\nname: careful\nrequires: [gh, tty, main-checkout]\n---\nRun `node scripts/gds/skill-preflight.js careful` first.\n',
+  });
+  assert.equal(r.hardFail, false, r.violations.join('\n'));
+});
+
+test('a declared capability that is not in the registry is caught', () => {
+  const r = sp.checkOpsSkillsDeclareMachine({
+    names: ['typo'],
+    read: () => '---\nname: typo\nrequires: [man-checkout]\n---\nbody\n',
+  });
+  assert.equal(r.hardFail, true);
+  assert.match(r.violations.join('\n'), /unknown capability "man-checkout"/);
+});
+
+test('an empty skills dir FAILS rather than reporting all-clear', () => {
+  const r = sp.checkOpsSkillsDeclareMachine({ dir: '/definitely/not/here' });
+  assert.equal(r.hardFail, true);
+  assert.match(r.violations[0], /scan defect/);
+});
+
+// ---- the three findings from the first grader pass ------------------------
+test('ghAuthed is memoized — one preflight must not spawn `gh` twice', () => {
+  // merge-mode declares BOTH gh and push-credential, and push-credential's probe
+  // also consults gh. Unmemoized that was two 15s-timeout subprocesses in one
+  // run, and a preflight slow enough to skip is one nobody runs.
+  const a = sp.ghAuthed();
+  const b = sp.ghAuthed();
+  assert.equal(a, b, 'repeat calls must agree');
+  assert.equal(typeof a, 'boolean');
+});
+
+test('a skill name must be a single path segment', () => {
+  // `skill-preflight.js ../../../etc` must not read outside .claude/skills.
+  for (const bad of ['../../../etc', '..', '.', 'a/b', '', 'x/../../y']) {
+    assert.equal(sp.skillPath(bad), null, `${JSON.stringify(bad)} must be refused`);
+  }
+  assert.ok(String(sp.skillPath('merge-mode')).endsWith('merge-mode/SKILL.md'.replace('/', require('node:path').sep)));
+});
+
+test('a traversal name is refused with a message, not a crash', () => {
+  const r = sp.preflightSkill('../../../etc');
+  assert.equal(r.ok, false);
+  assert.match(r.missing[0].why, /not a skill name/);
+});
+
+test('DECLARING without ENFORCING is caught', () => {
+  // The gap the grader found in planning-session: a `requires:` with no
+  // preflight call is a contract stated where nothing checks it — the same
+  // shape as the original bug.
+  const r = sp.checkOpsSkillsDeclareMachine({
+    names: ['claims-but-never-checks'],
+    read: () => '---\nname: x\nrequires: [gh]\n---\nprose only, no preflight call\n',
+  });
+  assert.equal(r.hardFail, true);
+  assert.match(r.violations.join('\n'), /never runs/);
+});
+
+test('invoking the preflight anywhere satisfies enforcement — top OR at the step', () => {
+  // merge-mode gates at Step 0 (capabilities are preconditions for the whole
+  // procedure); planning-session gates at the one step that needs ssh. Both are
+  // legitimate, so the check must not demand a particular position.
+  const md = '---\nname: x\nrequires: [gh]\n---\nlater on:\n```bash\nnode scripts/gds/skill-preflight.js x\ngh pr view 1 --json state\n```\n';
+  const r = sp.checkOpsSkillsDeclareMachine({ names: ['x'], read: () => md });
+  assert.equal(r.hardFail, false, r.violations.join('\n'));
+});
+
+test('both live declaring skills actually invoke the preflight', () => {
+  const r = sp.checkOpsSkillsDeclareMachine();
+  assert.equal(r.hardFail, false, r.violations.join('\n'));
+  for (const name of ['merge-mode', 'planning-session']) {
+    const md = require('node:fs').readFileSync(sp.skillPath(name), 'utf8');
+    assert.match(md, /skill-preflight\.js\s+\S/, `${name} must run its own preflight`);
+  }
+});