@bongos/core 1.17.0

package/tests/interaction_prefs.mjs

@@ -0,0 +1,72 @@
+// tests/interaction_prefs.mjs — the per-builder interaction profile (task 2010).
+// Pure-shaper unit tests (no DB), mirroring tests/wandering_prefs.mjs.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const ip = require('../modules/builder-settings/interaction-prefs.js');
+
+test('defaults: unset prefs → all field defaults, empty contract, no inject', () => {
+  const eff = ip.effectiveProfile({});
+  assert.equal(eff.technical_level, 'non_technical');
+  assert.equal(eff.toolchain_familiarity, 'new');
+  assert.equal(eff.verbosity, 'concise');
+  assert.equal(ip.contractFor({}), '', 'all-default profile injects nothing');
+  assert.equal(ip.shouldInject({}), false);
+});
+
+test('null / missing behaviorPrefs is safe', () => {
+  assert.deepEqual(ip.storedProfile(null), {});
+  assert.equal(ip.contractFor(null), '');
+  assert.equal(ip.shouldInject(undefined), false);
+});
+
+test('a non-default field produces an injected contract', () => {
+  const prefs = { interaction: { technical_level: 'engineer' } };
+  const eff = ip.effectiveProfile(prefs);
+  assert.equal(eff.technical_level, 'engineer');
+  assert.equal(eff.toolchain_familiarity, 'new'); // untouched → default
+  assert.ok(ip.shouldInject(prefs));
+  const c = ip.contractFor(prefs);
+  assert.match(c, /Interaction profile/);
+  assert.match(c, /engineer/);
+});
+
+test('multiple non-default fields all appear in the contract', () => {
+  const prefs = { interaction: { technical_level: 'engineer', toolchain_familiarity: 'comfortable', verbosity: 'detailed' } };
+  const c = ip.contractFor(prefs);
+  assert.match(c, /engineer/);
+  assert.match(c, /comfortable/);
+  assert.match(c, /detailed/);
+});
+
+test('unknown fields/values in stored prefs are dropped (fall back to defaults)', () => {
+  const prefs = { interaction: { technical_level: 'wizard', bogus: 'x', verbosity: 'detailed' } };
+  const stored = ip.storedProfile(prefs);
+  assert.deepEqual(stored, { verbosity: 'detailed' }, 'invalid value + unknown key dropped');
+  assert.equal(ip.effectiveProfile(prefs).technical_level, 'non_technical');
+});
+
+test('validatePatch: good values pass, null clears, unknown field/value → 422', () => {
+  assert.deepEqual(ip.validatePatch({ technical_level: 'engineer' }), { ok: true, patch: { technical_level: 'engineer' } });
+  assert.deepEqual(ip.validatePatch({ technical_level: null }), { ok: true, patch: { technical_level: null } });
+  const bad = ip.validatePatch({ technical_level: 'wizard' });
+  assert.equal(bad.ok, false);
+  const unk = ip.validatePatch({ nope: 'x' });
+  assert.equal(unk.ok, false);
+  assert.equal(ip.validatePatch('nope').ok, false);
+});
+
+test('applyPatch merges and null clears', () => {
+  const base = { technical_level: 'engineer', verbosity: 'detailed' };
+  assert.deepEqual(ip.applyPatch(base, { toolchain_familiarity: 'comfortable' }), { technical_level: 'engineer', verbosity: 'detailed', toolchain_familiarity: 'comfortable' });
+  assert.deepEqual(ip.applyPatch(base, { technical_level: null }), { verbosity: 'detailed' });
+});
+
+test('describeForApi exposes catalog + effective + contract + inject', () => {
+  const d = ip.describeForApi({ interaction: { verbosity: 'detailed' } });
+  assert.ok(Array.isArray(d.fields) && d.fields.length === 3);
+  assert.equal(d.effective.verbosity, 'detailed');
+  assert.equal(d.inject, true);
+  assert.match(d.contract, /detailed/);
+});

package/tests/key-card.mjs

