@scrymore/scry-deployer 0.8.0 → 0.9.0-next.20260927093344

package/README.md

@@ -217,6 +217,9 @@ The CLI is configured through a combination of command-line options and environm
 | `--capture-mode` | `SCRY_CAPTURE_MODE`                 | Screenshot framing forwarded to scry-sbcov: `root` (crop to the component) or `viewport`. | No | unset: sbcov decides (`root` from sbcov 0.6) |
 | `--capture-scale` | `SCRY_CAPTURE_SCALE`               | Screenshot device scale factor forwarded to scry-sbcov, `0 < n <= 4`. | No | unset: sbcov decides (`2` from sbcov 0.6) |
 | `--capture-viewport` | `SCRY_CAPTURE_VIEWPORT`         | Browser viewport `WIDTHxHEIGHT` forwarded to scry-sbcov.       | No | unset: sbcov decides (`1280x720`) |
+| -              | `SCRY_CONCURRENCY` (or `concurrency` in `.storybook-deployer.json`) | Stories scry-sbcov renders at once (`--concurrency`, 1-32). Forwarded only to scry-sbcov 0.7+; with an older one the log says it was not applied. | No | unset: sbcov decides (`4` from 0.7) |
+| -              | `SCRY_RENDER_TIMEOUT_MS` (or `renderTimeoutMs`) | How long a story may take to show something before it is written off (`--render-timeout`, 100-600000 ms). sbcov 0.7+ only, as above. | No | unset: sbcov decides (`5000` from 0.7) |
+| -              | `SCRY_EXECUTE_BUDGET_BASE_S`, `SCRY_EXECUTE_BUDGET_PER_STORY_S` | Story execution budget = base + per story × declared stories. Over it: a warning (`::warning::` in GitHub Actions), never a failure. See "CI time". | No | `120` and `0.5` |
 | `--verbose`    | `STORYBOOK_DEPLOYER_VERBOSE`          | Enable verbose logging for debugging purposes.                 | No       | `false`                              |
 | -              | `SCRY_NO_UPDATE_CHECK=1`              | Skip the check against npm `latest` (a one-line warning when this deployer is older; 2 s limit, never fails the deploy). | No | check on |
 | `--help`, `-h` | -                                     | Show the help message.                                       | -        | -                                    |
