@bongos/core 1.19.1063 → 1.19.1065

package/scripts/gds/strand-watch.js

@@ -38,6 +38,7 @@
 // Exit codes: 0 always on --line (fail-open). Otherwise 0 clean, 1 strands found, 2 undetermined.
 
 const { apiCall, arg, hasFlag } = require('./cli-lib');
+const tweakHold = require('../../modules/lifecycle/page-tweak-hold.js');
 
 // ---- thresholds -------------------------------------------------------------
 // Reasoned, not magic. Written down because a future reader will want to retune them.
@@ -132,6 +133,31 @@ function rankStrands(strands) {
   });
 }
 
+// ---- the held pass (task 1004322, ADR 0341 D7) --------------------------------
+//
+// A page tweak whose grade PASSED waits at `completed` for its artist on purpose:
+// the artist approves the applied page before it lands. It is not a strand and not
+// a failed grade, and calling it one would send someone to /grade-recover a task
+// nobody should touch. The task list carries no grade, so each completed page
+// tweak's grade is read on its own (there are a handful at most; the read is
+// bounded anyway). A read that FAILS leaves the task to the ordinary
+// classification: an unknown must stay loud, never be explained away as a hold.
+const HOLD_READ_LIMIT = 25;
+
+async function heldPageTweaks(tasks, { call, withTimeout }) {
+  const candidates = tasks.filter((t) => t && t.status === 'completed' && tweakHold.isPageTweak(t) && safeId(t.id)).slice(0, HOLD_READ_LIMIT);
+  const held = new Set();
+  await Promise.all(candidates.map(async (t) => {
+    try {
+      const res = await withTimeout(call('GET', `/api/bongos/tasks/${safeId(t.id)}?include=grade`), 'page-tweak grade');
+      const body = res && (res.data || res);
+      const grade = body && body.grade;
+      if (tweakHold.isHeldForArtist(t, grade ? grade.passed : null)) held.add(String(t.id));
+    } catch { /* unknown: classified as usual */ }
+  }));
+  return held;
+}
+
 // ---- fetch ------------------------------------------------------------------
 
 async function check({ nowMs = Date.now(), timeoutMs = DEFAULT_TIMEOUT_MS, confirmedStaleMs, completedStaleMs, call = apiCall } = {}) {
@@ -157,14 +183,23 @@ async function check({ nowMs = Date.now(), timeoutMs = DEFAULT_TIMEOUT_MS, confi
 
   const strands = [];
   const truncated = [];
+  const waiting = [];
+  const completed = (pages.find((p) => p.status === 'completed') || { tasks: [] }).tasks;
+  const held = await heldPageTweaks(completed, { call, withTimeout });
   for (const { status, tasks } of pages) {
     if (tasks.length >= PAGE_LIMIT) truncated.push(status);
     for (const t of tasks) {
+      if (status === 'completed' && held.has(String(t.id))) {
+        const updated = Date.parse(t.updated_at || '');
+        const ageMs = Number.isFinite(updated) ? nowMs - updated : NaN;
+        waiting.push({ id: safeId(t.id), status, ageMs, age: humanAge(ageMs), shape: tweakHold.HOLD_STATE });
+        continue;
+      }
       const s = classifyStrand(t, { nowMs, confirmedStaleMs, completedStaleMs });
       if (s) strands.push(s);
     }
   }
-  return { undetermined: false, ok: strands.length === 0 && !truncated.length, strands: rankStrands(strands), truncated };
+  return { undetermined: false, ok: strands.length === 0 && !truncated.length, strands: rankStrands(strands), truncated, waiting };
 }
 
 // ---- rendering --------------------------------------------------------------
@@ -218,6 +253,11 @@ function report(r) {
     console.log(`  ! coverage capped: the ${r.truncated.join(' and ')} queue(s) returned a full ${PAGE_LIMIT}-row page,`);
     console.log('    so strands older than the cutoff are NOT listed below.');
   }
+  // task 1004322: named, and kept apart from the strands — nobody should recover these.
+  const waiting = Array.isArray(r.waiting) ? r.waiting : [];
+  for (const w of waiting) {
+    console.log(`  task ${w.id}  waiting for the artist (${w.age}) — a page tweak whose grade passed; not a strand, leave it`);
+  }
   if (r.ok) {
     console.log('  ✓ none — nothing parked at completed or confirmed past its threshold.');
     console.log('');

package/scripts/gds/task.js

@@ -13,6 +13,8 @@
 //   bongos task show <id> [--json]
 //   bongos task visual <id> <image> [--alt "caption"]   attach/replace the ship-time visual
 //   bongos task visual <id> --remove                    take it back off
+//   bongos task visual <id> <image> --slot <name>       attach/replace a NAMED visual (task 1004322)
+//   bongos task visual <id> --slot <name> --remove      take a named one back off
 //
 // Task CREATION is Archon-gated SERVER-SIDE (creating work shapes scope, ADR 0016). This
 // CLI adds no authority — a lower rank gets a clear 403 message pointing at idea capture.
@@ -84,6 +86,7 @@ function usage() {
   console.error('  bongos task show <id> [--json]');
   console.error('  bongos task visual <id> <image> [--alt "caption"]   attach or replace the ship-time visual');
   console.error('  bongos task visual <id> --remove                    remove it again');
+  console.error('  bongos task visual <id> <image> --slot <name>       attach or replace a named visual (e.g. after-phone-dark)');
   console.error(`\n  kinds: ${VALID_KINDS.join(' | ')}`);
   console.error(`  disciplines: ${VALID_DISCIPLINES.join(' | ')}`);
 }
@@ -174,6 +177,21 @@ async function cmdVisual(args) {
   }
   const api = await cliClient();
 
+  // task 1004322: --slot names the visual (lifecycle_013). Validated here with the
+  // server's own rule, so a bad name costs a retyped command, not an upload.
+  const slot = arg('--slot', args) || null;
+  if (slot !== null && !taskVisuals.isSafeSlot(slot)) {
+    console.error(`--slot "${slot}" is not a slot name: lowercase words joined by dashes, such as ${taskVisuals.TWEAK_RENDER_SLOTS[0]}.`);
+    process.exit(2);
+  }
+  if (slot && hasFlag('--remove', args)) {
+    const r = await api.tasks.deleteTasksIdVisualsSlot({ id, slot });
+    if (r.status === 404) { console.error(`task #${id} not found.`); process.exit(1); }
+    if (!r.ok) { console.error(`visual remove failed (${r.status}):`, r.data); process.exit(1); }
+    console.log(`✓ Task #${id} no longer carries the "${slot}" visual.`);
+    return;
+  }
+
   if (hasFlag('--remove', args)) {
     const r = await api.tasks.deleteTasksIdVisual({ id });
     if (r.status === 404) { console.error(`task #${id} not found.`); process.exit(1); }
@@ -199,14 +217,14 @@ async function cmdVisual(args) {
   }
 
   const alt = arg('--alt', args) || '';
-  const r = await api.tasks.postTasksIdVisual({
-    id,
-    body: { image_b64: visual.buf.toString('base64'), content_type: visual.contentType, ...(alt ? { alt } : {}) },
-  });
+  const body = { image_b64: visual.buf.toString('base64'), content_type: visual.contentType, ...(alt ? { alt } : {}) };
+  const r = slot
+    ? await api.tasks.postTasksIdVisualsSlot({ id, slot, body })
+    : await api.tasks.postTasksIdVisual({ id, body });
   if (r.status === 404) { console.error(`task #${id} not found.`); process.exit(1); }
   if (r.status === 403) { console.error(`Only task #${id}'s claim holder (or an Archon) may attach its visual.`); process.exit(1); }
   if (!r.ok) { console.error(`visual upload failed (${r.status}):`, r.data); process.exit(1); }
-  console.log(`✓ Task #${id} now carries a visual (${Math.round(visual.buf.length / 1024)} KB).`);
+  console.log(`✓ Task #${id} now carries ${slot ? `the "${slot}" visual` : 'a visual'} (${Math.round(visual.buf.length / 1024)} KB).`);
   console.log('  It renders wherever this task\'s value summary does.');
 }
 

package/scripts/gds/tweak-renders.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/gds/tweak-renders.js — the eight renders of a page tweak, shot and
+// attached (task 1004322 / BV2.TW11; ADR 0341 D7 and its builder pick 9).
+//
+// WHY. The artist approves the APPLIED PAGE, not a diff and not a page built from
+// the batch: the Approval queue (TW12) shows images of the applied branch, which
+// is what keeps ADR 0233's "nothing renders a task description as product copy"
+// true. So /tweak renders the page before it applies the batch and again after,
+// on a desktop (1440) and a phone (390), in light and in dark, and attaches the
+// eight pictures to the round's task under their slot names
+// (task-visuals.TWEAK_RENDER_SLOTS: before-desktop-light … after-phone-dark).
+//
+// HOW IT RENDERS. Exactly the way the page reader reads (scripts/gds/page-reader.js):
+// the hall through the hall-preview harness with the pinned fixture account, the
+// landing and status surfaces through the ui-design kit's stub, one browser from
+// the kit's launchBrowser (system Edge or Chrome; nothing is downloaded), the
+// clock pinned, the page's first state from its .states.json. A page that pins
+// one colour mode is shot in that mode for both of its "light" and "dark" slots,
+// and the run says so, rather than inventing a mode the page does not have.
+// Full-page JPEG, so a long page still fits under the store's 4 MB cap.
+//
+// Run:  node scripts/gds/tweak-renders.js shoot --page <id> --phase before|after --out <dir>
+//       node scripts/gds/tweak-renders.js attach <task-id> --dir <dir>   (every slot file in <dir>)
+//       node scripts/gds/tweak-renders.js plan --page <id>              (what would be shot; no browser)
+//
+// Exit: 0 done · 1 a render or an upload failed · 2 usage · 3 no browser.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const taskVisuals = require('../../modules/lifecycle/task-visuals');
+const { arg, cliClient, cliExit } = require('./cli-lib');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const EXT = 'jpg';
+const JPEG_QUALITY = 82;
+
+// ---- pure ------------------------------------------------------------------
+
+function slotName(phase, device, mode) {
+  return `${phase}-${device}-${mode}`;
+}
+
+// The shots for one phase of one page: one per device x mode, each carrying the
+// slot it fills and the mode the page will actually render in. `plan` is the
+// page's first render plan from page-reader.planRenders.
+function shotsFor(phase, plan) {
+  if (!taskVisuals.TWEAK_RENDER_PHASES.includes(phase)) throw new Error(`phase must be one of ${taskVisuals.TWEAK_RENDER_PHASES.join(', ')}`);
+  const pinned = plan && plan.pinnedMode ? plan.pinnedMode : null;
+  const out = [];
+  for (const [device, width] of Object.entries(taskVisuals.TWEAK_RENDER_DEVICES)) {
+    for (const mode of taskVisuals.TWEAK_RENDER_MODES) {
+      out.push({ slot: slotName(phase, device, mode), device, width, mode, renderMode: pinned || mode, file: `${slotName(phase, device, mode)}.${EXT}` });
+    }
+  }
+  return out;
+}
+
+// The page's first render plan, and whether its states file pins a mode. Reads
+// the inventory and the states file; no browser.
+function planForPage(pageId, { inventory, planRenders, root = REPO_ROOT }) {
+  const page = (inventory.pages || []).find((p) => p.id === pageId);
+  if (!page) return { ok: false, code: 'unknown_page', detail: { page: pageId } };
+  const plans = planRenders(page, { root });
+  const plan = plans[0];
+  let modes = null;
+  if (page.states_files && page.states_files.length) {
+    try { modes = JSON.parse(fs.readFileSync(path.join(root, page.states_files[0]), 'utf8')).modes || null; } catch { modes = null; }
+  }
+  const pinnedMode = Array.isArray(modes) && modes.length === 1 ? modes[0] : null;
+  return { ok: true, page, plan: { ...plan, pinnedMode } };
+}
+
+// Which slot files a directory holds, in slot order, and which are missing.
+function slotFilesIn(dir, { exists = (p) => fs.existsSync(p) } = {}) {
+  const found = [];
+  const missing = [];
+  for (const slot of taskVisuals.TWEAK_RENDER_SLOTS) {
+    const hit = ['jpg', 'png', 'webp'].map((e) => path.join(dir, `${slot}.${e}`)).find(exists);
+    if (hit) found.push({ slot, file: hit });
+    else missing.push(slot);
+  }
+  return { found, missing };
+}
+
+// ---- the browser half --------------------------------------------------------
+
+async function shoot({ pageId, phase, out }) {
+  const reader = require('./page-reader.js');
+  const kit = require('../../modules/ui-design/kit/lib');
+  const inventory = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, reader.INVENTORY_REL), 'utf8'));
+  const planned = planForPage(pageId, { inventory, planRenders: reader.planRenders });
+  if (!planned.ok) { console.error(`tweak-renders: ${planned.code} (${pageId})`); return 2; }
+  const { page, plan } = planned;
+  const shots = shotsFor(phase, plan);
+  if (plan.pinnedMode) console.log(`tweak-renders: ${pageId} pins the ${plan.pinnedMode} mode, so both of its mode slots are shot in ${plan.pinnedMode}.`);
+  fs.mkdirSync(out, { recursive: true });
+
+  let browser;
+  try { browser = await kit.launchBrowser(); } catch (e) {
+    console.error(`tweak-renders: ${e.message}`);
+    return e instanceof kit.NoBrowserError ? 3 : 1;
+  }
+  const stoppers = [];
+  let failed = 0;
+  try {
+    let base;
+    if (page.surface === 'builders') {
+      const h = await reader.startHarness(kit);
+      stoppers.push(h.stop);
+      base = h.base;
+    } else {
+      const s = await kit.startStub({ surface: reader.SURFACE_MODULE[page.surface] || page.surface, auth: plan.auth, prefix: plan.stub.prefix, child: plan.stub.child, fixtures: plan.stub.fixtures });
+      stoppers.push(s.stop);
+      base = s.base;
+    }
+    for (const shot of shots) {
+      const [W, H] = kit.SIZES[shot.width];
+      const ctx = await browser.newContext({ viewport: { width: W, height: H }, deviceScaleFactor: 1, colorScheme: shot.renderMode });
+      try {
+        if (ctx.clock && typeof ctx.clock.setFixedTime === 'function') await ctx.clock.setFixedTime(new Date(reader.PINNED_CLOCK));
+        const p = await ctx.newPage();
+        p.setDefaultTimeout(6000);
+        p.on('dialog', (d) => { d.dismiss().catch(() => {}); });
+        await p.goto(base + kit.withMode(plan.url, shot.renderMode, plan.modeQuery), { waitUntil: 'load', timeout: 45000 });
+        await p.evaluate(() => document.fonts.ready).catch(() => {});
+        await p.waitForTimeout(kit.SETTLE_MS);
+        try { await kit.runActions(p, plan.actions); } catch (e) { console.log(`  ${shot.slot}: an action failed (${String(e.message).split('\n')[0].slice(0, 100)}); shot as it stood`); }
+        await p.screenshot({ path: path.join(out, shot.file), fullPage: true, type: 'jpeg', quality: JPEG_QUALITY });
+        const kb = Math.round(fs.statSync(path.join(out, shot.file)).size / 1024);
+        console.log(`  ${shot.slot}: ${W}px ${shot.renderMode} -> ${shot.file} (${kb} KB)`);
+      } catch (e) {
+        failed += 1;
+        console.error(`  ${shot.slot}: NOT rendered (${String(e.message).split('\n')[0].slice(0, 160)})`);
+      } finally {
+        await ctx.close().catch(() => {});
+      }
+    }
+  } finally {
+    await browser.close().catch(() => {});
+    for (const stop of stoppers) stop();
+  }
+  console.log(`tweak-renders: ${shots.length - failed} of ${shots.length} ${phase} render(s) of ${pageId} in ${out}`);
+  return failed ? 1 : 0;
+}
+
+// ---- the upload half ---------------------------------------------------------
+
+async function attach({ taskId, dir }, deps = {}) {
+  const { found, missing } = slotFilesIn(dir, deps);
+  if (!found.length) { console.error(`tweak-renders: no slot files in ${dir} (expected ${taskVisuals.TWEAK_RENDER_SLOTS[0]}.${EXT} and the rest).`); return 1; }
+  const client = deps.client || await cliClient();
+  let failed = 0;
+  for (const { slot, file } of found) {
+    const img = taskVisuals.readImageFile(file);
+    if (!img.ok) { failed += 1; console.error(`  ${slot}: ${img.message}`); continue; }
+    const r = await client.tasks.postTasksIdVisualsSlot({ id: taskId, slot, body: { image_b64: img.buf.toString('base64'), content_type: img.contentType, alt: `${slot.replace(/-/g, ' ')} render of the page` } });
+    if (r.ok) console.log(`  ${slot}: attached (${Math.round(img.buf.length / 1024)} KB)`);
+    else { failed += 1; console.error(`  ${slot}: upload failed (${r.status})`); }
+  }
+  if (missing.length) console.error(`tweak-renders: MISSING ${missing.length} slot(s): ${missing.join(', ')}. The Approval queue shows what is attached; shoot the missing phase and attach again.`);
+  console.log(`tweak-renders: ${found.length - failed} of ${taskVisuals.TWEAK_RENDER_SLOTS.length} render(s) attached to task ${taskId}.`);
+  return failed || missing.length ? 1 : 0;
+}
+
+async function main(args) {
+  const cmd = args[0];
+  if (cmd === 'shoot' || cmd === 'plan') {
+    const pageId = arg('--page', args);
+    if (!pageId) { console.error('usage: node scripts/gds/tweak-renders.js shoot --page <id> --phase before|after --out <dir>'); return 2; }
+    if (cmd === 'plan') {
+      const reader = require('./page-reader.js');
+      const inventory = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, reader.INVENTORY_REL), 'utf8'));
+      const planned = planForPage(pageId, { inventory, planRenders: reader.planRenders });
+      if (!planned.ok) { console.error(`tweak-renders: ${planned.code} (${pageId})`); return 2; }
+      for (const phase of taskVisuals.TWEAK_RENDER_PHASES) for (const s of shotsFor(phase, planned.plan)) console.log(`${s.slot}\t${s.width}px\t${s.renderMode}\t${planned.plan.url}`);
+      return 0;
+    }
+    const phase = arg('--phase', args);
+    const out = arg('--out', args);
+    if (!taskVisuals.TWEAK_RENDER_PHASES.includes(phase) || !out) { console.error('usage: node scripts/gds/tweak-renders.js shoot --page <id> --phase before|after --out <dir>'); return 2; }
+    return shoot({ pageId, phase, out: path.resolve(out) });
+  }
+  if (cmd === 'attach') {
+    const taskId = Number(args[1]);
+    const dir = arg('--dir', args);
+    if (!Number.isInteger(taskId) || taskId <= 0 || !dir) { console.error('usage: node scripts/gds/tweak-renders.js attach <task-id> --dir <dir>'); return 2; }
+    return attach({ taskId, dir: path.resolve(dir) });
+  }
+  console.error('usage: node scripts/gds/tweak-renders.js shoot|attach|plan … (see the file header)');
+  return 2;
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then((code) => cliExit(code), (e) => { console.error(`tweak-renders: ${e.stack || e.message}`); cliExit(1); });
+}
+
+module.exports = { shotsFor, planForPage, attach };

