@stage5/lumine 0.3.80 → 0.3.81

package/lib/admin-arena.js

@@ -13,13 +13,16 @@ 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
+//   today-withdraw --user <id> (--keys <k,...> | --file <withdraw.json>) --reason <text>
+//                              withdraw that member's unserved queued Today's
+//                              Challenge questions (preview unless --confirm; audited)
 //   picture-audit [--items <ids> | --cursor <id>] [--limit 1-20] [--renders <dir>]
 //                              advisory JEV image review list of live picture
 //                              items; never retires or edits. --renders holds
 //                              <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] | today-queue [--cursor <id>] [--limit <1-100>] | today-member --user <id> | today-import --file <reviewed-questions.json> [--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] | status --item <id> --to live|retired|checked [--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) {
@@ -95,6 +98,58 @@ function readRenders(dir, itemIds) {
   return renders;
 }
 
+const TODAY_WITHDRAW_USAGE =
+  'Use today-withdraw --user <member id> (--keys <key,key,...> | --file <withdraw.json>) --reason "<why>" [--confirm].';
+const TODAY_WITHDRAW_MAX_KEYS = 100;
+
+// A withdrawal file is an array of keys, or an object with `keys` (or
+// `authorKeys`, or `items` of {key|authorKey}), an optional `userId` that must
+// match --user, and an optional `reason` used when --reason is absent.
+function readWithdrawFile(file, userId) {
+  const resolved = path.resolve(file);
+  let parsed;
+  try {
+    if (fs.statSync(resolved).size > 200_000) throw validationError("The withdrawal file must be under 200 KB.");
+    parsed = JSON.parse(fs.readFileSync(resolved, "utf8"));
+  } catch (error) {
+    if (error.code === "CLI_ADMIN_CLI_VALIDATION") throw error;
+    throw validationError(`Cannot read the withdrawal file ${resolved}: ${error.message}`);
+  }
+  const object = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  if (object?.userId !== undefined && Number(object.userId) !== userId) {
+    throw validationError(`The withdrawal file is for member ${object.userId}, not --user ${userId}.`);
+  }
+  const list = Array.isArray(parsed) ? parsed : object?.keys || object?.authorKeys || object?.items;
+  if (!Array.isArray(list)) throw validationError("The withdrawal file needs a list of question keys (an array, or {keys:[...]}).");
+  const keys = list.map((entry) => (typeof entry === "string" ? entry : entry?.authorKey ?? entry?.key));
+  return { keys, reason: typeof object?.reason === "string" ? object.reason : "" };
+}
+
+function buildTodayWithdraw(options) {
+  const userId = Number(options.adminUser);
+  if (!Number.isSafeInteger(userId) || userId <= 0) throw validationError(TODAY_WITHDRAW_USAGE);
+  const keyList = String(options.adminArenaKeys || "");
+  if (Boolean(keyList) === Boolean(options.adminFile)) throw validationError(`Pass exactly one of --keys or --file. ${TODAY_WITHDRAW_USAGE}`);
+  const fromFile = options.adminFile ? readWithdrawFile(options.adminFile, userId) : null;
+  const keys = fromFile ? fromFile.keys : keyList.split(",").map((key) => key.trim()).filter(Boolean);
+  if (!keys.length || keys.length > TODAY_WITHDRAW_MAX_KEYS ||
+      keys.some((key) => typeof key !== "string" || !/^[a-zA-Z0-9_-]{1,100}$/.test(key))) {
+    throw validationError(`Withdraw 1-${TODAY_WITHDRAW_MAX_KEYS} question keys (letters, digits, _ and -).`);
+  }
+  if (new Set(keys).size !== keys.length) throw validationError("Each question key may appear once.");
+  const reason = String(options.adminReason || fromFile?.reason || "").trim();
+  if (reason.length < 10 || reason.length > 500) throw validationError(`Give a 10-500 character --reason. ${TODAY_WITHDRAW_USAGE}`);
+  const confirm = confirmed(options);
+  return {
+    name: confirm ? "arena.today.withdraw" : "arena.today.withdraw.preview",
+    method: "POST",
+    path: "/cli/admin/arena/today/withdraw",
+    body: { userId, keys, reason, dryRun: !confirm },
+    mutates: confirm,
+    requiresRun: false,
+  };
+}
+
 export function buildArenaOperation({ action, options }) {
   if (action === "picture-audit") {
     const limit = Number(options.adminLimit ?? 10);
@@ -146,6 +201,7 @@ export function buildArenaOperation({ action, options }) {
     const confirm = confirmed(options);
     return { name: confirm ? "arena.today.import" : "arena.today.preview", method: "POST", path: "/cli/admin/arena/today/import", body: { ...payload, dryRun: !confirm }, mutates: confirm, requiresRun: false };
   }
+  if (action === "today-withdraw") return buildTodayWithdraw(options);
   if (action === "marking") {
     const cursor = Number(options.adminCursor || 0);
     const limit = Number(options.adminLimit ?? 100);
@@ -245,6 +301,16 @@ export function formatArenaResult({ operation, data }) {
   if (operation.name === "arena.today.preview" || operation.name === "arena.today.import") return [
     `${data?.dryRun ? "Dry run" : "Saved"}: ${data?.questions?.length || 0} reviewed personal questions.${data?.dryRun ? " Add --confirm to make new questions available." : ""}`,
   ];
+  if (operation.name === "arena.today.withdraw.preview" || operation.name === "arena.today.withdraw") {
+    const withdrawn = data?.withdrawn || [];
+    const skipped = data?.skipped || [];
+    return [
+      `${data?.dryRun ? "Dry run: would withdraw" : "Withdrew"} ${withdrawn.length} queued question(s) for member ${data?.userId}${withdrawn.length ? `: ${withdrawn.map((q) => q.key).join(", ")}` : ""}.`,
+      ...skipped.map((s) => `Skipped ${s.key}: ${s.reason} (${s.detail})`),
+      `Ready at preferences v${data?.revision ?? "-"}: ${data?.readyBefore ?? 0} before, ${data?.readyAfter ?? 0} after${data?.refillDue ? `; refill to ${data?.target}` : ""}.`,
+      ...(data?.dryRun && withdrawn.length ? ["Add --confirm to withdraw them."] : []),
+    ];
+  }
   if (operation.name === "arena.marking") {
     const entries = data?.entries || [];
     return [

package/lib/commands.js

@@ -2726,6 +2726,7 @@ export function parseArgs(args) {
     adminArenaTo: raw.to ? String(raw.to) : "",
     adminArenaRenders: raw.renders ? String(raw.renders) : "",
     adminArenaItems: raw.items ? String(raw.items) : "",
+    adminArenaKeys: raw.keys ? String(raw.keys) : "",
     // lumine admin jev-images (admin-jev-images.js)
     adminJevArea: raw.area ? String(raw.area) : "",
     adminJevKey: raw.key ? String(raw.key) : "",
@@ -3351,6 +3352,7 @@ export function printHelp() {
   lumine admin craft seed --build <id> --file <pairs.json> [--confirm] | stats --build <id> [--limit <1-100>] | revise --build <id> --item <id|name> [--why <text>] [--emoji <emoji>] [--category <field>] [--confirm] | revise --build <id> --pair <pairId|a+b> --why <text> [--confirm] | retire --build <id> --item <id|name> --reason <text> [--confirm] | unfizzle --build <id> [--since <iso>] [--pair <a+b>] [--confirm]   (Twinkle.craft curation: dry run without --confirm)
   lumine admin sliding-block status | add --file <levels.json> [--confirm]   (sliding-block-v1 campaign refills, RushHour: dry run without --confirm; the server solves each board and appends it)
   lumine admin arena queue | paper-queue [--cursor <id>] [--limit <1-100>] | import --dir <paper folder> [--audio audio/<exam>/<paper>] [--live] [--confirm] | status --item <id> --to live|retired|checked --confirm | picture-audit [--items <id,id,...> | --cursor <id>] [--limit 1-20] [--renders <dir of <itemId>.png>] [--output <review-list.json>]   (Arena's mock-exam bank; picture-audit is an advisory JEV image review list that never retires or edits items; import is a validation-only dry run without --confirm; upload audio first with twinkle-api scripts/arena-upload-media.ts)
+  lumine admin arena today-queue [--cursor <id>] | today-member --user <id> | today-import --file <reviewed-questions.json> [--confirm] | today-withdraw --user <id> (--keys <key,...> | --file <withdraw.json>) --reason <text> [--confirm]   (Today's Challenge personal queues; import and withdraw are dry runs without --confirm; withdraw removes only unserved queued questions and is audited)
   lumine admin nonogram status | add --file <pictures.json> | retire <key> | restore <key> [--confirm]   (private reviewed pictures; changes are dry runs without --confirm)
   lumine admin build-plans stuck [--days <1-90>] [--all] | recheck <buildId> [<buildId> ...] [--confirm]   (Lumine Build plans stuck on one milestone: runs, Energy vs estimate, gradings, loop-guard state; recheck re-grades the current milestone with today's evaluator, free for the creator, dry run without --confirm)
   lumine admin storage list [--status pending|approved|rejected|all] [--cursor <id>] | show <user-id-or-username> | approve <request-id> [--size <500MB|1GB|2GB|n MB>] [--reason <text>] | reject <request-id> [--reason <text>] | grant <user-id-or-username> --size <500MB|1GB|2GB|n MB> [--reason <text>]

package/package.json

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

package/sdk/LUMINE_ADMIN.md

@@ -5695,6 +5695,44 @@ Bridge Builder qualifies from QR check-ins: 7 different people, or one meetup a
 Every decision requires Mikey's authorization for that crew and action. Mutations are audited and idempotent; `--output <path>` is an explicit request to retain the canonical JSON. General write receipts omit private crew details.
 
 
+## Arena Today's Challenge personal queues
+
+Each member who chose Today's Challenge preferences is served the oldest
+`ready`, never-shown question written for their current preference revision.
+Questions are prepared editorially (see the repository's
+`agent-guides/lumine-admin.md`, Today's Challenge personal refills, for the
+content rules, including the 11-03 no-answer-revealing-options and real-test
+coverage rules).
+
+```
+lumine admin arena today-queue [--cursor <id>] [--limit <1-100>] --json
+lumine admin arena today-member --user <id> --json
+lumine admin arena today-import --file <reviewed-questions.json> [--confirm] --json
+lumine admin arena today-withdraw --user <id> (--keys <key,key,...> | --file <withdraw.json>) --reason "<why>" [--confirm] --json
+```
+
+`today-import` validates without publishing; `--confirm` publishes. Keys and
+content are immutable and duplicate questions are rejected.
+
+`today-withdraw` removes that member's unserved queued questions that failed
+review, so corrected replacements are not served behind them. Without
+`--confirm` it is a preview. It withdraws only `ready` questions never assigned
+to the member; a question shown today or on an earlier day is skipped as
+`served`, and keys are looked up only in that member's queue (another member's
+key reads as `not_found`). Already-withdrawn keys are skipped, so a repeat is a
+no-op, and a retried request replays its original receipt. Each confirmed run is
+recorded in the administrator audit log (operator, time, member, keys, reason),
+and each withdrawn question keeps that record in its review evidence. The result
+lists `withdrawn` and `skipped` keys (`not_found`, `already_withdrawn`, `served`,
+`not_ready`) with `readyBefore`/`readyAfter` at the current preference revision.
+Withdrawn questions are never served or counted as ready. Their keys stay
+reserved and the identical question cannot be imported again; import the
+corrected version under a new key (it may keep the same passage and prompt).
+A withdrawal file is a JSON array of keys, or `{ "userId": <id>, "keys": [...],
+"reason": "..." }` (`userId` must match `--user`; `--reason` overrides the
+file's reason). Re-read `today-member` afterwards and refill if the member is
+due.
+
 ## Nonogram picture collection
 
 Nonogram's `nonogram-picture-v1` proof uses a private, reviewed picture bank.