@reshotdev/screenshot 0.0.1-beta.8 → 0.0.1-beta.9

package/src/commands/verify-publish.js

@@ -0,0 +1,46 @@
+"use strict";
+
+const chalk = require("chalk");
+const { runVerifyPublish } = require("../lib/certification");
+
+async function verifyPublishCommand(options = {}) {
+  const scenarioKeys = options.scenarios
+    ? String(options.scenarios)
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean)
+    : null;
+
+  const report = await runVerifyPublish({
+    scenarioKeys,
+    tag: options.tag,
+    message: options.message,
+  });
+
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(chalk.cyan("\n📦 Publish Verification\n"));
+    console.log(
+      report.ok
+        ? chalk.green("  ✔ Publish, pull, and hosted delivery verified")
+        : chalk.red("  ✖ Publish verification failed"),
+    );
+    console.log(chalk.gray(`  Published: ${report.publishResult.assetsProcessed || 0}`));
+    console.log(chalk.gray(`  Pull repairs: ${report.pullResult.normalizationRepairs || 0}`));
+    const failedChecks = (report.deliveryChecks || []).filter((check) => !check.ok);
+    if (failedChecks.length > 0) {
+      for (const check of failedChecks.slice(0, 10)) {
+        console.log(chalk.red(`  ✖ ${check.scenario}/${check.assetKey}: ${check.reason}`));
+      }
+    }
+  }
+
+  if (!report.ok) {
+    process.exitCode = 1;
+  }
+
+  return report;
+}
+
+module.exports = verifyPublishCommand;

package/src/index.js

@@ -153,10 +153,70 @@ program
     }
   });
 
+// Capture: Compatibility alias for older docs and snippets
+program
+  .command("capture")
+  .description("Compatibility alias for `reshot run` (prefer `reshot run` and `reshot publish`)")
+  .option("-s, --scenarios <keys>", "Comma-separated list of scenario keys")
+  .option("--mode <mode>", "Compatibility mode: preview | publish", "preview")
+  .option("--config <path>", "Compatibility config path (defaults to reshot.config.json)")
+  .option("--base-url <url>", "Temporary base URL override for compatibility flows")
+  .option("--tag <tag>", "Version tag when mode=publish")
+  .option("-m, --message <message>", "Publish message when mode=publish")
+  .option("--no-headless", "Run browser in visible mode")
+  .option("-c, --concurrency <n>", "Number of parallel browser workers", parseInt)
+  .option("--debug", "Enable verbose debug logging")
+  .action(async (options) => {
+    if (options.debug) {
+      process.env.RESHOT_DEBUG = "1";
+    }
+    if (options.config && options.config !== "reshot.config.json") {
+      console.log(
+        chalk.yellow(
+          "Compatibility mode currently uses reshot.config.json from the working directory.",
+        ),
+      );
+    }
+    if (options.baseUrl) {
+      process.env.RESHOT_BASE_URL = options.baseUrl;
+      console.log(
+        chalk.gray(
+          `Using temporary base URL override for this run: ${options.baseUrl}`,
+        ),
+      );
+    }
+    try {
+      const runCommand = require("./commands/run");
+      const scenarioKeys = options.scenarios
+        ? options.scenarios.split(",").map((s) => s.trim())
+        : null;
+      await runCommand({
+        scenarioKeys,
+        headless: options.headless,
+        concurrency: options.concurrency,
+      });
+
+      if (String(options.mode || "preview").toLowerCase() === "publish") {
+        const publishCommand = require("./commands/publish");
+        await publishCommand({
+          tag: options.tag,
+          message: options.message,
+        });
+      }
+    } catch (error) {
+      console.error(chalk.red("Error:"), error.message);
+      if (options.debug && error.stack) {
+        console.error(chalk.gray(error.stack));
+      }
+      process.exit(1);
+    }
+  });
+
 // Record: Interactive visual recording from live browser
 program
   .command("record [title]")
   .description("Interactively record visuals from a live browser session")
