@stage5/lumine 0.3.84 → 0.3.85

package/lib/admin-arena.js

@@ -13,6 +13,10 @@ import path from "node:path";
 //                              at once; a dry run (validation only) unless --confirm;
 //                              re-importing a folder retires that paper's earlier items
 //   status --item <id> --to live|retired|checked
+//   paper-assemble --file <manifest.json>   publish a complete paper from existing,
+//                              never-served IDs, including reviewed text passages
+//                              and unscored writing; preview unless --confirm;
+//                              preserves content versions and exposures
 //   revise --file <revisions.json>   in-place text/passage/visual/review fixes to
 //                              live items: same item id, a new content version;
 //                              a dry run unless --confirm; audited
@@ -25,7 +29,7 @@ import path from "node:path";
 //                              <itemId>.png renders of picture-option items
 //                              (panels are drawn by the web, not stored)
 export const ARENA_USAGE =
-  "Usage: lumine admin arena queue | paper-queue [--cursor <id>] [--limit <1-100>] | marking [--cursor <id>] [--limit <1-200>] | import (--dir <paper folder> | --additive --file <reviewed-items.json>) [--audio audio/<exam>/<paper>] [--live] [--confirm] | status --item <id> --to live|retired|checked [--confirm] | revise --file <revisions.json> [--confirm] | today-queue [--cursor <id>] [--limit <1-100>] | today-member --user <id> | today-import --file <reviewed-questions.json> [--confirm] | today-withdraw --user <id> (--keys <key,...> | --file <withdraw.json>) --reason <text> [--confirm] | picture-audit [--items <id,id,...> | --cursor <id>] [--limit <1-20>] [--renders <dir of <itemId>.png>] [--output <review-list.json>] [--json]";
+  "Usage: lumine admin arena queue | paper-queue [--cursor <id>] [--limit <1-100>] | marking [--cursor <id>] [--limit <1-200>] | import (--dir <paper folder> | --additive --file <reviewed-items.json>) [--audio audio/<exam>/<paper>] [--live] [--confirm] | paper-assemble --file <manifest.json> [--confirm] | status --item <id> --to live|retired|checked [--confirm] | revise --file <revisions.json> [--confirm] | today-queue [--cursor <id>] [--limit <1-100>] | today-member --user <id> | today-import --file <reviewed-questions.json> [--confirm] | today-withdraw --user <id> (--keys <key,...> | --file <withdraw.json>) --reason <text> [--confirm] | picture-audit [--items <id,id,...> | --cursor <id>] [--limit <1-20>] [--renders <dir of <itemId>.png>] [--output <review-list.json>] [--json]";
 const MAX_ITEMS = 300;
 
 function validationError(message) {
@@ -154,6 +158,56 @@ function buildTodayWithdraw(options) {
 }
 
 export function buildArenaOperation({ action, options }) {
+  if (action === "paper-assemble") {
+    if (!options.adminFile || options.adminDir || options.adminArenaAdditive || options.adminArenaAudio) {
+      throw validationError("Use paper-assemble --file <manifest.json> [--confirm]; it uses existing item IDs, never a content import.");
+    }
+    const file = path.resolve(options.adminFile);
+    let parsed;
+    try {
+      if (fs.statSync(file).size > 200_000) throw validationError("The assembly manifest must be under 200 KB.");
+      parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    } catch (error) {
+      if (error.code === "CLI_ADMIN_CLI_VALIDATION") throw error;
+      throw validationError(`Cannot read the assembly manifest ${file}: ${error.message}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) ||
+        typeof parsed.exam !== "string" || !["easy", "normal", "hard"].includes(parsed.difficulty) ||
+        typeof parsed.paper !== "string" || !/^[A-Za-z0-9][A-Za-z0-9-]{0,39}$/.test(parsed.paper) ||
+        !Array.isArray(parsed.items) || !parsed.items.length || parsed.items.length > MAX_ITEMS || !parsed.review) {
+      throw validationError("The manifest needs exam, difficulty, paper, reviewed existing items and review evidence.");
+    }
+    for (const item of parsed.items) {
+      if (!item || !Number.isSafeInteger(item.itemId) || item.itemId <= 0 ||
+          !Number.isSafeInteger(item.expectedVersion) || item.expectedVersion < 1 ||
+          !Number.isSafeInteger(item.number) || item.number < 1 ||
+          typeof item.contentHash !== "string" || !/^[a-f0-9]{64}$/.test(item.contentHash) ||
+          (item.passageId !== undefined && (!Number.isSafeInteger(item.passageId) || item.passageId <= 0)) ||
+          Object.keys(item).some(key => !["itemId", "expectedVersion", "number", "contentHash", "passageId"].includes(key))) {
+        throw validationError("Each entry needs itemId, expectedVersion, number and contentHash; replacement content is not accepted.");
+      }
+    }
+    if (new Set(parsed.items.map(i => i.itemId)).size !== parsed.items.length || new Set(parsed.items.map(i => i.number)).size !== parsed.items.length) {
+      throw validationError("Item IDs and blueprint numbers must be unique.");
+    }
+    if (parsed.passages !== undefined && (!Array.isArray(parsed.passages) || parsed.passages.length > MAX_ITEMS ||
+        parsed.passages.some(p => !p || !Number.isSafeInteger(p.passageId) || p.passageId <= 0 ||
+          !Number.isSafeInteger(p.expectedVersion) || p.expectedVersion <= 0 ||
+          typeof p.contentHash !== "string" || !/^[a-f0-9]{64}$/.test(p.contentHash) ||
+          Object.keys(p).some(key => !["passageId", "expectedVersion", "contentHash"].includes(key))) ||
+        new Set(parsed.passages.map(p => p.passageId)).size !== parsed.passages.length)) {
+      throw validationError("Passages need unique existing IDs, expectedVersion and canonical hashes, never replacement text.");
+    }
+    const referenced = [...new Set(parsed.items.flatMap(i => i.passageId === undefined ? [] : [i.passageId]))].sort((a, b) => a - b);
+    const reviewed = (parsed.passages || []).map(p => p.passageId).sort((a, b) => a - b);
+    if (JSON.stringify(referenced) !== JSON.stringify(reviewed)) throw validationError("Review every referenced passage exactly once and omit unreferenced passages.");
+    const confirm = confirmed(options);
+    return { name: confirm ? "arena.paper.assemble" : "arena.paper.assemble.preview", method: "POST",
+      path: "/cli/admin/arena/papers/assemble",
+      body: { exam: parsed.exam, difficulty: parsed.difficulty, paper: parsed.paper, items: parsed.items,
+        ...(parsed.passages !== undefined ? { passages: parsed.passages } : {}), review: parsed.review, dryRun: !confirm },
+      mutates: confirm, requiresRun: false, timeoutMs: 120000 };
+  }
   if (action === "picture-audit") {
     const limit = Number(options.adminLimit ?? 10);
     if (!Number.isInteger(limit) || limit < 1 || limit > PICTURE_AUDIT_MAX) throw validationError(`Use --limit from 1 to ${PICTURE_AUDIT_MAX}.`);
@@ -307,6 +361,11 @@ export function buildArenaOperation({ action, options }) {
 }
 
 export function formatArenaResult({ operation, data }) {
+  if (operation.name === "arena.paper.assemble" || operation.name === "arena.paper.assemble.preview") {
+    if (data?.alreadyAssembled) return [`${data.paper}: already assembled from the same existing items; nothing changed.`];
+    return [`${data?.dryRun ? "Dry run: would assemble" : "Assembled"} ${data?.wouldAssemble ?? data?.assembled ?? 0} existing items as ${data?.paper}. IDs, content versions and exposures are preserved.`,
+      ...(data?.dryRun ? ["Add --confirm to publish this reviewed complete paper."] : [])];
+  }
   if (operation.name === "arena.paper.queue") return [
     `Checked ${data?.scannedMembers ?? 0} members; ${data?.entries?.length ?? 0} exam tracks are waiting for fresh papers on this page.`,
     ...(data?.entries || []).map(row => `${row.username} (${row.userId}): ${row.examKey} ${row.difficulty}/${row.length}${row.reason === "solo_mastery_paper" ? " — solo mastery ready" : ""}`),

package/lib/admin-daily.js

@@ -250,7 +250,7 @@ export async function dailyRunGather(options, { run = runAdmin, now, clock } = {
   step("brief", ["brief"], "brief.json");
   step("todos", ["todo", "list"], "todos.json");
   step("escalations", ["escalation", "list"], "escalations.json");
-  const paperQueue = { complete: false, pages: 0, waitingTracks: 0 };
+  const paperQueue = { complete: false, pages: 0, waitingTracks: 0, demandBases: [] };
   let paperCursor = 0;
   for (;;) {
     paperQueue.pages++;
@@ -260,11 +260,12 @@ export async function dailyRunGather(options, { run = runAdmin, now, clock } = {
     if (!res.ok) break;
     const data = res.json?.data;
     const next = data?.nextCursor;
-    if (data?.demandBasis !== "waiting-published-papers-v1" || !Array.isArray(data?.entries) ||
+    if (!["waiting-published-papers-v1", "cleared-exhausted-papers-v2"].includes(data?.demandBasis) || !Array.isArray(data?.entries) ||
         !(next === null || (Number.isSafeInteger(next) && next > paperCursor))) {
       failLast("Invalid or non-advancing Arena paper-waiting page.");
       break;
     }
+    if (!paperQueue.demandBases.includes(data.demandBasis)) paperQueue.demandBases.push(data.demandBasis);
     paperQueue.waitingTracks += data.entries.length;
     if (next === null) { paperQueue.complete = true; break; }
     if (paperQueue.pages >= 100) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.3.84",
+  "version": "0.3.85",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {