@bongos/core 1.19.492 → 1.19.493

package/modules/copy-desk/proposals.js

@@ -0,0 +1,278 @@
+// modules/copy-desk/proposals.js — the PROPOSAL: an artist's replacement wording
+// for one string, carried as a patch on a GDS task (task 1003114 / R03 of goal
+// 1000074, the artist's loop).
+//
+// WHY THIS FILE EXISTS. R02 gave the artist a way to say "this sentence is
+// wrong" (the flag). It deliberately gave them no way to say what it should say
+// instead, because the obvious place to put that — a column next to the flag —
+// is the exact shape goal 1000074 forbids: "NO LIVE CMS ... never a write path
+// that bypasses the ledger" (and ADR 0178 §3, which pins that copy_desk_flags
+// has no column that could hold replacement text and must never gain one).
+//
+// THE SHAPE THAT SATISFIES BOTH HALVES, and it is borrowed rather than invented:
+// ADR 0081 already solved this problem for the DESIGN half. A tool authors, an
+// adapter EXPORTS its output into the repo as a committed diff under a claimed
+// task, and the repo stays the source of truth (modules/ui-design/adapters/*,
+// `adapter.export()`). This is that contract for TEXT. The artist is the tool;
+// the copy desk is where they author; the proposal is the export. So a proposal
+// is not a row this module keeps — it is a PATCH, rendered into the description
+// of a task, which is the ledger the methodology already requires every change
+// to pass through. Nothing renders from it; scripts/gds/copy-apply.js is the
+// only reader, and it runs under a claim.
+//
+// WHERE THE PATCH LIVES, AND WHY IT IS A FENCED BLOCK. It has to be readable by
+// a person reviewing the task (the whole point is that the change is arguable
+// before it lands) and parseable by the applier. A fenced ```copy-proposal block
+// in the task description is both, renders as itself in the hall, and survives a
+// person editing the prose around it. It is deliberately NOT a database column
+// anywhere: a column is one join away from being read as copy, which is the
+// erosion ADR 0178 describes.
+//
+// PURE — no DB, no fs, no clock. Both callers import it: the route
+// (routes/copy-desk.js) composes, the applier (scripts/gds/copy-apply.js)
+// parses, and neither owns a second copy of the format.
+
+'use strict';
+
+// The patch format's version. The applier refuses anything else BY NAME rather
+// than doing its best with a shape it does not know — a half-understood patch
+// edits the wrong characters of a real file.
+const PROPOSAL_SCHEMA = 1;
+
+// The fence tag. Chosen to be unmistakable in a task description and impossible
+// to produce by accident.
+const FENCE = 'copy-proposal';
+
+// The same judgement floor R02 put on a flag's reason, for the same reason
+// (ADR 0178 §2): a proposal with no argument hands a reviewer a diff and no way
+// to decide it, which costs them more than not proposing. The DB CHECK that
+// backs the flag's floor has no equivalent here because there is no row — the
+// floor is enforced at the one write vector, which is this file's caller.
+const MIN_WHY_CHARS = 10;
+const MAX_WHY_CHARS = 2000;
+
+// 400 is the registry's own upper bound on what counts as one string
+// (`looksLikeCopy` in scripts/gds/copy-inventory.js). Proposing something longer
+// than the inventory can hold would produce a patch that lands and then vanishes
+// from the next registry — a change that silently un-inventories itself.
+const MAX_TEXT_CHARS = 400;
+
+// The interpolation hole the inventory writes for `${...}`. A proposal must keep
+// exactly as many as the current text has, in the same order: the applier maps
+// the k-th hole back to the k-th expression it found in the source. Reordering
+// or dropping one is a code change, not a copy change, and is refused by name.
+const PLACEHOLDER = '{…}';
+
+const fail = (code, detail) => ({ ok: false, code, detail: detail ?? null });
+
+// Collapse whitespace runs and trim — the same normalization the inventory
+// applies when it records a string, so a proposal is measured and stored in the
+// form it will actually be compared against.
+function tidy(raw) {
+  return String(raw == null ? '' : raw).replace(/\s+/g, ' ').trim();
+}
+
+function placeholderCount(text) {
+  return String(text || '').split(PLACEHOLDER).length - 1;
+}
+
+// Validate one POSTed proposal into the patch the task will carry.
+//
+// `entry` is the registry occurrence being changed, and it is REQUIRED and
+// server-side. Every fact about the TARGET — surface, file, line, render path,
+// and the current wording — is copied from it and never from the request body,
+// which is R02's rule for a flag's snapshot (ADR 0178 §6) and matters more here:
+// a caller-supplied "current text" would let a proposal describe a change to a
+// sentence that does not exist, and the applier would then be editing a file on
+// the strength of a claim nobody checked.
+//
+// PURE. The caller resolves `entry` from the loaded registry first.
+function normalizeProposalPayload({ body = {}, entry, builderId = null } = {}) {
+  if (!entry || !entry.file || !entry.text) return fail('unknown_target');
+
+  const proposed = tidy(body.proposed_text);
+  const why = tidy(body.why);
+  const current = tidy(entry.text);
+
+  if (!proposed) {
+    return fail('proposed_text_missing', {
+      what_this_means: 'A proposal is a replacement wording. Without one there is nothing to land — file a flag instead if you only want to mark this as wrong.',
+    });
+  }
+  if (proposed.length > MAX_TEXT_CHARS) {
+    return fail('proposed_text_too_long', { max: MAX_TEXT_CHARS, was: proposed.length });
+  }
+  if (proposed === current) {
+    return fail('proposed_text_unchanged', {
+      what_this_means: 'The proposed wording is the current wording. Nothing would change.',
+    });
+  }
+  if (why.length < MIN_WHY_CHARS) {
+    return fail('why_too_thin', {
+      min: MIN_WHY_CHARS,
+      what_this_means: 'A reviewer has to be able to decide this without asking you. Say what is wrong with the current wording and what the new one does better — the same floor a flag’s reason carries.',
+    });
+  }
+  if (why.length > MAX_WHY_CHARS) {
+    return fail('why_too_long', { max: MAX_WHY_CHARS, was: why.length });
+  }
+
+  // The placeholder arithmetic. This is the one rule that makes the patch
+  // MECHANICALLY applicable rather than a note for an engineer: the applier
+  // re-injects the source's own interpolations into the holes, so the count has
+  // to match and the order has to be the author's intent.
+  const want = placeholderCount(current);
+  const got = placeholderCount(proposed);
+  if (want !== got) {
+    return fail('placeholder_mismatch', {
+      expected: want,
+      got,
+      placeholder: PLACEHOLDER,
+      what_this_means: want === 0
+        ? `This string has no ${PLACEHOLDER} holes, so the new wording must not introduce any.`
+        : `This string is assembled at render time and has ${want} ${PLACEHOLDER} hole(s) where a value is dropped in. Keep all ${want}, in the order the sentence needs them — moving or removing one is a code change, not a copy change.`,
+    });
+  }
+
+  return {
+    ok: true,
+    patch: {
+      schema: PROPOSAL_SCHEMA,
+      string_id: entry.id,
+      surface: entry.surface,
+      file: entry.file,
+      line: entry.line,
+      origin: entry.origin,
+      current,
+      proposed,
+      why,
+      proposed_by: builderId ?? null,
+    },
+  };
+}
+
+// Render the patch as the fenced block that goes in the task's description.
+// JSON with a stable key order and two-space indent: a reviewer reads it, and a
+// diff of two proposals against the same string lines up.
+function composeProposalBlock(patch) {
+  const ordered = {
+    schema: patch.schema,
+    string_id: patch.string_id,
+    surface: patch.surface,
+    file: patch.file,
+    line: patch.line,
+    origin: patch.origin,
+    current: patch.current,
+    proposed: patch.proposed,
+  };
+  return ['```' + FENCE, JSON.stringify(ordered, null, 2), '```'].join('\n');
+}
+
+// The reverse. Returns the FIRST block in the text: a task description carries
+// exactly one proposal, and if someone has pasted a second the applier must not
+// silently pick one — so a second block is a named refusal, not a coin flip.
+function parseProposalBlock(markdown) {
+  const src = String(markdown || '');
+  const re = new RegExp('```' + FENCE + '\\s*\\n([\\s\\S]*?)\\n```', 'g');
+  const found = [...src.matchAll(re)];
+  if (!found.length) return fail('no_proposal_block', { fence: FENCE });
+  if (found.length > 1) {
+    return fail('multiple_proposal_blocks', {
+      count: found.length,
+      what_this_means: 'This task carries more than one proposal. Split them: one task changes one string, so the grade and the diff are about one decision.',
+    });
+  }
+  let patch;
+  try {
+    patch = JSON.parse(found[0][1]);
+  } catch (err) {
+    return fail('proposal_block_unreadable', { reason: err.message });
+  }
+  if (Number(patch && patch.schema) !== PROPOSAL_SCHEMA) {
+    return fail('proposal_schema_unknown', { expected: PROPOSAL_SCHEMA, got: patch && patch.schema });
+  }
+  for (const field of ['string_id', 'surface', 'file', 'origin', 'current', 'proposed']) {
+    if (typeof patch[field] !== 'string' || !patch[field]) {
+      return fail('proposal_field_missing', { field });
+    }
+  }
+  if (!Number.isInteger(patch.line) || patch.line < 1) {
+    return fail('proposal_field_missing', { field: 'line' });
+  }
+  return { ok: true, patch };
+}
+
+// The task a proposal becomes. Title names the surface and quotes enough of the
+// current wording to be recognizable in a board list; the body carries the
+// artist's argument, the patch, and the one command that lands it.
+function proposalTaskTitle(patch) {
+  const snippet = patch.current.length > 60 ? `${patch.current.slice(0, 57)}…` : patch.current;
+  return `Copy: reword “${snippet}” on ${patch.surface}`;
+}
+
+// The task's own instructions. They must be RUNNABLE AS WRITTEN — a placeholder
+// a claimer has to substitute is a step to get wrong, and this is the one
+// handoff between the person who wrote the words and the person who lands them.
+//
+// The task cannot know its own id at the moment its description is composed, so
+// the command takes none: `copy-apply.js` with no argument acts on the task you
+// are HOLDING. That is not a convenience, it is the rule — a copy change lands
+// under a claim, and a claim already names a task.
+function proposalTaskBody(patch) {
+  return [
+    `An artist proposed new wording for one string on the \`${patch.surface}\` surface.`,
+    '',
+    '**Why**',
+    '',
+    patch.why,
+    '',
+    '**The change**',
+    '',
+    `- current: ${JSON.stringify(patch.current)}`,
+    `- proposed: ${JSON.stringify(patch.proposed)}`,
+    `- where: \`${patch.file}:${patch.line}\` (${patch.origin})`,
+    '',
+    '**How it lands**',
+    '',
+    'This is a proposal, not a change — nothing has been written. Claim this task and run:',
+    '',
+    '```bash',
+    'node scripts/gds/copy-apply.js',
+    '```',
+    '',
+    'That re-derives the string’s position in the working tree, replaces exactly those characters, regenerates the copy registry and prints the diff for review. Then ship it like any other change — the grader sees the real diff.',
+    '',
+    'If the applier refuses, it says why in one line; a refusal means the file moved on under the proposal and a person should look, not that the wording was wrong.',
+    '',
+    composeProposalBlock(patch),
+  ].join('\n');
+}
+
+// The (source, source_ref) pair the create-vector idempotency read keys on
+// (db.findTaskBySourceRef). Keyed on the string AND the proposed wording, so a
+// double-submitted proposal resolves to the task it already made, while a
+// genuinely different second attempt at the same string is a new task — which is
+// right: two people can disagree about the fix, and the board should hold both.
+function proposalSourceRef(patch) {
+  let hash = 5381;
+  const material = `${patch.string_id}${patch.file}${patch.line}${patch.proposed}`;
+  for (let i = 0; i < material.length; i += 1) hash = (((hash << 5) + hash) ^ material.charCodeAt(i)) >>> 0;
+  return `copy-proposal-${patch.string_id}-${hash.toString(36)}`;
+}
+
+module.exports = {
+  PROPOSAL_SCHEMA,
+  FENCE,
+  PLACEHOLDER,
+  MIN_WHY_CHARS,
+  MAX_WHY_CHARS,
+  MAX_TEXT_CHARS,
+  tidy,
+  placeholderCount,
+  normalizeProposalPayload,
+  composeProposalBlock,
+  parseProposalBlock,
+  proposalTaskTitle,
+  proposalTaskBody,
+  proposalSourceRef,
+};