+  .option("--name <title>", "Compatibility alias for the scenario title")
   .option("--browser", "Launch Chrome with remote debugging before recording")
   .option("-p, --port <port>", "Chrome debugging port (default: 9222)")
   .option("--url <url>", "URL to open when launching browser")
@@ -166,14 +226,15 @@ program
     if (options.debug) {
       process.env.RESHOT_DEBUG = "1";
     }
+    const resolvedTitle = title || options.name;
     try {
       // If --refresh-session, just sync the session and exit
       if (options.refreshSession) {
         const { autoSyncSessionFromCDP, getDefaultSessionPath } = require("./lib/record-cdp");
         const sessionPath = getDefaultSessionPath();
         console.log(chalk.gray("  Syncing session from active browser..."));
-        const synced = await autoSyncSessionFromCDP(sessionPath);
-        if (synced) {
+        const result = await autoSyncSessionFromCDP(sessionPath);
+        if (result.synced) {
           console.log(chalk.green("  ✔ Session refreshed at " + sessionPath));
         } else {
           console.log(chalk.yellow("  ⚠ No active CDP browser found. Launch Chrome with remote debugging first:"));
@@ -194,7 +255,7 @@ program
       }
 
       const recordCommand = require("./commands/record");
-      await recordCommand(title);
+      await recordCommand(resolvedTitle);
     } catch (error) {
       console.error(chalk.red("Error:"), error.message);
       if (options.debug && error.stack) {
@@ -275,6 +336,62 @@ program
     }
   });
 
+// Doctor: Validate target contract and readiness
+const doctor = program.command("doctor").description("Validate target configuration and readiness");
+
+doctor
+  .command("target")
+  .description("Audit the certified target contract before capture")
+  .option("-s, --scenarios <keys>", "Comma-separated list of scenario keys")
+  .option("--json", "Output JSON report")
+  .action(async (options) => {
+    try {
+      const doctorTargetCommand = require("./commands/doctor-target");
+      await doctorTargetCommand(options);
+    } catch (error) {
+      console.error(chalk.red("Error:"), error.message);
+      process.exit(1);
+    }
+  });
+
+// Verify: Publish/pull/hosted delivery verification
+const verify = program.command("verify").description("Verify publish and delivery flows");
+
+verify
+  .command("publish")
+  .description("Verify publish, pull, and hosted asset delivery")
+  .option("-s, --scenarios <keys>", "Comma-separated list of scenario keys")
+  .option("--tag <tag>", "Version tag for verification publish")
+  .option("-m, --message <message>", "Publish message override")
+  .option("--json", "Output JSON report")
+  .action(async (options) => {
+    try {
+      const verifyPublishCommand = require("./commands/verify-publish");
+      await verifyPublishCommand(options);
+    } catch (error) {
+      console.error(chalk.red("Error:"), error.message);
+      process.exit(1);
+    }
+  });
+
+// Certify: full certified-target release gate
+program
+  .command("certify")
+  .description("Run the full certified target pipeline")
+  .option("-s, --scenarios <keys>", "Comma-separated list of scenario keys")
+  .option("--tag <tag>", "Version tag for certification publish")
+  .option("-m, --message <message>", "Publish message override")
+  .option("--json", "Output JSON report")
+  .action(async (options) => {
+    try {
+      const certifyCommand = require("./commands/certify");
+      await certifyCommand(options);
+    } catch (error) {
+      console.error(chalk.red("Error:"), error.message);
+      process.exit(1);
+    }
+  });
+
 // CI: CI/CD integration commands
 const ciCommand = program
   .command("ci")
@@ -353,9 +470,22 @@ Actions:
 // ============================================================================
 
 // Auth: Standalone authentication (for re-auth scenarios)
-program
+const auth = program
   .command("auth")
-  .description("Authenticate with Reshot Cloud")
+  .description("Authenticate with Reshot Cloud (or set RESHOT_API_KEY + RESHOT_PROJECT_ID env vars)")
+  .action(async () => {
+    try {
+      const authCommand = require("./commands/auth");
+      await authCommand();
+    } catch (error) {
+      console.error(chalk.red("Error:"), error.message);
+      process.exit(1);
+    }
+  });
+
+auth
+  .command("login")
+  .description("Compatibility alias for `reshot auth`")
   .action(async () => {
     try {
       const authCommand = require("./commands/auth");

package/src/lib/api-client.js

@@ -5,6 +5,51 @@ const fs = require("fs");
 
 const PRODUCTION_API_URL = "https://reshot.dev/api";
 
+function summarizeApiBody(body) {
+  if (body == null) return "";
+  if (typeof body === "string") return body.trim();
+  if (typeof body !== "object") return String(body);
+
+  const candidates = [
+    body.message,
+    body.error?.message,
+    body.error,
+    body.reason,
+    body.details,
+  ].filter(Boolean);
+
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim()) {
+      return candidate.trim();
+    }
+  }
+
+  try {
+    return JSON.stringify(body);
+  } catch {
+    return String(body);
+  }
+}
+
+function createApiError(kind, endpoint, error) {
+  const status = error.response?.status || null;
+  const statusText = error.response?.statusText || "";
+  const bodySummary = summarizeApiBody(error.response?.data);
+  const baseMessage = bodySummary || error.message || "Unknown API error";
+  const statusLabel = status ? `${status}${statusText ? ` ${statusText}` : ""}` : "request failed";
+  const wrapped = new Error(`${kind} (${statusLabel}) at ${endpoint}: ${baseMessage}`);
+  wrapped.response = error.response;
+  wrapped.code = error.code;
+  wrapped.reshot = {
+    kind,
+    endpoint,
+    status,
+    statusText,
+    bodySummary,
+  };
+  return wrapped;
+}
+
 function getApiBaseUrl() {
   // 1. Explicit env var override (for CI or local dev)
   if (process.env.RESHOT_API_BASE_URL) {
@@ -210,20 +255,7 @@ async function publishAssetsV1(apiKey, metadata, assets) {
     });
     return response.data;
   } catch (error) {
-    if (error.response) {
-      const status = error.response.status;
-      const errorMsg = error.response.data?.error || error.message;
-
-      // Create an error that preserves the response for auth detection
-      const err = new Error(
-        status === 401 || status === 403
-          ? `Authentication failed: ${errorMsg}`
-          : `Failed to publish assets: ${errorMsg}`,
-      );
-      err.response = error.response;
-      throw err;
-    }
-    throw new Error(`Failed to publish assets: ${error.message}`);
+    throw createApiError("publish_ingest_failure", `${baseUrl}/v1/publish`, error);
   }
 }
 
@@ -700,15 +732,23 @@ async function exportVisuals(projectId, options = {}) {
   }
 
   return withRetry(async () => {
-    const response = await axios.get(
-      `${baseUrl}/projects/${projectId}/visuals/export`,
-      {
-        params: { format, status },
-        headers: { Authorization: `Bearer ${apiKey}` },
-        timeout: 60000,
-      },
-    );
-    return response.data;
+    try {
+      const response = await axios.get(
+        `${baseUrl}/projects/${projectId}/visuals/export`,
+        {
+          params: { format, status },
+          headers: { Authorization: `Bearer ${apiKey}` },
+          timeout: 60000,
+        },
+      );
+      return response.data;
+    } catch (error) {
+      throw createApiError(
+        "export_visuals_failure",
+        `${baseUrl}/projects/${projectId}/visuals/export`,
+        error,
+      );
+    }
   });
 }
 
@@ -838,6 +878,7 @@ module.exports = {
   getProjectConfig,
   postChangelogDrafts,
   getApiBaseUrl,
+  createApiError,
   syncPushAssets,
   getSyncStatus,
   // New transactional flow

package/src/lib/capture-engine.js

@@ -98,6 +98,8 @@ class CaptureEngine {
     this.capturedAssets = [];
     this.logger = options.logger || console.log;
     this.headless = options.headless !== false; // Default to headless
+    this.injectWorkspaceStore = options.injectWorkspaceStore !== false;
+    this.diagnostics = [];
 
     // Storage state path for authenticated sessions
     // If provided, loads cookies/localStorage from file to preserve auth state
@@ -289,7 +291,9 @@ class CaptureEngine {
       logVariantSummary(this.variantConfig, this.logger);
     }
 
-    await this._injectWorkspaceStore();
+    if (this.injectWorkspaceStore) {
+      await this._injectWorkspaceStore();
+    }
 
     // Inject privacy masking CSS (after variant injection, before captures)
     this._privacyInjectionOk = true;
@@ -306,24 +310,76 @@ class CaptureEngine {
     this._authResponseDetected = false;
     this.page.on("response", (response) => {
       const status = response.status();
+      const url = response.url();
       if (
         (status === 401 || status === 403) &&
         response.request().resourceType() === "document"
       ) {
         this._authResponseDetected = true;
       }
+
+      if (status >= 400 && response.request().resourceType() === "document") {
+        this._recordDiagnostic("response_error", "error", {
+          url,
+          status,
+          resourceType: response.request().resourceType(),
+        });
+      }
     });
 
     // Set up error handling
     this.page.on("pageerror", (err) => {
       const firstLine = (err.message || '').split('\n')[0].slice(0, 200);
+      this._recordDiagnostic("pageerror", "error", {
+        message: err.message || String(err),
+      });
       this.logger(chalk.yellow(`  [Page Error] ${firstLine}`));
     });
+    this.page.on("console", (message) => {
+      const type = message.type();
+      const text = message.text();
+      const severity =
+        type === "error"
+          ? "error"
+          : type === "warning"
+            ? "warning"
+            : "info";
+
+      if (severity === "error" || severity === "warning") {
+        this._recordDiagnostic("console", severity, {
+          message: text,
+          consoleType: type,
+          cspViolation: /content security policy|csp/i.test(text),
+        });
+      }
+    });
+    this.page.on("requestfailed", (request) => {
+      this._recordDiagnostic("requestfailed", "error", {
+        url: request.url(),
+        method: request.method(),
+        resourceType: request.resourceType(),
+        message: request.failure()?.errorText || "Request failed",
+      });
+    });
 
     this.logger(chalk.green("  ✔ Browser initialized"));
     return this;
   }
 
+  _recordDiagnostic(kind, severity, details = {}) {
+    this.diagnostics.push({
+      id: `${Date.now()}-${this.diagnostics.length + 1}`,
+      kind,
+      severity,
+      ...details,
+      capturedAt: new Date().toISOString(),
+    });
+  }
+
+  getDiagnostics() {
+    return [...this.diagnostics];
+  }
+
   /**
    * Hide development overlays (Next.js devtools, Vercel toolbar, etc.)
    * Injects CSS to hide common development UI elements before each navigation
@@ -512,10 +568,15 @@ class CaptureEngine {
     }
 
     // Check for auth redirect after navigation (URL patterns + HTTP 401/403)
+    // Skip the check if the scenario explicitly targeted this URL (e.g. capturing /login)
     const currentUrl = this.page.url();
+    const targetPath = url.startsWith("http") ? new URL(url).pathname : url;
+    const currentPath = (() => { try { return new URL(currentUrl).pathname; } catch { return currentUrl; } })();
+    const isIntentionalTarget = currentPath === targetPath;
     const isAuthRedirect =
-      isAuthRedirectUrl(currentUrl, this._customAuthPatterns) ||
-      this._authResponseDetected;
+      !isIntentionalTarget &&
+      (isAuthRedirectUrl(currentUrl, this._customAuthPatterns) ||
+      this._authResponseDetected);
     if (isAuthRedirect) {
       const errorMsg = `Auth redirect detected: navigated to ${currentUrl}. Session may be expired. Re-run \`reshot record\` to refresh session, or export a fresh Playwright storage state to .reshot/auth-state.json.`;
       this.logger(chalk.red(`  ✖ ${errorMsg}`));

package/src/lib/capture-script-runner.js

@@ -251,7 +251,11 @@ async function executeWithRetry(engine, readySelector, options = {}) {
  * @returns {Promise<{ok: boolean, message?: string}>}
  */
 async function preflightAuthCheck(baseUrl, options = {}) {
-  const { storageStatePath, viewport = { width: 1280, height: 720 } } = options;
+  const {
+    storageStatePath,
+    viewport = { width: 1280, height: 720 },
+    authCheckUrl = "/app/projects",
+  } = options;
 
   if (!storageStatePath || !fs.existsSync(storageStatePath)) {
     return { ok: true }; // No session to verify
@@ -272,8 +276,12 @@ async function preflightAuthCheck(baseUrl, options = {}) {
   try {
     await engine.init();
 
-    // Navigate to projects page (a page that requires auth + data)
-    await engine.page.goto(`${baseUrl}/app/projects`, {
+    const preflightPath = authCheckUrl.startsWith("http")
+      ? authCheckUrl
+      : `${baseUrl}${authCheckUrl}`;
+
+    // Navigate to a known authenticated page and validate session/data loading.
+    await engine.page.goto(preflightPath, {
       waitUntil: "domcontentloaded",
       timeout: 15000,
     });
@@ -290,6 +298,19 @@ async function preflightAuthCheck(baseUrl, options = {}) {
       };
     }
 
+    // Also detect login page via DOM (catches SPA redirects where URL hasn't changed)
+    const hasLoginForm = await engine.page.evaluate(() => {
+      const h = document.querySelector("h1, h2");
+      return h && /sign\s*in|log\s*in/i.test(h.textContent);
+    }).catch(() => false);
+    if (hasLoginForm) {
+      return {
+        ok: false,
+        message:
+          "Auth session expired (login form detected). Run `reshot record` to refresh.",
+      };
+    }
+
     // Wait for data to settle
     await engine.page.waitForTimeout(3000);
     await engine._waitForStability();
@@ -418,6 +439,14 @@ async function retryInteractiveStep(engine, action, params, context) {
   }
 }
 
+function promoteLastGotoUrl(lastGotoUrl, currentUrl) {
+  if (!currentUrl || currentUrl === "about:blank") {
+    return lastGotoUrl;
+  }
+
+  return currentUrl !== lastGotoUrl ? currentUrl : lastGotoUrl;
+}
+
 /**
  * Calculate a perceptual hash for an image buffer
  * This is a simple hash based on resizing the image to a small grid
@@ -854,6 +883,7 @@ async function runScenarioWithStepByStepCapture(scenario, options = {}) {
     waitForReady: scenario.waitForReady || null, // Custom loading-state hook
     privacyConfig: hasPrivacy ? scenarioPrivacyConfig : null, // Privacy masking
     styleConfig: hasStyle ? scenarioStyleConfig : null, // Image beautification
+    injectWorkspaceStore: scenario.needsWorkspaceInjection !== false,
     logger: quiet ? () => {} : (msg) => console.log(msg),
   });
 
@@ -1278,6 +1308,11 @@ async function runScenarioWithStepByStepCapture(scenario, options = {}) {
           }
         }
 
+        // Promote the current page URL after successful interactive steps so
+        // retries restore the page we actually navigated to, not the last
+        // explicit goto target.
+        lastGotoUrl = promoteLastGotoUrl(lastGotoUrl, engine.page.url());
+
         // Wait for animations/transitions - longer wait for multi-step flows
         const isMultiStep = script.length > 3;
         await engine.page.waitForTimeout(isMultiStep ? 500 : 150);
@@ -1443,7 +1478,17 @@ async function runScenarioWithStepByStepCapture(scenario, options = {}) {
       // Non-critical — don't fail the capture
     }
 
-    return { success: failedSteps.length === 0, assets, skippedSteps, duplicatesSkipped, failedSteps, retriedSteps, privacy: privacyMeta, style: styleMeta };
+    return {
+      success: failedSteps.length === 0,
+      assets,
+      skippedSteps,
+      duplicatesSkipped,
+      failedSteps,
+      retriedSteps,
+      privacy: privacyMeta,
+      style: styleMeta,
+      diagnostics: engine.getDiagnostics(),
+    };
     })(); // End of scenarioExecution async IIFE
 
     // Race scenario execution against timeout
@@ -1472,7 +1517,15 @@ async function runScenarioWithStepByStepCapture(scenario, options = {}) {
       // Ignore
     }
 
-    return { success: false, error: error.message, assets, skippedSteps, failedSteps, retriedSteps };
+    return {
+      success: false,
+      error: error.message,
+      assets,
+      skippedSteps,
+      failedSteps,
+      retriedSteps,
+      diagnostics: engine.getDiagnostics(),
+    };
   } finally {
     await engine.close();
   }
@@ -2606,6 +2659,7 @@ async function runScenarioWithEngine(scenario, options = {}) {
     storageStatePath: hasSession ? sessionPath : null, // Use saved session if available
     storageStateData, // Pre-loaded auth state
     hideDevtools: true, // Always hide dev overlays in captures
+    injectWorkspaceStore: scenario.needsWorkspaceInjection !== false,
     logger: quiet ? () => {} : (msg) => console.log(msg),
   });
 
@@ -2617,7 +2671,7 @@ async function runScenarioWithEngine(scenario, options = {}) {
       chalk.green(`\n  ✔ Scenario completed: ${assets.length} assets captured`)
     );
 
-    return { success: true, assets };
+    return { success: true, assets, diagnostics: engine.getDiagnostics() };
   } catch (error) {
     console.error(chalk.red(`\n  ❌ Scenario failed: ${error.message}`));
 
@@ -2637,7 +2691,7 @@ async function runScenarioWithEngine(scenario, options = {}) {
       // Ignore screenshot errors
     }
 
-    return { success: false, error: error.message };
+    return { success: false, error: error.message, diagnostics: engine.getDiagnostics() };
   } finally {
     await engine.close();
   }
@@ -2882,7 +2936,14 @@ async function runAllScenarios(config, options = {}) {
   // Run auth pre-flight check if any scenario requires auth
   const captureConfig = getCaptureConfig(config.capture || {});
   const scenarios = config.scenarios || [];
-  const hasAuthScenarios = scenarios.some((s) => s.requiresAuth);
+  const hasAuthScenarios = scenarios.some((s) => s.captureClass !== "public");
+  const authPreflightScenario = scenarios.find(
+    (scenario) => scenario.captureClass === "live-auth" || scenario.requiresAuth,
+  );
+  const authCheckUrl =
+    config.target?.authPreflightUrl ||
+    authPreflightScenario?.url ||
+    "/app/projects";
 
   if (captureConfig.preflightCheck && hasAuthScenarios) {
     const sessionPath = getDefaultSessionPath();
@@ -2893,6 +2954,7 @@ async function runAllScenarios(config, options = {}) {
         {
           storageStatePath: sessionPath,
           viewport: config.viewport || { width: 1280, height: 720 },
+          authCheckUrl,
         }
       );
       if (!preflightResult.ok) {
@@ -3160,6 +3222,7 @@ async function runAllScenarios(config, options = {}) {
 
 module.exports = {
   convertLegacySteps,
+  substituteUrlVariables,
   runScenarioWithEngine,
   runScenarioWithStepByStepCapture,
   runScenarioWithVideoCapture,
@@ -3171,6 +3234,7 @@ module.exports = {
   waitForVisualStability,
   // Error detection & retry
   retryInteractiveStep,
+  promoteLastGotoUrl,
   executeWithRetry,
   preflightAuthCheck,
   // New exports for output templating