@bongos/core 1.19.348 → 1.19.350

package/src/module-api.js

@@ -1126,8 +1126,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.346 with no explicit bump. run 32802265337. (task 1002620)
 //   1.19.348 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.347 with no explicit bump. run 32802746363. (task 1002620)
+//   1.19.349 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.348 with no explicit bump. run 32803276871. (task 1002620)
+//   1.19.350 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.349 with no explicit bump. run 32810944115. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.348'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.350'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/ship_publish_error.mjs

@@ -99,7 +99,19 @@ test('a "fetch first" rejection names the branch and the reset-onto-origin remed
   assert.match(out, /reset/i, 'names the reset');
   assert.match(out, /generator/i, 'and the regenerate step before re-shipping');
   assert.match(out, /re-ship|fast-forward/i, 'and why: so the push fast-forwards');
-  assert.ok(!/\n/.test(out), 'multi-line git stderr is collapsed — this goes mid-sentence into one log line');
+  // CONTRACT CHANGED, task 1003222. This used to assert the OPPOSITE — that the
+  // whole thing collapsed to one line — which was right while the server clipped
+  // stderr to 200 chars, and wrong once it stopped. The summary line is still
+  // collapsed and scannable; the verbatim text is quoted BELOW it, because git puts
+  // the line that names the cause last and a one-line squash buries it.
+  const [summary] = out.split('\n');
+  assert.ok(!/\n/.test(summary), 'the SUMMARY is still one scannable line');
+  assert.match(summary, /reason:/, 'and still carries a reason inline');
+  assert.match(out, /what the remote actually said/, 'the untruncated stderr is quoted below');
+  assert.ok(
+    out.includes("error: failed to push some refs to 'github.com/org/repo.git'"),
+    'the remote message survives VERBATIM, on its own line — the whole point of the task',
+  );
 });
 
 test('the "non-fast-forward" wording triggers the same hint through the envelope', () => {
@@ -158,5 +170,77 @@ test('1003221 a non-NFF failure gains no hint from either flag', () => {
   }
 });
 
+
+// --- task 1003222: the remote's own words reach the builder ------------------
+//
+// The failure this closes: a builder saw `reason: error: failed` — clipped
+// mid-word by a 200-char slice on top of an earlier 500-char one — while the line
+// that named the cause (`remote: fatal error in commit_refs`) and the HTTP status
+// existed server-side only. That cost hours AND produced a wrong first diagnosis,
+// because the real message was never in the room.
+
+const LONG_STDERR = [
+  'To https://github.com/org/repo.git',
+  ' ! [remote rejected] b -> b (pre-receive hook declined)',
+  'error: failed to push some refs',
+  'remote: fatal error in commit_refs',   // git's useful line is LAST
+].join('\n');
+
+test('1003222 the LAST line survives — a head-truncation would have eaten it', () => {
+  const out = fmt({ error: 'publish_failed', step: 'push', reason: LONG_STDERR });
+  assert.ok(
+    out.includes('remote: fatal error in commit_refs'),
+    'the cause git printed last must reach the builder',
+  );
+});
+
+test('1003222 the git exit code is reported — 128 and 1 are different remedies', () => {
+  const out = fmt({ error: 'publish_failed', step: 'push', reason: 'boom', git_exit_code: 128 });
+  assert.match(out, /git exit 128/);
+});
+
+test('1003222 a GitHub HTTP status is reported when the API refused', () => {
+  const out = fmt({ error: 'pr_create_failed', github_status: 422, reason: 'No commits between main and b' });
+  assert.match(out, /GitHub HTTP 422/, '422 vs 403 vs 404 are three different fixes');
+});
+
+test('1003222 a timeout says so rather than looking like a rejection', () => {
+  const out = fmt({ error: 'publish_failed', step: 'push', reason: 'killed', timed_out: true });
+  assert.match(out, /TIMED OUT/);
+});
+
+test('1003222 a single-line stderr is NOT repeated in a quote block', () => {
+  // It is already fully present in the summary; quoting it again is noise.
+  const out = fmt({ error: 'publish_failed', step: 'push', reason: 'fatal: repository not found' });
+  assert.ok(!out.includes('what the remote actually said'), 'no block for a one-liner');
+  assert.match(out, /fatal: repository not found/);
+});
+
+test('1003222 an omitted middle is DECLARED, never silently clipped', () => {
+  const out = fmt({
+    error: 'publish_failed', step: 'push', reason: LONG_STDERR, reason_bytes: 99999,
+  });
+  assert.match(out, /99999 bytes at the server/, 'the reader is told text is missing');
+  assert.match(out, /omitted/);
+});
+
+test('1003222 the remedy precedes the quote block, not stranded under it', () => {
+  // The remedy is the actionable sentence. Below twenty lines of git chatter it
+  // reads as a footnote to the quotation and gets missed.
+  const out = fmt({ error: 'publish_failed', step: 'push', reason: NON_FF_STDERR });
+  const remedy = out.indexOf('reset onto');
+  const quote = out.indexOf('what the remote actually said');
+  assert.ok(remedy > -1 && quote > -1, 'both present');
+  assert.ok(remedy < quote, 'remedy comes first');
+});
+
+test('1003222 nothing regressed for a failure carrying no stderr at all', () => {
+  const out = fmt({ error: 'publish_failed' });
+  assert.match(out, /publish_failed/);
+  assert.ok(!out.includes('what the remote actually said'));
+  assert.ok(!/undefined|null|\[object/.test(out), 'no placeholder leakage');
+});
+
+
 console.log(`ship_publish_error: ${passed} passed, ${failed} failed`);
-process.exit(failed === 0 ? 0 : 1);
+process.exit(failed === 0 ? 0 : 1);

package/tests/task_visual_route_gate.mjs

@@ -0,0 +1,151 @@
+// tests/task_visual_route_gate.mjs
+//
+// Route-level proof of the ONE rule behind ship-time task visuals (task 1003109,
+// ADR 0184): a visual has no audience of its own — it inherits the audience of the
+// value_summary it restates. Already-public work (shipped|confirmed, not
+// security_sensitive) serves unauthenticated; EVERYTHING else falls through to
+// auth.requireBuilder and never past it.
+//
+// The unit tests in tests/task_visuals.mjs pin the predicate. This pins the WIRING
+// — that the handler actually consults it, in the right order, and fails closed on
+// every miss. It runs the real Express router with the data layer and the auth gate
+// stubbed at the module boundary; no DB, no network, no session.
+//
+// Run:  node tests/task_visual_route_gate.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+const require = createRequire(import.meta.url);
+
+const TMP = path.join(os.tmpdir(), `otb-visualroute-${process.pid}`);
+process.env.TASK_VISUALS_DIR = TMP;
+
+const express = require('express');
+const api = require('../src/module-api.js');
+const visualDb = require('../modules/lifecycle/task-visual-db.js');
+const visuals = require('../modules/lifecycle/task-visuals.js');
+
+// ---- stubs at the module boundary -----------------------------------------
+// The route reads `db.getTaskVisualAccess` and `auth.requireBuilder` off these
+// module objects at CALL time, so replacing the properties is enough — no loader
+// tricks, and the router under test is the real one.
+let taskRow = null;      // what the "DB" says about the task
+let lookupThrows = false;
+visualDb.getTaskVisualAccess = async () => {
+  if (lookupThrows) throw new Error('simulated DB outage');
+  return taskRow;
+};
+let authCalls = 0;
+api.requireBuilder = (req, res) => {
+  authCalls++;
+  // Stand in for the real gate's deny path: it owns its own response, so reaching
+  // here means the request was NOT served publicly.
+  res.status(401).json({ error: 'unauthenticated' });
+};
+
+const buildRouter = require('../modules/lifecycle/routes/visuals.js');
+
+// res.fail is composed at the kernel level in production; supply the same shape.
+const app = express();
+app.use((req, res, next) => {
+  res.fail = (code, status) => res.status(typeof status === 'number' ? status : (status && status.status) || 500).json({ error: code });
+  next();
+});
+app.use(buildRouter());
+
+const server = http.createServer(app);
+await new Promise((r) => server.listen(0, '127.0.0.1', r));
+const base = `http://127.0.0.1:${server.address().port}`;
+
+// A real stored file, so a successful gate actually streams bytes.
+const PNG = Buffer.from('89504e470d0a1a0a0000000d49484452', 'hex');
+const stored = await visuals.persistImageBuffer(PNG, { taskId: 4242, contentType: 'image/png', dir: TMP });
+const NAME = stored.file;
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  return Promise.resolve().then(fn)
+    .then(() => { passed++; console.log(`  PASS  ${name}`); })
+    .catch((e) => { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); });
+}
+async function get(name) {
+  authCalls = 0;
+  const res = await fetch(`${base}/task-visuals/${name}`);
+  return { status: res.status, authCalls, buf: Buffer.from(await res.arrayBuffer()), headers: res.headers };
+}
+
+console.log('Task-visual serve gate (task 1003109 / ADR 0184):');
+
+await t('a SHIPPED task serves its visual to an unauthenticated caller', async () => {
+  taskRow = { id: 4242, status: 'shipped', security_sensitive: false };
+  const r = await get(NAME);
+  assert.equal(r.status, 200);
+  assert.equal(r.authCalls, 0, 'public work must not be sent through the auth gate');
+  assert.deepEqual(r.buf, PNG);
+  assert.equal(r.headers.get('content-type'), 'image/png');
+  assert.equal(r.headers.get('x-content-type-options'), 'nosniff');
+  assert.equal(r.headers.get('content-disposition'), 'inline');
+  assert.match(r.headers.get('cache-control'), /^public,/);
+});
+
+await t('a CONFIRMED task is public too — the same set as a public value_summary', async () => {
+  taskRow = { id: 4242, status: 'confirmed', security_sensitive: false };
+  assert.equal((await get(NAME)).status, 200);
+});
+
+await t('IN-FLIGHT work never serves publicly — it falls through to requireBuilder', async () => {
+  for (const status of ['backlog', 'ready', 'active', 'completed', 'abandoned']) {
+    taskRow = { id: 4242, status, security_sensitive: false };
+    const r = await get(NAME);
+    assert.equal(r.status, 401, status);
+    assert.equal(r.authCalls, 1, `${status} must reach the auth gate`);
+    assert.equal(r.buf.length && r.buf.includes(PNG), false, `${status} must not leak bytes`);
+  }
+});
+
+await t('a SHIPPED but security-sensitive task stays builders-only (the one narrowing)', async () => {
+  taskRow = { id: 4242, status: 'shipped', security_sensitive: true };
+  const r = await get(NAME);
+  assert.equal(r.status, 401);
+  assert.equal(r.authCalls, 1);
+});
+
+await t('an ABSENT task fails closed — no public serve, no crash', async () => {
+  taskRow = null;
+  const r = await get(NAME);
+  assert.equal(r.status, 401);
+  assert.equal(r.authCalls, 1);
+});
+
+await t('a DB outage fails closed rather than opening the door', async () => {
+  taskRow = { id: 4242, status: 'shipped', security_sensitive: false };
+  lookupThrows = true;
+  const r = await get(NAME);
+  lookupThrows = false;
+  assert.equal(r.status, 401, 'a lookup failure must not be read as "public"');
+  assert.equal(r.authCalls, 1);
+});
+
+await t('a malformed name is refused BEFORE any lookup (the traversal wall)', async () => {
+  taskRow = { id: 4242, status: 'shipped', security_sensitive: false };
+  for (const bad of ['..%2F..%2Fetc%2Fpasswd', 'screenshot.png', 'task-4242-0011.png', 'task-4242-0011223344556677.svg']) {
+    const r = await get(bad);
+    assert.equal(r.status, 400, bad);
+    assert.equal(r.authCalls, 0, `${bad} must not even reach the task lookup`);
+  }
+});
+
+await t('a well-formed name with no file on disk is a 404, not a 200', async () => {
+  taskRow = { id: 4242, status: 'shipped', security_sensitive: false };
+  const r = await get('task-4242-ffffffffffffffff.png');
+  assert.equal(r.status, 404);
+});
+
+server.close();
+await fs.rm(TMP, { recursive: true, force: true });
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/task_visuals.mjs

