feat(bulk-assets): retry publishing assets whose scan was pending

Assets still being scanned for malware were skipped on every publish run
with only a console warning, leaving no way to publish them once the scan
finished. Record those skips to pending-scan.json in the bulk operation
folder, and add --retry-pending to re-check their status and publish the
ones that came back clean.

The log is self-pruning: a retry drops the entries it published along with
any that turned quarantined, keeping only those still scanning. It is also
excluded from clearLogs(), since a scan can outlast the gap between two
unrelated runs.

Quarantined assets are never retried, and the flag is rejected for
unpublish, delete and move — scan status only gates publish.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: naman-contentstack

.talismanrc

@@ -32,11 +32,17 @@ fileignoreconfig:
 - filename: packages/contentstack-audit/test/unit/mock/am-contents/stack/stack.json
   checksum: c4ac3ff80eb38b1c58eb0db21a232bd84f856d4647093542296199036945083c
 - filename: packages/contentstack-bulk-operations/src/commands/cm/stacks/bulk-assets.ts
-  checksum: 60f33657cc6e2664c17397a2f6b4b54a3f7bf71618931d63cd2811822bd4837e
+  checksum: 0b07ebebd0aaf3c1cb2dedd74801c93ed4a083864c96b8457d7e612c5736d0da
 - filename: packages/contentstack-bulk-operations/src/utils/data-dir-asset-fetcher.ts
   checksum: ddcf4601ac47be300eba0eb901e4d45d748c2c4eab676c56677cb9a802fe3db0
 - filename: packages/contentstack-migration/src/commands/cm/stacks/migration.ts
   checksum: a64a4d396eddd936a63b799eff58c5c6660b5dcaa3a310fd8b09a027932f1789
 - filename: packages/contentstack-migration/README.md
   checksum: e96006c1a948f766c88ae972b29582fa58eaf8184606bf011eebddc5a06cd7b6
+- filename: packages/contentstack-bulk-operations/src/utils/bulk-operation-log-handler.ts
+  checksum: e67a7a16a395be315c7464c8a24b142cbd259c59d31b17e1cdd32f613060c2b4
+- filename: packages/contentstack-bulk-operations/test/unit/commands/bulk-assets.test.ts
+  checksum: 92e0ba427283573dd629ca96e5d2c4286bfd90cf6f36af65b404c09bb32d856f
+- filename: packages/contentstack-bulk-operations/test/unit/utils/bulk-operation-log-handler.test.ts
+  checksum: a660f8caac1418746ef6ec7ef9b69d04065ce0a8c0e7568bcbbd6e5287841304
 version: ""

packages/contentstack-bulk-operations/README.md

@@ -44,8 +44,8 @@ USAGE
   $ csdx cm:stacks:bulk-assets [-a <value>] [-k <value>] [--operation publish|unpublish|delete|move] [--environments
     <value>...] [--locales <value>...] [--source-env <value>] [--source-alias <value>] [--publish-mode bulk|single]
     [--branch <value>] [-c <value>] [-y] [--retry-failed <value>] [--revert <value>] [--bulk-operation-file <value>]
-    [--folder-uid <value>] [-d <value>] [--dry-run] [--space-uid <value>] [--org-uid <value>] [--workspace <value>]
-    [--asset-uids-file <value>] [--locale <value>] [--target-folder-uid <value>]
+    [--folder-uid <value>] [-d <value>] [--dry-run] [--retry-pending <value>] [--space-uid <value>] [--org-uid <value>]
+    [--workspace <value>] [--asset-uids-file <value>] [--locale <value>] [--target-folder-uid <value>]
 
 FLAGS
   -a, --alias=<value>                Uses the name of a saved Management Token to authenticate the command. The command
@@ -85,6 +85,10 @@ FLAGS
       --retry-failed=<value>         (optional) Use this option to retry publishing the failed entries/assets from the
                                      logfile. Specify the name of the logfile that lists failed publish calls. If this
                                      option is used, it will override all other flags.