package/modules/copy-desk/routes/copy-desk.js

@@ -1,12 +1,14 @@
 // modules/copy-desk/routes/copy.js — the copy-flag surface (task 1003113 / R02 of
 // goal 1000074, the artist's loop).
 //
-// Three jobs:
+// Four jobs (the fourth added by task 1003114 / R03 — see below):
 //   GET  /copy-desk/queue            — the artist's working list: open flags with
 //                                 live registry state attached, plus the
 //                                 deterministic duplicate candidates.
 //   POST /copy-desk/flags            — file a flag. ANY signed-in builder, any role.
 //   POST /copy-desk/flags/:id/close  — resolve or dismiss one, with a note.
+//   POST /copy-desk/proposals        — propose new wording. Creates a TASK carrying
+//                                 the patch; writes no file and stores no copy.
 //
 // THE RANK SHAPE, AND WHY IT IS ASYMMETRIC:
 //
@@ -24,10 +26,14 @@
 //   The refusal names both paths rather than dead-ending on a bare 403.
 //
 // WHAT DOES NOT EXIST HERE, AND MUST NOT: any route that writes a user-facing
-// string. NO LIVE CMS is the goal's hard non-goal (task 1003114 / R03 makes the
-// editing affordance produce a TASK, not a write). A flag is a work request.
-// modules/copy-desk/tests/copy_no_cms.mjs pins that by asserting this router's write
-// surface stays exactly these two verbs.
+// string. NO LIVE CMS is the goal's hard non-goal, and R03 kept it while adding
+// the editing affordance the goal also asked for — by making the affordance
+// produce a TASK carrying a patch, never a write. A flag is a work request; a
+// proposal is a work request with a suggested fix attached. Neither reaches a
+// reader. modules/copy-desk/tests/copy_no_cms.mjs pins that by asserting this
+// router's write surface stays exactly these three verbs, that none of them
+// touches the filesystem, and that the one place a proposed wording is allowed
+// to rest is the GDS ledger.
 //
 // Same idioms as modules/security/routes/*.js: doorway-only requires, res.fail
 // codes, factory export mounted from module.json contributes.