@@ -0,0 +1,200 @@
+// tests/task_visuals.mjs
+//
+// Unit tests for ship-time task visuals (task 1003109, goal 1000072 "Human
+// legibility"): filename safety / path-traversal, the task-id a stored name
+// belongs to, the upload screening (type allowlist, size cap, magic-byte sniff),
+// the AUDIENCE predicate that decides whether an image is public, alt-text
+// normalization, and persist/delete against a temp dir. No network, no DB.
+//
+// Run:  node tests/task_visuals.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+const require = createRequire(import.meta.url);
+
+// Point storage at a throwaway dir BEFORE requiring the module.
+const TMP = path.join(os.tmpdir(), `otb-taskvisual-${process.pid}`);
+process.env.TASK_VISUALS_DIR = TMP;
+const tv = require('../modules/lifecycle/task-visuals.js');
+const kit = require('../modules/hall-ui/public/hall-kit.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  return Promise.resolve().then(fn)
+    .then(() => { passed++; console.log(`  PASS  ${name}`); })
+    .catch((e) => { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); });
+}
+
+// Minimal real headers, long enough for the sniff's 12-byte floor.
+const PNG = Buffer.from('89504e470d0a1a0a0000000d49484452', 'hex');
+const JPG = Buffer.from('ffd8ffe000104a46494600010101', 'hex');
+const GIF = Buffer.from('4749463839610100010080000000', 'hex');
+const WEBP = Buffer.concat([Buffer.from('RIFF'), Buffer.from([0, 0, 0, 0]), Buffer.from('WEBPVP8 ')]);
+const NOT_AN_IMAGE = Buffer.from('<?php system($_GET[0]); ?>            ');
+
+console.log('Ship-time task visuals (task 1003109):');
+
+// ---- isSafeName / resolveSafe / taskIdFromName -----------------------------
+await t('isSafeName: accepts a server-generated name, rejects junk + traversal', () => {
+  assert.equal(tv.isSafeName('task-1003109-0011223344556677.png'), true);
+  assert.equal(tv.isSafeName('task-1-aabbccddeeff0011.webp'), true);
+  // Not the minted shape: user-chosen names, wrong hex length, bad extension.
+  assert.equal(tv.isSafeName('screenshot.png'), false);
+  assert.equal(tv.isSafeName('task-1003109-00112233.png'), false);
+  assert.equal(tv.isSafeName('task-1003109-0011223344556677.svg'), false);
+  assert.equal(tv.isSafeName('task-1003109-0011223344556677.png.php'), false);
+  // Traversal, absolute paths, and a name that merely CONTAINS a valid one.
+  assert.equal(tv.isSafeName('../task-1003109-0011223344556677.png'), false);
+  assert.equal(tv.isSafeName('/etc/passwd'), false);
+  assert.equal(tv.isSafeName('a/task-1003109-0011223344556677.png'), false);
+  assert.equal(tv.isSafeName(null), false);
+  assert.equal(tv.isSafeName(42), false);
+});
+
+await t('resolveSafe: stays inside the dir, and returns null for anything unsafe', () => {
+  const p = tv.resolveSafe('task-7-0011223344556677.png', { dir: TMP });
+  assert.equal(p, path.join(path.resolve(TMP), 'task-7-0011223344556677.png'));
+  assert.equal(tv.resolveSafe('../../etc/passwd', { dir: TMP }), null);
+  assert.equal(tv.resolveSafe('task-7-0011223344556677.png/../../x', { dir: TMP }), null);
+});
+
+await t('taskIdFromName: reads the owning task, and fails closed on a bad name', () => {
+  assert.equal(tv.taskIdFromName('task-1003109-0011223344556677.png'), 1003109);
+  // Fails CLOSED: the serve route looks the task up through this, and a null id
+  // resolves to no task, which resolves to "not public" — never to open access.
+  assert.equal(tv.taskIdFromName('../secrets.png'), null);
+  assert.equal(tv.taskIdFromName(''), null);
+});
+
+// ---- screening -------------------------------------------------------------
+await t('screenImage: accepts each allowlisted format with matching bytes', () => {
+  assert.deepEqual(tv.screenImage(PNG, 'image/png'), { ok: true, ext: 'png' });
+  assert.deepEqual(tv.screenImage(JPG, 'image/jpeg'), { ok: true, ext: 'jpg' });
+  assert.deepEqual(tv.screenImage(GIF, 'image/gif'), { ok: true, ext: 'gif' });
+  assert.deepEqual(tv.screenImage(WEBP, 'image/webp'), { ok: true, ext: 'webp' });
+  // A content-type with parameters still resolves.
+  assert.deepEqual(tv.screenImage(PNG, 'image/png; charset=binary'), { ok: true, ext: 'png' });
+});
+
+await t('screenImage: refuses a type outside the allowlist (SVG is executable)', () => {
+  assert.equal(tv.screenImage(PNG, 'image/svg+xml').ok, false);
+  assert.equal(tv.screenImage(PNG, 'text/html').ok, false);
+  assert.equal(tv.screenImage(PNG, 'application/octet-stream').ok, false);
+  assert.equal(tv.screenImage(PNG, '').ok, false);
+});
+
+await t('screenImage: a mislabeled content-type cannot smuggle a non-image in', () => {
+  const r = tv.screenImage(NOT_AN_IMAGE, 'image/png');
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'sniff_mismatch');
+  // Right family, wrong format: JPEG bytes claiming to be a PNG.
+  assert.equal(tv.screenImage(JPG, 'image/png').reason, 'sniff_mismatch');
+});
+
+await t('screenImage: refuses empty and over-cap payloads', () => {
+  assert.equal(tv.screenImage(Buffer.alloc(0), 'image/png').reason, 'empty');
+  const huge = Buffer.concat([PNG, Buffer.alloc(tv.MAX_BYTES)]);
+  const r = tv.screenImage(huge, 'image/png');
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'too_big');
+  assert.equal(r.bytes, huge.length);
+});
+
+// ---- the audience predicate ------------------------------------------------
+await t('isPubliclyViewable: already-public work only', () => {
+  assert.equal(tv.isPubliclyViewable({ status: 'shipped' }), true);
+  assert.equal(tv.isPubliclyViewable({ status: 'confirmed' }), true);
+  // In-flight work is builders-only, exactly like its value_summary.
+  for (const status of ['backlog', 'ready', 'active', 'completed', 'abandoned']) {
+    assert.equal(tv.isPubliclyViewable({ status }), false, status);
+  }
+});
+
+await t('isPubliclyViewable: fails closed, and narrows on security_sensitive', () => {
+  assert.equal(tv.isPubliclyViewable(null), false);
+  assert.equal(tv.isPubliclyViewable(undefined), false);
+  assert.equal(tv.isPubliclyViewable({}), false);
+  // The one deliberate narrowing vs value_summary: a shipped security task's
+  // screenshot stays builders-only.
+  assert.equal(tv.isPubliclyViewable({ status: 'shipped', security_sensitive: true }), false);
+  assert.equal(tv.isPubliclyViewable({ status: 'shipped', security_sensitive: false }), true);
+});
+
+// ---- alt text --------------------------------------------------------------
+await t('normalizeAlt: flattens, trims, bounds — and empty becomes null', () => {
+  assert.equal(tv.normalizeAlt('  before  and\n after '), 'before and after');
+  assert.equal(tv.normalizeAlt(''), null);
+  assert.equal(tv.normalizeAlt('   '), null);
+  assert.equal(tv.normalizeAlt(null), null);
+  assert.equal(tv.normalizeAlt('x'.repeat(1000)).length, tv.MAX_ALT_LENGTH);
+});
+
+// ---- persist / delete ------------------------------------------------------
+await t('persistImageBuffer: writes a name the serve route accepts, under the right task', async () => {
+  const r = await tv.persistImageBuffer(PNG, { taskId: 1003109, contentType: 'image/png', dir: TMP });
+  assert.equal(r.ok, true);
+  assert.equal(tv.isSafeName(r.file), true);
+  assert.equal(tv.taskIdFromName(r.file), 1003109);
+  assert.equal(r.url, `/api/bongos/task-visuals/${r.file}`);
+  // Both prefixes are permanent aliases, so a URL minted under either resolves.
+  assert.equal(kit.isTaskVisualUrl(r.url), true);
+  assert.equal(r.bytes, PNG.length);
+  const onDisk = await fs.readFile(path.join(TMP, r.file));
+  assert.deepEqual(onDisk, PNG);
+});
+
+await t('persistImageBuffer: two writes never collide (a replace keeps the old file distinct)', async () => {
+  const a = await tv.persistImageBuffer(PNG, { taskId: 5, contentType: 'image/png', dir: TMP });
+  const b = await tv.persistImageBuffer(PNG, { taskId: 5, contentType: 'image/png', dir: TMP });
+  assert.notEqual(a.file, b.file);
+});
+
+await t('persistImageBuffer: refuses without writing anything', async () => {
+  const before = (await fs.readdir(TMP)).length;
+  assert.equal((await tv.persistImageBuffer(NOT_AN_IMAGE, { taskId: 1, contentType: 'image/png', dir: TMP })).reason, 'sniff_mismatch');
+  assert.equal((await tv.persistImageBuffer(PNG, { taskId: 0, contentType: 'image/png', dir: TMP })).reason, 'bad_task_id');
+  assert.equal((await tv.persistImageBuffer(PNG, { taskId: 'x', contentType: 'image/png', dir: TMP })).reason, 'bad_task_id');
+  assert.equal((await fs.readdir(TMP)).length, before);
+});
+
+await t('deleteStored: removes by name or URL, is idempotent, refuses a traversal', async () => {
+  const r = await tv.persistImageBuffer(PNG, { taskId: 9, contentType: 'image/png', dir: TMP });
+  assert.equal(await tv.deleteStored(r.url, { dir: TMP }), true);
+  // Idempotent — removing an already-absent visual is a success, so a replace
+  // whose old file was already swept doesn't error.
+  assert.equal(await tv.deleteStored(r.url, { dir: TMP }), true);
+  assert.equal(await tv.deleteStored('../../etc/passwd', { dir: TMP }), false);
+});
+
+// ---- the client-side URL guard --------------------------------------------
+await t('hall-kit: only a server-minted visual URL is ever rendered', () => {
+  assert.equal(kit.isTaskVisualUrl('/api/gds/task-visuals/task-1003109-0011223344556677.png'), true);
+  assert.equal(kit.isTaskVisualUrl('/api/bongos/task-visuals/task-1-aabbccddeeff0011.webp'), true);
+  // Anything that is not that exact shape renders nothing — including an
+  // absolute URL to another origin, and a javascript: payload.
+  assert.equal(kit.isTaskVisualUrl('https://evil.example/x.png'), false);
+  assert.equal(kit.isTaskVisualUrl('javascript:alert(1)'), false);
+  assert.equal(kit.isTaskVisualUrl('/api/gds/task-visuals/../../secrets'), false);
+  assert.equal(kit.isTaskVisualUrl(''), false);
+  assert.equal(kit.isTaskVisualUrl(null), false);
+});
+
+await t('hall-kit: no visual renders nothing at all — never a placeholder', () => {
+  assert.equal(kit.shipVisualThumbHtml({ id: 1 }), '');
+  assert.equal(kit.shipVisualThumbHtml({ id: 1, visual_url: null }), '');
+  assert.equal(kit.shipVisualThumbHtml(null), '');
+  const html = kit.shipVisualThumbHtml({ id: 1, visual_url: '/api/gds/task-visuals/task-1-0011223344556677.png', visual_alt: 'a "before" shot' });
+  assert.ok(html.includes('ship-visual-thumb'));
+  // The caption is attacker-adjacent text (a builder wrote it) — it must be escaped.
+  assert.ok(html.includes('&quot;before&quot;'));
+  assert.ok(!html.includes('"before"'));
+});
+
+// ---- cleanup ---------------------------------------------------------------
+await fs.rm(TMP, { recursive: true, force: true });
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);