@scrymore/scry-deployer 0.0.6 → 0.1.1

package/README.md

@@ -217,6 +217,28 @@ The configuration is resolved in the following order of precedence:
 3.  **Configuration File**: Values from `.storybook-deployer.json` in your project directory (automatically created during installation).
 4.  **Programmatic Defaults**: Lowest precedence (e.g., for `--api-url`).
 
+## Private Projects
+
+If your project is set to **private** in the Scry dashboard, uploaded Storybook
+and coverage reports will only be accessible to logged-in project members.
+
+### How it works
+
+1. Upload works the same way (using your API key)
+2. The generated links work for anyone who is:
+   - Logged into the Scry dashboard
+   - A member of your project
+
+### Sharing with team members
+
+To give someone access to a private project:
+
+1. Go to your project in the [Scry Dashboard](https://dashboard.scrymore.com)
+2. Navigate to **Settings** → **Members**
+3. Add their email address
+
+They'll need to log in once, then all project links will work automatically.
+
 ### Configuration File
 
 The configuration file (`.storybook-deployer.json`) is automatically created in your project directory when you install the package. You can edit this file to set default values for common options:

package/bin/cli.js

@@ -17,6 +17,7 @@ const { analyzeStorybook } = require('../lib/analysis.js');
 const { runCoverageAnalysis, loadCoverageReport, extractCoverageSummary } = require('../lib/coverage.js');
 const { postPRComment } = require('../lib/pr-comment.js');
 const { runInit } = require('../lib/init.js');
+const { runUpdateWorkflows } = require('../lib/update-workflows.js');
 
 async function runAnalysis(argv) {
     const logger = createLogger(argv);
@@ -84,88 +85,46 @@ async function runDeployment(argv) {
     logger.debug(`Received arguments: ${JSON.stringify(argv)}`);
 
     const outPath = path.join(os.tmpdir(), `storybook-deployment-${Date.now()}.zip`);
+    let metadataZipPath = null;
 
     try {
-        const { coverageReport, coverageSummary } = await resolveCoverage(argv, logger);
+        const coverage = await resolveCoverage(argv, logger);
+        const coverageReport = coverage.coverageReport;
+        const coverageSummary = coverage.coverageSummary;
+        metadataZipPath = coverage.metadataZipPath;
 
         if (argv.withAnalysis) {
-            // Full deployment with analysis
             logger.info('Running deployment with analysis...');
+        }
 
-            // 1. Capture screenshots if storybook URL provided
-            if (argv.storybookUrl) {
-                logger.info(`1/5: Capturing screenshots from '${argv.storybookUrl}'...`);
-                await captureScreenshots(argv.storybookUrl, argv.storycapOptions || {});
-                logger.success('✅ Screenshots captured');
-            } else {
-                logger.info('1/5: Skipping screenshot capture (no Storybook URL provided)');
-            }
+        // 1. Archive only the static Storybook files.
+        logger.info(`1/3: Zipping directory '${argv.dir}'...`);
+        await zipDirectory(argv.dir, outPath);
+        logger.success(`✅ Archive created: ${outPath}`);
+        logger.debug(`Archive size: ${fs.statSync(outPath).size} bytes`);
 
-            // 2. Analyze stories and map screenshots
-            logger.info('2/5: Analyzing stories and mapping screenshots...');
-            const analysisResults = analyzeStorybook({
-                storiesDir: argv.storiesDir,
-                screenshotsDir: argv.screenshotsDir,
+        // 2. Upload Storybook ZIP + coverage + metadata ZIP (if present).
+        logger.info('2/3: Uploading to deployment service...');
+        const apiClient = getApiClient(argv.apiUrl, argv.apiKey);
+        const uploadResult = await uploadBuild(
+            apiClient,
+            {
                 project: argv.project,
-                version: argv.version
-            });
-            logger.success(`✅ Found ${analysisResults.summary.totalStories} stories (${analysisResults.summary.withScreenshots} with screenshots)`);
-
-            // 3. Create master ZIP with staticsite, images, and metadata
-            logger.info('3/5: Creating master archive with static site, images, and metadata...');
-            await createMasterZip({
-                outPath: outPath,
-                staticsiteDir: argv.dir,
-                screenshotsDir: argv.screenshotsDir,
-                metadata: analysisResults
-            });
-            logger.success(`✅ Master archive created: ${outPath}`);
-            logger.debug(`Archive size: ${fs.statSync(outPath).size} bytes`);
-
-            // 4. Upload archive (+ optional coverage)
-            logger.info('4/5: Uploading to deployment service...');
-            const apiClient = getApiClient(argv.apiUrl, argv.apiKey);
-            const uploadResult = await uploadBuild(
-                apiClient,
-                {
-                    project: argv.project,
-                    version: argv.version,
-                },
-                { zipPath: outPath, coverageReport }
-            );
-            logger.success('✅ Archive uploaded.');
-            logger.debug(`Upload result: ${JSON.stringify(uploadResult)}`);
-
-            await postPRComment(buildDeployResult(argv, coverageSummary), coverageSummary);
-
-            logger.success('\n🎉 Deployment with analysis successful! 🎉');
+                version: argv.version,
+            },
+            {
+                zipPath: outPath,
+                coverageReport,
+                metadataZipPath,
+            }
+        );
+        logger.success('✅ Archive uploaded.');
+        logger.debug(`Upload result: ${JSON.stringify(uploadResult)}`);
 
-        } else {
-            // Simple deployment without analysis
-            // 1. Archive the directory
-            logger.info(`1/3: Zipping directory '${argv.dir}'...`);
-            await zipDirectory(argv.dir, outPath);
-            logger.success(`✅ Archive created: ${outPath}`);
-            logger.debug(`Archive size: ${fs.statSync(outPath).size} bytes`);
-
-            // 2. Authenticate and upload directly (+ optional coverage)
-            logger.info('2/3: Uploading to deployment service...');
-            const apiClient = getApiClient(argv.apiUrl, argv.apiKey);
-            const uploadResult = await uploadBuild(
-                apiClient,
-                {
-                    project: argv.project,
-                    version: argv.version,
-                },
-                { zipPath: outPath, coverageReport }
-            );
-            logger.success('✅ Archive uploaded.');
-            logger.debug(`Upload result: ${JSON.stringify(uploadResult)}`);
-
-            await postPRComment(buildDeployResult(argv, coverageSummary), coverageSummary);
-
-            logger.success('\n🎉 Deployment successful! 🎉');
-        }
+        await postPRComment(buildDeployResult(argv, coverageSummary, uploadResult), coverageSummary);
+
+        logger.success('\n🎉 Deployment successful! 🎉');
+        logUploadLinks(argv, coverageSummary, uploadResult, logger);
 
     } finally {
         // 4. Clean up the local archive
@@ -173,6 +132,10 @@ async function runDeployment(argv) {
             fs.unlinkSync(outPath);
             logger.info(`🧹 Cleaned up temporary file: ${outPath}`);
         }
+        if (metadataZipPath && fs.existsSync(metadataZipPath)) {
+            fs.unlinkSync(metadataZipPath);
+            logger.info(`🧹 Cleaned up temporary file: ${metadataZipPath}`);
+        }
     }
 }
 
@@ -352,7 +315,64 @@ async function main() {
 
                 await runAnalysis(config);
             })