+      --retry-pending=<value>        (optional) Re-checks the malware scan status of assets a previous run skipped
+                                     because scanning was still in progress, and publishes the ones that are now clean.
+                                     Specify the bulk operation folder used by that run. Quarantined assets are never
+                                     retried.
       --revert=<value>               (optional) Revert publish operations from a log folder. Specify the folder path
                                      containing success logs. Works similar to retry-failed.
       --source-alias=<value>         Alias name for source environment delivery token (required for cross-publish). Add
@@ -112,6 +116,8 @@ EXAMPLES
 
   $ csdx cm:stacks:bulk-assets --retry-failed ./bulk-operation -a myAlias
 
+  $ csdx cm:stacks:bulk-assets --retry-pending ./bulk-operation -a myAlias
+
   $ csdx cm:stacks:bulk-assets --revert ./bulk-operation -a myAlias
 
   $ csdx cm:stacks:bulk-assets --data-dir ./content --operation publish -k blt123

packages/contentstack-bulk-operations/src/base-bulk-command.ts

@@ -156,6 +156,18 @@ export abstract class BaseBulkCommand extends Command {
     return false;
   }
 
+  /**
+   * Hook for a resource-specific retry flow that loads its config from a log file
+   * rather than the usual flags — like --retry-failed/--revert, but with its own
+   * pre-publish checks (see BulkAssets and --retry-pending).
+   *
+   * Return true when the flow handled the run: init() then returns immediately,
+   * skipping interactive prompts, the normal pipeline, and clearLogs().
+   */
+  protected async handleResourceSpecificRetryFlow(_flags: any): Promise<boolean> {
+    return false;
+  }
+
   /**
    * Initialize common components
    */
