@stage5/lumine 0.2.39 → 0.2.41

package/lib/admin.js

@@ -1,7 +1,21 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { assertAuthScope, resolveAuth } from "./auth.js";
 import { requestJson } from "./http.js";
+import {
+  extractNewsClaim,
+  readAdminJsonFile,
+  validateNewsEditorial,
+  writeNewsClaimArtifacts,
+} from "./admin-news.js";
+import {
+  runAutomaticPagination,
+  runBatchSkips,
+} from "./admin-workflows.js";
+import {
+  parseBuildReviewReceipt,
+  runManagedBuildReview,
+} from "./build-review.js";
 
 const MAX_EDITORIAL_FILE_BYTES = 256 * 1024;
 const MAX_COMPOSED_TEXT_FILE_BYTES = 64 * 1024;
@@ -64,6 +78,19 @@ function readEditorialFile(filePath) {
 
 export async function adminCommand(options) {
   const operation = parseAdminOperation(options);
+  if (operation.name === "news.validate") {
+    const validation = validateNewsEditorial({
+      claim: operation.claim,
+      editorial: operation.editorial,
+    });
+    const result = {
+      ok: true,
+      status: "success",
+      changed: false,
+      data: { validation },
+    };
+    return finishAdminOutput({ options, operation, result });
+  }
   const viewFilter = resolveOperatorViewFilter({
     operation,
     unviewed: options.adminUnviewed,
@@ -112,34 +139,76 @@ export async function adminCommand(options) {
     options.idempotencyKey || (operation.mutates ? `cli:${randomUUID()}` : "");
   let result;
   try {
-    result = await requestJson({
-      method: operation.method,
-      url: `${options.apiUrl}${operation.path}`,
-      authToken: auth.token,
-      body: operation.body,
-      headers: {
-        ...(runId ? { "x-lumine-admin-run-id": String(runId) } : {}),
-        ...(requestId ? { "x-lumine-idempotency-key": requestId } : {}),
-      },
-      timeoutMs: options.timeoutMs,
-    });
-    if (operation.name === "builds.candidates") {
-      result = normalizeAdminBuildCandidatesResult({
-        result,
-        siteUrl: options.siteUrl,
+    const fetchOperation = async (requestPath = operation.path) =>
+      requestJson({
+        method: operation.method,
+        url: `${options.apiUrl}${requestPath}`,
+        authToken: auth.token,
+        body: operation.body,
+        headers: {
+          ...(runId ? { "x-lumine-admin-run-id": String(runId) } : {}),
+          ...(requestId ? { "x-lumine-idempotency-key": requestId } : {}),
+        },
+        timeoutMs: options.timeoutMs,
       });
-    }
-    if (recommendationContentTypes) {
-      result = filterRecommendationQueueResult({
-        result,
-        contentTypes: recommendationContentTypes,
+    const transformResult = (rawResult) =>
+      transformAdminResult({
+        operation,
+        result: rawResult,
+        options,
+        recommendationContentTypes,
+        viewFilter,
       });
-    }
-    if (viewFilter) {
-      result = filterListResultByOperatorView({ result, viewFilter });
+    if (operation.name === "build.review") {
+      result = await runManagedBuildReview({
+        options,
+        authToken: auth.token,
+        buildId: operation.buildId,
+      });
+    } else if (operation.name === "post.skip-batch") {
+      result = await runBatchSkips({
+        options,
+        authToken: auth.token,
+        runId,
+        parseTarget: parseRecommendationTarget,
+      });
+    } else if (options.adminAll) {
+      if (options.adminCursor) {
+        throw cliValidationError(
+          "Use --resume with the scan checkpoint instead of combining --all with --cursor.",
+        );
+      }
+      result = await runAutomaticPagination({
+        options,
+        operation,
+        runId,
+        fetchPage: fetchOperation,
+        transformPage: transformResult,
+        recordCoverage: async (coverage) =>
+          requestJson({
+            method: "POST",
+            url: `${options.apiUrl}/cli/admin/daily-runs/coverage`,
+            authToken: auth.token,
+            body: coverage,
+            headers: {
+              "x-lumine-admin-run-id": String(runId),
+              "x-lumine-idempotency-key": `cli:queue-coverage:${runId}:${adminValueFingerprint(coverage).slice(0, 32)}`,
+            },
+            timeoutMs: options.timeoutMs,
+          }),
+      });
+    } else {
+      if (options.adminResume) {
+        throw cliValidationError("--resume requires --all or post skip-batch.");
+      }
+      result = transformResult(await fetchOperation());
     }
   } catch (error) {
-    if (operation.mutates && requestId) {
+    if (
+      operation.mutates &&
+      requestId &&
+      operation.name !== "post.skip-batch"
+    ) {
       const retryInstruction = `Retry with --idempotency-key ${requestId}.`;
       error.data = error.data || {
         ok: false,
@@ -175,6 +244,81 @@ export async function adminCommand(options) {
       expectedContent: operation.body.content,
     });
   }
+  if (operation.name === "news.claim") {
+    const artifacts = writeNewsClaimArtifacts({
+      result,
+      outputPath: options.adminOutput,
+      scaffoldPath: options.adminScaffoldFile,
+    });
+    result = {
+      ...result,
+      data: { ...(result.data || {}), artifacts },
+    };
+  }
+  return finishAdminOutput({ options, operation, result });
+}
+
+function transformAdminResult({
+  operation,
+  result,
+  options,
+  recommendationContentTypes,
+  viewFilter,
+}) {
+  let transformed = result;
+  if (operation.name === "recommendations.list") {
+    assertRecommendationWindowResult({ operation, result: transformed });
+  }
+  if (operation.name === "builds.candidates") {
+    transformed = normalizeAdminBuildCandidatesResult({
+      result: transformed,
+      siteUrl: options.siteUrl,
+    });
+  }
+  if (recommendationContentTypes) {
+    transformed = filterRecommendationQueueResult({
+      result: transformed,
+      contentTypes: recommendationContentTypes,
+    });
+  }
+  if (viewFilter) {
+    transformed = filterListResultByOperatorView({
+      result: transformed,
+      viewFilter,
+    });
+  }
+  return transformed;
+}
+
+export function assertRecommendationWindowResult({ operation, result }) {
+  const mode = operation?.pagination?.coverageMode;
+  if (!mode || mode === "legacy") return;
+  const after = result?.data?.pagination?.after;
+  const snapshotTimeStamp = result?.data?.pagination?.snapshotTimeStamp;
+  if (
+    !Number.isSafeInteger(after) ||
+    after < 0 ||
+    !Number.isSafeInteger(snapshotTimeStamp) ||
+    snapshotTimeStamp < 0
+  ) {
+    const error = new Error(
+      "The deployed API did not confirm the bounded recommendation window and snapshot. Deploy the matching API before using this CLI; use --include-legacy only for an intentional historical scan.",
+    );
+    error.code = "LUMINE_ADMIN_RECOMMENDATION_WINDOW_UNSUPPORTED";
+    error.data = {
+      ok: false,
+      status: "validation_error",
+      error: {
+        code: error.code,
+        message: error.message,
+        details: { requestedMode: mode },
+      },
+    };
+    throw error;
+  }
+}
+
+function finishAdminOutput({ options, operation, result }) {
   if (options.json) {
     console.log(JSON.stringify(result));
     return result;
@@ -460,6 +604,31 @@ export function parseAdminOperation(options) {
     if (action === "status") {
       return readOperation("daily-run.status", "/cli/admin/daily-runs/status");
     }
+    if (action === "report") {
+      return readOperation("daily-run.report", "/cli/admin/daily-runs/report");
+    }
+    if (action === "escalation" && target === "add") {
+      const rawTarget = String(options.adminTarget || "").trim();
+      const summary = String(options.note || "").trim();
+      if (!rawTarget || !summary) {
+        throw cliValidationError(
+          "Pass a concrete --target and --note when recording a run escalation.",
+        );
+      }
+      const parsedTarget = parseAdminEscalationTarget(rawTarget);
+      return writeOperation(
+        "daily-run.escalation.add",
+        "POST",
+        "/cli/admin/daily-runs/escalations",
+        {
+          targetType: parsedTarget.targetType || undefined,
+          targetId: parsedTarget.targetId || undefined,
+          url: parsedTarget.url || undefined,
+          summary,
+          severity: options.adminSeverity || "attention",
+        },
+      );
+    }
     if (action === "complete" || action === "fail") {
       return writeOperation(
         `daily-run.${action}`,
@@ -478,6 +647,7 @@ export function parseAdminOperation(options) {
     if (kind !== "recommend") {
       throw cliValidationError("--kind currently supports only recommend.");
     }
+    const recommendationWindow = parseRecommendationWindow(options);
     return readOperation(
       "recommendations.list",
       withQuery("/cli/admin/recommendations", {
@@ -485,7 +655,33 @@ export function parseAdminOperation(options) {
         contentTypes: options.adminContentTypes,
         cursor: options.adminCursor,
         limit: options.limit,
+        sinceRun: recommendationWindow.mode === "since-run" ? "true" : "",
+        after:
+          recommendationWindow.mode === "after"
+            ? recommendationWindow.after
+            : "",
+        includeLegacy:
+          recommendationWindow.mode === "legacy" ? "true" : "",
       }),
+      {
+        pagination: {
+          collectionKey: "items",
+          coverageQueue: "recommendations",
+          coverageMode: recommendationWindow.mode,
+          after:
+            recommendationWindow.mode === "after"
+              ? parseAfterForCoverage(recommendationWindow.after)
+              : null,
+          filters: {
+            contentTypes: options.adminContentTypes || null,
+            operatorView: options.adminUnviewed
+              ? "unviewed"
+              : options.adminViewed
+                ? "viewed"
+                : null,
+          },
+        },
+      },
     );
   }
 
@@ -498,8 +694,33 @@ export function parseAdminOperation(options) {
         cursor: options.adminCursor,
         limit: options.limit,
       }),
+      {
+        pagination: {
+          collectionKey: "builds",
+          coverageQueue: "builds",
+          coverageMode: "all",
+          after: null,
+          filters: { sort: "recent", scope: "all" },
+        },
+      },
     );
   }
+  if (namespace === "builds" && action === "review") {
+    const parsed = parseAdminCommentTarget({ target, explicitType: "build" });
+    if (parsed.type !== "build") {
+      throw cliValidationError(
+        "Build review targets a Build URL or build:<id>.",
+      );
+    }
+    return {
+      name: "build.review",
+      method: "GET",
+      path: "",
+      body: undefined,
+      mutates: false,
+      buildId: parsed.id,
+    };
+  }
 
   if (
     namespace === "subjects" &&
@@ -524,6 +745,7 @@ export function parseAdminOperation(options) {
           cursor: options.adminCursor,
           limit: options.limit,
         }),
+        { pagination: { collectionKey: "comments" } },
       );
     }
     if (action === "reveal") {
@@ -591,6 +813,7 @@ export function parseAdminOperation(options) {
           cursor: options.adminCursor,
           limit: options.limit,
         }),
+        { pagination: { collectionKey: "comments" } },
       );
     }
     if (action === "recommend") {
@@ -613,6 +836,20 @@ export function parseAdminOperation(options) {
         { reason: options.adminReason || undefined },
       );
     }
+    if (action === "skip-batch") {
+      if (!options.adminTargetFile) {
+        throw cliValidationError(
+          "Pass batch skip targets with --target-file <file>.",
+        );
+      }
+      return {
+        name: "post.skip-batch",
+        method: "POST",
+        path: "",
+        body: undefined,
+        mutates: true,
+      };
+    }
     if (action === "reward") {
       const parsedTarget = parseRecommendationTarget({
         target,
@@ -653,22 +890,41 @@ export function parseAdminOperation(options) {
         ...(repairDate ? { date: repairDate } : {}),
       });
     }
-    if (action === "submit") {
-      const editionId = parseRequiredInteger(
-        options.adminEditionId,
-        "--edition-id",
-        1,
+    if (action === "validate") {
+      const claim = extractNewsClaim(
+        readAdminJsonFile(options.adminClaimFile, "--claim <claim.json>"),
       );
-      const leaseToken = String(options.adminLeaseToken || "").trim();
+      return {
+        name: "news.validate",
+        local: true,
+        mutates: false,
+        claim,
+        editorial: readEditorialFile(options.adminFile),
+      };
+    }
+    if (action === "submit") {
+      const claim = options.adminClaimFile
+        ? extractNewsClaim(
+            readAdminJsonFile(options.adminClaimFile, "--claim <claim.json>"),
+          )
+        : null;
+      const editionId = claim
+        ? claim.editionId
+        : parseRequiredInteger(options.adminEditionId, "--edition-id", 1);
+      const leaseToken = claim
+        ? claim.leaseToken
+        : String(options.adminLeaseToken || "").trim();
       if (!leaseToken) {
         throw cliValidationError(
           "Pass the claim's lease token with --lease-token <token>.",
         );
       }
+      const editorial = readEditorialFile(options.adminFile);
+      if (claim) validateNewsEditorial({ claim, editorial });
       return writeOperation("news.submit", "POST", "/cli/admin/news/submit", {
         editionId,
         leaseToken,
-        editorial: readEditorialFile(options.adminFile),
+        editorial,
         model: options.model || undefined,
       });
     }
@@ -776,6 +1032,7 @@ export function parseAdminOperation(options) {
         limit: options.limit,
         full: options.adminFull ? "true" : "",
       }),
+      { pagination: { collectionKey: "events" } },
     );
   }
 
@@ -800,20 +1057,46 @@ export function parseAdminOperation(options) {
       const buildReviewMethod = options.adminBuildReviewMethod
         ? parseAdminBuildReviewMethod(options.adminBuildReviewMethod)
         : undefined;
+      const reviewReceipt = options.adminReviewReceipt
+        ? parseBuildReviewReceipt(options.adminReviewReceipt)
+        : null;
+      if (
+        reviewReceipt &&
+        (reviewedBuildVersionId || buildReviewMethod)
+      ) {
+        throw cliValidationError(
+          "Pass either --review-receipt or manual --reviewed-version/--reviewed-via evidence, not both.",
+        );
+      }
+      const confirmedBuildVersionId = reviewReceipt
+        ? Number(reviewReceipt.publishedArtifactVersionId)
+        : reviewedBuildVersionId;
+      const confirmedBuildReviewMethod = reviewReceipt
+        ? "runtime"
+        : buildReviewMethod;
+      if (
+        reviewReceipt &&
+        parsedTarget.type === "build" &&
+        Number(reviewReceipt.buildId) !== parsedTarget.id
+      ) {
+        throw cliValidationError(
+          "The review receipt belongs to a different Build.",
+        );
+      }
       if (parsedTarget.type === "build") {
         if (!options.adminFile) {
           throw cliValidationError(
             "Build comments are management-agent composed only; pass --file <comment.md> after reviewing the project.",
           );
         }
-        if (!reviewedBuildVersionId || !buildReviewMethod) {
+        if (!confirmedBuildVersionId || !confirmedBuildReviewMethod) {
           throw cliValidationError(
             "After reviewing the project, pass both --reviewed-version <published-artifact-id> and --reviewed-via runtime|code.",
           );
         }
       } else if (
         parsedTarget.type !== "comment" &&
-        (reviewedBuildVersionId || buildReviewMethod)
+        (confirmedBuildVersionId || confirmedBuildReviewMethod)
       ) {
         throw cliValidationError(
           "Build review evidence applies only to build:<id> or a comment:<id> inside a Build.",
@@ -832,8 +1115,12 @@ export function parseAdminOperation(options) {
           ...(options.adminFile
             ? { content: readComposedTextFile(options.adminFile) }
             : {}),
-          ...(reviewedBuildVersionId ? { reviewedBuildVersionId } : {}),
-          ...(buildReviewMethod ? { buildReviewMethod } : {}),
+          ...(confirmedBuildVersionId
+            ? { reviewedBuildVersionId: confirmedBuildVersionId }
+            : {}),
+          ...(confirmedBuildReviewMethod
+            ? { buildReviewMethod: confirmedBuildReviewMethod }
+            : {}),
         },
       );
     }
@@ -890,6 +1177,17 @@ function subjectsListOperation(options) {
       effort: options.adminEffort,
       limit: options.limit,
     }),
+    {
+      pagination: {
+        collectionKey: "subjects",
+        coverageQueue: "subjects",
+        coverageMode: options.adminAfter ? "after" : "all",
+        after: options.adminAfter
+          ? parseAfterForCoverage(options.adminAfter)
+          : null,
+        filters: { effort: options.adminEffort || "all" },
+      },
+    },
   );
 }
 
@@ -997,6 +1295,35 @@ function recommendOperation(target, options) {
   );
 }
 
+export function parseRecommendationWindow(options) {
+  const selected = [
+    options.adminSinceRun ? "since-run" : "",
+    options.adminAfter ? "after" : "",
+    options.adminIncludeLegacy ? "legacy" : "",
+  ].filter(Boolean);
+  if (selected.length > 1) {
+    throw cliValidationError(
+      "Choose one recommendation window: --since-run, --after, or --include-legacy.",
+    );
+  }
+  const mode = selected[0] || "since-run";
+  if (mode === "after") parseAfterForCoverage(options.adminAfter);
+  return { mode, after: mode === "after" ? options.adminAfter : "" };
+}
+
+function parseAfterForCoverage(value) {
+  const raw = String(value || "").trim();
+  if (/^\d+$/.test(raw)) {
+    const parsed = Number(raw);
+    if (Number.isSafeInteger(parsed) && parsed >= 0) return parsed;
+  }
+  const parsedMs = Date.parse(raw);
+  if (Number.isFinite(parsedMs)) return Math.floor(parsedMs / 1000);
+  throw cliValidationError(
+    "--after must be a Unix timestamp or ISO-8601 date.",
+  );
+}
+
 export function parseSubjectId(value) {
   const normalized = String(value || "").trim();
   const match = normalized.match(/(?:^subject:|\/subjects\/)(\d+)(?:[/?#]|$)/i);
@@ -1090,6 +1417,42 @@ export function parseAdminCommentTarget({ target, explicitType = "" }) {
   return baseTarget;
 }
 
+export function parseAdminEscalationTarget(value) {
+  const normalized = String(value || "").trim();
+  const genericTarget = normalized.match(
+    /^([a-zA-Z][a-zA-Z0-9_-]{0,39}):(\d+)$/,
+  );
+  if (genericTarget) {
+    return {
+      targetType: genericTarget[1],
+      targetId: parseRequiredInteger(genericTarget[2], "escalation target ID", 1),
+      url: null,
+    };
+  }
+  if (/^https:\/\//i.test(normalized)) {
+    let parsedUrl;
+    try {
+      parsedUrl = new URL(normalized);
+    } catch {
+      throw cliValidationError("The escalation target URL is invalid.");
+    }
+    if (parsedUrl.protocol !== "https:") {
+      throw cliValidationError("The escalation target URL must use HTTPS.");
+    }
+    if (
+      /\/(?:subjects|comments|ai-stories|daily-reflections|app|build)\/\d+(?:[/?#]|$)/i.test(
+        normalized,
+      )
+    ) {
+      const parsed = parseAdminCommentTarget({ target: normalized });
+      return { targetType: parsed.type, targetId: parsed.id, url: normalized };
+    }
+    return { targetType: null, targetId: null, url: normalized };
+  }
+  const parsed = parseAdminCommentTarget({ target: normalized });
+  return { targetType: parsed.type, targetId: parsed.id, url: null };
+}
+
 function parseAdminBuildReviewMethod(value) {
   const normalized = String(value || "")
     .trim()
@@ -1134,8 +1497,15 @@ export function formatAdminJsonError(error) {
   };
 }
 
-function readOperation(name, path) {
-  return { name, method: "GET", path, body: undefined, mutates: false };
+function readOperation(name, path, extra = {}) {
+  return {
+    name,
+    method: "GET",
+    path,
+    body: undefined,
+    mutates: false,
+    ...extra,
+  };
 }
 
 function writeOperation(name, method, path, body) {
@@ -1276,8 +1646,73 @@ function cliValidationError(message) {
   return error;
 }
 
+function adminValueFingerprint(value) {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+
 function printAdminResult({ operation, result }) {
   const data = result?.data || {};
+  if (data.review) {
+    console.log(
+      `Confirmed Build #${data.review.buildId} runtime at published artifact #${data.review.publishedArtifactVersionId}.`,
+    );
+    console.log(`Screenshot: ${data.screenshotPath}`);
+    console.log(`Review receipt: ${data.receiptPath}`);
+    return;
+  }
+  if (data.validation) {
+    console.log(
+      `Editorial valid for edition #${data.validation.editionId}: ${data.validation.citedEventCount} cited and ${data.validation.coveredEventCount} covered event(s).`,
+    );
+    return;
+  }
+  if (data.batch) {
+    console.log(
+      `Skipped ${data.batch.completedCount} audited target(s); ${data.batch.changedCount} changed canonical state.`,
+    );
+    console.log(`Checkpoint: ${data.batch.checkpointPath}`);
+    return;
+  }
+  if (data.report) {
+    const report = data.report;
+    console.log(
+      `Run #${report.run.id}: ${report.mutations.successfulMutationCount} successful mutation(s), ${report.queueCoverage.length} queue coverage record(s), ${report.escalations.length} escalation(s).`,
+    );
+    for (const coverage of report.queueCoverage) {
+      console.log(
+        `  ${coverage.queue}: ${coverage.candidateCount} candidate(s), ${coverage.scannedCount} row(s) scanned across ${coverage.pages} page(s).`,
+      );
+    }
+    for (const escalation of report.escalations) {
+      const target =
+        escalation.url ||
+        `${escalation.targetType || "target"}:${escalation.targetId || "?"}`;
+      console.log(
+        `  ${String(escalation.severity || "attention").toUpperCase()} ${target} — ${escalation.summary}`,
+      );
+    }
+    const surfaces = report.brief?.engagementPulse?.surfaces;
+    if (surfaces && typeof surfaces === "object") {
+      const deltas = Object.entries(surfaces)
+        .filter(([, value]) => Number(value?.delta || 0) !== 0)
+        .sort(
+          ([, left], [, right]) =>
+            Math.abs(Number(right?.delta || 0)) -
+            Math.abs(Number(left?.delta || 0)),
+        )
+        .slice(0, 5)
+        .map(
+          ([name, value]) =>
+            `${name} ${Number(value.delta) > 0 ? "+" : ""}${Number(value.delta)}`,
+        );
+      if (deltas.length) console.log(`Engagement deltas: ${deltas.join(", ")}.`);
+    }
+    const notableCount = Array.isArray(report.brief?.notableCandidates)
+      ? report.brief.notableCandidates.length
+      : 0;
+    console.log(`Notable-user candidates in this brief: ${notableCount}.`);
+    return;
+  }
   if (data.bucket && Array.isArray(data.memberUserIds)) {
     const added = Array.isArray(data.accounts)
       ? `; added ${data.accounts.length} explicit account(s)`
@@ -1347,12 +1782,28 @@ function printAdminResult({ operation, result }) {
     return;
   }
   if (data.claim) {
-    console.log(
-      `Claimed edition #${data.claim.editionId} (${data.claim.dateKey}): ${data.claim.events.length} event(s); lease token ${data.claim.leaseToken}.`,
-    );
-    console.log(
-      `Write the editorial JSON, then run: lumine admin news submit --edition-id ${data.claim.editionId} --lease-token ${data.claim.leaseToken} --file editorial.json`,
-    );
+    if (data.artifacts?.claimFile) {
+      console.log(
+        `Claimed edition #${data.claim.editionId} (${data.claim.dateKey}): ${data.claim.events.length} event(s).`,
+      );
+      console.log(`Claim file: ${data.artifacts.claimFile}`);
+      if (data.artifacts?.scaffoldFile) {
+        console.log(`Editorial scaffold: ${data.artifacts.scaffoldFile}`);
+      }
+      console.log(
+        `Validate before submission: lumine admin news validate --claim ${data.artifacts.claimFile} --file ${data.artifacts.scaffoldFile || "editorial.json"}`,
+      );
+      console.log(
+        `Submit the confirmed pair: lumine admin news submit --claim ${data.artifacts.claimFile} --file ${data.artifacts.scaffoldFile || "editorial.json"}`,
+      );
+    } else {
+      console.log(
+        `Claimed edition #${data.claim.editionId} (${data.claim.dateKey}): ${data.claim.events.length} event(s); lease token ${data.claim.leaseToken}.`,
+      );
+      console.log(
+        `Write the editorial JSON, then run: lumine admin news submit --edition-id ${data.claim.editionId} --lease-token ${data.claim.leaseToken} --file editorial.json`,
+      );
+    }
     return;
   }
   if (data.newspaper) {