@scrymore/scry-deployer 0.0.5 → 0.1.0

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+const Sentry = require('@sentry/node');
 const yargs = require('yargs/yargs');
 const { hideBin } = require('yargs/helpers');
 const fs = require('fs');
@@ -16,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);
@@ -135,9 +137,10 @@ async function runDeployment(argv) {
             logger.success('✅ Archive uploaded.');
             logger.debug(`Upload result: ${JSON.stringify(uploadResult)}`);
 
-            await postPRComment(buildDeployResult(argv, coverageSummary), coverageSummary);
+            await postPRComment(buildDeployResult(argv, coverageSummary, uploadResult), coverageSummary);
 
             logger.success('\n🎉 Deployment with analysis successful! 🎉');
+            logUploadLinks(argv, coverageSummary, uploadResult, logger);
 
         } else {
             // Simple deployment without analysis
@@ -161,9 +164,10 @@ async function runDeployment(argv) {
             logger.success('✅ Archive uploaded.');
             logger.debug(`Upload result: ${JSON.stringify(uploadResult)}`);
 
-            await postPRComment(buildDeployResult(argv, coverageSummary), coverageSummary);
+            await postPRComment(buildDeployResult(argv, coverageSummary, uploadResult), coverageSummary);
 
             logger.success('\n🎉 Deployment successful! 🎉');
+            logUploadLinks(argv, coverageSummary, uploadResult, logger);
         }
 
     } finally {
@@ -175,10 +179,26 @@ async function runDeployment(argv) {
     }
 }
 
-function handleError(error, argv) {
+async function handleError(error, argv) {
     const logger = createLogger(argv || {});
     logger.error(`\n❌ Error: ${error.message}`);
 
+    // Capture error in Sentry with additional context
+    Sentry.withScope((scope) => {
+        if (argv) {
+            scope.setTags({
+                project: argv.project,
+                version: argv.version,
+                command: argv._ ? argv._[0] : 'unknown',
+            });
+            scope.setExtra('argv', argv);
+        }
+        Sentry.captureException(error);
+    });
+    
+    // Ensure the event is sent before the process exits
+    await Sentry.close(2000);
+
     if (error instanceof ApiError) {
         if (error.statusCode === 401) {
             logger.error('Suggestion: Check that your API key is correct and has not expired.');
@@ -195,6 +215,13 @@ function handleError(error, argv) {
 }
 
 async function main() {
+    // Initialize Sentry
+    Sentry.init({
+        dsn: "https://c66ce229a1db2289f145eebd02436d9c@o4507889391828992.ingest.us.sentry.io/4510699330732032", // Fallback to hardcoded DSN for user reporting
+        tracesSampleRate: 1.0,
+        environment: process.env.NODE_ENV || 'production',
+    });
+
     let config;
     try {
         const args = await yargs(hideBin(process.argv))
@@ -328,7 +355,63 @@ 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 report = await runCoverageAnalysis({
+                    storybookDir: argv.dir,
+                    baseBranch: argv.coverageBase || 'main',
+                    failOnThreshold: Boolean(argv.coverageFailOnThreshold),
+                    execute: Boolean(argv.coverageExecute),
+                    outputPath: argv.output,
+                    keepReport: true,
+                });
+
+                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',
@@ -378,6 +461,9 @@ async function main() {
 
                 await runInit(initConfig);
             })
+            .command('debug-sentry', 'Test Sentry integration by throwing an error', () => {}, () => {
+                throw new Error('Sentry debug error from scry-node CLI');
+            })
             .env('STORYBOOK_DEPLOYER')
             .help()
             .alias('help', 'h')
@@ -385,7 +471,7 @@ async function main() {
             .parse();
 
     } catch (error) {
-        handleError(error, config);
+        await handleError(error, config);
     }
 }
 
@@ -438,7 +524,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';
@@ -455,9 +541,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();
 }
@@ -468,4 +569,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,39 @@ 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);
   }
 }
 
@@ -182,6 +293,7 @@ async function uploadCoverageReportDirectly(apiClient, target, coverageReport) {
  * @param {{zipPath: string, coverageReport?: any|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,7 +301,16 @@ 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);
+    }
   }
 
   return { zipUpload, coverageUpload };

package/lib/coverage.js

