@stage5/lumine 0.3.48 → 0.3.49

package/lib/admin-build-plans.js

@@ -0,0 +1,118 @@
+// `lumine admin build-plans stuck|recheck`: Lumine Build plans whose current
+// milestone is not finishing (twinkle-api controllers/cli/admin/buildPlans.ts).
+// stuck lists running plans with their current milestone's runs, Energy vs
+// estimate, gradings and loop-guard state (flagged ones only unless --all).
+// recheck re-grades the current milestone of up to 10 builds with today's
+// evaluator, free for the creator; it is a dry run unless --confirm is given.
+
+export const BUILD_PLANS_USAGE =
+  "Usage: lumine admin build-plans stuck [--days <1-90>] [--all] | recheck <buildId> [<buildId> ...] [--confirm] [--json]";
+const RECHECK_MAX = 10;
+
+function validationError(message) {
+  const error = new Error(message);
+  error.code = "CLI_ADMIN_CLI_VALIDATION";
+  return error;
+}
+
+function confirmed(options) {
+  const confirm = options.adminConfirm;
+  // absent is "", a bare --confirm is "true"
+  if (confirm !== "" && confirm !== "true") {
+    throw validationError("Pass --confirm on its own, without a value.");
+  }
+  return confirm === "true";
+}
+
+export function buildBuildPlansOperation({ action, options }) {
+  if (!action || action === "stuck") {
+    const query = new URLSearchParams();
+    if (options.adminDays) {
+      const days = Number(options.adminDays);
+      if (!Number.isSafeInteger(days) || days < 1 || days > 90) {
+        throw validationError("--days must be a whole number from 1 to 90.");
+      }
+      query.set("days", String(days));
+    }
+    if (options.adminAll) query.set("all", "1");
+    const qs = query.toString();
+    return {
+      name: "build-plans.stuck",
+      method: "GET",
+      path: `/cli/admin/build-plans/stuck${qs ? `?${qs}` : ""}`,
+      body: undefined,
+      mutates: false,
+      requiresRun: false,
+    };
+  }
+  if (action === "recheck") {
+    const ids = (options.positional || [])
+      .slice(2)
+      .map((value) => String(value).split(","))
+      .flat()
+      .filter(Boolean)
+      .map((value) => Number(value));
+    if (
+      !ids.length ||
+      ids.length > RECHECK_MAX ||
+      ids.some((id) => !Number.isSafeInteger(id) || id <= 0)
+    ) {
+      throw validationError(`Give 1 to ${RECHECK_MAX} build ids. ${BUILD_PLANS_USAGE}`);
+    }
+    const confirm = confirmed(options);
+    return {
+      name: confirm ? "build-plans.recheck" : "build-plans.recheck.preview",
+      method: "POST",
+      path: "/cli/admin/build-plans/recheck",
+      body: { buildIds: [...new Set(ids)], dryRun: !confirm },
+      mutates: confirm,
+      requiresRun: false,
+      // One grading per build, one at a time, each up to a few minutes.
+      timeoutMs: 15 * 60 * 1000,
+    };
+  }
+  throw validationError(BUILD_PLANS_USAGE);
+}
+
+function formatRow(row) {
+  const ratio = row.energyRatio == null ? "?" : `${row.energyRatio}x`;
+  const milestone =
+    row.milestoneIndex == null ? "-" : `${row.milestoneIndex + 1}/${row.milestones}`;
+  const coverage = row.coverage
+    ? ` files ${row.coverage.shown}/${row.coverage.total}${row.coverage.toolRounds ? ` +${row.coverage.toolFilesRead} read in ${row.coverage.toolRounds} rounds` : ""}${row.coverage.omittedReferenced ? `, ${row.coverage.omittedReferenced} referenced omitted` : ""}`
+    : "";
+  const state = row.stalled
+    ? ` STALLED(${row.stallReason})`
+    : row.wouldStall
+      ? ` would stall (${row.wouldStall})`
+      : "";
+  return `Build ${row.buildId}: milestone ${milestone} (${row.milestonesDone} done), ${row.runs} runs, Energy ${ratio} of estimate, ${row.evaluations ?? "?"} gradings, non-pass streak ${row.consecutiveNonPass ?? "?"}, ${row.passed}/${row.criteria} passing, ${row.unverified} unverified${state};${coverage}${row.flags?.length ? ` [${row.flags.join(", ")}]` : ""}`;
+}
+
+export function formatBuildPlansResult({ operation, data }) {
+  if (operation.name === "build-plans.stuck") {
+    const rows = data?.rows || [];
+    return [
+      `${data?.running ?? 0} running build plan(s); ${data?.inWindow ?? rows.length} updated in the last ${data?.days} days or stalled (${data?.stalled ?? 0} stalled); ${rows.length} shown.`,
+      ...rows.map(formatRow),
+    ];
+  }
+  const lines = [];
+  for (const error of data?.errors || []) {
+    lines.push(`Skipped "${error.value}": ${error.reason === "duplicate" ? "listed twice" : "not a build id"}`);
+  }
+  if (data?.dryRun) {
+    lines.push(`Dry run: would recheck ${data?.buildIds?.length || 0} build(s).`);
+    for (const row of data?.rows || []) lines.push(formatRow(row));
+    lines.push("Nothing was graded. Add --confirm to recheck them (free for the creators).");
+    return lines;
+  }
+  for (const result of data?.results || []) {
+    lines.push(
+      result?.ok
+        ? `${result.replayed ? "(already rechecked by this request) " : ""}Build ${result.buildId}: milestone ${result.milestoneIndex + 1} ${result.verdict}, ${result.passed}/${result.criteria} passing, ${result.unverified} unverified${result.milestoneCompleted ? ", milestone completed" : ""}${result.stalled ? `, stalled (${result.stalled.reason})` : ""}${result.fileCoverage ? `; files ${result.fileCoverage.shownFiles}/${result.fileCoverage.totalFiles} + ${result.fileCoverage.toolFilesRead || 0} read in ${result.fileCoverage.toolRounds || 0} rounds` : ""}${result.usage ? `; cost ${result.usage.energyUnits} Energy units (${result.usage.inputTokens} in / ${result.usage.outputTokens} out tokens), not charged to the creator` : ""}`
+        : `Build ${result?.buildId}: not rechecked (${result?.reason === "run_in_progress" ? "a Lumine run is in progress; try again later" : result?.reason || "unknown"})`,
+    );
+  }
+  return lines;
+}