package/scripts/hall-preview/server.js

@@ -136,6 +136,9 @@ const FIXTURE_FALLBACKS = [
   // page id, since the editor shows one page. A page id carries a colon, which a
   // Windows file name cannot, so there is no per-id file to find first.
   [/^copy-desk\/pages\/[a-z0-9-]+:[a-z0-9-]+\/draft$/, 'copy-desk__pages__draft'],
+  // the Approval queue's renders (task 1004323): a round's named visuals, one
+  // fixture for any task id, as the editor read above serves any page.
+  [/^tasks\/\d+\/visuals$/, 'tasks__visuals'],
 ];
 
 // CANNED WRITES (task 1004321). The tweak editor's whole flow is writes (the
@@ -148,6 +151,10 @@ const CANNED_WRITES = [
   ['PUT', /^copy-desk\/pages\/[a-z0-9-]+:[a-z0-9-]+\/draft$/, 'copy-desk__pages__draft.put'],
   ['POST', /^copy-desk\/pages\/[a-z0-9-]+:[a-z0-9-]+\/submit$/, 'copy-desk__pages__submit.post'],
   ['POST', /^copy-desk\/pages\/[a-z0-9-]+:[a-z0-9-]+\/claim$/, 'copy-desk__pages__claim.post'],
+  // the Approval queue's two decisions (task 1004323), so the approved and
+  // sent-back lines the artboard draws render too.
+  ['POST', /^copy-desk\/pages\/[a-z0-9-]+:[a-z0-9-]+\/approve$/, 'copy-desk__pages__approve.post'],
+  ['POST', /^copy-desk\/pages\/[a-z0-9-]+:[a-z0-9-]+\/send-back$/, 'copy-desk__pages__send-back.post'],
 ];
 
 // A DATE THAT ROTS CANNOT DEMO AN AGE SIGNAL (task 1004041). The help-request