@@ -249,6 +252,38 @@ which does not know the flag, it is not passed and the log says dropped stories
 Before 0.7.0 the metadata-upload failure, the "not queued" case, an empty archive, a non-zero
 scry-sbcov exit and a workflow that simply forgot `--with-analysis` all ended green (ISSUES.md #50).
 
+### CI time (0.9.0)
+
+Every deploy measures how much CI time Scry took and records it with the build (ISSUES.md #54:
+a 461-story preview ran for 20 minutes and nothing said so). What you see in the log:
+
+```
+Story execution: 461 stories in 3.5 min (4 workers), budget 5.8 min.
+CI time recorded: deployer 4.4 min, job 6.1 min so far (Actions API).
+CI timings: stored with the build.
+```
+
+- **Budget.** Story execution is judged against `120 s + 0.5 s × declared stories`
+  (`SCRY_EXECUTE_BUDGET_BASE_S`, `SCRY_EXECUTE_BUDGET_PER_STORY_S`). Over it, the run gets a
+  `::warning title=Scry story execution over budget::…` annotation naming the time, the budget and
+  where the time went (`timeout 40 s, …`). It is a warning; the exit code does not change.
+- **What is recorded** on the build (`ciTimings`): `analyzeMs`, `executeMs` (from scry-sbcov;
+  `executeSource: "deployer-wall"` when an older sbcov does not report it and the whole sbcov run
+  is used instead), `archiveMs`, `uploadMs`, `deployerTotalMs`, story counts, time lost per reason,
+  sbcov and deployer versions, `runner` (`github-hosted` / `self-hosted` / `unknown`), the Actions
+  run id and attempt, `budgetMs` and `overBudget`. A number that could not be measured is left
+  out, never sent as 0.
+- **Whole-job time** needs `permissions: actions: read` and `GITHUB_TOKEN` in the deploy step (the
+  generated workflows have both). The deployer reads its own job's start time from the Actions API
+  (5 s limit). Without it the log says `CI time recorded: deployer time only (job start unknown:
+  no-token | forbidden | timeout | not-github | …)` and only the deployer's own time is recorded.
+- **Never fails a deploy.** An upload service without the CI-timings route answers 404: the log
+  says `the upload service does not record CI timings yet; not stored` once and the summary line
+  reads `CI timings: final record not stored (1)`. A record the service rejects (400) is a warning
+  with the reason. Exit codes come from indexing only (table above).
+- The generated workflows also set `timeout-minutes: 20` on the Storybook job, so a stuck run
+  stops after 20 minutes instead of GitHub's default 6 hours.
+
 ### Story File Auto-Detection
 
 The analysis feature now automatically detects `.stories.*` files anywhere in your project! You no longer need to specify a stories directory - the system intelligently searches for story files with these features:
@@ -598,6 +633,10 @@ The PR preview workflow uses these environment variables (configured via GitHub
 | `SCRY_VIEW_URL` | GitHub Variable | No | Base URL where users view Storybooks (default: `https://view.scrymore.com`) |
 | `SCRY_API_KEY` | GitHub Secret | No | API authentication key (if required) |
 | `STORYBOOK_DEPLOYER_WITH_ANALYSIS` | GitHub Variable | No | Set to `false` to disable build processing service integration (enabled by default in generated workflows) |
+| `SCRY_MAX_DROPPED` | GitHub Variable | No | Stories allowed to fail capture before the deploy ends red (default 0) |
+| `SCRY_CONCURRENCY`, `SCRY_RENDER_TIMEOUT_MS` | GitHub Variable | No | Stories rendered at once (default 4) and how long one may take to show something (default 5000 ms); scry-sbcov 0.7+ |
+| `SCRY_EXECUTE_BUDGET_BASE_S`, `SCRY_EXECUTE_BUDGET_PER_STORY_S` | GitHub Variable | No | Story execution budget (default 120 s + 0.5 s per story); over it = a warning, see "CI time" |
+| `GITHUB_TOKEN` | Actions token | No | Posts the PR comment and, with `permissions: actions: read`, lets the deployer record whole-job CI time |
 
 **Important:** `SCRY_API_URL` (where files are uploaded) and `SCRY_VIEW_URL` (where users view the deployed Storybook) are two different URLs:
 - **API URL**: Backend service endpoint (e.g., `https://api.scrymore.com`)

package/bin/cli.js

@@ -24,6 +24,7 @@ const { resolveBuildGitContext } = require('../lib/gitContext.js');
 const { countMetadataEntries, readSbcovManifest, droppedReasons } = require('../lib/metadataArchive.js');
 const { checkForNewerVersion } = require('../lib/versionCheck.js');
 const { version: DEPLOYER_VERSION } = require('../package.json');
+const ciTimings = require('../lib/ciTimings.js');
 
 async function runAnalysis(argv) {
     const logger = createLogger(argv);
@@ -130,7 +131,161 @@ function describeCapture(report) {
     return { total: typeof total === 'number' ? total : null, firstError };
 }
 
+/**
+ * The installed scry-sbcov's version, when the deployer runs its own copy.
+ * Unknown (undefined) under SCRY_SBCOV_CMD or when it cannot be resolved.
+ */
+function installedSbcovVersion() {
+    if (process.env.SCRY_SBCOV_CMD) return undefined;
+    try {
+        return require('@scrymore/scry-sbcov/package.json').version;
+    } catch (_) {
+        return undefined;
+    }
+}
+
+/**
+ * The pre-upload part of the CI timings record (storybook-preview-ci-runtime,
+ * ISSUES.md #54): phases measured so far, story counts, versions, runner, run
+ * ids and the execute budget. Anything not measured is left out, never 0.
+ */
+function buildPreUploadTimings({ coverage, manifest, archiveMs, env = process.env }) {
+    // sbcov 0.7 writes its execution block into the manifest (in the metadata
+    // archive) as `execution`, and into the report at `execution.timing`; the
+    // report is the fallback when there is no archive (execution without screenshots).
+    const fromReport = coverage.coverageReport?.execution?.timing;
+    const execution = manifest?.execution
+        || (fromReport && typeof fromReport === 'object' && !Array.isArray(fromReport) ? fromReport : null);
+    // No report = sbcov crashed or never ran: its wall time is neither an
+    // analysis nor an execute time, so neither is recorded.
+    const executedTimes = !coverage.coverageReport ? {} : ciTimings.splitSbcovTime({
+        sbcovWallMs: coverage.sbcovWallMs ?? null,
+        manifestExecution: execution,
+        report: coverage.coverageReport,
+        executed: Boolean(coverage.executed),
+    });
+    const stories = coverage.executed
+        ? ciTimings.storyCounts({ manifest, manifestExecution: execution, report: coverage.coverageReport })
+        : undefined;
+    const timeLostMs = ciTimings.timeLost(execution);
+    const share = typeof execution?.failedTimeShare === 'number' && execution.failedTimeShare >= 0 && execution.failedTimeShare <= 1
+        ? execution.failedTimeShare
+        : undefined;
+    const concurrency = Number.isInteger(execution?.concurrency) && execution.concurrency > 0 ? execution.concurrency : undefined;
+
+    let budget = null;
+    if (executedTimes.executeMs !== undefined) {
+        budget = ciTimings.resolveBudget({ declared: stories?.declared ?? null, env });
+    }
+    const overBudget = budget && budget.budgetMs !== null ? executedTimes.executeMs > budget.budgetMs : undefined;
+
+    const record = ciTimings.compact({
+        ...executedTimes,
+        archiveMs,
+        stories,
+        timeLostMs,
+        failedTimeShare: share,
+        concurrency,
+        sbcovVersion: typeof manifest?.sbcovVersion === 'string' ? manifest.sbcovVersion.slice(0, 40) : installedSbcovVersion(),
+        deployerVersion: DEPLOYER_VERSION,
+        runner: ciTimings.detectRunner(env),
+        ci: ciTimings.readCiContext(env) || undefined,
+        budgetMs: budget?.budgetMs ?? undefined,
+        overBudget,
+    });
+    return { record, budget };
+}
+
+/**
+ * The duration line, and the budget warning when story execution took longer
+ * than its budget (G6). A warning, never a failure: a slow run is information.
+ */
+function reportExecutionTime(record, budget, logger, env = process.env) {
+    if (budget) {
+        for (const w of budget.warnings) logger.warn(`⚠️  ${w}.`);
+    }
+    if (record.executeMs === undefined) return;
+    const fmt = ciTimings.formatDuration;
+    const n = record.stories?.declared;
+    const stories = typeof n === 'number' ? `${n} ${n === 1 ? 'story' : 'stories'}` : 'stories';
+    const workers = record.concurrency ? ` (${record.concurrency} ${record.concurrency === 1 ? 'worker' : 'workers'})` : '';
+    const source = record.executeSource === 'deployer-wall' ? ' [sbcov run wall time; this scry-sbcov does not report execution time]' : '';
+    const budgetText = record.budgetMs !== undefined ? `, budget ${fmt(record.budgetMs)}` : ', no budget (story count unknown)';
+    const lost = ciTimings.describeTimeLost(record.timeLostMs);
+    logger.info(`Story execution: ${stories} in ${fmt(record.executeMs)}${workers}${budgetText}${lost ? `; time lost: ${lost}` : ''}${source}.`);
+
+    if (record.overBudget) {
+        const formula = `${budget.baseS} s + ${budget.perStoryS} s × ${typeof n === 'number' ? n : '?'} stories`;
+        const detail = `Executing ${stories} took ${fmt(record.executeMs)}, over the ${fmt(record.budgetMs)} budget (${formula})` +
+            (lost ? `. Time lost: ${lost}` : '') +
+            '. Set SCRY_EXECUTE_BUDGET_BASE_S / SCRY_EXECUTE_BUDGET_PER_STORY_S to change the budget.';
+        if (env.GITHUB_ACTIONS === 'true') {
+            // A workflow command must start the line, on stdout.
+            process.stdout.write(`::warning title=Scry story execution over budget::${detail.replace(/\r?\n/g, ' ')}\n`);
+        }
+        logger.warn(`⚠️  Story execution took ${fmt(record.executeMs)}, over its ${fmt(record.budgetMs)} budget (${formula}).`);
+    }
+}
+
+/**
+ * Finish the record (upload, total, whole-job time) and send it to the
+ * ci-timings route. Never throws and never changes the exit code; every way it
+ * can fall short is said once, and counted in the summary line.
+ */
+async function recordCiTimings({ apiClient, argv, preUpload, uploadMs, totalTimer, uploadResult, logger }) {
+    const summary = { notStored: 0 };
+    try {
+        const job = await ciTimings.fetchJobElapsed();
+        const record = ciTimings.compact({
+            ...preUpload,
+            uploadMs,
+            ...job,
+            deployerTotalMs: totalTimer.stop(),
+        });
+        // The build this deploy created, from the presigned-URL response.
+        const buildId = uploadResult?.zipUpload?.buildId;
+        const sent = await ciTimings.sendCiTimings(apiClient, { project: argv.project, version: argv.version }, buildId, record);
+        if (sent.stored && sent.dropped) {
+            summary.droppedFields = sent.dropped.length;
+            logger.warn(`⚠️  CI timings: stored, but the upload service dropped ${sent.dropped.length} field(s) it would not accept: ${sent.dropped.join(', ')}.`);
+        }
+        if (!sent.stored) {
+            summary.notStored += 1;
+            if (sent.reason === 'not-supported') {
+                logger.warn('⚠️  CI timings: the upload service does not record CI timings yet; not stored.');
+            } else if (sent.reason === 'rejected') {
+                logger.warn(`⚠️  CI timings: the upload service rejected the CI timings (${sent.detail}); not stored.`);
+            } else if (sent.reason === 'build-not-found') {
+                logger.warn(`⚠️  CI timings: the upload service has the CI-timings route but did not find this build (${sent.detail}); not stored.`);
+            } else if (sent.reason === 'no-build-id') {
+                logger.warn('⚠️  CI timings: the upload service returned no build id, so the final record could not be sent; not stored.');
+            } else {
+                logger.warn(`⚠️  CI timings: could not reach the upload service (${sent.detail}); not stored.`);
+            }
+        }
+        const fmt = ciTimings.formatDuration;
+        // "recorded" only when the service kept it; otherwise it was measured and printed here.
+        const verb = sent.stored ? 'CI time recorded' : 'CI time measured (not stored)';
+        if (record.jobTimeSource === 'actions-api') {
+            logger.info(`${verb}: deployer ${fmt(record.deployerTotalMs)}, job ${fmt(record.jobElapsedMs)} so far (Actions API).`);
+        } else {
+            logger.info(`${verb}: deployer time only (job start unknown: ${record.jobTimeReason}). Deployer ${fmt(record.deployerTotalMs)}.`);
+        }
+    } catch (err) {
+        // Nothing in here may fail a deploy; say what did not happen.
+        summary.notStored += 1;
+        logger.warn(`⚠️  CI timings: not recorded (${err.message}).`);
+    }
+    logger.info(summary.notStored
+        ? `CI timings: final record not stored (${summary.notStored}); the build's time is incomplete, the deploy is not affected.`
+        : summary.droppedFields
+            ? `CI timings: stored with the build, ${summary.droppedFields} field(s) dropped by the service.`
+            : 'CI timings: stored with the build.');
+    return summary;
+}
+
 async function runDeployment(argv) {
+    const totalTimer = ciTimings.startTimer();
     const logger = createLogger(argv);
     logger.info('🚀 Starting deployment...');
     // Credentials masked: this line is also a Sentry breadcrumb.
@@ -162,6 +317,13 @@ async function runDeployment(argv) {
         let metadataToSend = metadataZipPath;
         let emptyArchive = null;
         let dropped = null;
+        let sbcovManifest = null;
+        if (coverage.executionUnsupported && coverage.executionUnsupported.length) {
+            logger.warn(
+                `⚠️  The installed scry-sbcov does not support ${coverage.executionUnsupported.join(' / ')}, so SCRY_CONCURRENCY /\n` +
+                '   SCRY_RENDER_TIMEOUT_MS were not applied. Upgrade @scrymore/scry-sbcov to 0.7 or later.'
+            );
+        }
         if (coverage.maxDroppedUnsupported) {
             logger.warn(
                 '⚠️  The installed scry-sbcov does not support --max-dropped, so stories that fail to\n' +
@@ -176,6 +338,7 @@ async function runDeployment(argv) {
             if (manifestError) {
                 logger.warn(`⚠️  ${manifestError}; dropped stories cannot be counted for this build.`);
             } else if (manifest) {
+                sbcovManifest = manifest;
                 const allowed = coverage.effectiveMaxDropped ?? 0;
                 const n = manifest.dropped.length;
                 const reasons = n ? ` (${droppedReasons(manifest.dropped)})` : '';
@@ -199,13 +362,18 @@ async function runDeployment(argv) {
 
         // 1. Archive only the static Storybook files.
         logger.info(`1/3: Zipping directory '${argv.dir}'...`);
+        const archiveTimer = ciTimings.startTimer();
         await zipDirectory(argv.dir, outPath);
+        const archiveMs = archiveTimer.stop();
         logger.success(`✅ Archive created: ${outPath}`);
         logger.debug(`Archive size: ${fs.statSync(outPath).size} bytes`);
 
         // 2. Upload Storybook ZIP + coverage + metadata ZIP (if present).
         logger.info('2/3: Uploading to deployment service...');
         const apiClient = getApiClient(argv.apiUrl, argv.apiKey);
+        // CI timings, pre-upload part: sent with the request that creates the build.
+        const { record: preUpload, budget } = buildPreUploadTimings({ coverage, manifest: sbcovManifest, archiveMs });
+        reportExecutionTime(preUpload, budget, logger);
         // Which commit this build is of. `version` is a PR number, a branch, a
         // tag or a short SHA depending on the CI event, so it identifies a
         // deploy but never a commit — without this a search result cannot say
@@ -216,6 +384,7 @@ async function runDeployment(argv) {
         } else {
             logger.debug('No git context available; build will record no commit SHA');
         }
+        const uploadTimer = ciTimings.startTimer();
         const uploadResult = await uploadBuild(
             apiClient,
             {
@@ -227,13 +396,18 @@ async function runDeployment(argv) {
                 coverageReport,
                 metadataZipPath: metadataToSend,
                 gitContext,
+                ciTimings: preUpload,
             }
         );
+        const uploadMs = uploadTimer.stop();
         logger.success('✅ Archive uploaded.');
         logger.debug(`Upload result: ${JSON.stringify(uploadResult)}`);
 
         await postPRComment(buildDeployResult(argv, coverageSummary, uploadResult), coverageSummary);
 
+        // CI timings, final record. Never fails the deploy (G7).
+        await recordCiTimings({ apiClient, argv, preUpload, uploadMs, totalTimer, uploadResult, logger });
+
         // Report only what actually completed. Uploading is synchronous;
         // indexing is not. A build can fail in the queue seconds after this
         // point — during one run the pipeline died 7s later on a revoked
@@ -618,7 +792,7 @@ async function main() {
                 const logger = createLogger(argv);
 
                 // Capture settings: CLI flag > env > .storybook-deployer.json; unset = sbcov decides.
-                const { captureMode, captureScale, captureViewport, maxDropped } = loadConfig(argv);
+                const { captureMode, captureScale, captureViewport, maxDropped, concurrency, renderTimeoutMs } = loadConfig(argv);
                 const result = await runCoverageAnalysis({
                     storybookDir: argv.dir,
                     baseBranch: argv.coverageBase || 'main',
@@ -629,9 +803,14 @@ async function main() {
                     captureMode,
                     captureScale,
                     captureViewport,
+                    concurrency,
+                    renderTimeoutMs,
                     maxDropped,
                 });
                 const report = result.report;
+                if (result.executionUnsupported && result.executionUnsupported.length) {
+                    logger.warn(`⚠️  The installed scry-sbcov does not support ${result.executionUnsupported.join(' / ')}; SCRY_CONCURRENCY / SCRY_RENDER_TIMEOUT_MS not applied.`);
+                }
 
                 if (result.sbcovFailure) {
                     logger.error(`Coverage: ${result.sbcovFailure.reason}${report ? ` (report written to ${argv.output})` : ''}`);
@@ -835,7 +1014,7 @@ async function resolveCoverage(argv, logger) {
     const enabled = argv.coverage !== false;
     if (!enabled) {
         logger.info('Coverage: disabled (--no-coverage)');
-        return { coverageReport: null, coverageSummary: null, metadataZipPath: null, sbcovFailure: null, effectiveMaxDropped: null, maxDroppedUnsupported: false };
+        return { coverageReport: null, coverageSummary: null, metadataZipPath: null, sbcovFailure: null, effectiveMaxDropped: null, maxDroppedUnsupported: false, sbcovWallMs: null, executed: false, executionUnsupported: [] };
     }
 
     try {
@@ -844,6 +1023,9 @@ async function resolveCoverage(argv, logger) {
         let sbcovFailure = null;
         let effectiveMaxDropped = null;
         let maxDroppedUnsupported = false;
+        let sbcovWallMs = null;
+        let executed = false;
+        let executionUnsupported = [];
 
         if (argv.coverageReport) {
             logger.info(`Coverage: using existing report at ${argv.coverageReport}`);
@@ -864,9 +1046,14 @@ async function resolveCoverage(argv, logger) {
                 captureMode: argv.captureMode,
                 captureScale: argv.captureScale,
                 captureViewport: argv.captureViewport,
+                concurrency: argv.concurrency,
+                renderTimeoutMs: argv.renderTimeoutMs,
                 maxDropped: argv.maxDropped,
             });
             report = result.report;
+            sbcovWallMs = result.sbcovWallMs ?? null;
+            executed = Boolean(result.executed);
+            executionUnsupported = result.executionUnsupported || [];
             metadataZipPath = result.metadataZipPath;
             sbcovFailure = result.sbcovFailure || null;
             effectiveMaxDropped = result.effectiveMaxDropped ?? null;
@@ -881,7 +1068,7 @@ async function resolveCoverage(argv, logger) {
             logger.info('Coverage: no report generated (tool failed or report shape unexpected)');
         }
 
-        return { coverageReport: report, coverageSummary: summary, metadataZipPath, sbcovFailure, effectiveMaxDropped, maxDroppedUnsupported };
+        return { coverageReport: report, coverageSummary: summary, metadataZipPath, sbcovFailure, effectiveMaxDropped, maxDroppedUnsupported, sbcovWallMs, executed, executionUnsupported };
     } catch (err) {
         logger.error(`Coverage: failed (${err.message})`);
         throw err;
@@ -939,6 +1126,9 @@ module.exports = {
     runAnalysis,
     resolveCoverage,
     resolveAnalysis,
+    buildPreUploadTimings,
+    reportExecutionTime,
+    recordCiTimings,
     reportIndexingOutcome,
     buildDeployResult,
     logUploadLinks,

package/lib/apiClient.js

@@ -129,8 +129,10 @@ function getApiClient(apiUrl, apiKey) {
  *
  * @param {axios.AxiosInstance} apiClient
  * @param {{project: string, version: string}} target
- * @param {{fileName: string, contentType: string}} file
- * @returns {Promise<{url: string, visibility?: string}>} presigned URL details
+ * @param {{fileName: string, contentType: string, ciTimings?: object}} file
+ *   `ciTimings`: the pre-upload part of the CI timings record, sent next to
+ *   contentType. An upload service older than the field ignores it.
+ * @returns {Promise<{url: string, visibility?: string, buildId?: string, buildNumber?: number}>} presigned URL details
  */
 async function requestPresignedUrl(apiClient, target, file) {
   const projectName = target.project || 'main';
@@ -140,7 +142,7 @@ async function requestPresignedUrl(apiClient, target, file) {
   
   const presignedResponse = await apiClient.post(
     `/presigned-url/${projectName}/${versionName}/${file.fileName}`,
-    { contentType: file.contentType },
+    file.ciTimings ? { contentType: file.contentType, ciTimings: file.ciTimings } : { contentType: file.contentType },
     {
       headers: {
         'Content-Type': 'application/json',
@@ -170,7 +172,12 @@ async function requestPresignedUrl(apiClient, target, file) {
   const parsedUrl = validatePresignedUrl(presignedUrl);
   logger.debug(`Validated presigned URL host: ${parsedUrl.hostname}`);
 
-  return { url: presignedUrl, visibility };
+  return {
+    url: presignedUrl,
+    visibility,
+    buildId: presignedResponse.data?.buildId,
+    buildNumber: presignedResponse.data?.buildNumber,
+  };
 }
 
 function getAxiosErrorDetails(error, fallbackUrl) {
@@ -256,7 +263,7 @@ async function putToPresignedUrl(presignedUrl, data, contentType) {
  * @param {string} payload.project The project name/identifier.
  * @param {string} payload.version The version identifier.
  * @param {string} filePath The local path to the file to upload.
- * @param {{fileName?: string, contentType?: string}} [file] Optional overrides
+ * @param {{fileName?: string, contentType?: string, ciTimings?: object}} [file] Optional overrides
  * @returns {Promise<object>} A promise that resolves to the upload result.
  */
 async function uploadFileDirectly(apiClient, { project, version }, filePath, file = {}) {
@@ -282,9 +289,16 @@ async function uploadFileDirectly(apiClient, { project, version }, filePath, fil
     // backoff must re-request it — reusing a stale one fails with a confusing
     // signature error instead of the real network cause.
     return await withUploadRetry(async () => {
-      const presigned = await requestPresignedUrl(apiClient, { project, version }, { fileName, contentType });
+      const presigned = await requestPresignedUrl(apiClient, { project, version }, { fileName, contentType, ciTimings: file.ciTimings });
       const upload = await putToPresignedUrl(presigned.url, fileBuffer, contentType);
-      return { success: true, url: presigned.url, status: upload.status, visibility: presigned.visibility };
+      return {
+        success: true,
+        url: presigned.url,
+        status: upload.status,
+        visibility: presigned.visibility,
+        buildId: presigned.buildId,
+        buildNumber: presigned.buildNumber,
+      };
     }, `Upload of ${fileName}`);
   } catch (error) {
     logger.debug(`Upload failed. Error type: ${error.constructor.name}, Message: ${error.message}`);
@@ -421,13 +435,16 @@ async function uploadMetadataZip(apiClient, target, metadataZipPath, customLogge
  *
  * @param {axios.AxiosInstance} apiClient
  * @param {{project: string, version: string}} target
- * @param {{zipPath: string, coverageReport?: any|null, metadataZipPath?: string|null, gitContext?: {commitSha?: string, branch?: string}}} options
+ * @param {{zipPath: string, coverageReport?: any|null, metadataZipPath?: string|null, gitContext?: {commitSha?: string, branch?: string}, ciTimings?: object|null}} options
+ *   `ciTimings`: the pre-upload part of the CI timings record; rides on the
+ *   storybook.zip presigned-URL request, which is what creates the build.
  */
 async function uploadBuild(apiClient, target, options) {
   logger.debug('uploadBuild orchestration started');
   const zipUpload = await uploadFileDirectly(apiClient, target, options.zipPath, {
     fileName: 'storybook.zip',
     contentType: 'application/zip',
+    ...(options.ciTimings ? { ciTimings: options.ciTimings } : {}),
   });
 
   let coverageUpload = null;

package/lib/ciTimings.js

@@ -0,0 +1,350 @@
+const axios = require('axios');
+
+/**
+ * CI timings recorded with every upload (storybook-preview-ci-runtime, ISSUES.md #54).
+ *
+ * A dashboard PR preview took 19-21 minutes and nothing measured it: no line
+ * said how long story execution took, nothing compared it with a budget, and
+ * the build document stored no time at all. The deployer now measures its own
+ * phases, judges story execution against a budget scaled to the number of
+ * stories, and sends the record to the upload service in two parts (the
+ * pre-upload part in the presigned-URL body, the final record on
+ * POST /upload/:project/:version/builds/:buildNumber/ci-timings).
+ *
+ * Rules: a number that could not be measured is left out (never 0); nothing
+ * here can fail a deploy; every "could not" is said in the log.
+ */
+
+const DEFAULT_BUDGET_BASE_S = 120;
+const DEFAULT_BUDGET_PER_STORY_S = 0.5;
+const ACTIONS_API_TIMEOUT_MS = 5000;
+const MAX_STRING = 100;
+
+/** A monotonic clock in whole milliseconds. */
+function monotonicMs() {
+  return Number(process.hrtime.bigint() / 1000000n);
+}
+
+/**
+ * Start a stopwatch. `stop()` returns whole elapsed ms from a monotonic clock.
+ * @returns {{stop: () => number}}
+ */
+function startTimer() {
+  const start = monotonicMs();
+  return { stop: () => Math.max(0, monotonicMs() - start) };
+}
+
+/**
+ * Which kind of runner this is, from GitHub's RUNNER_ENVIRONMENT.
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {'github-hosted'|'self-hosted'|'unknown'}
+ */
+function detectRunner(env = process.env) {
+  const v = String(env.RUNNER_ENVIRONMENT || '').trim().toLowerCase();
+  if (v === 'github-hosted') return 'github-hosted';
+  if (v === 'self-hosted') return 'self-hosted';
+  return 'unknown';
+}
+
+function shortString(v) {
+  if (typeof v !== 'string') return undefined;
+  const t = v.trim();
+  return t ? t.slice(0, MAX_STRING) : undefined;
+}
+
+/**
+ * A workflow or job name in the character set the upload service accepts
+ * (`[\w .:@+/()-]`). The service rejects a whole record over one bad string,
+ * so "Build & Deploy" or "CI, preview" would lose every timing on every run;
+ * other characters become "-".
+ */
+function safeLabel(v) {
+  const t = shortString(v);
+  if (!t) return undefined;
+  const clean = t.replace(/[^\w .:@+/()-]/g, '-').replace(/-{2,}/g, '-').trim();
+  return clean && /[\w]/.test(clean) ? clean : undefined;
+}
+
+function positiveInt(v) {
+  const n = Number(v);
+  return Number.isInteger(n) && n > 0 ? n : undefined;
+}
+
+/**
+ * The GitHub Actions run this deploy is part of, or null outside Actions.
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {null|{provider:'github', runId?:string, runAttempt?:number, workflow?:string, job?:string}}
+ */
+function readCiContext(env = process.env) {
+  if (env.GITHUB_ACTIONS !== 'true' && !env.GITHUB_RUN_ID) return null;
+  const ci = { provider: 'github' };
+  const runId = /^\d{1,20}$/.test(String(env.GITHUB_RUN_ID || '')) ? String(env.GITHUB_RUN_ID) : undefined;
+  if (runId) ci.runId = runId;
+  const attempt = positiveInt(env.GITHUB_RUN_ATTEMPT);
+  if (attempt) ci.runAttempt = attempt;
+  const workflow = safeLabel(env.GITHUB_WORKFLOW);
+  if (workflow) ci.workflow = workflow;
+  const job = safeLabel(env.GITHUB_JOB);
+  if (job) ci.job = job;
+  return ci;
+}
+
+/**
+ * Read a budget setting from the environment. Unset = the default; set but not
+ * a number >= 0 = the default plus a warning (a typo must not silently change
+ * the budget).
+ */
+function readBudgetSetting(env, name, dflt, warnings) {
+  const raw = env[name];
+  if (raw === undefined || raw === null || String(raw).trim() === '') return dflt;
+  const text = String(raw).trim();
+  const n = Number(text);
+  if (!/^\d+(\.\d+)?$/.test(text) || !Number.isFinite(n) || n < 0) {
+    warnings.push(`${name}=${JSON.stringify(text.slice(0, 20))} is not a number of seconds >= 0; using ${dflt}`);
+    return dflt;
+  }
+  return n;
+}
+
+/**
+ * The execute budget: SCRY_EXECUTE_BUDGET_BASE_S (120) + SCRY_EXECUTE_BUDGET_PER_STORY_S (0.5) × declared stories.
+ * `budgetMs` is null when the number of stories is unknown.
+ *
+ * @param {{declared:number|null|undefined, env?:NodeJS.ProcessEnv}} opts
+ * @returns {{budgetMs:number|null, baseS:number, perStoryS:number, warnings:string[]}}
+ */
+function resolveBudget({ declared, env = process.env }) {
+  const warnings = [];
+  const baseS = readBudgetSetting(env, 'SCRY_EXECUTE_BUDGET_BASE_S', DEFAULT_BUDGET_BASE_S, warnings);
+  const perStoryS = readBudgetSetting(env, 'SCRY_EXECUTE_BUDGET_PER_STORY_S', DEFAULT_BUDGET_PER_STORY_S, warnings);
+  const n = typeof declared === 'number' && Number.isFinite(declared) && declared >= 0 ? declared : null;
+  const budgetMs = n === null ? null : Math.round((baseS + perStoryS * n) * 1000);
+  return { budgetMs, baseS, perStoryS, warnings };
+}
+
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : undefined);
+
+/**
+ * How long story execution took, and from where.
+ *
+ * sbcov 0.7+ writes `execution.durationMs` into its manifest; older sbcov puts
+ * the executor's own duration in the report (`execution.summary.duration`).
+ * Both are sbcov's measurement. Without either, the whole sbcov run (analysis
+ * and execution together) is the only number, and it is labelled as such; the
+ * analysis part then cannot be separated and is left out.
+ *
+ * @param {{sbcovWallMs:number|null, manifestExecution?:any, report?:any, executed:boolean}} o
+ * @returns {{analyzeMs?:number, executeMs?:number, executeSource?:'sbcov'|'deployer-wall'}}
+ */
+function splitSbcovTime({ sbcovWallMs, manifestExecution, report, executed }) {
+  const wall = num(sbcovWallMs);
+  if (wall === undefined) return {};
+  if (!executed) return { analyzeMs: wall };
+  const fromSbcov = num(manifestExecution?.durationMs) ?? num(report?.execution?.summary?.duration);
+  if (fromSbcov !== undefined && fromSbcov <= wall) {
+    return { analyzeMs: wall - fromSbcov, executeMs: fromSbcov, executeSource: 'sbcov' };
+  }
+  return { executeMs: wall, executeSource: 'deployer-wall' };
+}
+
+/**
+ * Story counts for the record, from sbcov's manifest `execution` block (0.7+),
+ * else from what an older manifest and report hold. Unknown counts are left out.
+ *
+ * @param {{manifest?:any, manifestExecution?:any, report?:any}} o
+ * @returns {{declared?:number, passed?:number, failed?:number, timeouts?:number, notIndexed?:number}|undefined}
+ */
+function storyCounts({ manifest, manifestExecution, report }) {
+  const e = manifestExecution || {};
+  const s = report?.execution?.summary || {};
+  const dropped = Array.isArray(manifest?.dropped) ? manifest.dropped : null;
+  const out = {};
+  const set = (k, v) => { const n = num(v); if (n !== undefined) out[k] = Math.round(n); };
+  set('declared', e.declared ?? manifest?.declared ?? s.declared ?? s.total);
+  set('passed', e.passed ?? s.passed);
+  set('failed', e.failed ?? s.failed);
+  set('timeouts', e.timeouts ?? (dropped ? dropped.filter((d) => /timeout/.test(String(d?.reason || ''))).length : undefined));
+  set('notIndexed', e.notIndexed ?? (dropped ? dropped.length : s.notIndexed));
+  return Object.keys(out).length ? out : undefined;
+}
+
+/**
+ * sbcov's time lost per reason. `{}` when every story passed; undefined when
+ * the sbcov is too old to say (never a made-up zero).
+ */
+function timeLost(manifestExecution) {
+  const t = manifestExecution?.timeLostMs;
+  if (!t || typeof t !== 'object' || Array.isArray(t)) return undefined;
+  const out = {};
+  for (const [k, v] of Object.entries(t)) {
+    const key = String(k).slice(0, 40);
+    const n = num(v);
+    if (n !== undefined) out[key] = Math.round(n);
+  }
+  return out;
+}
+
+/** "212 s", "5.8 min" */
+function formatDuration(ms) {
+  if (typeof ms !== 'number' || !Number.isFinite(ms)) return '?';
+  if (ms < 1000) return `${ms} ms`;
+  const s = ms / 1000;
+  if (s < 120) return `${s < 10 ? s.toFixed(1) : Math.round(s)} s`;
+  return `${(s / 60).toFixed(1)} min`;
+}
+
+/** "timeout 40 s, console_error 3 s" (largest first) */
+function describeTimeLost(t) {
+  if (!t) return '';
+  return Object.entries(t)
+    .filter(([, v]) => v > 0)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 3)
+    .map(([k, v]) => `${k} ${formatDuration(v)}`)
+    .join(', ');
+}
+
+/**
+ * Whole-job elapsed time from the GitHub Actions API: this job's started_at.
+ *
+ * GitHub exposes no job start time in the environment, so the deployer asks
+ * GET /repos/{repo}/actions/runs/{run}/attempts/{n}/jobs (needs GITHUB_TOKEN
+ * with `actions: read`), bounded to 5 s. The job is the in-progress one on
+ * this runner (RUNNER_NAME), else the one named GITHUB_JOB. Any failure gives
+ * `jobTimeSource: "deployer-only"` and the reason; never throws.
+ *
+ * @param {{env?:NodeJS.ProcessEnv, timeoutMs?:number, now?:() => number, http?:{get:Function}}} [o]
+ * @returns {Promise<{jobElapsedMs?:number, jobTimeSource:'actions-api'|'deployer-only', jobTimeReason?:string}>}
+ */
+async function fetchJobElapsed({ env = process.env, timeoutMs = ACTIONS_API_TIMEOUT_MS, now = Date.now, http = axios } = {}) {
+  const only = (reason) => ({ jobTimeSource: 'deployer-only', jobTimeReason: reason });
+  if (env.GITHUB_ACTIONS !== 'true') return only('not-github');
+  const repo = String(env.GITHUB_REPOSITORY || '');
+  const runId = String(env.GITHUB_RUN_ID || '');
+  const attempt = positiveInt(env.GITHUB_RUN_ATTEMPT) || 1;
+  if (!/^[\w.-]+\/[\w.-]+$/.test(repo) || !/^\d+$/.test(runId)) return only('no-run-id');
+  const token = env.GITHUB_TOKEN || env.GH_TOKEN;
+  if (!token) return only('no-token');
+
+  const base = String(env.GITHUB_API_URL || 'https://api.github.com').replace(/\/$/, '');
+  const url = `${base}/repos/${repo}/actions/runs/${runId}/attempts/${attempt}/jobs?per_page=100`;
+  let data;
+  try {
+    const res = await http.get(url, {
+      timeout: timeoutMs,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.github+json',
+        'X-GitHub-Api-Version': '2022-11-28',
+      },
+      // Never follow a redirect with the token to another host.
+      maxRedirects: 0,
+    });
+    data = res.data;
+  } catch (error) {
+    const status = error?.response?.status;
+    if (status === 401 || status === 403) return only('forbidden');
+    if (status === 404) return only('not-found');
+    if (typeof status === 'number') return only(`http-${status}`);
+    if (error?.code === 'ECONNABORTED' || error?.code === 'ETIMEDOUT' || /timeout/i.test(String(error?.message))) return only('timeout');
+    return only('network-error');
+  }
+
+  const jobs = Array.isArray(data?.jobs) ? data.jobs : [];
+  const running = jobs.filter((j) => j && j.status === 'in_progress');
+  let job = null;
+  if (env.RUNNER_NAME) job = running.find((j) => j.runner_name === env.RUNNER_NAME) || null;
+  if (!job && env.GITHUB_JOB) {
+    const named = running.filter((j) => j.name === env.GITHUB_JOB);
+    if (named.length === 1) job = named[0];
+  }
+  if (!job && running.length === 1) job = running[0];
+  if (!job) return only('job-not-found');
+
+  const started = Date.parse(job.started_at);
+  if (!Number.isFinite(started)) return only('job-not-found');
+  const elapsed = now() - started;
+  if (!(elapsed >= 0 && elapsed < 24 * 3600 * 1000)) return only('clock-skew');
+  return { jobElapsedMs: Math.round(elapsed), jobTimeSource: 'actions-api' };
+}
+
+/**
+ * Send the final record to POST /upload/:project/:version/builds/:buildId/ci-timings.
+ * Keyed by the build id the presigned-URL response returned (a build number
+ * could name a newer build of the same version by the time this is sent).
+ * Never throws: an upload service without the route (404), one that has the
+ * route but not the build (404 "Build not found"), one that rejects the record
+ * (400) or one that cannot be reached is reported, and the deploy result does
+ * not change.
+ *
+ * @param {import('axios').AxiosInstance} apiClient
+ * @param {{project?:string, version?:string}} target
+ * @param {string|null|undefined} buildId
+ * @param {object} record
+ * @returns {Promise<{stored:true, dropped?:string[]}|{stored:false, reason:'no-build-id'|'not-supported'|'build-not-found'|'rejected'|'error', detail?:string}>}
+ */
+async function sendCiTimings(apiClient, target, buildId, record) {
+  if (typeof buildId !== 'string' || !/^[\w-]{1,128}$/.test(buildId)) {
+    return { stored: false, reason: 'no-build-id' };
+  }
+  const project = encodeURIComponent(target.project || 'main');
+  const version = encodeURIComponent(target.version || 'latest');
+  try {
+    const res = await apiClient.post(
+      `/upload/${project}/${version}/builds/${encodeURIComponent(buildId)}/ci-timings`,
+      { ciTimings: record },
+      { headers: { 'Content-Type': 'application/json' }, timeout: 15000 },
+    );
+    // The service drops a bad field and keeps the rest; it names what it dropped.
+    const dropped = Array.isArray(res?.data?.dropped)
+      ? res.data.dropped.map((d) => String(typeof d === 'string' ? d : d?.path || d?.field || JSON.stringify(d)).slice(0, 60)).slice(0, 20)
+      : [];
+    return dropped.length ? { stored: true, dropped } : { stored: true };
+  } catch (error) {
+    const status = error?.response?.status;
+    if (status === 404) {
+      // The route exists but has no such build, or the service predates the route.
+      const body = error.response.data;
+      const text = typeof body === 'string' ? body : String(body?.error || '');
+      if (/build not found/i.test(text)) return { stored: false, reason: 'build-not-found', detail: text.slice(0, 200) };
+      return { stored: false, reason: 'not-supported' };
+    }
+    if (status === 400) {
+      const body = error.response.data || {};
+      const issues = Array.isArray(body.issues) ? body.issues.map((i) => (typeof i === 'string' ? i : (i?.path || []).join?.('.') || JSON.stringify(i))).join(', ') : '';
+      return { stored: false, reason: 'rejected', detail: (issues || body.error || 'HTTP 400').slice(0, 200) };
+    }
+    return { stored: false, reason: 'error', detail: status ? `HTTP ${status}` : (error?.code || error?.message || 'unknown error') };
+  }
+}
+
+/**
+ * Drop undefined members so an unmeasured value is absent, not null or 0.
+ * @template T
+ * @param {T} obj
+ * @returns {T}
+ */
+function compact(obj) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) if (v !== undefined && v !== null) out[k] = v;
+  return /** @type {T} */ (out);
+}
+
+module.exports = {
+  DEFAULT_BUDGET_BASE_S,
+  DEFAULT_BUDGET_PER_STORY_S,
+  ACTIONS_API_TIMEOUT_MS,
+  startTimer,
+  detectRunner,
+  readCiContext,
+  resolveBudget,
+  splitSbcovTime,
+  storyCounts,
+  timeLost,
+  formatDuration,
+  describeTimeLost,
+  fetchJobElapsed,
+  sendCiTimings,
+  compact,
+  safeLabel,
+};

package/lib/config.js

@@ -127,7 +127,10 @@ function loadEnvConfig() {
     'CAPTURE_SCALE': 'captureScale',
     'CAPTURE_VIEWPORT': 'captureViewport',
     // Forwarded to scry-sbcov as --max-dropped
-    'MAX_DROPPED': 'maxDropped'
+    'MAX_DROPPED': 'maxDropped',
+    // Forwarded to scry-sbcov 0.7+ as --concurrency / --render-timeout (unset = sbcov decides)
+    'CONCURRENCY': 'concurrency',
+    'RENDER_TIMEOUT_MS': 'renderTimeoutMs'
   };
 
   Object.keys(envMapping).forEach(envKey => {

package/lib/coverage.js

@@ -2,6 +2,7 @@ const { execSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 const chalk = require('chalk');
+const { startTimer } = require('./ciTimings.js');
 
 /**
  * @typedef {Object} RunCoverageOptions
@@ -15,6 +16,8 @@ const chalk = require('chalk');
  * @property {'root'|'viewport'} [captureMode] Screenshot framing forwarded as --capture-mode
  * @property {number|string} [captureScale] Device scale factor (0 < n <= 4) forwarded as --capture-scale
  * @property {string|{width:number,height:number}} [captureViewport] "WxH" or {width,height}, forwarded as --capture-viewport
+ * @property {number|string} [concurrency] Stories rendered at once, forwarded as --concurrency (sbcov 0.7+; unset: sbcov default 4)
+ * @property {number|string} [renderTimeoutMs] How long a story may take to show something, forwarded as --render-timeout (sbcov 0.7+; unset: sbcov default 5000)
  * @property {number|string} [maxDropped] Forwarded as --max-dropped: sbcov exits 3 when more stories than this were dropped.
  *   Unset: with screenshots on, the deployer passes --max-dropped 0 (any dropped story ends the
  *   deploy red, after the rest are uploaded) when the installed scry-sbcov supports the flag.
@@ -127,6 +130,8 @@ async function runCoverageAnalysis(options) {
     captureMode,
     captureScale,
     captureViewport,
+    concurrency,
+    renderTimeoutMs,
     maxDropped,
   } = options || {};
 
@@ -139,6 +144,7 @@ async function runCoverageAnalysis(options) {
   const captureArgs = buildCaptureArgs({ captureMode, captureScale, captureViewport });
   // Validated up front; the default (0) is decided below, once the command is known.
   const userMaxDroppedArgs = buildMaxDroppedArgs(maxDropped);
+  const executionArgs = buildExecutionArgs({ concurrency, renderTimeoutMs });
 
   console.log(chalk.blue('Running Storybook coverage analysis...'));
 
@@ -218,6 +224,20 @@ async function runCoverageAnalysis(options) {
     }
   }
 
+  // --concurrency / --render-timeout (sbcov 0.7+), forwarded only to an sbcov
+  // that lists them: an older one rejects an unknown option and captures
+  // nothing. What could not be applied is returned for the caller to say.
+  /** @type {string[]} */
+  const executionUnsupported = [];
+  // Without execution the settings have nothing to act on.
+  for (let i = 0; (execute || screenshots) && i < executionArgs.length; i += 2) {
+    if (sbcovSupportsFlag(sbcovCommandPrefix, executionArgs[i])) {
+      cliArgs.push(executionArgs[i], executionArgs[i + 1]);
+    } else {
+      executionUnsupported.push(executionArgs[i]);
+    }
+  }
+
   const npxCommand = `${sbcovCommandPrefix} ${cliArgs.map(shellEscape).join(' ')}`;
 
   // Debug logging to show the exact command being executed
@@ -227,6 +247,16 @@ async function runCoverageAnalysis(options) {
   console.log(chalk.yellow('Working directory: ' + process.cwd()));
   console.log(chalk.yellow('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'));
 
+  // Wall time of the sbcov process (analysis + execution), from a monotonic
+  // clock; null when it never started. Used for the CI timings record.
+  let sbcovStarted = null;
+  let sbcovWallMs = null;
+  // `executed`: stories were asked to run AND sbcov produced a report (exit 0
+  // or 3). A crashed or missing sbcov ran no stories, so its wall time is not
+  // an execute time (review should-fix 2).
+  let producedReport = false;
+  const extras = () => ({ sbcovWallMs, executionUnsupported, executed: Boolean((execute || screenshots) && producedReport) });
+
   try {
     // Determine the correct working directory
     // If storybookDir is relative, resolve it from cwd
@@ -240,17 +270,21 @@ async function runCoverageAnalysis(options) {
     console.log(chalk.yellow('Project root: ' + projectRoot));
     console.log(chalk.yellow('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'));
 
+    sbcovStarted = startTimer();
     execSync(npxCommand, {
       stdio: 'inherit',
       cwd: projectRoot // Run from the project root, not scry-node directory
     });
+    sbcovWallMs = sbcovStarted.stop();
 
     const report = JSON.parse(fs.readFileSync(outputPath, 'utf-8'));
+    producedReport = true;
     const metadataZipPath = existingZip(screenshots, outputZipPath);
 
     if (!keepReport && !providedOutputPath) safeUnlink(outputPath);
-    return { report, metadataZipPath, sbcovFailure: null, effectiveMaxDropped, maxDroppedUnsupported };
+    return { report, metadataZipPath, sbcovFailure: null, effectiveMaxDropped, maxDroppedUnsupported, ...extras() };
   } catch (error) {
+    if (sbcovStarted !== null && sbcovWallMs === null) sbcovWallMs = sbcovStarted.stop();
     const exitCode = typeof error.status === 'number' ? error.status : null;
     const signal = error.signal || null;
     // A throw with no exit status is not sbcov's verdict: the command never
@@ -263,6 +297,7 @@ async function runCoverageAnalysis(options) {
     // keep both so they can still be uploaded and indexed. Any other failure
     // promises no complete archive, so a leftover one is removed, never sent.
     const report = readReportIfPresent(outputPath);
+    producedReport = report !== null;
     let metadataZipPath = null;
     if (exitCode === 3) {
       metadataZipPath = existingZip(screenshots, outputZipPath);
@@ -280,6 +315,7 @@ async function runCoverageAnalysis(options) {
       sbcovFailure: { exitCode, signal, reason },
       effectiveMaxDropped,
       maxDroppedUnsupported,
+      ...extras(),
     };
   }
 }
@@ -299,32 +335,52 @@ function readReportIfPresent(outputPath) {
   }
 }
 
-const maxDroppedSupport = new Map();
+const sbcovHelp = new Map();
 
 /**
- * Whether this scry-sbcov command knows --max-dropped (0.5.2+), from its --help.
- * Cached per command for the life of the process. Any failure to ask = no.
+ * This scry-sbcov command's --help text, cached per command for the life of
+ * the process. Any failure to ask = '' (no optional flag is judged supported).
  *
  * @param {string} commandPrefix
- * @returns {boolean}
+ * @returns {string}
  */
-function sbcovSupportsMaxDropped(commandPrefix) {
-  if (maxDroppedSupport.has(commandPrefix)) return maxDroppedSupport.get(commandPrefix);
-  let supported = false;
+function sbcovHelpText(commandPrefix) {
+  if (sbcovHelp.has(commandPrefix)) return sbcovHelp.get(commandPrefix);
+  let out = '';
   try {
-    const out = execSync(`${commandPrefix} --help`, {
+    out = execSync(`${commandPrefix} --help`, {
       encoding: 'utf-8',
       stdio: ['ignore', 'pipe', 'pipe'],
       timeout: 30000,
     });
-    supported = /--max-dropped\b/.test(out);
   } catch (_) {
-    // An sbcov whose --help fails is judged unable to take the flag; the
-    // caller prints that dropped stories cannot be checked.
-    supported = false;
+    // An sbcov whose --help fails is judged unable to take optional flags;
+    // the caller prints what could not be applied.
+    out = '';
   }
-  maxDroppedSupport.set(commandPrefix, supported);
-  return supported;
+  sbcovHelp.set(commandPrefix, out);
+  return out;
+}
+
+/**
+ * Whether this scry-sbcov command knows --max-dropped (0.5.2+), from its --help.
+ *
+ * @param {string} commandPrefix
+ * @returns {boolean}
+ */
+function sbcovSupportsMaxDropped(commandPrefix) {
+  return /--max-dropped\b/.test(sbcovHelpText(commandPrefix));
+}
+
+/**
+ * Whether this scry-sbcov command knows a flag, from its --help.
+ *
+ * @param {string} commandPrefix
+ * @param {string} flag e.g. '--concurrency'
+ * @returns {boolean}
+ */
+function sbcovSupportsFlag(commandPrefix, flag) {
+  return new RegExp(`${flag.replace(/[-]/g, '\\-')}\\b`).test(sbcovHelpText(commandPrefix));
 }
 
 /**
@@ -342,6 +398,37 @@ function buildMaxDroppedArgs(maxDropped) {
   return ['--max-dropped', String(Number(text))];
 }
 
+/**
+ * --concurrency / --render-timeout for scry-sbcov 0.7+ (storybook-preview-ci-runtime).
+ * Only settings that were set are returned; each is validated to a bounded
+ * whole number before it gets near a shell command, and anything else throws.
+ *
+ * @param {{concurrency?:any, renderTimeoutMs?:any}} [settings]
+ * @returns {string[]}
+ */
+function buildExecutionArgs(settings = {}) {
+  const { concurrency, renderTimeoutMs } = settings || {};
+  const isSet = (v) => v !== undefined && v !== null && v !== '';
+  const args = [];
+  if (isSet(concurrency)) {
+    const text = String(concurrency).trim();
+    const n = Number(text);
+    if (!/^\d{1,2}$/.test(text) || n < 1 || n > 32) {
+      throw new Error(`Invalid concurrency ${JSON.stringify(concurrency)} (SCRY_CONCURRENCY): expected a whole number of stories from 1 to 32`);
+    }
+    args.push('--concurrency', String(n));
+  }
+  if (isSet(renderTimeoutMs)) {
+    const text = String(renderTimeoutMs).trim();
+    const n = Number(text);
+    if (!/^\d{1,6}$/.test(text) || n < 100 || n > 600000) {
+      throw new Error(`Invalid renderTimeoutMs ${JSON.stringify(renderTimeoutMs)} (SCRY_RENDER_TIMEOUT_MS): expected whole milliseconds from 100 to 600000`);
+    }
+    args.push('--render-timeout', String(n));
+  }
+  return args;
+}
+
 /**
  * Load a coverage report from disk.
  *
@@ -512,8 +599,10 @@ module.exports = {
   runCoverageAnalysis,
   buildCaptureArgs,
   buildMaxDroppedArgs,
+  buildExecutionArgs,
   describeSbcovExit,
   sbcovSupportsMaxDropped,
+  sbcovSupportsFlag,
   loadCoverageReport,
   extractCoverageSummary,
   normalizeGitBaseRef,

package/lib/metadataArchive.js

@@ -43,13 +43,14 @@ function countMetadataEntries(zipPath) {
 
 /**
  * Read scry-sbcov's `sbcov-manifest.json` from an analysis archive (0.5.2+):
- * `{declared, captured, dropped:[{storyId, storyTitle, reason}], capture, sbcovVersion}`.
+ * `{declared, captured, dropped:[{storyId, storyTitle, reason}], capture, sbcovVersion}`,
+ * plus `execution` (timings and counts) from 0.7.
  *
  * Never throws. `manifest: null` with no error = an older sbcov that writes no
  * manifest; with an error = present but unreadable, which the caller surfaces.
  *
  * @param {string} zipPath
- * @returns {{manifest: null|{declared:number|null, captured:number|null, dropped:Array<{storyId?:string, storyTitle?:string, reason?:string}>, sbcovVersion?:string}, error: string|null}}
+ * @returns {{manifest: null|{declared:number|null, captured:number|null, dropped:Array<{storyId?:string, storyTitle?:string, reason?:string}>, sbcovVersion?:string, execution:object|null}, error: string|null}}
  */
 function readSbcovManifest(zipPath) {
   try {
@@ -60,8 +61,11 @@ function readSbcovManifest(zipPath) {
       return { manifest: null, error: 'sbcov-manifest.json has no dropped list' };
     }
     const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+    // sbcov 0.7+ adds an `execution` timing block (storybook-preview-ci-runtime);
+    // older manifests have none and it stays null, never a made-up zero.
+    const execution = m.execution && typeof m.execution === 'object' && !Array.isArray(m.execution) ? m.execution : null;
     return {
-      manifest: { declared: num(m.declared), captured: num(m.captured), dropped: m.dropped, sbcovVersion: m.sbcovVersion },
+      manifest: { declared: num(m.declared), captured: num(m.captured), dropped: m.dropped, sbcovVersion: m.sbcovVersion, execution },
       error: null,
     };
   } catch (err) {

package/lib/templates.js

@@ -63,9 +63,10 @@ function getCacheValue(packageManager) {
  * the "nothing will be indexed" guards (0.7.0), never a surprise major. The
  * repo's own package.json cannot lower it, because the deployer is installed
  * into its own folder (ISSUES.md #50: a repo pinned to 0.2.2 ran it for seven
- * weeks through a bare `npx @scrymore/scry-deployer`).
+ * weeks through a bare `npx @scrymore/scry-deployer`). 0.9.0: CI timings and
+ * the execute budget warning (ISSUES.md #54).
  */
-const DEPLOYER_RANGE = '^0.7.0';
+const DEPLOYER_RANGE = '^0.9.0';
 
 /**
  * Where the deployer is installed on the runner: outside the checkout, so
@@ -120,6 +121,17 @@ function getDeployerSetupSteps() {
 `;
 }
 
+/**
+ * Job limits shared by both workflows (ISSUES.md #54).
+ *
+ * timeout-minutes: a Storybook run once took 21 minutes and nothing bounded it;
+ * GitHub's default is 6 hours. 20 still lets today's slowest run finish.
+ * permissions: actions: read lets the deployer read its own job's start time
+ * from the Actions API (whole-job CI time). A permissions block drops every
+ * scope it does not list, so contents: read (checkout) is listed too.
+ */
+const JOB_TIMEOUT_MINUTES = 20;
+
 /** Deployer flags shared by both workflows. */
 const COMMON_FLAGS = `            \${{ vars.SCRY_COVERAGE_ENABLED == 'false' && '--no-coverage' || '' }} \\
             \${{ vars.SCRY_COVERAGE_FAIL_ON_THRESHOLD == 'true' && '--coverage-fail-on-threshold' || '' }} \\
@@ -148,6 +160,14 @@ on:
 jobs:
   deploy:
     runs-on: ubuntu-latest
+    timeout-minutes: ${JOB_TIMEOUT_MINUTES}
+
+    permissions:
+      contents: read
+      actions: read
+      # Listed because a permissions block drops every scope it does not name
+      # (GitHub Packages installs need it).
+      packages: read
 
     steps:
       - name: Checkout code
@@ -181,6 +201,13 @@ ${COMMON_FLAGS}
           STORYBOOK_DEPLOYER_API_KEY: \${{ secrets.SCRY_API_KEY }}
           # Optional: stories allowed to fail capture before the deploy ends red (default 0).
           SCRY_MAX_DROPPED: \${{ vars.SCRY_MAX_DROPPED }}
+          # Optional: stories rendered at once (default 4) and how long one may take to show something (ms, default 5000).
+          SCRY_CONCURRENCY: \${{ vars.SCRY_CONCURRENCY }}
+          SCRY_RENDER_TIMEOUT_MS: \${{ vars.SCRY_RENDER_TIMEOUT_MS }}
+          # Optional: story execution budget = base + per story × stories (default 120 s + 0.5 s); over it = a warning.
+          SCRY_EXECUTE_BUDGET_BASE_S: \${{ vars.SCRY_EXECUTE_BUDGET_BASE_S }}
+          SCRY_EXECUTE_BUDGET_PER_STORY_S: \${{ vars.SCRY_EXECUTE_BUDGET_PER_STORY_S }}
+          # Also lets the deployer read this job's start time (needs actions: read above).
           GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
 `;
 }
@@ -214,10 +241,12 @@ jobs:
     # Drafts are skipped; marking the PR ready for review deploys it.
     if: github.event.pull_request.draft == false
     runs-on: ubuntu-latest
+    timeout-minutes: ${JOB_TIMEOUT_MINUTES}
 
     permissions:
       contents: read
       pull-requests: write
+      actions: read
 
     steps:
       - name: Checkout code
@@ -260,6 +289,13 @@ ${COMMON_FLAGS}
           STORYBOOK_DEPLOYER_API_KEY: \${{ secrets.SCRY_API_KEY }}
           # Optional: stories allowed to fail capture before the deploy ends red (default 0).
           SCRY_MAX_DROPPED: \${{ vars.SCRY_MAX_DROPPED }}
+          # Optional: stories rendered at once (default 4) and how long one may take to show something (ms, default 5000).
+          SCRY_CONCURRENCY: \${{ vars.SCRY_CONCURRENCY }}
+          SCRY_RENDER_TIMEOUT_MS: \${{ vars.SCRY_RENDER_TIMEOUT_MS }}
+          # Optional: story execution budget = base + per story × stories (default 120 s + 0.5 s); over it = a warning.
+          SCRY_EXECUTE_BUDGET_BASE_S: \${{ vars.SCRY_EXECUTE_BUDGET_BASE_S }}
+          SCRY_EXECUTE_BUDGET_PER_STORY_S: \${{ vars.SCRY_EXECUTE_BUDGET_PER_STORY_S }}
+          # Also lets the deployer read this job's start time (needs actions: read above).
           GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
 `;
 }
@@ -268,4 +304,5 @@ module.exports = {
     generateMainWorkflow,
     generatePRWorkflow,
     DEPLOYER_RANGE,
+    JOB_TIMEOUT_MINUTES,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scrymore/scry-deployer",
-  "version": "0.8.0",
+  "version": "0.9.0-next.20260927093344",
   "description": "A CLI to automate the deployment of Storybook static builds.",
   "main": "index.js",
   "bin": {
@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "@octokit/rest": "^20.0.0",
-    "@scrymore/scry-sbcov": "^0.6.0",
+    "@scrymore/scry-sbcov": "^0.7.0",
     "@sentry/node": "^10.33.0",
     "archiver": "^7.0.1",
     "axios": "^1.12.2",