@bongos/core 1.19.348 → 1.19.350

package/modules/lifecycle/github-push.js

@@ -130,6 +130,23 @@ function scrubCredential(s) {
     .replace(/(ghs_|ghp_|github_pat_)[A-Za-z0-9_]+/g, '$1***');
 }
 
+// How much scrubbed stderr travels with a failure (task 1003222). Sized to hold a
+// real git failure whole — the 'remote:' lines that name the cause arrive LAST, so a
+// short cap deletes precisely the part worth reading. It is a payload bound, nothing
+// more; when it bites, truncateLoudly says so rather than ending mid-word.
+const STDERR_MAX = 8000;
+
+// Truncate in a way the reader can SEE. A silent clip is worse than no message: it
+// looks like the complete text, which is how 'error: failed' got mistaken for the
+// whole story. Keeps the TAIL as well as the head, because git's useful line is last.
+function truncateLoudly(text, max = STDERR_MAX) {
+  const s = String(text || '');
+  if (s.length <= max) return s;
+  const head = Math.floor(max * 0.4);
+  const tail = max - head;
+  return `${s.slice(0, head)}\n\n…[${s.length - max} characters omitted — full text in the server log]…\n\n${s.slice(-tail)}`;
+}
+
 // Default git seam: execFile arg-array, shell:false, stdout captured. On failure
 // throws GIT_FAILED. We never echo the (possibly credentialed) argv, but DO attach
 // the credential-scrubbed stderr + the caller's step label (task 1547) so a real
@@ -149,9 +166,30 @@ async function defaultExec(args, opts = {}) {
     return stdout;
   } catch (e) {
     // Identify the failing step by the caller's label, never by echoing argv.
-    // Surface the scrubbed stderr (truncated) so the cause is loud in the log.
-    const stderr = scrubCredential(e && (e.stderr || e.message)).trim().slice(0, 500);
-    throw err('GIT_FAILED', { git_step: step || (args && args[0]) || null, stderr });
+    //
+    // THE STDERR IS NOT CLIPPED SHORT ANY MORE (task 1003222). It used to be cut at
+    // 500 chars here and again at 200 on the way to the client, so a builder saw
+    // 'error: failed' — clipped mid-word, naming neither cause nor remedy — while the
+    // line that mattered ('remote: fatal error in commit_refs') and the exit code
+    // existed only server-side. That cost hours on the blocker-1000117 outage AND
+    // produced a WRONG first diagnosis, because the real message was never in the
+    // room. git puts the useful line LAST (the 'remote:' lines follow the progress
+    // chatter), which is exactly what a head-truncation throws away.
+    //
+    // The cap is a payload guard, not an editorial decision: generous enough that a
+    // real push failure fits whole, and when it does bite the text SAYS SO instead of
+    // ending mid-word and reading like the whole message.
+    const raw = scrubCredential(e && (e.stderr || e.message)).trim();
+    const stderr = truncateLoudly(raw, STDERR_MAX);
+    throw err('GIT_FAILED', {
+      git_step: step || (args && args[0]) || null,
+      stderr,
+      stderr_bytes: raw.length,
+      // The exit code distinguishes failure SHAPES that read identically in prose —
+      // 128 (git said no) vs 1 (a ref was rejected) vs null (killed by the timeout).
+      exit_code: (e && typeof e.code === 'number') ? e.code : null,
+      timed_out: !!(e && e.killed),
+    });
   }
 }
 
@@ -456,7 +494,14 @@ async function openOrFindPullRequest({ branch, title, body }, deps = {}) {
   });
   if (!createRes.ok) {
     const detail = await createRes.text().catch(() => '');
-    throw err('PR_CREATE_FAILED', { status: createRes.status, detail: detail.slice(0, 300) });
+    // Same reasoning as GIT_FAILED's stderr (task 1003222): GitHub's refusal body
+    // names the actual rule that refused ('No commits between main and X', a
+    // protected-branch rule, a validation error naming the field) and a 300-char
+    // clip regularly cut it off. Scrubbed, because a body can echo a request header.
+    throw err('PR_CREATE_FAILED', {
+      status: createRes.status,
+      detail: truncateLoudly(scrubCredential(detail), STDERR_MAX),
+    });
   }
   const pr = await createRes.json();
   return { number: pr.number, url: pr.html_url, node_id: pr.node_id };