@@ -182,6 +194,12 @@ export abstract class BaseBulkCommand extends Command {
     this.logger = log;
     this.loggerContext = { module: this.id };
 
+    // Resource-specific retry flows (e.g. asset scan-status retry) run their own
+    // init and must bypass clearLogs() for the same reason revert/retry does.
+    if (await this.handleResourceSpecificRetryFlow(flags)) {
+      return;
+    }
+
     // Check for revert/retry EARLY - all config comes from log file
     const isRevertOrRetry = flags.revert || flags['retry-failed'];
 

packages/contentstack-bulk-operations/src/commands/cm/stacks/bulk-assets.ts

@@ -3,7 +3,14 @@ import * as path from 'path';
 
 import { flags, handleAndLogError, log, FlagInput } from '@contentstack/cli-utilities';
 
-import { AssetPublishData, BulkOperationResult, ResourceType, OperationType, CsAssetsFlags } from '../../../interfaces';
+import {
+  AssetPublishData,
+  BulkOperationResult,
+  ResourceType,
+  OperationType,
+  CsAssetsFlags,
+  PendingScanLogEntry,
+} from '../../../interfaces';
 import { BaseBulkCommand } from '../../../base-bulk-command';
 import {
   $t,
@@ -21,6 +28,12 @@ import {
   RETRY_REVERT_CONTEXT,
 } from '../../../utils';
 import type { DataDirScanStats } from '../../../utils';
+import {
+  appendPendingScanLog,
+  getLogPaths,
+  readPendingScanLog,
+  writePendingScanLog,
+} from '../../../utils/bulk-operation-log-handler';
 import { AssetService } from '../../../services';
 
 type RegionWithOptionalCsAssetsUrl = { csAssetsUrl?: string };
@@ -65,6 +78,9 @@ export default class BulkAssets extends BaseBulkCommand {
     // Retry failed assets from a log file
     '<%= config.bin %> <%= command.id %> --retry-failed ./bulk-operation -a myAlias',
 
+    // Re-check scan status and publish assets a previous run skipped as still scanning
+    '<%= config.bin %> <%= command.id %> --retry-pending ./bulk-operation -a myAlias',
+
     // Revert (unpublish) previously published assets using success log
     '<%= config.bin %> <%= command.id %> --revert ./bulk-operation -a myAlias',
 
@@ -96,6 +112,9 @@ export default class BulkAssets extends BaseBulkCommand {
       description: messages.DRY_RUN_FLAG_DESC,
       default: false,
     }),
+    'retry-pending': flags.string({
+      description: messages.RETRY_PENDING,
+    }),
 
     // CS Assets delete/move flags
     'space-uid': flags.string({
@@ -140,7 +159,9 @@ export default class BulkAssets extends BaseBulkCommand {
         token === '--retry-failed' ||
         token.startsWith('--retry-failed=') ||
         token === '--revert' ||
-        token.startsWith('--revert=')
+        token.startsWith('--revert=') ||
+        token === '--retry-pending' ||
+        token.startsWith('--retry-pending=')
     );
 
     if (!operation && !isRevertOrRetry) {
@@ -217,6 +238,20 @@ export default class BulkAssets extends BaseBulkCommand {
         pending.forEach((a) => this.logger.warn($t(messages.SCAN_STATUS_SKIPPED_PENDING, { uid: a.uid })));
         quarantined.forEach((a) => this.logger.warn($t(messages.SCAN_STATUS_SKIPPED_QUARANTINED, { uid: a.uid })));
 
+        // Persist the pending ones so --retry-pending can publish them once the scan clears.
+        // fetchAssets() builds one row per uid x locale, so each carries its own locale/version.
+        appendPendingScanLog(
+          pending.map((a) =>
+            this.buildPendingScanEntry({
+              uid: a.uid,
+              locale: a.locale,
+              version: a.version ?? a._version,
+              environments: (a.publish_details || []).map((pd: any) => pd.environment),
+            })
+          ),
+          this.bulkOperationConfig.bulkOperationFolder
+        );
+
         this.printScanningDashboard({
           total: assets.length,
           clean: clean.length,
@@ -361,6 +396,9 @@ export default class BulkAssets extends BaseBulkCommand {
     let workingBatch: AssetPublishData[] = [];
     let batchNumber = 0;
     let totalSubmitted = 0;
+    // Collected across the whole stream and written once at the end — a per-asset
+    // write would defeat the one-chunk-at-a-time design of this pass.
+    const pendingScanEntries: PendingScanLogEntry[] = [];
 
     this.batchResults.clear();
 
@@ -394,15 +432,21 @@ export default class BulkAssets extends BaseBulkCommand {
           this.logger.warn($t(messages.SCAN_STATUS_SKIPPED_QUARANTINED, { uid: targetUid }));
           continue;
         }
+        const assetLocales: string[] = useOverrideLocales
+          ? cliLocales
+          : [...new Set<string>(asset.publish_details.map((pd: any) => pd.locale as string))];
+
         if (scanStatus === 'pending') {
           this.logger.warn($t(messages.SCAN_STATUS_SKIPPED_PENDING, { uid: targetUid }));
+          // Record per locale so --retry-pending republishes the same rows this run would have.
+          for (const locale of assetLocales) {
+            pendingScanEntries.push(
+              this.buildPendingScanEntry({ uid: targetUid, locale, version: asset._version, environments })
+            );
+          }
           continue;
         }
 
-        const assetLocales: string[] = useOverrideLocales
-          ? cliLocales
-          : [...new Set<string>(asset.publish_details.map((pd: any) => pd.locale as string))];
-
         for (const locale of assetLocales) {
           workingBatch.push({ type: 'asset', uid: targetUid, locale, version: asset._version });
           if (workingBatch.length >= BATCH_SIZE) {
@@ -415,6 +459,9 @@ export default class BulkAssets extends BaseBulkCommand {
 
     flushBatch();
 
+    // One write for the whole streamed run.
+    appendPendingScanLog(pendingScanEntries, this.bulkOperationConfig.bulkOperationFolder);
+
     // Invariant: pass 1 and pass 2 use identical counting logic (excluding scan status filtering).
     // If batchNumber < totalBatches, scan status filtering reduced the published count — expected.
     if (batchNumber !== totalBatches) {
@@ -464,4 +511,132 @@ export default class BulkAssets extends BaseBulkCommand {
   protected async fetchItems(): Promise<any[]> {
     return await fetchAssets(this.bulkOperationConfig, this.managementStack, this.deliveryStack, this.logger);
   }
+
+  protected async handleResourceSpecificRetryFlow(flags: any): Promise<boolean> {
+    if (!flags['retry-pending']) {
+      return false;
+    }
+    await this.initForRetryPendingScan(flags);
+    return true;
+  }
+
+  /**
+   * Initialize the --retry-pending run. Mirrors initForRevertOrRetry: everything
+   * needed comes from the pending-scan log, with any CLI flag overriding it.
+   */
+  private async initForRetryPendingScan(flags: any): Promise<void> {
+    const logPath = flags['retry-pending'];
+    const pendingEntries = readPendingScanLog(logPath);
+
+    if (pendingEntries.length === 0) {
+      log.warn($t(messages.NO_PENDING_SCAN_ITEMS_IN_LOG, { path: getLogPaths(logPath).pendingScan }));
+      this.finalizeProgressSummary();
+      process.exit(0);
+    }
+
+    const [first] = pendingEntries;
+    const mergedFlags = {
+      ...flags,
+      'stack-api-key': flags['stack-api-key'] || first.apiKey,
+      environments:
+        flags.environments?.length > 0
+          ? flags.environments
+          : [...new Set(pendingEntries.flatMap((entry) => entry.environments))],
+      locales: flags.locales?.length > 0 ? flags.locales : [...new Set(pendingEntries.map((entry) => entry.locale))],
+      branch: flags.branch !== 'main' ? flags.branch : first.branch || 'main',
+      // Scan status only ever gates publish.
+      operation: OperationType.PUBLISH,
+      'publish-mode': flags['publish-mode'] || 'bulk',
+    };
+
+    this.parsedFlags = mergedFlags;
+    await this.buildConfiguration(mergedFlags);
+    await this.setupStack();
+    await this.initializeComponents();
+
+    await this.retryPendingScan(logPath, pendingEntries);
+
+    // Mirrors initForRevertOrRetry: this early exit bypasses finally().
+    this.finalizeProgressSummary();
+    process.exit(0);
+  }
+
+  /**
+   * Stamp a pending-scan skip with the run metadata --retry-pending needs to
+   * rebuild the publish call later without re-fetching the asset.
+   */
+  private buildPendingScanEntry(item: {
+    uid: string;
+    locale: string;
+    version?: number;
+    environments: string[];
+  }): PendingScanLogEntry {
+    return {
+      ...item,
+      operation: 'publish',
+      timestamp: new Date().toISOString(),
+      apiKey: this.bulkOperationConfig.apiKey || this.bulkOperationConfig.stackApiKey || '',
+      branch: this.bulkOperationConfig.branch,
+    };
+  }
+
+  /**
+   * Re-check the scan status of assets a previous run skipped as still scanning,
+   * publish the ones now clean, and prune the log down to those still pending.
+   */
+  private async retryPendingScan(logPath: string, pendingEntries: PendingScanLogEntry[]): Promise<void> {
+    const uids = [...new Set(pendingEntries.map((entry) => entry.uid))];
+    const assetService = new AssetService(this.managementStack, this.deliveryStack, this.logger);
+    const scanStatusMap = await assetService.fetchScanStatusByUIDs(uids);
+
+    const nowClean: PendingScanLogEntry[] = [];
+    const stillPending: PendingScanLogEntry[] = [];
+    const nowQuarantined: PendingScanLogEntry[] = [];
+
+    for (const entry of pendingEntries) {
+      const status = scanStatusMap.get(entry.uid);
+      if (status === 'pending') stillPending.push(entry);
+      else if (status === 'quarantined') nowQuarantined.push(entry);
+      else nowClean.push(entry); // clean, or undefined when scanning is disabled
+    }
+
+    log.info(
+      $t(messages.SCAN_RECHECK_SUMMARY, {
+        total: pendingEntries.length,
+        clean: nowClean.length,
+        pending: stillPending.length,
+        quarantined: nowQuarantined.length,
+      })
+    );
+    nowQuarantined.forEach((entry) =>
+      this.logger.warn($t(messages.SCAN_STATUS_SKIPPED_QUARANTINED, { uid: entry.uid }))
+    );
+
+    if (nowClean.length === 0) {
+      this.logger.warn($t(messages.NO_PUBLISHABLE_ASSETS));
+      // Still prune: the quarantined ones will never become publishable.
+      writePendingScanLog(stillPending, logPath);
+      return;
+    }
+
+    const items: AssetPublishData[] = nowClean.map((entry) => ({
+      type: 'asset',
+      uid: entry.uid,
+      locale: entry.locale,
+      version: entry.version,
+      publish_details: entry.environments.map((environment) => ({ environment, locale: entry.locale })),
+    }));
+
+    const confirmed = await this.confirmOperation(items);
+    if (!confirmed) {
+      this.logger.warn($t(messages.OPERATION_CANCELLED));
+      // Leave the log untouched so the next run sees the same set.
+      return;
+    }
+
+    const result = await this.executeBulkOperation(items);
+    this.printOperationSummary(result);
+
+    writePendingScanLog(stillPending, logPath);
+  }
 }

packages/contentstack-bulk-operations/src/interfaces/index.ts

@@ -400,6 +400,25 @@ export interface SingleModeLogEntry {
  */
 export type LogEntry = BulkModeLogEntry | SingleModeLogEntry;
 
+/**
+ * Log entry for an asset skipped because its malware scan was still pending.
+ *
+ * Flat (no bulk/single split) — the skip happens before the publish mode matters.
+ * Self-sufficient by design: a later --retry-pending run rebuilds the publish
+ * payload straight from this record without re-fetching the asset.
+ */
+export interface PendingScanLogEntry {
+  uid: string;
+  locale: string;
+  version?: number;
+  environments: string[];
+  operation: 'publish'; // scan status only gates publish
+  timestamp: string;
+  // Metadata
+  apiKey: string;
+  branch?: string;
+}
+
 export interface LogPaths {
   folder: string;
   // Bulk mode logs
@@ -408,6 +427,8 @@ export interface LogPaths {
   // Single mode logs
   singleSuccess: string;
   singleFailed: string;
+  // Assets skipped for a pending scan, retried via --retry-pending
+  pendingScan: string;
 }
 
 /**

packages/contentstack-bulk-operations/src/messages/index.ts

@@ -231,6 +231,10 @@ const bulkAssetsMsg = {
   SCAN_STATUS_SKIPPED_QUARANTINED: 'Skipped (quarantined): {uid}',
   SCAN_STATUS_FETCHING: 'Checking asset scan status for {count} assets...',
   NO_PUBLISHABLE_ASSETS: 'No publishable assets — all assets are either still scanning or quarantined.',
+  SCAN_RECHECK_SUMMARY:
+    'Re-checked {total} pending asset(s): {clean} now clean (will publish), {pending} still scanning, {quarantined} now quarantined (skipped permanently).',
+  NO_PENDING_SCAN_ITEMS_IN_LOG:
+    'No pending-scan assets found in {path} — nothing to retry. Assets are recorded there when a publish run skips them for a scan still in progress.',
 };
 
 /**
@@ -423,6 +427,8 @@ const flagDescriptions = {
   YES: 'Skips interactive confirmation prompts and runs the command immediately using the provided options. Useful for automation and scripts.',
   RETRY_FAILED:
     '(optional) Use this option to retry publishing the failed entries/assets from the logfile. Specify the name of the logfile that lists failed publish calls. If this option is used, it will override all other flags.',
+  RETRY_PENDING:
+    '(optional) Re-checks the malware scan status of assets a previous run skipped because scanning was still in progress, and publishes the ones that are now clean. Specify the bulk operation folder used by that run. Quarantined assets are never retried.',
 
   // Entry-specific flags
   CONTENT_TYPES: 'Content type UIDs to perform operation on. If not provided, operates on all content types.',