@@ -38,9 +44,16 @@ const express = require('express');
 const api = require('../../../src/module-api');
 const flags = require('../flags');
 const registry = require('../registry');
+const proposals = require('../proposals');
 
 const { validateOrRespond } = api;
 
+// The doorway's namespaced logger, not console.error (task 1003114). Same seam
+// builder-settings / dev-box / ideas / government already use: a module's log
+// lines come out structured and attributable, and an error object logged as
+// `{ err }` keeps its stack instead of being stringified into one line.
+const log = api.logger('copy-desk');
+
 // The write schemas (ADR 0118): strict by default, so an unknown or typo'd field
 // is REJECTED rather than silently dropped. Built once at module scope — the
 // [...flags.KINDS] spreads mean a renamed export crashes at boot with a named
@@ -61,6 +74,19 @@ const CLOSE_BODY_SCHEMA = Object.freeze({
   resolution_note:  { required: true, type: 'string', maxLength: flags.MAX_NOTE_CHARS, minLength: 1 },
   resolved_task_id: { type: 'integer', min: 1 },
 });
+// The proposal body (task 1003114 / R03). `file` and `line` are OPTIONAL and only
+// disambiguate a string that appears at several sites — see the route. Notice
+// what is absent and must stay absent: nothing here names a destination. The
+// target is resolved from the registry by `string_id`, so a caller can propose a
+// change to a string the product actually shows and to nothing else.
+const PROPOSAL_BODY_SCHEMA = Object.freeze({
+  string_id:     { required: true, type: 'string', maxLength: 64, minLength: 1 },
+  proposed_text: { required: true, type: 'string', maxLength: proposals.MAX_TEXT_CHARS, minLength: 1 },
+  why:           { required: true, type: 'string', maxLength: proposals.MAX_WHY_CHARS, minLength: 1 },
+  file:          { type: 'string', maxLength: 400 },
+  line:          { type: 'integer', min: 1 },
+  flag_id:       { type: 'integer', min: 1 },
+});
 
 // Load the registry or answer the named "no registry" state. Returns null when
 // it has already responded, so every handler is `if (!reg) return;`.