@@ -1360,6 +1405,8 @@ module.exports = {
   prReferencesTask,
   findTaskPullRequest,
   scrubCredential,
+  truncateLoudly,   // task 1003222 — exported so its behaviour is testable, not just its effect
+  STDERR_MAX,
   isAncestorOfDefaultBranch,
   resolveToken,
   getInstallationToken,

package/modules/lifecycle/module.json

@@ -18,7 +18,8 @@
       "gate-approvals",
       "analytics",
       "lifecycle",
-      "help-requests"
+      "help-requests",
+      "visuals"
     ],
     "pollers": [
       "publish-reconciler"

package/modules/lifecycle/routes/tasks.js

@@ -979,7 +979,12 @@ module.exports = function buildTasksRouter() {
       if (e.code === 'NO_REPO_INFO') return res.fail('no_repo_info', 500);
       if (e.code === 'PUSH_UNCONFIGURED') return res.fail('push_unconfigured', { status: 503, message: PUSH_UNCONFIGURED_MSG });
       if (e.code === 'APP_NOT_INSTALLED') return res.fail('push_unconfigured', { status: 503, message: appNotInstalledMessage(e) });
-      if (e.code === 'PR_CREATE_FAILED') return res.fail('pr_create_failed', 502, { detail: e.detail });
+      // The GitHub HTTP status travels WITH the body (task 1003222). 422 ('no commits
+      // between'), 403 (a protected-branch rule) and 404 (the App cannot see the repo)
+      // are three different remedies, and the body alone does not always separate them.
+      if (e.code === 'PR_CREATE_FAILED') {
+        return res.fail('pr_create_failed', 502, { detail: e.detail, github_status: e.status ?? null });
+      }
       // task 1547: GIT_FAILED now carries WHICH git step failed + the credential-
       // scrubbed stderr (github-push.defaultExec). Log both so the next push outage
       // is a one-line diagnosis, not a multi-hour opaque-`publish_failed` mystery
@@ -990,7 +995,22 @@ module.exports = function buildTasksRouter() {
         e.git_step ? `step=${e.git_step}` : '',
         e.stderr ? `stderr=${e.stderr}` : ''
       );
-      return res.fail('publish_failed', 500, { ...(e.git_step ? { step: e.git_step } : {}), ...(e.stderr ? { reason: String(e.stderr).slice(0, 200) } : {}) });
+      // NO SECOND TRUNCATION (task 1003222). This line used to clip the already-
+      // shortened stderr to 200 chars, so the builder got 'error: failed' — cut
+      // mid-word, naming neither cause nor remedy — while the real remote message sat
+      // in a log they could not reach. A publish failure must be diagnosable from
+      // where the builder is STANDING; that is the whole point of the task.
+      //
+      // `reason` keeps its name and position so existing readers (ship.js prints it)
+      // keep working; it is simply no longer amputated. Everything here is already
+      // credential-scrubbed at the throw site by github-push.scrubCredential.
+      return res.fail('publish_failed', 500, {
+        ...(e.git_step ? { step: e.git_step } : {}),
+        ...(e.stderr ? { reason: e.stderr } : {}),
+        ...(e.stderr_bytes != null ? { reason_bytes: e.stderr_bytes } : {}),
+        ...(e.exit_code != null ? { git_exit_code: e.exit_code } : {}),
+        ...(e.timed_out ? { timed_out: true } : {}),
+      });
     } finally {
       try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) { /* best-effort */ }
     }

package/modules/lifecycle/routes/visuals.js