@@ -252,6 +259,17 @@ app.use((req, res, next) => {
   // frame, so the one thing being reviewed is the one thing you cannot see.
   // A generated stand-in; see scripts/hall-preview/task-visual.js.
   if (/^task-visuals\/[A-Za-z0-9._-]+$/.test(apiPath) && req.method === 'GET') {
+    // HALL_PREVIEW_VISUALS=<dir> serves a REAL image of that name from <dir>
+    // instead (task 1004323): the Approval queue's review sheet shows the renders
+    // /tweak really attached, copied under the fixture's names into a scratch
+    // dir. Nothing is committed; unset, every visual is the stand-in as before.
+    const realDir = process.env.HALL_PREVIEW_VISUALS;
+    const name = apiPath.slice('task-visuals/'.length);
+    const real = realDir && /^task-\d+-[0-9a-f]{16}\.(png|jpg)$/.test(name) ? path.join(realDir, name) : null;
+    if (real && fs.existsSync(real)) {
+      res.set({ 'content-type': name.endsWith('.png') ? 'image/png' : 'image/jpeg', 'cache-control': 'no-store' });
+      return res.end(fs.readFileSync(real));
+    }
     const png = require('./task-visual').placeholderPng();
     res.set({ 'content-type': 'image/png', 'cache-control': 'no-store' });
     return res.end(png);

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.1063'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1065'; // 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('dev-box'); log.info('mounted');