@stage5/lumine 0.3.73 → 0.3.75

package/README.md

@@ -305,10 +305,11 @@ viewer sees (by default the MCP client's own name).
 ## Inspecting Build SDK data
 
 `lumine sdk call <namespace.method> '<jsonArgs>'` calls a build's data SDK
-endpoint with your login and prints the response, so you can inspect real data
+endpoint and prints the response, so you can inspect real data
 and measure latency while building. Run `lumine sdk list` to see callable
-methods. The JSON args are sent as the request body (shapes follow
-`TWINKLE_BUILD_SDK.md`).
+methods. Most methods use your login and send JSON args as the request body
+(shapes follow `TWINKLE_BUILD_SDK.md`). Newspaper reads use the same public
+GET routes as the app and send no login or Build API token.
 
 ```bash
 lumine sdk call aiStories.chapters '{"limit": 5}'
@@ -317,6 +318,9 @@ lumine sdk call live.list '{}'
 lumine sdk call live.get '{"sessionId": "..."}'
 lumine sdk call live.listReplays '{"limit": 20}'
 lumine sdk call live.getReplay '{"replayId": "..."}'
+lumine sdk call news.getCurrentEdition '{}' --build 1929
+lumine sdk call news.listEditions '{"limit": 12}' --build 1929
+lumine sdk call news.getEdition '{"dayIndex": 1762, "revisionNumber": 1}' --build 1929
 ```
 
 It targets the build in the current workspace, or pass `--build <id>`. Add
@@ -324,6 +328,10 @@ It targets the build in the current workspace, or pass `--build <id>`. Add
 which can differ from a method's `Twinkle.*` SDK return shape — check
 `TWINKLE_BUILD_SDK.md` for SDK return shapes. Methods that change data require
 `--allow-write`.
+For newspaper reads, omit `revisionNumber` to read the day's canonical revision;
+pass the archive's `cursor` to `news.listEditions` for the next page. These reads
+never queue generation or refresh an edition; publication uses the separate
+authorized newspaper workflow.
 Stopping a hosted stream is available as
 `lumine sdk call live.stop '{"sessionId":"..."}' --allow-write`; the command
 prints canonical server state and refuses to mint `live:write` without the

package/lib/admin-arena.js

@@ -186,12 +186,14 @@ export function formatArenaResult({ operation, data }) {
       ...types.map(
         (t) =>
           `${t.examFamily} ${t.difficulty || "normal"} ${t.itemType}: ${t.live} live, ${t.activeLearners ?? "unknown"} active learner(s), ${t.minFresh} unseen${
-            t.stockLow && !t.refillDue ? " (low stock; no active demand)" : ""
+            t.refillUse === "complete-paper-only" ? " (complete paper required; check paper-queue)"
+              : t.refillUse === "unknown-type" ? " (unknown current type; review before authoring)"
+                : t.stockLow && !t.refillDue && t.activeLearners === 0 ? " (low stock; no active demand)" : ""
           }${
             t.refillDue ? ` -> write ${t.toWrite}` : ""
           }`,
       ),
-      due.length ? `${due.length} type(s) due for a refill.` : "No refill due.",
+      due.length ? `${due.length} type(s) due for a refill.` : "No standalone practice refill due; check paper-queue for waiting exams.",
     ];
   }
   if (operation.name === "arena.import.preview") {

package/lib/math-lab-build-sheet.js

@@ -14,11 +14,37 @@ import {
   verifyRewardEconomy,
 } from "./math-lab-preservation.js";
 
+export function serializeMathLabSets(sets) {
+  return sets.map((set) => ({
+    key: set.key,
+    // This also makes a set eligible as a rematch of the named puzzle.
+    // It remains an ordinary collection puzzle for other learners.
+    // Preserve it for existing and appended sets; let canonical validation
+    // reject invalid references instead of silently changing their meaning.
+    ...(set.variantOf !== undefined ? { variantOf: set.variantOf } : {}),
+    questions: set.questions.map((q) => ({
+      prompt: q.prompt,
+      answer: q.answer,
+      ...(q.hint ? { hint: q.hint } : {}),
+      ...(q.guide ? { guide: q.guide } : {}),
+    })),
+  }));
+}
+
 export async function buildMathLabSheet({
   contentDir,
+  apiRoot,
+  appDir,
+  outputFile,
   args = process.argv.slice(2),
 }) {
   const here = path.resolve(contentDir);
+  // Private review directories need not imitate the historical sibling layout.
+  // Defaults preserve existing wrappers; explicit paths retain the same guards.
+  const policyRoot = path.resolve(
+    apiRoot || path.join(here, "..", "..", "twinkle-api"),
+  );
+  const declaredApp = path.resolve(appDir || path.join(here, "..", "math-lab"));
   const parts = path.join(here, "parts");
   if (
     args.length !== 2 ||
@@ -59,18 +85,12 @@ export async function buildMathLabSheet({
     }
     const data = JSON.parse(fs.readFileSync(file, "utf8"));
     sheet.rules[`${level}-daily`] = {
-      sets: data.sets.map((set) => ({
-        key: set.key,
-        questions: set.questions.map((q) => ({
-          prompt: q.prompt,
-          answer: q.answer,
-          ...(q.hint ? { hint: q.hint } : {}),
-          ...(q.guide ? { guide: q.guide } : {}),
-        })),
-      })),
+      sets: serializeMathLabSets(data.sets),
     };
   }
-  const out = path.resolve(here, "..", "math-lab-sheet.json");
+  const out = path.resolve(
+    outputFile || path.join(here, "..", "math-lab-sheet.json"),
+  );
   if (missing.length)
     throw new Error(
       `Missing grade parts: ${missing.join(", ")}. No sheet was written.`,
@@ -80,22 +100,11 @@ export async function buildMathLabSheet({
   // Server-identical validation: rewards.json + sheet → approved-shape config.
   const policy = await import(
     pathToFileURL(
-      path.resolve(
-        here,
-        "..",
-        "..",
-        "twinkle-api",
-        "helpers",
-        "build",
-        "rewardsPolicy.ts",
-      ),
+      path.join(policyRoot, "helpers", "build", "rewardsPolicy.ts"),
     ).href
   );
   const declared = JSON.parse(
-    fs.readFileSync(
-      path.resolve(here, "..", "math-lab", "rewards.json"),
-      "utf8",
-    ),
+    fs.readFileSync(path.join(declaredApp, "rewards.json"), "utf8"),
   );
   const composed = policy.composeRewardConfig({ declared, sheet });
   if (composed.errors.length) {

package/lib/sdk.js

@@ -13,6 +13,11 @@ import { findLocalProjectMetadata } from "./workspace.js";
 // TWINKLE_BUILD_SDK.md. Methods that mutate data require --allow-write.
 // Anything not listed can be called with --path api/<endpoint>.
 export const SDK_CLI_METHODS = {
+  // Newspaper reads use the public GET routes, not POST /api/* or Build
+  // tokens. Generation remains a separate, explicitly authorized workflow.
+  "news.getCurrentEdition": { special: "newsRead", operation: "current", publicRead: true },
+  "news.listEditions": { special: "newsRead", operation: "list", publicRead: true },
+  "news.getEdition": { special: "newsRead", operation: "edition", publicRead: true },
   "soundtracks.searchSources": { path: "api/soundtracks/sources", scopes: ["sharedDb:read"] },
   "soundtracks.getTags": { path: "api/soundtracks/tags", scopes: ["sharedDb:read"] },
   "soundtracks.getRecommendations": { path: "api/soundtracks/recommendations", scopes: ["sharedDb:read"] },
@@ -458,7 +463,7 @@ export async function sdkCommand(options) {
 
 export function printSdkMethodList() {
   console.log(
-    "Callable Build endpoints (args JSON = request body). Prints the raw\n" +
+    "Callable Build endpoints (args JSON selects the documented request fields). Prints the raw\n" +
       "endpoint response, which can differ from the SDK return shape (*).\n",
   );
   const byNamespace = new Map();
@@ -485,8 +490,10 @@ Usage:
   lumine sdk call leaderboards.get '{"boardKey": "default", "limit": 10}'
   lumine sdk call aiStories.list '{"difficulty": 1}' --repeat 5 --build 1374
   lumine sdk call userDb.query '{"sql": "SELECT * FROM sqlite_master"}'
+  lumine sdk call news.getEdition '{"dayIndex": 1762, "revisionNumber": 1}' --build 1929
 
-Request-body (args) shapes follow TWINKLE_BUILD_SDK.md. Output is the raw
+Argument shapes follow TWINKLE_BUILD_SDK.md; public newspaper reads use GET
+without a login or Build token. Output is the raw
 endpoint response; (*) methods are reshaped by their Twinkle.* SDK wrapper, so
 check TWINKLE_BUILD_SDK.md for the real SDK return shape. Add --repeat <n> for
 latency stats, --build <id> to target a build outside the current workspace.
@@ -570,6 +577,9 @@ export async function sdkCall(options) {
   const requestedScopes = options.sdkScopes.length
     ? options.sdkScopes
     : endpoint.scopes || [];
+  if (endpoint.publicRead && options.sdkScopes.length) {
+    throw new Error(`${methodName} is a public read and does not use --scopes.`);
+  }
   // A curated readOnly method (rewards.getStatus) needs a scope whose name is
   // write-capable but only ever sends its read operation; its own default
   // scopes do not trip the gate. Explicit --scopes overrides always do.
@@ -597,12 +607,23 @@ export async function sdkCall(options) {
   // before any auth side effects, so invalid local input fails immediately
   // instead of after starting the device-login flow.
   const buildId = await resolveSdkBuildId(options);
-  const auth = await ensureAuth(options);
-  await assertAuthScope({ options, auth, scope: "build:sdk" });
+  // Validate selectors before login/network calls. Public reads deliberately
+  // carry no saved login, even when one is available in this CLI session.
+  const newsUrl = endpoint.special === "newsRead"
+    ? buildNewsReadUrl({ apiUrl: options.apiUrl, buildId, operation: endpoint.operation, args })
+    : null;
+  const auth = endpoint.publicRead ? null : await ensureAuth(options);
+  if (auth) await assertAuthScope({ options, auth, scope: "build:sdk" });
   const attempts = [];
   let lastResult = null;
 
-  if (endpoint.special === "leaderboardGet" || endpoint.special === "leaderboardSubmit") {
+  if (endpoint.special === "newsRead") {
+    for (let attempt = 0; attempt < options.repeat; attempt += 1) {
+      lastResult = await executeSdkHttpCall({ options, method: "GET", url: newsUrl });
+      attempts.push(lastResult);
+      printSdkAttemptLine(attempts.length, lastResult);
+    }
+  } else if (endpoint.special === "leaderboardGet" || endpoint.special === "leaderboardSubmit") {
     const boardKey = String(args.boardKey || "default");
     const rest = { ...args };
     delete rest.boardKey;
@@ -742,6 +763,39 @@ export async function sdkCall(options) {
   }
 }
 
+function buildNewsReadUrl({ apiUrl, buildId, operation, args }) {
+  const allowed = operation === "edition" ? ["dayIndex", "revisionNumber"]
+    : operation === "list" ? ["limit", "cursor"] : [];
+  if (Object.keys(args).some((key) => !allowed.includes(key))) {
+    throw new Error(`Unexpected newspaper selector; accepted fields: ${allowed.join(", ") || "none"}.`);
+  }
+  let suffix = "current";
+  if (operation === "edition") {
+    if (!Number.isSafeInteger(args.dayIndex) || args.dayIndex < 0) {
+      throw new Error("dayIndex is required and must be a nonnegative integer.");
+    }
+    if (args.revisionNumber != null && (!Number.isSafeInteger(args.revisionNumber) || args.revisionNumber <= 0)) {
+      throw new Error("revisionNumber must be a positive integer.");
+    }
+    suffix = `editions/${args.dayIndex}`;
+  } else if (operation === "list") {
+    if (args.limit != null && (!Number.isSafeInteger(args.limit) || args.limit < 1)) {
+      throw new Error("limit must be a positive integer (capped at 30).");
+    }
+    if (args.cursor != null && (typeof args.cursor !== "string" || args.cursor.length > 200)) {
+      throw new Error("cursor must be the string returned by news.listEditions.");
+    }
+    suffix = "editions";
+  }
+  const url = new URL(`${apiUrl}/build/${buildId}/news/${suffix}`);
+  for (const [key, value] of operation === "edition"
+    ? [["revision", args.revisionNumber]] : operation === "list"
+      ? [["limit", args.limit == null ? null : Math.min(30, args.limit)], ["cursor", args.cursor]] : []) {
+    if (value != null) url.searchParams.set(key, String(value));
+  }
+  return url.toString();
+}
+
 export function printSdkAttemptLine(attemptNumber, result) {
   console.error(
     `#${attemptNumber} ${result.status}${result.ok ? " OK" : ""} · ` +

package/lib/workspace.js

@@ -8,9 +8,11 @@ import {
   EXCLUDED_UPLOAD_FILES,
   LUMINE_AGENT_INSTRUCTIONS,
   LUMINE_AGENT_INSTRUCTIONS_MARKER,
+  LUMINE_MAIN_CHECKOUT_INSTRUCTIONS_MARKER,
   LUMINE_REFERENCE_INSTRUCTIONS,
   LUMINE_REFERENCE_INSTRUCTIONS_MARKER,
   LUMINE_SDK_REFERENCE_MARKER,
+  LUMINE_VERSION_CHECKOUT_INSTRUCTIONS_MARKER,
   PROJECT_EFFECTIVE_LINE_MAX_COLUMNS,
   PROJECT_MAX_EFFECTIVE_FILE_LINES,
   PROJECT_MAX_FILES,
@@ -39,14 +41,23 @@ export async function writeReferenceInstructions({ dir }) {
   });
 }
 
-// Write AGENTS.md/CLAUDE.md, but never clobber a file the user customized:
-// only (re)write when the file is absent or still carries our marker.
+// All checkout modes generate these same two files. A previous mode's header
+// still identifies a CLI-managed guide and must change with the checkout.
+// Custom guides omit the generated header; quoting a marker later is not ownership.
 export async function writeInstructionFiles({ dir, marker, content }) {
+  const managedHeaders = new Set([
+    marker,
+    LUMINE_AGENT_INSTRUCTIONS_MARKER,
+    LUMINE_REFERENCE_INSTRUCTIONS_MARKER,
+    LUMINE_MAIN_CHECKOUT_INSTRUCTIONS_MARKER,
+    LUMINE_VERSION_CHECKOUT_INSTRUCTIONS_MARKER,
+  ]);
   for (const fileName of AGENT_INSTRUCTION_FILES) {
     const filePath = path.join(dir, fileName);
     try {
       const existing = await fs.readFile(filePath, "utf8");
-      if (!existing.includes(marker)) {
+      const header = existing.replace(/^\uFEFF/, "").split(/\r?\n/, 1)[0];
+      if (!managedHeaders.has(header)) {
         continue;
       }
     } catch (error) {

package/package.json

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