@@ -0,0 +1,110 @@
+// tests/key-card.mjs
+//
+// Unit tests for scripts/gds/key-card.js (task 1391) — the reusable "key
+// needed" visual callout, mirroring modules/lifecycle/ship-card.js's model.
+// Pure surface: buildKeyCardModel, renderMonospaceKeyCard, renderKeyCardHtml.
+// emitKeyCard writes to os.tmpdir(), so it's exercised too (file-system side
+// effect, but deterministic and self-cleaning).
+//
+// Run:  node tests/key-card.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+
+const require = createRequire(import.meta.url);
+const keyCard = require('../scripts/gds/key-card.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}`); }
+}
+
+// ---------- buildKeyCardModel ----------
+
+test('builds a model from caller-supplied fields', () => {
+  const m = keyCard.buildKeyCardModel({
+    keyId: 'gemini', keyLabel: 'Image-generation key', forWhat: 'the art pipeline',
+    settingsAnchor: 'art-key', brand: { productName: 'Cloud Bongos', settingsUrl: 'https://x.test/builders/settings' },
+  });
+  assert.equal(m.keyId, 'gemini');
+  assert.equal(m.keyLabel, 'Image-generation key');
+  assert.equal(m.forWhat, 'the art pipeline');
+  assert.equal(m.settingsUrl, 'https://x.test/builders/settings#art-key');
+});
+
+test('defaults are safe when fields are omitted', () => {
+  const m = keyCard.buildKeyCardModel({});
+  assert.equal(m.keyId, 'key');
+  assert.equal(m.keyLabel, 'API key');
+  assert.ok(m.settingsUrl.startsWith('http'));
+});
+
+test('an explicit settingsUrl wins over anchor composition', () => {
+  const m = keyCard.buildKeyCardModel({ settingsUrl: 'https://x.test/custom', settingsAnchor: 'art-key' });
+  assert.equal(m.settingsUrl, 'https://x.test/custom');
+});
+
+// ---------- renderMonospaceKeyCard ----------
+
+test('monospace card names the key, the reason, and the settings URL', () => {
+  const m = keyCard.buildKeyCardModel({
+    keyId: 'gemini', keyLabel: 'Image-generation key', forWhat: 'the art pipeline',
+    settingsUrl: 'https://x.test/builders/settings#art-key',
+  });
+  const out = keyCard.renderMonospaceKeyCard(m);
+  assert.ok(out.includes('Image-generation key'));
+  assert.ok(out.includes('the art pipeline'));
+  assert.ok(/don.t paste keys in chat/i.test(out));
+  assert.ok(out.includes('https://x.test/builders/settings#art-key'));
+});
+
+// ---------- renderKeyCardHtml ----------
+
+test('HTML card embeds the settings link and the no-paste rule, escaped safely', () => {
+  const m = keyCard.buildKeyCardModel({
+    keyId: 'gemini', keyLabel: 'Image-generation key', forWhat: 'the art pipeline',
+    settingsUrl: 'https://x.test/builders/settings#art-key',
+  });
+  const html = keyCard.renderKeyCardHtml(m);
+  assert.ok(html.includes('href="https://x.test/builders/settings#art-key"'));
+  assert.ok(/don't paste keys in chat/i.test(html));
+  assert.ok(html.includes('Add it in Settings'));
+  assert.ok(!html.includes('<script'), 'no script injection surface');
+});
+
+test('esc() neutralizes HTML-special characters', () => {
+  assert.equal(keyCard.esc('<b>&"\''), '&lt;b&gt;&amp;&quot;&#39;');
+  assert.equal(keyCard.esc(null), '');
+});
+
+// ---------- emitKeyCard ----------
+
+test('emitKeyCard writes HTML + prints the marker when widgets are on', () => {
+  const m = keyCard.buildKeyCardModel({ keyId: 'test-key-card-unit', keyLabel: 'Test key' });
+  const lines = [];
+  const file = keyCard.emitKeyCard(m, { log: (s) => lines.push(s), widgetsEnabled: true });
+  assert.ok(file, 'returns the written file path');
+  assert.ok(fs.existsSync(file));
+  const joined = lines.join('\n');
+  assert.ok(joined.includes(`[otb-key-card-html] ${file}`));
+  fs.unlinkSync(file); // clean up
+});
+
+test('emitKeyCard prints only the monospace card when widgets are off', () => {
+  const m = keyCard.buildKeyCardModel({ keyId: 'test-key-card-unit-off', keyLabel: 'Test key' });
+  const lines = [];
+  const result = keyCard.emitKeyCard(m, { log: (s) => lines.push(s), widgetsEnabled: false });
+  assert.equal(result, null);
+  const joined = lines.join('\n');
+  assert.ok(!joined.includes('[otb-key-card-html]'), 'no HTML marker when widgets are off');
+  assert.ok(joined.includes('[otb-card]'), 'still explains the plain-text-is-the-summary rule');
+});
+
+// ---------- Summary ----------
+
+console.log('');
+console.log(`key-card tests: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

package/tests/key-status.mjs

@@ -0,0 +1,45 @@
+// tests/key-status.mjs
+//
+// Unit tests for scripts/gds/key-status.js's pasted-key guard (task 1391,
+// done-when #3: "no code path accepts a key pasted in chat without warning +
+// redirect"). Only the pure guard function is exercised here — the rest of
+// the script makes network calls (GET /me/art-key) and belongs in the
+// integration/manual-run category, not this DB/network-free unit gate.
+//
+// Run:  node tests/key-status.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const keyStatus = require('../scripts/gds/key-status.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}`); }
+}
+
+test('refuses an argument that looks like a pasted API key', () => {
+  assert.equal(keyStatus.refuseIfKeyPasted(['AIzaSyABCDEFGHIJKLMNOPQRSTUVWXYZ1234567']), true);
+  assert.equal(keyStatus.refuseIfKeyPasted(['sk-ant-api03-abcdefghijklmnopqrstuvwxyz0123456789']), true);
+});
+
+test('does not refuse ordinary flags or short args', () => {
+  assert.equal(keyStatus.refuseIfKeyPasted(['--recheck']), false);
+  assert.equal(keyStatus.refuseIfKeyPasted([]), false);
+  assert.equal(keyStatus.refuseIfKeyPasted(['gemini']), false, 'a short word is not key-like');
+});
+
+test('KEY_LIKE_RE requires 20+ chars of key-alphabet with no flag prefix', () => {
+  assert.ok(keyStatus.KEY_LIKE_RE.test('a'.repeat(20)));
+  assert.ok(!keyStatus.KEY_LIKE_RE.test('a'.repeat(19)), 'too short to look like a key');
+  assert.ok(!keyStatus.KEY_LIKE_RE.test('has a space in it just kidding'.slice(0, 25)));
+});
+
+// ---------- Summary ----------
+
+console.log('');
+console.log(`key-status tests: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

package/tests/land_watch.mjs

@@ -0,0 +1,115 @@
+// tests/land_watch.mjs
+//
+// GDS-V4 task 1687 — locks the pending-land watcher (scripts/gds/land-watch.js) that
+// renders the SHIPPED banner once an async CI land completes. Pure + DB-free + network-
+// free: classifyLand's truth table, buildShippedEnvelope's shape (forces the shipped
+// stage, honors widgets-off), and watch()'s orchestration (emit newest shipped, drop the
+// give-ups, keep the still-landing) via injected deps — no real breadcrumb files touched.
+//
+// Run:  node tests/land_watch.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const L = require('../scripts/gds/land-watch.js');
+const { classifyLand, buildShippedEnvelope, watch } = L;
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+const STALE = 1000;
+
+// ── classifyLand truth table ─────────────────────────────────────────────────────────
+t('shipped → emit (even when stale)', () => {
+  assert.equal(classifyLand({ status: 'shipped' }, 10, { staleMs: STALE }), 'emit');
+  assert.equal(classifyLand({ status: 'shipped' }, 999999, { staleMs: STALE }), 'emit');
+});
+t('confirmed (still landing) → keep', () => {
+  assert.equal(classifyLand({ status: 'confirmed' }, 10, { staleMs: STALE }), 'keep');
+});
+t('left the land path (completed / ready / abandoned) → drop', () => {
+  for (const s of ['completed', 'ready', 'active', 'abandoned', 'blocked', 'backlog']) {
+    assert.equal(classifyLand({ status: s }, 10, { staleMs: STALE }), 'drop', s);
+  }
+});
+t('transient read failure (no task) fresh → keep, stale → drop', () => {
+  assert.equal(classifyLand(null, 10, { staleMs: STALE }), 'keep');
+  assert.equal(classifyLand(null, 5000, { staleMs: STALE }), 'drop');
+  assert.equal(classifyLand({}, 10, { staleMs: STALE }), 'keep'); // no status field
+});
+t('confirmed but stale → drop (stop watching a land that never completes)', () => {
+  assert.equal(classifyLand({ status: 'confirmed' }, 5000, { staleMs: STALE }), 'drop');
+});
+
+// ── buildShippedEnvelope shape ───────────────────────────────────────────────────────
+const CRUMB = {
+  taskId: '1211',
+  widgetsEnabled: true,
+  cardInputs: {
+    taskId: '1211', title: 'V4.R72 export pipeline', valueSummary: 'redacted mirror publish',
+    postGradeStatus: 'confirmed', // must be OVERRIDDEN to shipped
+    fileCount: 11, added: 1238, removed: 173,
+    credits: { awarded: 80, total: 23046 }, usage: { tokens: 60090973, costUsd: 55.55 }, deploy: { commit: null },
+  },
+};
+t('renders the SHIPPED banner (overrides the stored confirmed stage)', () => {
+  const env = buildShippedEnvelope(CRUMB, { status: 'shipped', title: 'x', value_summary: 'y' });
+  assert.equal(env.title, 'task_1211_card');
+  assert.equal(env.widgets_enabled, true);
+  assert.ok(/shipped to production/i.test(env.html), 'html must carry the shipped banner');
+  assert.ok(/Shipped/.test(env.markdown), 'monospace card must say Shipped');
+  assert.ok(!/confirmed — landing/i.test(env.html), 'must NOT still show the confirmed banner');
+});
+t('honors widgets-off (task 1279)', () => {
+  const env = buildShippedEnvelope({ ...CRUMB, widgetsEnabled: false }, { status: 'shipped' });
+  assert.equal(env.widgets_enabled, false);
+  assert.ok(env.markdown && /Shipped/.test(env.markdown));
+});
+t('falls back to the task row for title/value when the crumb lacks them', () => {
+  const env = buildShippedEnvelope({ taskId: '42', widgetsEnabled: true, cardInputs: {} }, { status: 'shipped', title: 'From task row', value_summary: 'VS' });
+  assert.ok(/From task row/.test(env.html), 'title should come from the fresh task row');
+});
+
+// ── watch() orchestration (injected deps — no disk, no network) ──────────────────────
+await ta('emits the NEWEST shipped card, keeps confirmed, drops the rest — one card per run', async () => {
+  const removed = [];
+  const crumbs = [
+    { taskId: '1', at: '2026-07-01T00:00:01.000Z', _file: 'f1', cardInputs: {} }, // shipped (older)
+    { taskId: '2', at: '2026-07-01T00:00:02.000Z', _file: 'f2', cardInputs: {} }, // confirmed
+    { taskId: '3', at: '2026-07-01T00:00:03.000Z', _file: 'f3', cardInputs: {} }, // shipped (newest)
+  ];
+  const statuses = { 1: 'shipped', 2: 'confirmed', 3: 'shipped' };
+  const env = await watch({
+    nowMs: Date.parse('2026-07-01T00:00:03.500Z'),
+    getTask: async (id) => ({ status: statuses[id] }),
+    readCrumbs: () => crumbs,
+    removeCrumb: (f) => removed.push(f),
+  });
+  assert.ok(env, 'should emit an envelope');
+  assert.equal(env.title, 'task_3_card', 'newest shipped wins');
+  assert.ok(removed.includes('f3'), 'the emitted crumb is cleared');
+  assert.ok(!removed.includes('f2'), 'the still-confirmed crumb is kept');
+  assert.ok(!removed.includes('f1'), 'the 2nd shipped waits for the next turn (one card per run)');
+});
+await ta('no shipped → no envelope; drops the give-ups', async () => {
+  const removed = [];
+  const env = await watch({
+    nowMs: Date.parse('2026-07-01T00:00:03.000Z'),
+    getTask: async () => ({ status: 'abandoned' }),
+    readCrumbs: () => [{ taskId: '9', at: '2026-07-01T00:00:01.000Z', _file: 'f9', cardInputs: {} }],
+    removeCrumb: (f) => removed.push(f),
+  });
+  assert.equal(env, null);
+  assert.ok(removed.includes('f9'), 'an abandoned (off-path) crumb is dropped');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/lifecycle-card.mjs

@@ -0,0 +1,145 @@
+// tests/lifecycle-card.mjs
+//
+// Unit tests for the lifecycle-card PostToolUse hook (.claude/hooks/lifecycle-card.js,
+// task 1288) — deterministic delivery of MUTATING lifecycle cards (claim/ship/
+// release). The model runs the script via Bash; this hook fires after, reads the
+// card the script wrote, and injects it. Covers the pure surface: matchesLifecycle
+// (which Bash commands carry a card), extractCardPath + responseText (find the
+// marker in the tool output), cardTitle, buildLifecycleContext. The stdin / file
+// read / inject plumbing is thin and silent-fail; exercised live at ship time.
+//
+// Also covers the task-1391 "key needed" callout addition to the same hook:
+// extractKeyCardPath / keyCardTitle / buildKeyCardContext — a second marker
+// type the hook scans for on ANY Bash output (not gated by matchesLifecycle),
+// since the art pipeline surfaces it from a Python subprocess, not a node CLI.
+//
+// Run:  node tests/lifecycle-card.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const hook = require('../.claude/hooks/lifecycle-card.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 count = (hay, needle) => hay.split(needle).length - 1;
+
+// ---------- matchesLifecycle ----------
+
+test('matches claim / ship / release script invocations', () => {
+  assert.ok(hook.matchesLifecycle('node scripts/gds/claim.js 1288'));
+  assert.ok(hook.matchesLifecycle('node scripts/gds/ship.js 1288 --notes x --summary y'));
+  assert.ok(hook.matchesLifecycle('node scripts/gds/release.js 1288'));
+  assert.ok(hook.matchesLifecycle('cd /repo && node scripts/gds/ship.js 5'));
+});
+
+test('does NOT match other Bash commands', () => {
+  for (const c of ['git status', 'node scripts/gds/start.js --hook', 'node scripts/gds/status.js C8',
+    'ls scripts/gds/claim.js', 'node scripts/gds/capture.js "idea"']) {
+    assert.ok(!hook.matchesLifecycle(c), `should not match: ${c}`);
+  }
+  assert.equal(hook.matchesLifecycle(null), false);
+  assert.equal(hook.matchesLifecycle(42), false);
+});
+
+// ---------- responseText (normalize the Bash tool_response shape) ----------
+
+test('responseText handles string, object, and unknown shapes', () => {
+  assert.equal(hook.responseText('hello'), 'hello');
+  assert.ok(hook.responseText({ stdout: 'out', stderr: 'err' }).includes('out'));
+  assert.ok(hook.responseText({ stdout: 'out', stderr: 'err' }).includes('err'));
+  assert.equal(hook.responseText(null), '');
+  assert.equal(hook.responseText(42), '');
+});
+
+// ---------- extractCardPath ----------
+
+test('extracts the [otb-card-html] path (widgets ON)', () => {
+  assert.equal(hook.extractCardPath('done\n[otb-card-html] /tmp/otb-ship-card-1288.html\nmore'),
+    '/tmp/otb-ship-card-1288.html');
+  assert.equal(hook.extractCardPath('shipped [otb-card-html] /tmp/otb-ship-card-7.html'),
+    '/tmp/otb-ship-card-7.html');
+});
+
+test('returns null when there is no HTML marker (widgets OFF / no card)', () => {
+  assert.equal(hook.extractCardPath('[otb-card] widgets are off — relay plain text'), null);
+  assert.equal(hook.extractCardPath('just some output'), null);
+  assert.equal(hook.extractCardPath(null), null);
+});
+
+// ---------- cardTitle ----------
+
+test('derives a per-task title from the temp filename', () => {
+  assert.equal(hook.cardTitle('/tmp/otb-ship-card-1288.html'), 'task_1288_card');
+  assert.equal(hook.cardTitle('/var/folders/x/otb-ship-card-642.html'), 'task_642_card');
+  assert.equal(hook.cardTitle('/tmp/something-else.html'), 'lifecycle_card');
+});
+
+// ---------- buildLifecycleContext ----------
+
+test('builds a render directive embedding the HTML verbatim, fenced exactly twice', () => {
+  const ctx = hook.buildLifecycleContext('<div>SHIP CARD</div>', 'task_1288_card');
+  assert.ok(ctx.includes('mcp__visualize__show_widget'));
+  assert.ok(ctx.includes('title "task_1288_card"'));
+  assert.ok(ctx.includes('<div>SHIP CARD</div>'), 'embeds the card HTML verbatim');
+  assert.ok(/Render it ONCE/i.test(ctx), 'tells the model to render once');
+  assert.ok(/no prose recap/i.test(ctx), 'forbids a prose recap');
+  assert.equal(count(ctx, '<<<LIFECYCLE_HTML>>>'), 2, 'fence appears exactly twice');
+});
+
+test('empty / missing HTML or title → empty string (inject nothing)', () => {
+  assert.equal(hook.buildLifecycleContext('', 'task_1288_card'), '');
+  assert.equal(hook.buildLifecycleContext('   ', 'task_1288_card'), '');
+  assert.equal(hook.buildLifecycleContext('<div>x</div>', null), '');
+});
+
+// ---------- extractKeyCardPath (task 1391 — the key-needed callout) ----------
+// Unlike extractCardPath, this marker is NOT gated to a specific command —
+// it can surface from any Bash output (the art pipeline shells key-card.js
+// out as a subprocess), so only the marker text itself is tested here.
+
+test('extracts the [otb-key-card-html] path', () => {
+  assert.equal(hook.extractKeyCardPath('some python traceback\n[otb-key-card-html] /tmp/otb-key-card-gemini.html\nmore'),
+    '/tmp/otb-key-card-gemini.html');
+});
+
+test('returns null when there is no key-card marker', () => {
+  assert.equal(hook.extractKeyCardPath('just some output'), null);
+  assert.equal(hook.extractKeyCardPath('[otb-card-html] /tmp/otb-ship-card-7.html'), null, 'does not match the lifecycle marker');
+  assert.equal(hook.extractKeyCardPath(null), null);
+});
+
+// ---------- keyCardTitle ----------
+
+test('derives a per-key title from the temp filename', () => {
+  assert.equal(hook.keyCardTitle('/tmp/otb-key-card-gemini.html'), 'key_needed_gemini_card');
+  assert.equal(hook.keyCardTitle('/tmp/something-else.html'), 'key_needed_card');
+});
+
+// ---------- buildKeyCardContext ----------
+
+test('builds a render directive embedding the HTML verbatim, fenced exactly twice', () => {
+  const ctx = hook.buildKeyCardContext('<div>KEY CARD</div>', 'key_needed_gemini_card');
+  assert.ok(ctx.includes('mcp__visualize__show_widget'));
+  assert.ok(ctx.includes('title "key_needed_gemini_card"'));
+  assert.ok(ctx.includes('<div>KEY CARD</div>'), 'embeds the card HTML verbatim');
+  assert.ok(/Render it ONCE/i.test(ctx), 'tells the model to render once');
+  assert.ok(/never ask the builder to paste the key/i.test(ctx), 'restates the no-paste-in-chat rule');
+  assert.equal(count(ctx, '<<<KEY_CARD_HTML>>>'), 2, 'fence appears exactly twice');
+});
+
+test('empty / missing HTML or title → empty string (inject nothing)', () => {
+  assert.equal(hook.buildKeyCardContext('', 'key_needed_gemini_card'), '');
+  assert.equal(hook.buildKeyCardContext('<div>x</div>', null), '');
+});
+
+// ---------- Summary ----------
+
+console.log('');
+console.log(`lifecycle-card tests: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);