-            .command('init', 'Setup GitHub Actions workflows for automatic deployment', (yargs) => {
+            
+            .command('coverage', 'Run only Storybook coverage analysis and write the report to disk', (yargs) => {
+                return yargs
+                    .option('dir', {
+                        describe: 'Path to the built Storybook directory (e.g., storybook-static)',
+                        type: 'string',
+                        demandOption: true,
+                    })
+                    .option('coverage-base', {
+                        describe: 'Base ref/branch for new code analysis (supports SHAs, origin/main, HEAD~1)',
+                        type: 'string',
+                        default: 'main',
+                        alias: 'coverageBase'
+                    })
+                    .option('coverage-fail-on-threshold', {
+                        describe: 'Fail (exit 1) if coverage thresholds are not met',
+                        type: 'boolean',
+                        default: false,
+                        alias: 'coverageFailOnThreshold'
+                    })
+                    .option('coverage-execute', {
+                        describe: 'Execute stories during coverage analysis (requires playwright in the project)',
+                        type: 'boolean',
+                        default: false,
+                        alias: 'coverageExecute'
+                    })
+                    .option('output', {
+                        describe: 'Where to write the JSON coverage report',
+                        type: 'string',
+                        default: './scry-sbcov-report.json'
+                    })
+                    .option('verbose', {
+                        describe: 'Enable verbose logging',
+                        type: 'boolean',
+                        default: false,
+                    });
+            }, async (argv) => {
+                const logger = createLogger(argv);
+
+                const result = await runCoverageAnalysis({
+                    storybookDir: argv.dir,
+                    baseBranch: argv.coverageBase || 'main',
+                    failOnThreshold: Boolean(argv.coverageFailOnThreshold),
+                    execute: Boolean(argv.coverageExecute),
+                    outputPath: argv.output,
+                    keepReport: true,
+                });
+                const report = result.report;
+
+                if (!report) {
+                    logger.error('Coverage: no report generated (tool failed or returned null)');
+                    process.exit(1);
+                }
+
+                logger.success(`✅ Coverage report written to ${argv.output}`);
+            })
+
+.command('init', 'Setup GitHub Actions workflows for automatic deployment', (yargs) => {
                 return yargs
                     .option('project-id', {
                         describe: 'Project ID from Scry dashboard',
@@ -426,22 +446,32 @@ async function resolveCoverage(argv, logger) {
     const enabled = argv.coverage !== false;
     if (!enabled) {
         logger.info('Coverage: disabled (--no-coverage)');
-        return { coverageReport: null, coverageSummary: null };
+        return { coverageReport: null, coverageSummary: null, metadataZipPath: null };
     }
 
     try {
         let report = null;
+        let metadataZipPath = null;
 
         if (argv.coverageReport) {
             logger.info(`Coverage: using existing report at ${argv.coverageReport}`);
             report = loadCoverageReport(argv.coverageReport);
         } else {
-            report = await runCoverageAnalysis({
+            const needsScreenshots = Boolean(argv.withAnalysis);
+            const outputZipPath = needsScreenshots
+                ? path.join(os.tmpdir(), `scry-metadata-${Date.now()}.zip`)
+                : null;
+
+            const result = await runCoverageAnalysis({
                 storybookDir: argv.dir,
                 baseBranch: argv.coverageBase || 'main',
                 failOnThreshold: Boolean(argv.coverageFailOnThreshold),
-                execute: Boolean(argv.coverageExecute),
+                execute: Boolean(argv.coverageExecute) || needsScreenshots,
+                screenshots: needsScreenshots,
+                outputZipPath,
             });
+            report = result.report;
+            metadataZipPath = result.metadataZipPath;
         }
 
         const summary = extractCoverageSummary(report);
@@ -452,7 +482,7 @@ async function resolveCoverage(argv, logger) {
             logger.info('Coverage: no report generated (tool failed or report shape unexpected)');
         }
 
-        return { coverageReport: report, coverageSummary: summary };
+        return { coverageReport: report, coverageSummary: summary, metadataZipPath };
     } catch (err) {
         logger.error(`Coverage: failed (${err.message})`);
         throw err;
@@ -465,7 +495,7 @@ async function resolveCoverage(argv, logger) {
  * @param {any} argv
  * @param {any|null} coverageSummary
  */
-function buildDeployResult(argv, coverageSummary) {
+function buildDeployResult(argv, coverageSummary, uploadResult) {
     const project = argv.project || 'main';
     const version = argv.version || 'latest';
     const viewBaseUrl = process.env.SCRY_VIEW_URL || 'https://view.scrymore.com';
@@ -482,9 +512,24 @@ function buildDeployResult(argv, coverageSummary) {
         viewUrl,
         coverageUrl,
         coveragePageUrl: coverageUrl,
+        visibility: uploadResult?.zipUpload?.visibility,
     };
 }
 
+function logUploadLinks(argv, coverageSummary, uploadResult, logger) {
+    const deployResult = buildDeployResult(argv, coverageSummary, uploadResult);
+
+    logger.success('\n✅ Upload successful!\n');
+    logger.info(`📖 Storybook: ${deployResult.viewUrl}`);
+    if (deployResult.coverageUrl) {
+        logger.info(`📊 Coverage:  ${deployResult.coverageUrl}`);
+    }
+
+    if (deployResult.visibility === 'private') {
+        logger.info('\n🔒 This project is private. Viewers must be logged in to access.');
+    }
+}
+
 if (require.main === module) {
     main();
 }
@@ -495,4 +540,5 @@ module.exports = {
     runAnalysis,
     resolveCoverage,
     buildDeployResult,
+    logUploadLinks,
 };

package/lib/apiClient.js

@@ -1,6 +1,24 @@
 const axios = require('axios');
 const fs = require('fs');
 const { ApiError } = require('./errors.js');
+const { createLogger } = require('./logger.js');
+
+const isVerbose =
+  process.env.SCRY_VERBOSE === 'true' ||
+  process.env.STORYBOOK_DEPLOYER_VERBOSE === 'true' ||
+  process.env.VERBOSE === 'true' ||
+  process.env.SCRY_API_DEBUG === 'true' ||
+  process.env.SCRY_DEBUG === 'true' ||
+  process.argv.includes('--verbose');
+
+const logger = createLogger({ verbose: isVerbose });
+
+const COVERAGE_UPLOAD_DELAY_MS = 5000;
+const COVERAGE_RETRY_DELAY_MS = 60000;
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 
 /**
  * Creates a pre-configured axios instance for making API calls.
@@ -9,8 +27,10 @@ const { ApiError } = require('./errors.js');
  * @returns {axios.AxiosInstance} A configured axios instance.
  */
 function getApiClient(apiUrl, apiKey) {
+  logger.debug(`Initializing API client with baseURL: ${apiUrl}`);
   // This is a mock check to allow testing of a 401 error case.
   if (apiKey === 'fail-me-401') {
+    logger.debug('Mock 401 failure triggered by API key');
     throw new ApiError('The provided API key is invalid or has expired.', 401);
   }
   
@@ -27,6 +47,7 @@ function getApiClient(apiUrl, apiKey) {
   return axios.create({
     baseURL: apiUrl,
     headers: headers,
+    timeout: 60000, // 60 second timeout for large uploads
   });
 }
 
@@ -36,12 +57,14 @@ function getApiClient(apiUrl, apiKey) {
  * @param {axios.AxiosInstance} apiClient
  * @param {{project: string, version: string}} target
  * @param {{fileName: string, contentType: string}} file
- * @returns {Promise<string>} presigned URL
+ * @returns {Promise<{url: string, visibility?: string}>} presigned URL details
  */
 async function requestPresignedUrl(apiClient, target, file) {
   const projectName = target.project || 'main';
   const versionName = target.version || 'latest';
 
+  logger.debug(`Requesting presigned URL for ${projectName}/${versionName}/${file.fileName}`);
+  
   const presignedResponse = await apiClient.post(
     `/presigned-url/${projectName}/${versionName}/${file.fileName}`,
     { contentType: file.contentType },
@@ -52,21 +75,78 @@ async function requestPresignedUrl(apiClient, target, file) {
     }
   );
 
+  logger.debug(`Presigned URL response status: ${presignedResponse.status}`);
+  if (presignedResponse.data?.buildId || presignedResponse.data?.buildNumber) {
+    logger.info(
+      `Build record confirmed by presigned URL response (buildId: ${presignedResponse.data?.buildId || 'n/a'}, buildNumber: ${presignedResponse.data?.buildNumber || 'n/a'}).`
+    );
+  } else {
+    logger.debug(
+      `Presigned URL response did not include buildId/buildNumber. Response keys: ${Object.keys(presignedResponse.data || {}).join(', ') || 'none'}`
+    );
+  }
   const presignedUrl = presignedResponse.data?.url;
+  const visibility = presignedResponse.data?.visibility;
   if (!presignedUrl || typeof presignedUrl !== 'string' || presignedUrl.trim() === '') {
+    logger.debug(`Invalid presigned URL received: ${JSON.stringify(presignedResponse.data)}`);
     throw new ApiError(
       `Failed to get valid presigned URL from server response. Received: ${JSON.stringify(presignedResponse.data)}`
     );
   }
 
-  // Validate URL format
+  const parsedUrl = validatePresignedUrl(presignedUrl);
+  logger.debug(`Validated presigned URL host: ${parsedUrl.hostname}`);
+
+  return { url: presignedUrl, visibility };
+}
+
+function getAxiosErrorDetails(error, fallbackUrl) {
+  if (error.response) {
+    return {
+      message: `HTTP ${error.response.status} ${error.response.statusText}${error.response.data ? ` - ${JSON.stringify(error.response.data)}` : ''}`,
+      statusCode: error.response.status,
+      kind: 'response'
+    };
+  }
+
+  if (error.request) {
+    const code = error.code ? ` (${error.code})` : '';
+    const url = error.config?.url || fallbackUrl || 'unknown URL';
+    const baseURL = error.config?.baseURL ? ` (baseURL: ${error.config.baseURL})` : '';
+    return {
+      message: `No response received from ${url}${baseURL}${code}`,
+      statusCode: undefined,
+      kind: 'request'
+    };
+  }
+
+  return {
+    message: error.message || 'Unknown error',
+    statusCode: undefined,
+    kind: 'unknown'
+  };
+}
+
+function validatePresignedUrl(presignedUrl) {
+  let parsedUrl;
   try {
-    new URL(presignedUrl);
+    parsedUrl = new URL(presignedUrl);
   } catch (urlError) {
     throw new ApiError(`Received invalid URL format from server: "${presignedUrl}". URL validation error: ${urlError.message}`);
   }
 
-  return presignedUrl;
+  const hostname = parsedUrl.hostname || '';
+  if (hostname.includes('undefined')) {
+    throw new ApiError(
+      `Presigned URL hostname contains "undefined": ${hostname}. This usually means the upload service is missing its R2 account ID or bucket configuration.`
+    );
+  }
+
+  if (!hostname.endsWith('.r2.cloudflarestorage.com')) {
+    logger.debug(`Presigned URL hostname does not look like a standard R2 host: ${hostname}`);
+  }
+
+  return parsedUrl;
 }
 
 /**
@@ -78,14 +158,19 @@ async function requestPresignedUrl(apiClient, target, file) {
  * @returns {Promise<{status:number}>}
  */
 async function putToPresignedUrl(presignedUrl, buffer, contentType) {
+  logger.debug(`Starting PUT upload to presigned URL. Size: ${buffer.length} bytes, Content-Type: ${contentType}`);
+  
   const uploadResponse = await axios.put(presignedUrl, buffer, {
     headers: {
       'Content-Type': contentType,
     },
     maxContentLength: Infinity,
     maxBodyLength: Infinity,
+    // Use a separate timeout for the actual upload if needed, 
+    // but here we rely on the global axios or the one passed in.
   });
 
+  logger.debug(`PUT upload completed with status: ${uploadResponse.status}`);
   return { status: uploadResponse.status };
 }
 
@@ -101,30 +186,36 @@ async function putToPresignedUrl(presignedUrl, buffer, contentType) {
  * @returns {Promise<object>} A promise that resolves to the upload result.
  */
 async function uploadFileDirectly(apiClient, { project, version }, filePath, file = {}) {
+  logger.debug(`uploadFileDirectly called for file: ${filePath}`);
+  
   // This is a mock check to allow testing of a 500 server error.
   if (project === 'fail-me-500') {
+    logger.debug('Mock 500 failure triggered by project name');
     throw new ApiError('The deployment service encountered an internal error.', 500);
   }
 
+  if (!fs.existsSync(filePath)) {
+    logger.debug(`File not found: ${filePath}`);
+    throw new Error(`File not found: ${filePath}`);
+  }
+
   const fileBuffer = fs.readFileSync(filePath);
   const fileName = file.fileName || 'storybook.zip';
   const contentType = file.contentType || 'application/zip';
 
   try {
-    const presignedUrl = await requestPresignedUrl(apiClient, { project, version }, { fileName, contentType });
-    const upload = await putToPresignedUrl(presignedUrl, fileBuffer, contentType);
-    return { success: true, url: presignedUrl, status: upload.status };
+    const presigned = await requestPresignedUrl(apiClient, { project, version }, { fileName, contentType });
+    const upload = await putToPresignedUrl(presigned.url, fileBuffer, contentType);
+    return { success: true, url: presigned.url, status: upload.status, visibility: presigned.visibility };
   } catch (error) {
-    if (error.response) {
-      throw new ApiError(
-        `Failed to upload file: ${error.response.status} ${error.response.statusText}${error.response.data ? ` - ${JSON.stringify(error.response.data)}` : ''}`,
-        error.response.status
-      );
-    } else if (error.request) {
-      throw new ApiError(`Failed to upload file: No response from server at ${apiClient.defaults.baseURL}`);
-    } else {
-      throw new ApiError(`Failed to upload file: ${error.message}`);
+    logger.debug(`Upload failed. Error type: ${error.constructor.name}, Message: ${error.message}`);
+    const details = getAxiosErrorDetails(error, apiClient.defaults.baseURL);
+    if (details.kind === 'response') {
+      logger.debug(`Error response status: ${details.statusCode}`);
+    } else if (details.kind === 'request') {
+      logger.debug(`Error request details: ${details.message}`);
     }
+    throw new ApiError(`Failed to upload file: ${details.message}`, details.statusCode);
   }
 }
 
@@ -141,6 +232,9 @@ async function uploadCoverageReportDirectly(apiClient, target, coverageReport) {
   const projectName = target.project || 'main';
   const versionName = target.version || 'latest';
 
+  logger.info(`Uploading coverage report for ${projectName}/${versionName}...`);
+  logger.debug(`Uploading coverage report for ${projectName}/${versionName}`);
+
   try {
     const response = await apiClient.post(
       `/upload/${projectName}/${versionName}/coverage`,
@@ -152,22 +246,83 @@ async function uploadCoverageReportDirectly(apiClient, target, coverageReport) {
       }
     );
 
+    logger.debug(`Coverage upload response status: ${response.status}`);
+    logger.info(`Coverage report upload complete (status ${response.status}).`);
     return {
       success: response.data?.success ?? true,
       buildId: response.data?.buildId,
       coverageUrl: response.data?.coverageUrl,
     };
   } catch (error) {
-    if (error.response) {
-      throw new ApiError(
-        `Failed to upload coverage: ${error.response.status} ${error.response.statusText}${error.response.data ? ` - ${JSON.stringify(error.response.data)}` : ''}`,
-        error.response.status
-      );
-    } else if (error.request) {
-      throw new ApiError(`Failed to upload coverage: No response from server at ${apiClient.defaults.baseURL}`);
-    } else {
-      throw new ApiError(`Failed to upload coverage: ${error.message}`);
+    logger.debug(`Coverage upload failed. Message: ${error.message}`);
+    const details = getAxiosErrorDetails(error, apiClient.defaults.baseURL);
+
+    if (
+      details.statusCode === 404 &&
+      error.response?.data &&
+      typeof error.response.data === 'object' &&
+      String(error.response.data.error || '').includes('Build not found')
+    ) {
+      logger.error('Coverage upload failed with 404: Build not found for this version.');
+      logger.info('This is not a missing-secret error. The production Worker did not find a Firestore build record for the project + version you are attaching coverage to.');
+      logger.info('Coverage requires an existing build record created by a prior build upload or presigned URL generation.');
+      logger.info('Most common causes and fixes:');
+      logger.info('1) Coverage called before build exists. Upload the build ZIP first (or call the presigned URL endpoint) and then upload coverage.');
+      logger.info('2) Project/version mismatch. Coverage must use the same {project}/{version} as the build upload or presigned URL call.');
+      logger.info('3) Firestore secrets present but invalid. A malformed FIREBASE_PRIVATE_KEY (missing literal \\n sequences) or wrong project ID can prevent build creation.');
+      logger.info('4) Firestore integration disabled in prod. Ensure FIREBASE_PROJECT_ID, FIREBASE_CLIENT_EMAIL, FIREBASE_PRIVATE_KEY, and FIRESTORE_SERVICE_ACCOUNT_ID are set.');
+      logger.info('Recommended checks:');
+      logger.info('- Trigger a production upload or presigned URL call first and verify it returns buildId/buildNumber (confirms Firestore created a build).');
+      logger.info('- Then call the coverage endpoint for the same project/version.');
+      logger.info('- If upload does not return buildId/buildNumber, fix Firestore secrets and ensure FIREBASE_PRIVATE_KEY preserves literal \\n as documented.');
+      logger.info('See README.md and docs/PRODUCTION_SETUP.md for details.');
     }
+
+    throw new ApiError(`Failed to upload coverage: ${details.message}`, details.statusCode);
+  }
+}
+
+/**
+ * Upload metadata+screenshots ZIP.
+ * This triggers async build-processing through the upload service queue.
+ *
+ * @param {axios.AxiosInstance} apiClient
+ * @param {{project: string, version: string}} target
+ * @param {string} metadataZipPath
+ * @param {{info:Function,success:Function,warn:Function}} customLogger
+ * @returns {Promise<{success:boolean, status?:number, queued?:boolean, buildNumber?:number, zipKey?:string, error?:string}>}
+ */
+async function uploadMetadataZip(apiClient, target, metadataZipPath, customLogger = logger) {
+  const projectName = target.project || 'main';
+  const versionName = target.version || 'latest';
+  const url = `/upload/${projectName}/${versionName}/metadata`;
+
+  customLogger.info('Uploading metadata ZIP...');
+
+  try {
+    const fileBuffer = fs.readFileSync(metadataZipPath);
+    const response = await apiClient.post(url, fileBuffer, {
+      headers: { 'Content-Type': 'application/zip' },
+      maxContentLength: 100 * 1024 * 1024,
+      maxBodyLength: 100 * 1024 * 1024,
+    });
+
+    const data = response.data || {};
+    customLogger.success(
+      `Metadata ZIP uploaded (build #${data.buildNumber ?? 'n/a'}, queued: ${Boolean(data.queued)})`
+    );
+
+    return {
+      success: true,
+      status: response.status,
+      queued: Boolean(data.queued),
+      buildNumber: data.buildNumber,
+      zipKey: data.zipKey,
+    };
+  } catch (error) {
+    const message = error.response?.data?.error || error.message || 'Unknown error';
+    customLogger.warn(`Metadata ZIP upload failed: ${message}`);
+    return { success: false, error: message };
   }
 }
 
@@ -179,9 +334,10 @@ async function uploadCoverageReportDirectly(apiClient, target, coverageReport) {
  *
  * @param {axios.AxiosInstance} apiClient
  * @param {{project: string, version: string}} target
- * @param {{zipPath: string, coverageReport?: any|null}} options
+ * @param {{zipPath: string, coverageReport?: any|null, metadataZipPath?: string|null}} options
  */
 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',
@@ -189,16 +345,31 @@ async function uploadBuild(apiClient, target, options) {
 
   let coverageUpload = null;
   if (options.coverageReport) {
-    coverageUpload = await uploadCoverageReportDirectly(apiClient, target, options.coverageReport);
+    logger.info(`Waiting ${COVERAGE_UPLOAD_DELAY_MS / 1000}s before uploading coverage report...`);
+    await sleep(COVERAGE_UPLOAD_DELAY_MS);
+
+    try {
+      coverageUpload = await uploadCoverageReportDirectly(apiClient, target, options.coverageReport);
+    } catch (error) {
+      logger.info('Coverage upload failed; retrying in 60s...');
+      await sleep(COVERAGE_RETRY_DELAY_MS);
+      coverageUpload = await uploadCoverageReportDirectly(apiClient, target, options.coverageReport);
+    }
+  }
+
+  let metadataUpload = null;
+  if (options.metadataZipPath) {
+    metadataUpload = await uploadMetadataZip(apiClient, target, options.metadataZipPath, logger);
   }
 
-  return { zipUpload, coverageUpload };
+  return { zipUpload, coverageUpload, metadataUpload };
 }
 
 module.exports = {
   getApiClient,
   uploadFileDirectly,
   uploadCoverageReportDirectly,
+  uploadMetadataZip,
   uploadBuild,
   requestPresignedUrl,
   putToPresignedUrl,

package/lib/coverage.js

@@ -8,6 +8,10 @@ const chalk = require('chalk');
  * @property {string} storybookDir Path to a built Storybook static directory (e.g. ./storybook-static)
  * @property {string} [baseBranch='main'] Base branch name to compare for "new code" analysis
  * @property {boolean} [failOnThreshold=false] If true, pass "--ci" to the coverage tool and rethrow errors
+ * @property {string} [outputPath] If provided, write the report to this path (relative to cwd allowed)
+ * @property {boolean} [keepReport=false] If true, do not delete the output file after reading
+ * @property {boolean} [screenshots=false] Enable passing-story screenshots in scry-sbcov
+ * @property {string|null} [outputZipPath=null] Where to write metadata+screenshots ZIP
  */
 
 /**
@@ -19,13 +23,23 @@ const chalk = require('chalk');
  * - Reads and returns the parsed JSON report
  * - Deletes the temporary report file
  *
- * If the underlying tool fails and `failOnThreshold` is false, returns `null`.
+ * If the underlying tool fails and `failOnThreshold` is false, returns
+ * `{ report: null, metadataZipPath: null }`.
  *
  * @param {RunCoverageOptions} options
- * @returns {Promise<any|null>} The full coverage report JSON, or null if skipped/failed (non-fatal)
+ * @returns {Promise<{report:any|null, metadataZipPath:string|null}>}
  */
 async function runCoverageAnalysis(options) {
-  const { storybookDir, baseBranch = 'main', failOnThreshold = false, execute = false } = options || {};
+  const {
+    storybookDir,
+    baseBranch = 'main',
+    failOnThreshold = false,
+    execute = false,
+    outputPath: providedOutputPath,
+    keepReport = false,
+    screenshots = false,
+    outputZipPath = null,
+  } = options || {};
 
   if (!storybookDir || typeof storybookDir !== 'string') {
     throw new Error('runCoverageAnalysis: options.storybookDir is required');
@@ -33,7 +47,11 @@ async function runCoverageAnalysis(options) {
 
   console.log(chalk.blue('Running Storybook coverage analysis...'));
 
-  const outputPath = path.join(process.cwd(), `.scry-coverage-report-${Date.now()}.json`);
+  const outputPath = providedOutputPath
+    ? (path.isAbsolute(providedOutputPath) ? providedOutputPath : path.resolve(process.cwd(), providedOutputPath))
+    : path.join(process.cwd(), `.scry-coverage-report-${Date.now()}.json`);
+
+  const resolvedBaseRef = resolveCoverageBaseRef(baseBranch);
 
   /** @type {string[]} */
   const cliArgs = [
@@ -42,7 +60,7 @@ async function runCoverageAnalysis(options) {
     '--output',
     outputPath,
     '--base',
-    `origin/${baseBranch}`,
+    normalizeGitBaseRef(resolvedBaseRef),
     '--verbose', // Enable verbose logging to debug component detection
   ];
 
@@ -50,13 +68,21 @@ async function runCoverageAnalysis(options) {
     cliArgs.push('--ci');
   }
 
-  if (execute) {
+  if (execute || screenshots) {
     cliArgs.push('--execute');
   }
+  if (screenshots) {
+    cliArgs.push('--screenshots');
+    if (outputZipPath) {
+      cliArgs.push('--output-zip', outputZipPath);
+    }
+  }
 
-  // Use npx with -p flag to ensure package is installed, then run the binary
-  // This is more reliable than `npx @scrymore/scry-sbcov` which can fail to find the binary
-  const npxCommand = `npx -y -p @scrymore/scry-sbcov scry-sbcov ${cliArgs.map(shellEscape).join(' ')}`;
+  // Allow local override for E2E testing before package publication.
+  // Example:
+  //   SCRY_SBCOV_CMD="node /abs/path/to/scry-sbcov/dist/cli/index.js"
+  const sbcovCommandPrefix = (process.env.SCRY_SBCOV_CMD || 'npx -y @scrymore/scry-sbcov').trim();
+  const npxCommand = `${sbcovCommandPrefix} ${cliArgs.map(shellEscape).join(' ')}`;
 
   // Debug logging to show the exact command being executed
   console.log(chalk.yellow('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
@@ -85,13 +111,16 @@ async function runCoverageAnalysis(options) {
 
     const raw = fs.readFileSync(outputPath, 'utf-8');
     const report = JSON.parse(raw);
+    const metadataZipPath = (screenshots && outputZipPath && fs.existsSync(outputZipPath))
+      ? outputZipPath
+      : null;
 
-    safeUnlink(outputPath);
-    return report;
+    if (!keepReport && !providedOutputPath) safeUnlink(outputPath);
+    return { report, metadataZipPath };
   } catch (error) {
-    safeUnlink(outputPath);
+    if (!keepReport && !providedOutputPath) safeUnlink(outputPath);
     if (failOnThreshold) throw error;
-    return null;
+    return { report: null, metadataZipPath: null };
   }
 }
 
@@ -181,8 +210,91 @@ function shellEscape(value) {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
 
+
+
+/**
+ * Normalize a user-supplied base ref into something git understands.
+ *
+ * Why this exists:
+ * - In CI, the best base for "push" is often a SHA (e.g. github.event.before)
+ * - In PRs, the best base is often a remote-tracking branch (e.g. origin/main)
+ * - Locally, users may pass branch names (e.g. main) or rev expressions (e.g. HEAD~1)
+ *
+ * `scry-sbcov` expects a value it can pass to git commands as the base reference.
+ *
+ * @param {string} baseBranch
+ * @returns {string}
+ */
+function normalizeGitBaseRef(baseBranch) {
+  const value = (baseBranch || '').trim();
+
+  if (!value) return 'origin/main';
+
+  // Commit SHA (short or full)
+  if (/^[0-9a-f]{7,40}$/i.test(value)) return value;
+
+  // Common rev expressions that should not be prefixed.
+  if (value === 'HEAD' || value.startsWith('HEAD~') || value.startsWith('HEAD^')) return value;
+  if (/[~^]/.test(value)) return value;
+
+  // If user already provided a qualified ref, use it as-is.
+  if (value.startsWith('origin/')) return value;
+  if (value.startsWith('refs/')) return value;
+  if (value.startsWith('remotes/')) return value;
+
+  // Otherwise, treat it as a branch name and compare against the remote.
+  // This also works for branch names that contain slashes (e.g. feature/foo).
+  return `origin/${value}`;
+}
+
+/**
+ * Resolve the base ref to pass into `scry-sbcov`, preferring PR base SHAs
+ * from CI providers when available.
+ *
+ * @param {string} baseBranch
+ * @returns {string}
+ */
+function resolveCoverageBaseRef(baseBranch) {
+  const env = process.env || {};
+
+  const githubBaseSha = readGithubPullRequestBaseSha(env.GITHUB_EVENT_PATH);
+  if (githubBaseSha) return githubBaseSha;
+
+  const gitlabBaseSha = env.CI_MERGE_REQUEST_TARGET_BRANCH_SHA;
+  if (gitlabBaseSha) return gitlabBaseSha;
+
+  const bitbucketBaseSha = env.BITBUCKET_PR_DESTINATION_COMMIT || env.BITBUCKET_PR_BASE_COMMIT;
+  if (bitbucketBaseSha) return bitbucketBaseSha;
+
+  return baseBranch || 'main';
+}
+
+/**
+ * Read GitHub pull_request base.sha from the event payload.
+ *
+ * @param {string|undefined} eventPath
+ * @returns {string|null}
+ */
+function readGithubPullRequestBaseSha(eventPath) {
+  if (!eventPath || typeof eventPath !== 'string') return null;
+
+  try {
+    if (!fs.existsSync(eventPath)) return null;
+    const raw = fs.readFileSync(eventPath, 'utf-8');
+    const payload = JSON.parse(raw);
+    const baseSha = payload?.pull_request?.base?.sha;
+    if (typeof baseSha === 'string' && baseSha.trim()) return baseSha.trim();
+    return null;
+  } catch (error) {
+    return null;
+  }
+}
+
 module.exports = {
   runCoverageAnalysis,
   loadCoverageReport,
   extractCoverageSummary,
+  normalizeGitBaseRef,
+  resolveCoverageBaseRef,
+  readGithubPullRequestBaseSha,
 };

package/lib/templates.js

@@ -102,7 +102,8 @@ ${cache}
             --dir ./storybook-static \\
             \${{ vars.SCRY_COVERAGE_ENABLED == 'false' && '--no-coverage' || '' }} \\
             \${{ vars.SCRY_COVERAGE_FAIL_ON_THRESHOLD == 'true' && '--coverage-fail-on-threshold' || '' }} \\
-            --coverage-base \${{ vars.SCRY_COVERAGE_BASE || 'main' }}
+            \${{ vars.SCRY_COVERAGE_EXECUTE == 'false' && '' || '--coverage-execute' }} \\
+            --coverage-base \${{ vars.SCRY_COVERAGE_BASE || github.event.before }}
         env:
           STORYBOOK_DEPLOYER_API_URL: \${{ vars.SCRY_API_URL }}
           STORYBOOK_DEPLOYER_PROJECT: \${{ vars.SCRY_PROJECT_ID }}
@@ -165,7 +166,8 @@ ${cache}
             \${{ github.event.pull_request.draft == true && '--no-coverage' || '' }} \\
             \${{ vars.SCRY_COVERAGE_ENABLED == 'false' && '--no-coverage' || '' }} \\
             \${{ vars.SCRY_COVERAGE_FAIL_ON_THRESHOLD == 'true' && '--coverage-fail-on-threshold' || '' }} \\
-            --coverage-base \${{ vars.SCRY_COVERAGE_BASE || 'main' }}
+            \${{ vars.SCRY_COVERAGE_EXECUTE == 'false' && '' || '--coverage-execute' }} \\
+            --coverage-base \${{ vars.SCRY_COVERAGE_BASE || format('origin/{0}', github.base_ref) }}
  
           # Construct deployment URL using VIEW_URL (where users access the deployed Storybook)
           # Defaults to https://view.scrymore.com if SCRY_VIEW_URL is not set

package/lib/update-workflows.js

@@ -0,0 +1,110 @@
+const { createLogger } = require('./logger');
+const { generateMainWorkflow, generatePRWorkflow } = require('./templates');
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+/**
+ * Upgrade-only workflow generator.
+ *
+ * Goal: allow users to refresh .github/workflows/* to the latest templates
+ * WITHOUT needing the Scry API key.
+ *
+ * This intentionally does NOT:
+ * - validate credentials
+ * - touch .storybook-deployer.json
+ * - set GitHub variables/secrets
+ */
+async function runUpdateWorkflows(argv) {
+  const logger = createLogger({ verbose: Boolean(argv.verbose) });
+
+  logger.info('🛠️  Updating Scry GitHub Actions workflows...');
+
+  const envInfo = await checkEnvironment();
+  if (!envInfo.isGit) {
+    throw new Error('Not a git repository. Please run this from a git repo.');
+  }
+
+  const workflowsDir = '.github/workflows';
+  fs.mkdirSync(workflowsDir, { recursive: true });
+
+  const buildCmd = envInfo.storybookBuildCmd || 'build-storybook';
+
+  const mainWorkflow = generateMainWorkflow('', '', envInfo.packageManager, buildCmd);
+  const prWorkflow = generatePRWorkflow('', '', envInfo.packageManager, buildCmd);
+
+  const mainWorkflowPath = path.join(workflowsDir, 'deploy-storybook.yml');
+  const prWorkflowPath = path.join(workflowsDir, 'deploy-pr-preview.yml');
+
+  fs.writeFileSync(mainWorkflowPath, mainWorkflow, 'utf8');
+  fs.writeFileSync(prWorkflowPath, prWorkflow, 'utf8');
+
+  logger.success(`✅ Updated ${mainWorkflowPath}`);
+  logger.success(`✅ Updated ${prWorkflowPath}`);
+
+  if (argv.commit) {
+    gitAdd([mainWorkflowPath, prWorkflowPath], logger);
+    gitCommit(argv.commitMessage || 'chore: update Scry workflows', logger);
+  }
+
+  logger.success('✅ Workflow update complete');
+}
+
+async function checkEnvironment() {
+  const envInfo = {
+    isGit: false,
+    packageManager: 'npm',
+    storybookBuildCmd: null,
+  };
+
+  try {
+    execSync('git rev-parse --git-dir', { stdio: 'ignore' });
+    envInfo.isGit = true;
+  } catch {
+    envInfo.isGit = false;
+  }
+
+  if (fs.existsSync('pnpm-lock.yaml')) {
+    envInfo.packageManager = 'pnpm';
+  } else if (fs.existsSync('yarn.lock')) {
+    envInfo.packageManager = 'yarn';
+  } else if (fs.existsSync('bun.lockb')) {
+    envInfo.packageManager = 'bun';
+  }
+
+  try {
+    const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+    if (pkg.scripts) {
+      if (pkg.scripts['build-storybook']) envInfo.storybookBuildCmd = 'build-storybook';
+      else if (pkg.scripts['storybook:build']) envInfo.storybookBuildCmd = 'storybook:build';
+      else if (pkg.scripts['build:storybook']) envInfo.storybookBuildCmd = 'build:storybook';
+    }
+  } catch {
+    // ignore
+  }
+
+  return envInfo;
+}
+
+function gitAdd(files, logger) {
+  for (const file of files) {
+    if (fs.existsSync(file)) {
+      execSync(`git add "${file}"`, { stdio: 'pipe' });
+      logger.debug(`   ✓ Added ${file}`);
+    }
+  }
+}
+
+function gitCommit(message, logger) {
+  const status = execSync('git status --porcelain', { encoding: 'utf8' });
+  if (!status.trim()) {
+    logger.info('No changes to commit.');
+    return;
+  }
+
+  execSync(`git commit -m "${message}"`, { stdio: 'pipe' });
+  const sha = execSync('git rev-parse --short HEAD', { encoding: 'utf8' }).trim();
+  logger.success(`✅ Committed workflow update: ${sha}`);
+}
+
+module.exports = { runUpdateWorkflows };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scrymore/scry-deployer",
-  "version": "0.0.6",
+  "version": "0.1.1",
   "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.2.1",
+    "@scrymore/scry-sbcov": "^0.3.0",
     "@sentry/node": "^10.33.0",
     "archiver": "^7.0.1",
     "axios": "^1.12.2",