@@ -127,7 +153,7 @@ module.exports = function buildCopyDeskRouter() {
       res.set('Cache-Control', 'no-store');
       res.json(queue);
     } catch (err) {
-      console.error('[gds] GET /copy-desk/queue', err);
+      log.error({ err }, 'GET /copy-desk/queue failed');
       if (!res.headersSent) res.fail('copy_queue_failed', 500);
     }
   });
@@ -163,7 +189,7 @@ module.exports = function buildCopyDeskRouter() {
       res.set('Cache-Control', 'no-store');
       res.json(result);
     } catch (err) {
-      console.error('[gds] GET /copy-desk/strings', err);
+      log.error({ err }, 'GET /copy-desk/strings failed');
       if (!res.headersSent) res.fail('copy_search_failed', 500);
     }
   });
@@ -200,7 +226,7 @@ module.exports = function buildCopyDeskRouter() {
       }
       res.status(201).json({ ok: true, flag });
     } catch (err) {
-      console.error('[gds] POST /copy-desk/flags', err);
+      log.error({ err }, 'POST /copy-desk/flags failed');
       if (!res.headersSent) res.fail('copy_flag_failed', 500);
     }
   });
@@ -263,10 +289,148 @@ module.exports = function buildCopyDeskRouter() {
 
       res.json({ ok: true, flag });
     } catch (err) {
-      console.error('[gds] POST /copy-desk/flags/:id/close', err);
+      log.error({ err }, 'POST /copy-desk/flags/:id/close failed');
       if (!res.headersSent) res.fail('copy_flag_close_failed', 500);
     }
   });
 