@@ -0,0 +1,216 @@
+// modules/lifecycle/routes/visuals.js — the ship-time task VISUAL, whole
+// surface (task 1003109, goal 1000072 "Human legibility").
+//
+// NAMED `visuals.js`, NOT `task-visuals.js`, and that is load-bearing:
+// tests/helpers.mjs:taskRoutesSource() concatenates `tasks.js` + every
+// `task-*.js` in this directory as "the tasks-route family" (the carve products
+// task-route-helpers.js / task-write-routes.js). A file called task-visuals.js
+// sorts FIRST in that concatenation, so its `res.status(201)` body became the one
+// tests/goal_advisory.mjs + tests/est_advisory.mjs inspect — and both failed on a
+// route that was perfectly correct. Adding a `task-*.js` route file here silently
+// hijacks those assertions; don't.
+//
+//   POST   /tasks/:id/visual    attach or replace it   (claim holder | Archon)
+//   DELETE /tasks/:id/visual    take it back off       (claim holder | Archon)
+//   GET    /task-visuals/:name  serve one              (see the audience note)
+//
+// The twin of routes/bug-attachments.js, for the image a builder attaches to
+// their own shipped task instead of one the bot pulled out of #bugs. Storage +
+// screening live in ../task-visuals.js; all three routes live here rather than
+// in the (already 1800-line) routes/tasks.js so the feature reads as one thing.
+//
+// rank: public — but CONDITIONALLY, and the condition is the whole point of the
+// file, so read this before changing the mounting.
+//
+//   A visual carries no audience of its own: it restates the task's
+//   value_summary in another medium, so it inherits that summary's audience
+//   exactly. For already-public work (shipped|confirmed, not security_sensitive)
+//   the summary is on the open web — the unauthenticated status dashboard renders
+//   it — so the image is served unauthenticated too. For anything else the image
+//   is served ONLY to an authenticated builder, via the very same
+//   auth.requireBuilder used everywhere else in the GDS.
+//
+//   That is why the gate is applied INSIDE the handler rather than as a mounted
+//   middleware: the decision needs the task the filename names. The stored
+//   filename embeds the task id (task-<id>-<hex>.<ext>) precisely so this lookup
+//   is possible without a second table. It FAILS CLOSED at every step — an
+//   unparseable name, an absent task, or a task that is not already-public all
+//   fall through to requireBuilder, never past it.
+//
+// The audience predicate itself lives once, in ../task-visuals.js
+// (isPubliclyViewable), and is mirrored in the public shipped-feed SQL.
+
+const express = require('express');
+const fs = require('node:fs/promises');
+// Intra-module + the published doorway — a module never requires a core internal.
+const api = require('../../../src/module-api');
+const auth = api;
+// The feature's own two queries — kept out of the 5.8k-line ../db.js under the
+// shrink-only size ratchet; see the file header there.
+const db = require('../task-visual-db');
+const visuals = require('../task-visuals');
+// The claim-holder gate the whole ship path uses (/grade /confirm /ship
+// /publish-branch). Intra-module sibling — reused, never re-stated.
+const { gateTaskOwnership } = require('./tasks');
+const { validateOrRespond, parseId } = api;
+const log = api.logger('lifecycle');
+
+// Body caps for POST /tasks/:id/visual. Two layers, like /publish-branch: the
+// JSON limit bounds the ENCODED base64 string, and visuals.screenImage re-checks
+// the DECODED bytes against visuals.MAX_BYTES (4 MB).
+const VISUAL_BODY_LIMIT = '8mb';
+const VISUAL_B64_MAX = 7 * 1024 * 1024;
+
+module.exports = function buildTaskVisualsRouter() {
+  const router = express.Router();
+
+  // rank: public — the WIDEST path this route can take, declared honestly. It is
+  // reached only for already-public work (see isPubliclyViewable); every other
+  // request falls through to auth.requireBuilder INSIDE the handler, because the
+  // decision needs the task the filename names. Read the file header before
+  // changing this — a mounted middleware cannot express a per-row audience.
+  // GET /api/bongos/task-visuals/:name — stream one stored visual.
+  router.get('/task-visuals/:name', async (req, res, next) => {
+    const name = req.params.name;
+    const filePath = visuals.resolveSafe(name);
+    // Refuse a malformed name BEFORE any lookup — this is the path-traversal
+    // wall, and it also means the id parsed below is always well-formed.
+    if (!filePath) return res.fail('bad_name', 400);
+
+    const taskId = visuals.taskIdFromName(name);
+    let task = null;
+    try {
+      task = await db.getTaskVisualAccess(taskId);
+    } catch (err) {
+      // A lookup failure must not become an open door. Log and fall through to
+      // the authenticated path — a builder still gets the image, the open web
+      // does not.
+      log.error({ taskId, err: err && err.message }, 'task-visual access lookup failed — falling back to the authenticated path');
+    }
+
+    const send = async () => {
+      try {
+        const data = await fs.readFile(filePath);
+        res.setHeader('Content-Type', visuals.contentTypeForName(name));
+        // Never let a browser sniff a stored byte-string into something
+        // executable on our own origin, and keep it inline (it renders in the
+        // hall) but explicitly not as a download.
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        res.setHeader('Content-Disposition', 'inline');
+        res.setHeader('Content-Security-Policy', "default-src 'none'; sandbox");
+        // A stored file is immutable — a replacement gets a NEW random name — so
+        // it can be cached hard. Public work caches shared; everything else stays
+        // private to the builder's own browser.
+        res.setHeader(
+          'Cache-Control',
+          visuals.isPubliclyViewable(task) ? 'public, max-age=86400' : 'private, max-age=86400'
+        );
+        res.send(data);
+      } catch (err) {
+        if (err.code === 'ENOENT') return res.fail('not_found', 404);
+        log.error({ name, err: err && err.message }, 'task-visual read failed');
+        res.fail('read_failed', 500);
+      }
+    };
+
+    if (visuals.isPubliclyViewable(task)) return send();
+    // Not already-public → the ordinary builders-only GDS posture. requireBuilder
+    // owns its own 401/403 response; we only reach send() when it calls next().
+    return auth.requireBuilder(req, res, (err) => (err ? next(err) : send()));
+  });
+
+  // ==========================================================================
+  // Ship-time task VISUAL (task 1003109, goal 1000072 "Human legibility")
+  // --------------------------------------------------------------------------
+  // `value_summary` gives a reader the plain-language "what this means" line. A
+  // visual is that SAME claim in another medium — a screenshot of the surface
+  // that changed, a before/after, a diagram — so a non-engineer can SEE a change
+  // instead of reading about it (owner idea 1000400). Storage + screening live in
+  // ../task-visuals.js; the serve route above is what renders it back.
+  //
+  // ALWAYS OPTIONAL. Nothing on the ship path calls this, or blocks on it: the
+  // CLI uploads only when the builder passed --visual, and a failure there is a
+  // warning, never an abort. A task with no visual is a complete task.
+  //
+  // AUTH: requireBuilder + gateTaskOwnership — exactly the /grade /confirm /ship
+  // /publish-branch gate. Only the task's claim holder (or an Archon) may say
+  // what a task's shipped work looked like; anyone else attaching an image to
+  // someone else's ledger entry is the misattribution this closes.
+  const visualUpload = express.json({ limit: VISUAL_BODY_LIMIT });
+  // POST /tasks/:id/visual — attach (or replace) this task's ship-time visual.
+  router.post('/tasks/:id/visual', auth.requireBuilder, visualUpload, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    if (validateOrRespond(req, res, {
+      image_b64: { required: true, type: 'string', maxLength: VISUAL_B64_MAX, minLength: 1 },
+      content_type: { required: true, type: 'string', maxLength: 100, minLength: 1 },
+      alt: { type: 'string', maxLength: visuals.MAX_ALT_LENGTH },
+    })) return;
+    if (!(await gateTaskOwnership(req, res, id))) return;
+
+    // The JSON `limit` bounds the ENCODED payload; base64 inflates ~33%, so the
+    // DECODED bytes are re-checked in screenImage (the publish-branch posture).
+    // Buffer.from never throws on malformed base64 — it drops what it can't
+    // decode — so there is no decode error to catch here: garbage in produces
+    // bytes that fail the magic-byte sniff below, which is the real gate.
+    const buf = Buffer.from(req.body.image_b64, 'base64');
+    const screened = visuals.screenImage(buf, req.body.content_type);
+    if (!screened.ok) {
+      const status = screened.reason === 'too_big' ? 413 : 400;
+      return res.fail(`visual_${screened.reason}`, status, {
+        max_bytes: visuals.MAX_BYTES,
+        accepted: Object.keys(visuals.EXT_BY_TYPE),
+      });
+    }
+
+    // Read the task (and its current visual) BEFORE writing, so a replaced image
+    // can be unlinked and a vanished task 404s rather than orphaning a file.
+    const before = await db.getTaskVisualAccess(id);
+    if (!before) return res.fail('task_not_found', 404);
+
+    try {
+      const stored = await visuals.persistImageBuffer(buf, {
+        taskId: id,
+        contentType: req.body.content_type,
+      });
+      if (!stored.ok) return res.fail(`visual_${stored.reason}`, 400);
+      const row = await db.setTaskVisual({
+        taskId: id,
+        visualUrl: stored.url,
+        visualAlt: visuals.normalizeAlt(req.body.alt),
+      });
+      // Replacing: drop the superseded file. Best-effort — a failed unlink leaves
+      // an unreferenced file, which is harmless; a failed RESPONSE would not be.
+      if (before.visual_url && before.visual_url !== stored.url) {
+        await visuals.deleteStored(before.visual_url);
+      }
+      return res.status(201).json({ ok: true, visual_url: row.visual_url, visual_alt: row.visual_alt, bytes: stored.bytes });
+    } catch (err) {
+      log.error({ taskId: id, err: err && err.message }, 'task-visual upload failed');
+      return res.fail('visual_store_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // DELETE /tasks/:id/visual — remove it again. The counterpart to "always
+  // optional": a builder who attached the wrong screenshot must be able to take
+  // it back, and an image is not prose (the write-once rule of task 1003102
+  // guards a written CLAIM, not the picture beside it). Same ownership gate as
+  // the POST. Idempotent — removing an absent visual is a success.
+  router.delete('/tasks/:id/visual', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    if (!(await gateTaskOwnership(req, res, id))) return;
+    const before = await db.getTaskVisualAccess(id);
+    if (!before) return res.fail('task_not_found', 404);
+    try {
+      await db.setTaskVisual({ taskId: id, visualUrl: null, visualAlt: null });
+      if (before.visual_url) await visuals.deleteStored(before.visual_url);
+      return res.json({ ok: true, visual_url: null });
+    } catch (err) {
+      log.error({ taskId: id, err: err && err.message }, 'task-visual delete failed');
+      return res.fail('visual_delete_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};

package/modules/lifecycle/task-visual-db.js

@@ -0,0 +1,46 @@
+'use strict';
+
+// modules/lifecycle/task-visual-db.js — the two queries behind a task's ship-time
+// visual (task 1003109, goal 1000072 "Human legibility").
+//
+// WHY ITS OWN FILE. These belong logically in ../db.js with the rest of the
+// lifecycle data layer — but that file is already ~5,800 lines, and the size
+// ratchet (scripts/gds/fitness-ratchets.js, task 1003129) is shrink-only: an
+// oversized file may not grow. A feature's data access going into a small,
+// cohesive file next to the feature's storage lib is the shape that rule is
+// asking for, so this is the rule working rather than an exception to it.
+//
+// Both helpers are deliberately tiny and status-blind: this layer stores and
+// reads a URL. The ROUTES own who may WRITE it (the task's claim holder) and who
+// may SEE it (whoever may already read the task's value_summary — the predicate
+// is task-visuals.isPubliclyViewable).
+
+// The published doorway — a module never requires a core internal.
+const { pool } = require('../../src/module-api');
+
+// Set (or clear) a task's visual. Returns the updated row, or null when the task
+// does not exist. The caller reads the PREVIOUS visual_url through
+// getTaskVisualAccess first (it already does, to authorize) and unlinks the
+// superseded file after this returns.
+async function setTaskVisual({ taskId, visualUrl = null, visualAlt = null }) {
+  const { rows } = await pool.query(
+    `UPDATE tasks SET visual_url = $2, visual_alt = $3, updated_at = now()
+      WHERE id = $1 RETURNING id, visual_url, visual_alt`,
+    [taskId, visualUrl, visualAlt]
+  );
+  return rows[0] ?? null;
+}
+
+// The minimum a serve route needs to decide a stored image's audience: does the
+// task exist, is it already-public work, and is it security-sensitive. Kept to
+// these four columns on purpose — a gate must not be able to leak anything else
+// about a task it is about to refuse.
+async function getTaskVisualAccess(taskId) {
+  const { rows } = await pool.query(
+    `SELECT id, status, security_sensitive, visual_url FROM tasks WHERE id = $1`,
+    [taskId]
+  );
+  return rows[0] ?? null;
+}
+
+module.exports = { setTaskVisual, getTaskVisualAccess };