@stage5/lumine 0.2.66 → 0.2.68

package/lib/admin-workflows.js

@@ -130,7 +130,7 @@ function pathEntryExists(filePath) {
   }
 }
 
-function acquireCheckpointLock(checkpointPath, operationFingerprint) {
+export function acquireCheckpointLock(checkpointPath, operationFingerprint) {
   const lockPath = `${checkpointPath}.lock`;
   const reclaimPath = `${lockPath}.reclaim`;
   mkdirSync(path.dirname(lockPath), { recursive: true });
@@ -253,7 +253,7 @@ function removeDeadCheckpointLock(lockPath) {
   }
 }
 
-function releaseCheckpointLock(lock) {
+export function releaseCheckpointLock(lock) {
   try {
     const fileState = lstatSync(lock.lockPath);
     if (!fileState.isFile() || fileState.isSymbolicLink()) return;
@@ -339,9 +339,13 @@ function createCandidateSpool(checkpointPath) {
 function loadSupersededCandidateSpool(checkpointPath) {
   let saved;
   try {
-    saved = readAdminJsonFile(checkpointPath, "the previous pagination checkpoint", {
-      maxBytes: MAX_LEGACY_ADMIN_CHECKPOINT_BYTES,
-    });
+    saved = readAdminJsonFile(
+      checkpointPath,
+      "the previous pagination checkpoint",
+      {
+        maxBytes: MAX_LEGACY_ADMIN_CHECKPOINT_BYTES,
+      },
+    );
   } catch {
     return null;
   }
@@ -413,8 +417,7 @@ function normalizeClientFilterSummary(value) {
   if (
     !Array.isArray(value.contentTypes) ||
     value.contentTypes.some(
-      (contentType) =>
-        typeof contentType !== "string" || !contentType.trim(),
+      (contentType) => typeof contentType !== "string" || !contentType.trim(),
     )
   ) {
     throw validationError(
@@ -522,7 +525,9 @@ function verifyCandidateSpool({
   try {
     fileState = lstatSync(spoolPath);
   } catch {
-    throw validationError(`Could not read pagination candidates at ${spoolPath}.`);
+    throw validationError(
+      `Could not read pagination candidates at ${spoolPath}.`,
+    );
   }
   if (!fileState.isFile() || fileState.isSymbolicLink()) {
     throw validationError(
@@ -628,7 +633,9 @@ function serializedObjectEntries(value, excludedKeys = new Set()) {
 export async function forEachPaginatedResultItem(result, visit) {
   const storage = paginationStorageFromResult(result);
   if (!storage) {
-    throw validationError("The result does not contain spooled pagination data.");
+    throw validationError(
+      "The result does not contain spooled pagination data.",
+    );
   }
   verifyCandidateSpool({ ...storage, discardUnconfirmedTail: false });
   const input = createReadStream(storage.spoolPath, { encoding: "utf8" });
@@ -805,7 +812,9 @@ function aggregatePageResult({ operation, lastPage, checkpointPath, state }) {
 export async function runAutomaticPagination(args) {
   const { options, operation, runId } = args;
   if (!operation.pagination) {
-    throw validationError("--all is supported only by paginated admin listings.");
+    throw validationError(
+      "--all is supported only by paginated admin listings.",
+    );
   }
   const operationFingerprint = operationFingerprintValue({
     schemaVersion: ADMIN_PAGINATION_SCHEMA_VERSION,
@@ -820,13 +829,51 @@ export async function runAutomaticPagination(args) {
     operationFingerprint,
   });
   const lock = acquireCheckpointLock(checkpointPath, operationFingerprint);
+  const signalSource = args.signalSource || process;
+  const controller = new AbortController();
+  let interruptedSignal = "";
+  const interrupt = (signalName) => {
+    interruptedSignal ||= signalName;
+    controller.abort(
+      new Error(`Lumine admin scan interrupted by ${signalName}.`),
+    );
+  };
+  const onSigint = () => interrupt("SIGINT");
+  const onSigterm = () => interrupt("SIGTERM");
+  signalSource.once("SIGINT", onSigint);
+  signalSource.once("SIGTERM", onSigterm);
   try {
     return await runAutomaticPaginationWithLock({
       ...args,
       checkpointPath,
       operationFingerprint,
+      signal: controller.signal,
     });
+  } catch (error) {
+    if (interruptedSignal) {
+      const interrupted = validationError(
+        `Canonical scan cancelled by ${interruptedSignal}. Confirmed progress remains at ${checkpointPath}; rerun the same command with --resume to continue it.`,
+      );
+      interrupted.code = "LUMINE_ADMIN_SCAN_CANCELLED";
+      interrupted.data = {
+        ok: false,
+        status: "validation_error",
+        error: {
+          code: interrupted.code,
+          message: interrupted.message,
+          details: {
+            checkpointPath,
+            signal: interruptedSignal,
+            resumable: true,
+          },
+        },
+      };
+      throw interrupted;
+    }
+    throw error;
   } finally {
+    signalSource.removeListener("SIGINT", onSigint);
+    signalSource.removeListener("SIGTERM", onSigterm);
     releaseCheckpointLock(lock);
   }
 }
@@ -841,6 +888,7 @@ async function runAutomaticPaginationWithLock({
   transformPage,
   recordCoverage,
   reportProgress = (message) => process.stderr.write(`${message}\n`),
+  signal,
 }) {
   const requestedOutputPath = String(options.adminOutput || "").trim();
   if (options.adminOutput && !requestedOutputPath) {
@@ -990,15 +1038,12 @@ async function runAutomaticPaginationWithLock({
             : null,
         snapshotTimeStamp:
           savedPages > 0
-            ? normalizeBoundary(
-                saved?.snapshotTimeStamp,
-                "snapshotTimeStamp",
-              )
+            ? normalizeBoundary(saved?.snapshotTimeStamp, "snapshotTimeStamp")
             : null,
         after:
           savedPages > 0
             ? normalizeBoundary(saved?.after, "after")
-            : operation.pagination.after ?? null,
+            : (operation.pagination.after ?? null),
         boundariesConfirmed: saved?.boundariesConfirmed,
         candidateCount,
         spoolPath: path.resolve(String(saved?.spoolPath || "")),
@@ -1065,19 +1110,27 @@ async function runAutomaticPaginationWithLock({
   }
   let lastPage = null;
   while (!state.exhausted) {
+    signal?.throwIfAborted();
     if (state.pages >= MAX_AUTOMATIC_PAGES) {
       throw validationError(
         `Automatic pagination stopped at the ${MAX_AUTOMATIC_PAGES}-page safety ceiling. Start a narrower request with a new checkpoint.`,
       );
     }
     const requestPath = pathWithCursor(operation.path, state.nextCursor);
-    const raw = await fetchPage(requestPath);
+    const raw = await fetchPage(requestPath, signal);
+    signal?.throwIfAborted();
     const page = transformPage(raw);
     lastPage = page;
     const data = page?.data || {};
     const pagination = data.pagination;
-    if (!pagination || typeof pagination !== "object" || Array.isArray(pagination)) {
-      throw validationError("The API response is missing canonical pagination metadata.");
+    if (
+      !pagination ||
+      typeof pagination !== "object" ||
+      Array.isArray(pagination)
+    ) {
+      throw validationError(
+        "The API response is missing canonical pagination metadata.",
+      );
     }
     const items = Array.isArray(data[operation.pagination.collectionKey])
       ? data[operation.pagination.collectionKey]
@@ -1089,7 +1142,9 @@ async function runAutomaticPaginationWithLock({
     }
     const nextCursor = String(pagination.nextCursor || "");
     if (nextCursor && nextCursor === state.nextCursor) {
-      throw validationError("The API returned the same pagination cursor twice.");
+      throw validationError(
+        "The API returned the same pagination cursor twice.",
+      );
     }
     if (!pagination.exhausted && !nextCursor) {
       throw validationError(
@@ -1111,7 +1166,11 @@ async function runAutomaticPaginationWithLock({
     );
     const pageAfter = normalizeBoundary(pagination.after, "after");
     if (state.boundariesConfirmed) {
-      assertStableBoundary("snapshotMaxId", state.snapshotMaxId, pageSnapshotMaxId);
+      assertStableBoundary(
+        "snapshotMaxId",
+        state.snapshotMaxId,
+        pageSnapshotMaxId,
+      );
       assertStableBoundary(
         "snapshotTimeStamp",
         state.snapshotTimeStamp,
@@ -1119,7 +1178,10 @@ async function runAutomaticPaginationWithLock({
       );
       assertStableBoundary("after", state.after, pageAfter);
     } else {
-      const requestedAfter = normalizeBoundary(operation.pagination.after, "after");
+      const requestedAfter = normalizeBoundary(
+        operation.pagination.after,
+        "after",
+      );
       if (requestedAfter !== null) {
         assertStableBoundary("after", requestedAfter, pageAfter);
       }
@@ -1147,10 +1209,7 @@ async function runAutomaticPaginationWithLock({
       pages: state.pages + 1,
       scannedCount:
         state.scannedCount +
-        normalizeScannedCount(
-          pagination.scannedCount,
-          items.length,
-        ),
+        normalizeScannedCount(pagination.scannedCount, items.length),
       candidateCount: state.candidateCount + items.length,
       spoolBytes: state.spoolBytes + appended.addedBytes,
       spoolSha256: appended.spoolSha256,
@@ -1177,19 +1236,24 @@ async function runAutomaticPaginationWithLock({
     checkpointPath,
     state,
   });
+  signal?.throwIfAborted();
   if (recordCoverage && operation.pagination.coverageQueue) {
-    await recordCoverage({
-      queue: operation.pagination.coverageQueue,
-      mode: operation.pagination.coverageMode || "all",
-      after: state.after,
-      pages: state.pages,
-      scannedCount: state.scannedCount,
-      candidateCount: state.candidateCount,
-      snapshotMaxId: state.snapshotMaxId,
-      snapshotTimeStamp: state.snapshotTimeStamp,
-      exhausted: state.exhausted,
-      filters: operation.pagination.filters || {},
-    });
+    await recordCoverage(
+      {
+        queue: operation.pagination.coverageQueue,
+        mode: operation.pagination.coverageMode || "all",
+        after: state.after,
+        pages: state.pages,
+        scannedCount: state.scannedCount,
+        candidateCount: state.candidateCount,
+        snapshotMaxId: state.snapshotMaxId,
+        snapshotTimeStamp: state.snapshotTimeStamp,
+        exhausted: state.exhausted,
+        filters: operation.pagination.filters || {},
+      },
+      signal,
+    );
+    signal?.throwIfAborted();
   }
   if (outputPath) {
     result.data.scan.outputPath = outputPath;
@@ -1226,12 +1290,16 @@ export function readBatchSkipTargets({ filePath, parseTarget, defaultReason }) {
     throw validationError("The batch target file contains no targets.");
   }
   if (values.length > MAX_BATCH_TARGETS) {
-    throw validationError(`A batch can contain at most ${MAX_BATCH_TARGETS} targets.`);
+    throw validationError(
+      `A batch can contain at most ${MAX_BATCH_TARGETS} targets.`,
+    );
   }
   const deduped = new Map();
   for (const value of values) {
     const rawTarget =
-      typeof value === "string" ? value : value?.target || value?.url || value?.id;
+      typeof value === "string"
+        ? value
+        : value?.target || value?.url || value?.id;
     const parsed = parseTarget({
       target: rawTarget,
       explicitType: typeof value === "object" ? value?.type || "" : "",
@@ -1298,7 +1366,9 @@ export async function runBatchSkips({
       !saved.completed ||
       typeof saved.completed !== "object"
     ) {
-      throw validationError("The checkpoint does not match this exact skip batch.");
+      throw validationError(
+        "The checkpoint does not match this exact skip batch.",
+      );
     }
     state = saved;
   } else {
@@ -1339,8 +1409,9 @@ export async function runBatchSkips({
       batch: {
         targetCount: targets.length,
         completedCount: Object.keys(state.completed).length,
-        changedCount: Object.values(state.completed).filter((entry) => entry.changed)
-          .length,
+        changedCount: Object.values(state.completed).filter(
+          (entry) => entry.changed,
+        ).length,
         checkpointPath,
         resumed: options.adminResume === true,
         targets: state.completed,
@@ -1348,10 +1419,14 @@ export async function runBatchSkips({
     },
   };
   if (options.adminOutput) {
-    result.data.batch.outputPath = writeAdminJsonFile(options.adminOutput, result, {
-      privateFile: true,
-      maxBytes: MAX_BATCH_CHECKPOINT_BYTES,
-    });
+    result.data.batch.outputPath = writeAdminJsonFile(
+      options.adminOutput,
+      result,
+      {
+        privateFile: true,
+        maxBytes: MAX_BATCH_CHECKPOINT_BYTES,
+      },
+    );
   }
   return result;
 }