package/lib/admin.js

@@ -49,6 +49,10 @@ import {
   buildSlidingBlockOperation,
   formatSlidingBlockResult,
 } from "./admin-sliding-block.js";
+import {
+  buildBuildPlansOperation,
+  formatBuildPlansResult,
+} from "./admin-build-plans.js";
 import { formatChatReportResult } from "./admin-chat-reports.js";
 import { formatIdentityDeviceUsage } from "./admin-identity-inspection.js";
 import {
@@ -2646,6 +2650,10 @@ export function parseAdminOperation(options) {
   if (namespace === "sliding-block") {
     return buildSlidingBlockOperation({ action, options });
   }
+  // Stuck Lumine Build plans and their free recheck (admin-build-plans.js).
+  if (namespace === "build-plans") {
+    return buildBuildPlansOperation({ action, options });
+  }
 
   if (namespace === "correction" || namespace === "corrections") {
     if (!action || action === "status") {
@@ -7389,6 +7397,11 @@ function printAdminResult({ operation, result }) {
       console.log(line);
     return;
   }
+  if (operation.name.startsWith("build-plans.")) {
+    for (const line of formatBuildPlansResult({ operation, data }))
+      console.log(line);
+    return;
+  }
   if (operation.name.startsWith("craft.")) {
     const lines = formatCraftResult({ operation, data });
     if (lines) {

package/lib/commands.js

@@ -3261,6 +3261,7 @@ export function printHelp() {
   lumine admin cardcraft-review list [--status pending|approved|all] [--cursor <id>] | show <id> | approve|reject|revoke <id> [--reason <text>]
   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 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>]
   lumine admin meetup list [--status review|active|completed|all] | show <crewId> | info <crewId> <userId> --decision ask|accept|ask-again|withdraw [--note <text>] | set-branch <crewId> <userId> --branch "<name>" [--note <text>] | branches [list [--status pending|official|rejected|all] | show <id> | approve <id> | reject <id> [--note <text>] | merge <id> --into <officialId>] | emails [list|send <id>|discard <id>|review on|off] | friends [status|on|off] | funnel [--days <1-90>] | announce-checkins [--send] [--as zero|ciel]   (Bridge Builder crews and check-ins)
   lumine admin meetup story list | show <crewId> | approve <crewId> [--note <text>] [--no-announce] | send-back <crewId> --note <text> | unpublish <crewId> --note <text>   (Bridge Builder story pages: publishes only what every tagged member's parent allowed)

package/package.json

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