+  // -------------------------------------------------------------------------
+  // POST /copy-desk/proposals — an artist proposes new wording, and it becomes a
+  // TASK (task 1003114 / R03 of goal 1000074).
+  //
+  // Body: { string_id, proposed_text, why, file?, line?, flag_id? }
+  // rank: any signed-in builder — the same floor as filing, for the same reason
+  //       (an artist is a craft, not a rank; see the header).
+  //
+  // THIS IS THE ROUTE THE NON-GOAL IS ABOUT, so read what it does NOT do. It
+  // writes no file. It stores no wording in any table of this module — ADR 0178
+  // §3 pins that copy_desk_flags can never hold replacement text, and this
+  // route's whole design is what makes that pin survivable rather than merely
+  // strict. What it produces is a TASK carrying a patch, in the ledger every
+  // change already has to pass through, which nothing renders from. The wording
+  // reaches a person only after somebody claims that task, runs
+  // `node scripts/gds/copy-apply.js --task <id>`, and ships the resulting diff
+  // through the normal pipeline with the grader reading it.
+  //
+  // The shape is borrowed, not invented: it is `adapter.export()` from the
+  // design half (ADR 0081) applied to text. See modules/copy-desk/proposals.js.
+  // -------------------------------------------------------------------------
+  router.post('/copy-desk/proposals', api.requireBuilder, async (req, res) => {
+    try {
+      if (validateOrRespond(req, res, PROPOSAL_BODY_SCHEMA)) return;
+
+      const loaded = registryOrFail(res);
+      if (!loaded) return;
+
+      // Resolve the TARGET from the registry. Everything the patch says about
+      // what is being changed comes from here and never from the body — R02's
+      // snapshot rule (ADR 0178 §6), which matters more for a proposal than for
+      // a flag: a caller-supplied "current text" would let someone describe an
+      // edit to a sentence that does not exist, and the applier would then be
+      // editing a real file on the strength of a claim nobody checked.
+      const occurrences = registry.occurrencesOf(loaded.index, req.body.string_id);
+      if (!occurrences.length) {
+        return res.fail('unknown_string', 400, {
+          string_id: req.body.string_id,
+          what_this_means: 'The registry does not contain that string. It may have been reworded since this page loaded — reload the copy desk and look again.',
+        });
+      }
+
+      // One proposal changes ONE occurrence. When a string is shown in several
+      // places the caller must say which, because picking for them is exactly
+      // the silent wrong this goal exists to stop — and "the same sentence in
+      // seven places" is already its own signal on this page, with its own
+      // answer (change them all, deliberately, under a claim).
+      let entry = occurrences[0];
+      if (occurrences.length > 1) {
+        const file = req.body.file ? String(req.body.file) : null;
+        const line = Number.isInteger(req.body.line) ? req.body.line : null;
+        const picked = occurrences.filter((e) => e.file === file && e.line === line);
+        if (picked.length !== 1) {
+          return res.fail('ambiguous_string', 400, {
+            string_id: req.body.string_id,
+            occurrences: occurrences.map((e) => ({ file: e.file, line: e.line })),
+            what_this_means: 'This exact sentence is shown in more than one place, so a proposal has to name which one it means. That duplication is itself worth a look — the copy desk lists it under “Said more than once”.',
+          });
+        }
+        [entry] = picked;
+      }
+
+      const norm = proposals.normalizeProposalPayload({
+        body: req.body,
+        entry,
+        builderId: req.builder.id,
+      });
+      if (!norm.ok) return res.fail(norm.code, 400, norm.detail);
+      const { patch } = norm;
+
+      // An optional link back to the flag that prompted this. Validated so a
+      // typo'd id is a named 400 rather than a task quietly claiming a lineage
+      // it does not have. The flag is NOT auto-closed: closing is a person's
+      // verdict on someone else's judgement (ADR 0178 §4/§6), and a proposal is
+      // an argument for a change, not proof the change happened.
+      let flagRef = null;
+      if (Number.isInteger(req.body.flag_id)) {
+        const flag = await flags.getFlag(req.body.flag_id);
+        if (!flag) return res.fail('flag_not_found', 404, { flag_id: req.body.flag_id });
+        flagRef = flag.id;
+      }
+
+      const lifecycle = api.resolveOptional && api.resolveOptional('lifecycle');
+      if (!lifecycle || !lifecycle.createTask) {
+        // An instance without the lifecycle module has no tasks to land into, so
+        // there is no honest way to accept a proposal. Refuse loudly rather than
+        // take the wording and drop it — a proposal that vanishes is worse than
+        // one that was never accepted.
+        return res.fail('lifecycle_unavailable', 503, {
+          what_this_means: 'This instance cannot hold tasks, and a copy proposal is a task. Nothing was recorded.',
+        });
+      }
+
+      // The version the work lands in: the one currently being built, matching
+      // how every other unattributed create-vector picks. `createTask` then
+      // defaults the goal to that version's catch-all, so a copy change is
+      // ordinary work on the board rather than a special case.
+      const versions = await lifecycle.listVersions();
+      const building = (versions || []).find((v) => v.status === 'building') || (versions || [])[0];
+      if (!building) return res.fail('no_open_version', 503);
+
+      const sourceRef = proposals.proposalSourceRef(patch);
+      const existing = lifecycle.findTaskBySourceRef
+        ? await lifecycle.findTaskBySourceRef({ source: 'copy-proposal', sourceRef })
+        : null;
+      if (existing) {
+        // A double-submit resolves to the task it already made. 200, not 201:
+        // nothing was created this time, and the caller gets the same task back.
+        return res.json({ ok: true, task: existing, created: false });
+      }
+
+      const body = proposals.proposalTaskBody(patch);
+      const task = await lifecycle.createTask({
+        versionId: building.id,
+        title: proposals.proposalTaskTitle(patch),
+        description: flagRef
+          ? `${body}\n\nRaised from copy-desk flag ${flagRef}.`
+          : body,
+        // BACKLOG, deliberately. A proposal is a request, and the board's triage
+        // step is where a person decides it is worth doing — the same gate a
+        // captured idea passes. Landing it `ready` would let anyone with an
+        // opinion mint claimable work.
+        status: 'backlog',
+        kind: 'feature',
+        priority: 4,
+        touches: [patch.file],
+        source: 'copy-proposal',
+        sourceRef,
+        createdBy: req.builder.id,
+      });
+
+      res.status(201).json({ ok: true, task, created: true, patch });
+    } catch (err) {
+      log.error({ err }, 'POST /copy-desk/proposals failed');
+      if (!res.headersSent) res.fail('copy_proposal_failed', 500);
+    }
+  });
+
   return router;
 };