@@ -8,6 +8,8 @@ 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
  */
 
 /**
@@ -25,7 +27,7 @@ const chalk = require('chalk');
  * @returns {Promise<any|null>} The full coverage report JSON, or null if skipped/failed (non-fatal)
  */
 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 } = options || {};
 
   if (!storybookDir || typeof storybookDir !== 'string') {
     throw new Error('runCoverageAnalysis: options.storybookDir is required');
@@ -33,32 +35,39 @@ 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 args = [
-    '@scrymore/scry-sbcov',
+  const cliArgs = [
     '--storybook-static',
     storybookDir,
     '--output',
     outputPath,
     '--base',
-    `origin/${baseBranch}`,
+    normalizeGitBaseRef(resolvedBaseRef),
     '--verbose', // Enable verbose logging to debug component detection
   ];
 
   if (failOnThreshold) {
-    args.push('--ci');
+    cliArgs.push('--ci');
   }
 
   if (execute) {
-    args.push('--execute');
+    cliArgs.push('--execute');
   }
 
+  // Use npx with the package name directly.
+  // This is more reliable than `npx -p` which can fail to find the binary in some environments.
+  const npxCommand = `npx -y @scrymore/scry-sbcov ${cliArgs.map(shellEscape).join(' ')}`;
+
   // Debug logging to show the exact command being executed
   console.log(chalk.yellow('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
   console.log(chalk.yellow('DEBUG: Executing coverage command:'));
-  console.log(chalk.gray(`npx ${args.join(' ')}`));
+  console.log(chalk.gray(npxCommand));
   console.log(chalk.yellow('Working directory: ' + process.cwd()));
   console.log(chalk.yellow('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'));
 
@@ -75,7 +84,7 @@ async function runCoverageAnalysis(options) {
     console.log(chalk.yellow('Project root: ' + projectRoot));
     console.log(chalk.yellow('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'));
 
-    execSync(`npx ${args.map(shellEscape).join(' ')}`, {
+    execSync(npxCommand, {
       stdio: 'inherit',
       cwd: projectRoot // Run from the project root, not scry-node directory
     });
@@ -83,10 +92,10 @@ async function runCoverageAnalysis(options) {
     const raw = fs.readFileSync(outputPath, 'utf-8');
     const report = JSON.parse(raw);
 
-    safeUnlink(outputPath);
+    if (!keepReport && !providedOutputPath) safeUnlink(outputPath);
     return report;
   } catch (error) {
-    safeUnlink(outputPath);
+    if (!keepReport && !providedOutputPath) safeUnlink(outputPath);
     if (failOnThreshold) throw error;
     return null;
   }
@@ -178,8 +187,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/logger.js

@@ -8,6 +8,7 @@ const chalk = require('chalk');
  * @returns {{info: Function, error: Function, debug: Function, success: Function}}
  */
 function createLogger({ verbose = false }) {
+  const Sentry = require('@sentry/node');
   return {
     /**
      * Logs an informational message.
@@ -15,6 +16,11 @@ function createLogger({ verbose = false }) {
      */
     info: (message) => {
       console.log(message);
+      Sentry.addBreadcrumb({
+        category: 'log',
+        message: message,
+        level: 'info',
+      });
     },
 
     /**
@@ -31,6 +37,11 @@ function createLogger({ verbose = false }) {
      */
     error: (message) => {
       console.error(chalk.red(message));
+      Sentry.addBreadcrumb({
+        category: 'log',
+        message: message,
+        level: 'error',
+      });
     },
 
     /**
@@ -41,6 +52,11 @@ function createLogger({ verbose = false }) {
       if (verbose) {
         console.log(chalk.dim(`[debug] ${message}`));
       }
+      Sentry.addBreadcrumb({
+        category: 'log',
+        message: message,
+        level: 'debug',
+      });
     },
   };
 }

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.5",
+  "version": "0.1.0",
   "description": "A CLI to automate the deployment of Storybook static builds.",
   "main": "index.js",
   "bin": {
@@ -37,7 +37,8 @@
   },
   "dependencies": {
     "@octokit/rest": "^20.0.0",
-    "@scrymore/scry-sbcov": "^0.2.1",
+    "@scrymore/scry-sbcov": "^0.2.2",
+    "@sentry/node": "^10.33.0",
     "archiver": "^7.0.1",
     "axios": "^1.12.2",
     "chalk": "^4.1.2",