@bongos/core 1.19.1061 → 1.19.1063

package/modules/copy-desk/page-status.js

@@ -511,7 +511,70 @@ function composeNext({ inventory, readings, tasks, asks, builderId, alternatives
   };
 }
 
+// The margin note a line carries in the editor (ADR 0341 D4, TW10): shared
+// shell text changes on every page, and a line the applier cannot place goes
+// to an engineer at submit (pages.goesToEngineer, the submit's own rule).
+const EDITOR_NOTES = Object.freeze({ shared: 'changes this on every page', engineer: 'goes to an engineer' });
+
+function editorNote(line) {
+  if (pages.goesToEngineer(line)) return 'engineer';
+  return line.placement === 'shared' ? 'shared' : null;
+}
+
+// GET /copy-desk/pages/:pageId/draft — what the editor (task 1004321 / BV2.TW10)
+// opens on: every line of the page reading in page order, the open round and
+// whether the caller holds it, and the saved draft. A draft saved on another
+// reading is not applied to these lines (its keys may name other lines); it is
+// reported as `draft_on_older_reading` instead.
+//
+// `readingPage` is the page's entry in docs/page-readings.json (null when the
+// page has not been read); `round` is the page's open round as the lifecycle
+// port lists it, or null.
+function composeEditor({ page, readingPage, round, builderId }) {
+  const lines = ((readingPage && readingPage.lines) || []).map((l) => ({
+    key: l.key, section: l.section, text: l.text, placement: l.placement, note: editorNote(l),
+  }));
+  const readingHash = readingPage ? readingPage.reading_hash || null : null;
+  let draft = null;
+  let olderReading = false;
+  if (round) {
+    const d = pages.parseDraftBlock(round.description);
+    if (d.ok) {
+      if (d.draft.reading_hash === readingHash) {
+        const keys = new Set(lines.map((l) => l.key));
+        draft = {
+          reading_hash: d.draft.reading_hash,
+          saved_at: d.draft.saved_at || null,
+          lines: d.draft.lines.filter((l) => keys.has(l.key)).map((l) => ({ key: l.key, after: l.after })),
+        };
+      } else {
+        olderReading = true;
+      }
+    }
+  }
+  const heldByYou = !!round && round.holder_id != null && String(round.holder_id) === String(builderId);
+  return {
+    ok: true,
+    page_id: page.id,
+    page: { id: page.id, title: page.title || page.id, surface: page.surface, surface_word: surfaceWord(page.surface), path: page.path || null, url: page.url || null },
+    reading: { reading_hash: readingHash, read: !!readingPage, lines },
+    notes: EDITOR_NOTES,
+    round: round ? {
+      task_id: String(round.id),
+      state: roundState(round),
+      status: round.status,
+      held_by_you: heldByYou,
+      holder: round.holder_id != null ? { id: String(round.holder_id), login: round.holder_login || null } : null,
+      claim: { method: 'POST', path: `/copy-desk/pages/${page.id}/claim` },
+    } : null,
+    draft,
+    draft_on_older_reading: olderReading,
+    counter: { changed: draft ? draft.lines.length : 0, total: lines.length },
+  };
+}
+
 module.exports = {
+  composeEditor,
   TALLY_REASON_PREFIX,
   NEXT_ALTERNATIVES,
   NEXT_TIERS,

package/modules/copy-desk/pages.js

@@ -311,6 +311,21 @@ function sameDraft(saved, next) {
   return pick(saved) === pick(next);
 }
 
+// saveDraftInto(description, draft) -> { ok, description, draft } | refusal
+//
+// The one way a resolved draft is written into a round's description, shared by
+// the autosave (PUT .../draft) and the Word upload (POST .../draft.docx, task
+// 1004320), so both save through the same rules: the same draft again keeps the
+// stored block (saved_at included) and so writes nothing; no draft yet and
+// nothing changed stores nothing; otherwise the block is replaced in place.
+function saveDraftInto(description, draft) {
+  const prev = parseDraftBlock(description);
+  if (prev.ok && sameDraft(prev.draft, draft)) return { ok: true, description, draft: prev.draft };
+  if (prev.code === 'no_block' && !draft.lines.length) return { ok: true, description, draft };
+  const r = replaceBlock(description, FENCES.draft, composeDraftBlock(draft));
+  return r.ok ? { ok: true, description: r.description, draft } : r;
+}
+
 // Find a draft line on the CURRENT reading: the same key showing the same text,
 // else the one line showing that text in the same section, else the one line
 // showing it anywhere on the page. Anything else is gone, or too ambiguous to
@@ -431,7 +446,9 @@ module.exports = {
   replaceBlock,
   resolveDraft,
   sameDraft,
+  saveDraftInto,
   freezeBatch,
+  goesToEngineer,
   unplacedSourceRef,
   unplacedTaskTitle,
   unplacedTaskBody,

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

@@ -14,6 +14,10 @@
 // task 1004317): POST /copy-desk/pages/:pageId/claim opens or takes a page's
 // tweak round as a TASK with a web claim, and POST /copy-desk/pages/:pageId/asks
 // files a page ask, a flag row whose target is a page id. Neither stores copy.
+// TW08 (task 1004319) added the draft autosave and the submit, and TW09 (task
+// 1004320) the Word round trip, GET and POST /copy-desk/pages/:pageId/draft.docx:
+// the upload lands in the round's DRAFT, through the autosave's own port call.
+// TW10 (task 1004321) added the editor's read, GET /copy-desk/pages/:pageId/draft.
 //
 // THE RANK SHAPE, AND WHY IT IS ASYMMETRIC:
 //
@@ -53,6 +57,7 @@ const proposals = require('../proposals');
 const pageData = require('../page-data');
 const pageStatus = require('../page-status');
 const pages = require('../pages');
+const docx = require('../docx');
 
 const { validateOrRespond } = api;
 
@@ -125,6 +130,10 @@ const PAGE_REFUSAL_STATUS = Object.freeze({
   block_schema_unknown: 409,
   block_field_missing: 409,
   wrong_page: 409,
+  // The Word upload (task 1004320, ADR 0341 D12).
+  structure_changed: 409,
+  not_a_docx: 415,
+  upload_too_large: 413,
 });
 const PAGE_REFUSAL_MEANS = Object.freeze({
   reading_moved: 'The page changed since the editor loaded it, so a line key may now mean a different line. Reload the page to get the current reading; nothing was saved.',
@@ -133,7 +142,27 @@ const PAGE_REFUSAL_MEANS = Object.freeze({
   line_too_long: `A line holds at most ${pages.MAX_LINE_CHARS} characters.`,
   lines_refused: 'Some lines cannot be frozen as written: the page no longer shows them (target_gone), shows the same words in more than one place (ambiguous_target), or the rewrite dropped or added a {…} hole (placeholder_mismatch). Fix or remove each named line and submit again; nothing was submitted.',
   nothing_to_submit: 'The draft has no rewritten lines yet.',
+  structure_changed: 'The file\'s lines no longer match the page: a paragraph was added, removed or moved, or a heading changed. Each one is listed. Put them back (one paragraph per line, in the page\'s order) or download the page again, and upload once more; nothing was saved.',
+  not_a_docx: 'Upload the .docx file this page downloaded, as the request body. Nothing was saved.',
+  upload_too_large: `A page file is at most ${Math.round(docx.MAX_UPLOAD_BYTES / (1024 * 1024))} MB. Nothing was saved.`,
 });
+// The upload's answers when the file is readable but is not this page's, or not
+// this reading's (task 1004320, ADR 0341 D12).
+const UPLOAD_WRONG_PAGE_MEANS = 'This file is not the download of this page, or the program that saved it dropped the page details Word keeps. Download this page again and make your changes in that file. Nothing was saved.';
+const UPLOAD_READING_MOVED_MEANS = 'The page has changed since this file was downloaded, so its lines may no longer line up with the page. Download the page again and copy your changes across. Nothing was saved.';
+
+// The upload's body is the .docx itself, never JSON (the global parser only
+// reads application/json, so it passes this through). Capped at the parser, and
+// never inflated from a Content-Encoding, so the cap is the bytes on the wire.
+const DOCX_BODY_TYPES = [docx.DOCX_MIME, 'application/zip', 'application/x-zip-compressed', 'application/octet-stream'];
+const rawDocxBody = express.raw({ type: DOCX_BODY_TYPES, limit: docx.MAX_UPLOAD_BYTES, inflate: false });
+function docxBody(req, res, next) {
+  rawDocxBody(req, res, (err) => {
+    if (!err) return next();
+    if (err.type === 'entity.too.large') return refusePage(res, { code: 'upload_too_large', detail: { max_bytes: docx.MAX_UPLOAD_BYTES } });
+    return refusePage(res, { code: 'not_a_docx', detail: { reason: 'the upload could not be read' } });
+  });
+}
 
 function refusePage(res, r) {
   const status = PAGE_REFUSAL_STATUS[r.code] || 400;
@@ -944,6 +973,35 @@ module.exports = function buildCopyDeskRouter() {
     }
   });
 
+  // -------------------------------------------------------------------------
+  // GET /copy-desk/pages/:pageId/draft — what the tweak editor opens on (task
+  // 1004321 / BV2.TW10, ADR 0341 D4): every line of the page reading in page
+  // order with its margin note, the open round and whether the caller holds
+  // it, and the saved draft (only on the current reading). The read the PUT
+  // below saves over, and the .docx download's own data as JSON.
+  //
+  // rank: any signed-in builder, as the download: the words are the page's
+  //       own and the draft sits on a task every builder can read.
+  // -------------------------------------------------------------------------
+  router.get('/copy-desk/pages/:pageId/draft', api.requireBuilder, async (req, res) => {
+    try {
+      const found = pageOrFail(req, res);
+      if (!found) return;
+      const { page, pageId } = found;
+      const lifecycle = pageReadsOrFail(res);
+      if (!lifecycle) return;
+      const readingPage = readingPageOrFail(res, pageId);
+      if (!readingPage) return;
+      const round = openRoundOf(await lifecycle.listPageTweakTasks({ pageId }), pageId);
+      const out = pageStatus.composeEditor({ page, readingPage, round, builderId: req.builder.id });
+      res.set('Cache-Control', 'no-store');
+      res.json(out);
+    } catch (err) {
+      log.error({ err }, 'GET /copy-desk/pages/:pageId/draft failed');
+      if (!res.headersSent) res.fail('copy_page_editor_failed', 500);
+    }
+  });
+
   // -------------------------------------------------------------------------
   // PUT /copy-desk/pages/:pageId/draft — autosave the artist's draft (task
   // 1004319 / BV2.TW08, ADR 0341 D4).
@@ -999,16 +1057,12 @@ module.exports = function buildCopyDeskRouter() {
         taskId: round.id,
         builderId: req.builder.id,
         source: pages.SOURCE,
+        // The same draft again keeps the stored block (saved_at included) and
+        // writes nothing; see pages.saveDraftInto, which the upload shares.
         compose: (task) => {
-          const prev = pages.parseDraftBlock(task.description);
-          // The same draft again: keep the stored block, saved_at included.
-          if (prev.ok && pages.sameDraft(prev.draft, resolved.draft)) {
-            draft = prev.draft;
-            return { ok: true, description: task.description };
-          }
-          // No draft yet and nothing changed: there is nothing to store.
-          if (prev.code === 'no_block' && !resolved.draft.lines.length) return { ok: true, description: task.description };
-          return pages.replaceBlock(task.description, pages.FENCES.draft, pages.composeDraftBlock(resolved.draft));
+          const s = pages.saveDraftInto(task.description, resolved.draft);
+          if (s.ok) draft = s.draft;
+          return s;
         },
       });
       switch (r.outcome) {
@@ -1036,6 +1090,141 @@ module.exports = function buildCopyDeskRouter() {
     }
   });
 
+  // -------------------------------------------------------------------------
+  // GET /copy-desk/pages/:pageId/draft.docx — download the page's words as a
+  // Word document, to work on offline (task 1004320 / BV2.TW09, ADR 0341 D12).
+  //
+  // The file is built from the page reading plus the open round's draft (a line
+  // the artist has rewritten shows its rewrite). A draft saved on an older
+  // reading is not shown, since its keys may now name other lines.
+  // rank: any signed-in builder. The words are the page's own, and the draft is
+  //       on a task description every builder can already read; only the
+  //       upload is the holder's.
+  // -------------------------------------------------------------------------
+  router.get('/copy-desk/pages/:pageId/draft.docx', api.requireBuilder, async (req, res) => {
+    try {
+      const found = pageOrFail(req, res);
+      if (!found) return;
+      const { page, pageId } = found;
+      const lifecycle = pageReadsOrFail(res);
+      if (!lifecycle) return;
+      const readingPage = readingPageOrFail(res, pageId);
+      if (!readingPage) return;
+      const round = openRoundOf(await lifecycle.listPageTweakTasks({ pageId }), pageId);
+      const d = round ? pages.parseDraftBlock(round.description) : null;
+      const file = docx.composeDownload({ readingPage, title: page.title, draft: d && d.ok ? d.draft : null });
+      res.set('Content-Type', docx.DOCX_MIME);
+      res.set('Content-Disposition', `attachment; filename="${docx.downloadName(pageId)}"`);
+      res.set('Cache-Control', 'no-store');
+      res.send(file);
+    } catch (err) {
+      log.error({ err }, 'GET /copy-desk/pages/:pageId/draft.docx failed');
+      if (!res.headersSent) res.fail('copy_page_docx_failed', 500);
+    }
+  });
+
+  // -------------------------------------------------------------------------
+  // POST /copy-desk/pages/:pageId/draft.docx — upload the Word file back into
+  // the DRAFT (task 1004320 / BV2.TW09, ADR 0341 D12). Never to the site: the
+  // words land in the round's draft block, exactly where the autosave puts
+  // them, through the same port call (holder only) and the same resolver
+  // (every target from the page reading by key, never from the file).
+  //
+  // Body: the .docx bytes (Content-Type: the Word type, application/zip or
+  //       application/octet-stream), at most docx.MAX_UPLOAD_BYTES.
+  // rank: any signed-in builder; only the HOLDER of the page's writing claim.
+  //
+  // A MERGE, not a replace: a line is taken from the file only when the artist
+  // changed it in Word (against the text the download showed), so a line they
+  // rewrote in the studio after downloading keeps that rewrite.
+  //
+  //   200 saved | unchanged   the draft, the counter, and `merge` (which lines
+  //                           came from the file, and how they were matched)
+  //   409 structure_changed   a line added, dropped or reordered, or a heading
+  //                           changed; each is named (section, first words)
+  //   409 wrong_page · reading_moved · page_not_held · no_open_round
+  //   413 upload_too_large · 415 not_a_docx
+  // -------------------------------------------------------------------------
+  router.post('/copy-desk/pages/:pageId/draft.docx', api.requireBuilder, docxBody, async (req, res) => {
+    try {
+      const found = pageOrFail(req, res);
+      if (!found) return;
+      const { pageId } = found;
+      const lifecycle = pageReadsOrFail(res);
+      if (!lifecycle) return;
+      if (typeof lifecycle.updateHeldTaskDescription !== 'function') {
+        return res.fail('lifecycle_unavailable', 503, { what_this_means: 'This instance cannot save a page draft. Nothing was saved.' });
+      }
+      const readingPage = readingPageOrFail(res, pageId);
+      if (!readingPage) return;
+
+      const upload = docx.readUpload(Buffer.isBuffer(req.body) ? req.body : null);
+      if (!upload.ok) return refusePage(res, upload);
+      if (upload.page_id !== pageId) {
+        return res.fail('wrong_page', 409, { page_id: pageId, file_page_id: upload.page_id, what_this_means: UPLOAD_WRONG_PAGE_MEANS });
+      }
+      if (upload.reading_hash !== readingPage.reading_hash) {
+        return res.fail('reading_moved', 409, { reading_hash: readingPage.reading_hash || null, file_reading_hash: upload.reading_hash, what_this_means: UPLOAD_READING_MOVED_MEANS });
+      }
+      const mapped = docx.mapUpload({ readingPage, upload });
+      if (!mapped.ok) return refusePage(res, mapped);
+
+      const round = openRoundOf(await lifecycle.listPageTweakTasks({ pageId }), pageId);
+      if (!round) {
+        return res.fail('no_open_round', 409, {
+          page_id: pageId,
+          what_this_means: 'Nobody is writing this page. Claim it first (POST /copy-desk/pages/:pageId/claim), then upload the file.',
+        });
+      }
+
+      const savedAt = new Date().toISOString();
+      let draft = null;
+      let merge = null;
+      const r = await lifecycle.updateHeldTaskDescription({
+        taskId: round.id,
+        builderId: req.builder.id,
+        source: pages.SOURCE,
+        // Merged on the LOCKED task, so the draft the file merges into is the
+        // one stored now, not one read before the lock.
+        compose: (task) => {
+          const prev = pages.parseDraftBlock(task.description);
+          const m = docx.mergeUpload({ readingPage, texts: mapped.texts, baseline: upload.baseline, draft: prev.ok ? prev.draft : null });
+          const resolved = pages.resolveDraft({ readingPage, body: { reading_hash: readingPage.reading_hash, lines: m.lines }, savedAt });
+          if (!resolved.ok) return resolved;
+          const s = pages.saveDraftInto(task.description, resolved.draft);
+          if (s.ok) { draft = s.draft; merge = m; }
+          return s;
+        },
+      });
+      switch (r.outcome) {
+        case 'saved':
+        case 'unchanged':
+          return res.json({
+            ok: true,
+            outcome: r.outcome,
+            page_id: pageId,
+            round: { task_id: String(round.id), state: 'writing' },
+            draft: { reading_hash: draft.reading_hash, saved_at: draft.saved_at, lines: draft.lines },
+            counter: { changed: draft.lines.length, total: readingPage.lines.length },
+            // What the editor shows after an upload ("uploaded · 3 lines from
+            // your doc", Editor.dc.html): the lines the file changed, the draft
+            // lines it left alone, and whether lines were matched by tag or by
+            // position, with or without the file's record of what it showed.
+            merge: { mode: mapped.mode, baseline: !!upload.baseline, from_file: merge.from_file, kept_from_draft: merge.kept_from_draft },
+          });
+        case 'not_held':
+          return refuseNotHeld(res, pageId, r, round);
+        case 'refused':
+          return refusePage(res, r.refusal);
+        default:
+          throw new Error(`updateHeldTaskDescription: unexpected outcome ${r.outcome}`);
+      }
+    } catch (err) {
+      log.error({ err }, 'POST /copy-desk/pages/:pageId/draft.docx failed');
+      if (!res.headersSent) res.fail('copy_page_docx_upload_failed', 500);
+    }
+  });
+
   // -------------------------------------------------------------------------
   // POST /copy-desk/pages/:pageId/submit — freeze the draft and queue the page
   // for /tweak (task 1004319 / BV2.TW08, ADR 0341 D4, D7).