@reshotdev/screenshot 0.0.1-beta.2 → 0.0.1-beta.21

package/src/lib/config.js

@@ -21,6 +21,11 @@ const {
   getConfigDefaults,
   validateCaptureRequirements,
 } = require("./standalone-mode");
+const {
+  normalizeConfigContract,
+  validateNormalizedConfig,
+  getCertifiedScenarioKeys,
+} = require("./target-contract");
 
 const SETTINGS_DIR = ".reshot";
 const SETTINGS_PATH = path.join(process.cwd(), SETTINGS_DIR, "settings.json");
@@ -64,7 +69,7 @@ function createAuthErrorResponse(message) {
     code: "AUTH_REQUIRED",
   };
 }
-const CONFIG_PATH = path.join(process.cwd(), "docsync.config.json");
+const CONFIG_PATH = path.join(process.cwd(), "reshot.config.json");
 const WORKSPACE_PATH = path.join(process.cwd(), SETTINGS_DIR, "workspace.json");
 
 /**
@@ -279,13 +284,19 @@ function readConfig() {
     );
   }
 
-  const config = fs.readJSONSync(CONFIG_PATH);
+  const rawConfig = fs.readJSONSync(CONFIG_PATH);
+  const config = normalizeConfigContract(rawConfig);
 
   // Validate required fields
   if (!config.scenarios || !Array.isArray(config.scenarios)) {
     throw new Error('Config must have a "scenarios" array');
   }
 
+  const targetValidation = validateNormalizedConfig(config);
+  if (!targetValidation.valid) {
+    throw new Error(targetValidation.errors.join("\n"));
+  }
+
   const validActions = [
     "click",
     "type",
@@ -319,9 +330,9 @@ function readConfig() {
     if (!scenario.key) {
       throw new Error(`Scenario "${scenario.name}" must have a "key" field`);
     }
-    if (!/^[a-z0-9-]+$/i.test(scenario.key)) {
+    if (!/^[a-z0-9]([a-z0-9\-_/]*[a-z0-9])?$/i.test(scenario.key)) {
       throw new Error(
-        `Scenario "${scenario.name}" has invalid key "${scenario.key}". Keys must be alphanumeric with hyphens only.`
+        `Scenario "${scenario.name}" has invalid key "${scenario.key}". Keys must start and end alphanumeric; hyphens, underscores, and slashes are allowed in between.`
       );
     }
     if (!scenario.url) {
@@ -470,84 +481,22 @@ function readConfig() {
     }
   }
 
-  // Validate optional docs block
-  if (config.docs !== undefined) {
-    if (
-      typeof config.docs !== "object" ||
-      config.docs === null ||
-      Array.isArray(config.docs)
-    ) {
-      throw new Error("docs must be an object");
-    }
-    if (
-      config.docs.root !== undefined &&
-      typeof config.docs.root !== "string"
-    ) {
-      throw new Error("docs.root must be a string");
-    }
-    if (
-      config.docs.include !== undefined &&
-      !Array.isArray(config.docs.include)
-    ) {
-      throw new Error("docs.include must be an array of strings");
-    }
-    if (
-      config.docs.exclude !== undefined &&
-      !Array.isArray(config.docs.exclude)
-    ) {
-      throw new Error("docs.exclude must be an array of strings");
-    }
-  }
-
   return config;
 }
 
 /**
- * Read docsync.config.json with DocSync-specific configuration
- * Returns the full config including the documentation block for ingestion
- * @returns {Object} DocSync configuration
+ * Read reshot.config.json without requiring scenarios array
+ * Used by sync and other commands that don't need scenario validation
+ * @returns {Object} Configuration
  */
-function readDocSyncConfig() {
+function readConfigLenient() {
   if (!fs.existsSync(CONFIG_PATH)) {
     throw new Error(
       `Config file not found at ${CONFIG_PATH}. Run \`reshot init\` to create one.`
     );
   }
 
-  const config = fs.readJSONSync(CONFIG_PATH);
-  
-  // Validate documentation block if present
-  if (config.documentation) {
-    const doc = config.documentation;
-    
-    // Validate required fields
-    if (!doc.strategy) {
-      throw new Error('documentation.strategy is required (git_pr or external_host)');
-    }
-    
-    if (!['git_pr', 'external_host'].includes(doc.strategy)) {
-      throw new Error('documentation.strategy must be "git_pr" or "external_host"');
-    }
-    
-    // Validate optional fields
-    if (doc.assetFormat && !['cdn_link', 'markdown'].includes(doc.assetFormat)) {
-      throw new Error('documentation.assetFormat must be "cdn_link" or "markdown"');
-    }
-    
-    if (doc.include && !Array.isArray(doc.include)) {
-      throw new Error('documentation.include must be an array of glob patterns');
-    }
-    
-    if (doc.exclude && !Array.isArray(doc.exclude)) {
-      throw new Error('documentation.exclude must be an array of glob patterns');
-    }
-    
-    if (doc.mappings && typeof doc.mappings !== 'object') {
-      throw new Error('documentation.mappings must be an object');
-    }
-  }
-  
-  return config;
+  return normalizeConfigContract(fs.readJSONSync(CONFIG_PATH));
 }
 
 /**
@@ -555,7 +504,7 @@ function readDocSyncConfig() {
  * @param {Object} config - Config object to write
  */
 function writeConfig(config) {
-  fs.writeJSONSync(CONFIG_PATH, config, { spaces: 2 });
+  fs.writeJSONSync(CONFIG_PATH, normalizeConfigContract(config), { spaces: 2 });
 }
 
 /**
@@ -701,10 +650,10 @@ function getPrivacyConfig(scenarioOverrides = {}) {
  * Default style configuration
  */
 const DEFAULT_STYLE_CONFIG = {
-  enabled: true,
+  enabled: false,
   frame: "none",
-  shadow: "medium",
-  padding: 40,
+  shadow: "none",
+  padding: 0,
   background: "transparent",
   borderRadius: 0,
 };
@@ -851,8 +800,6 @@ async function initializeProject(projectId, apiKey, options = {}) {
         contextCount: 1,
         features: {
           visuals: true,
-          docs: false,
-          changelog: true,
         },
       },
     };
@@ -1040,19 +987,175 @@ function getModeInfo() {
   };
 }
 
+function readSettingsSafe() {
+  try {
+    return readSettings();
+  } catch (error) {
+    return null;
+  }
+}
+
+function collectTemplateVariables(value) {
+  if (typeof value !== "string" || value.length === 0) {
+    return [];
+  }
+
+  const variables = new Set();
+  const regex = /\{\{(\w+)\}\}/g;
+  let match = regex.exec(value);
+
+  while (match) {
+    variables.add(match[1]);
+    match = regex.exec(value);
+  }
+
+  return [...variables];
+}
+
+function hasDeterministicReadyContract(scenario) {
+  if (!scenario || typeof scenario !== "object") {
+    return false;
+  }
+
+  if (scenario.readySelector) {
+    return true;
+  }
+
+  if (scenario.ready?.selector || scenario.ready?.expression) {
+    return true;
+  }
+
+  return Array.isArray(scenario.steps)
+    ? scenario.steps.some(
+        (step) => step?.action === "waitForSelector" && step?.selector,
+      )
+    : false;
+}
+
 /**
  * Validate full configuration for capture readiness
+ * @param {Object} [options] - Validation options
+ * @param {string[]} [options.scenarioKeys] - Restrict validation to scenario keys
+ * @param {boolean} [options.requireReadyContract] - Enforce deterministic readiness
  * @returns {Object} Validation result
  */
-function validateConfig() {
+function validateConfig(options = {}) {
+  const { scenarioKeys = null, requireReadyContract = false } = options;
+
   try {
     const config = readConfig();
-    return validateCaptureRequirements(config);
+    const baseResult = validateCaptureRequirements(config);
+    const errors = [...baseResult.errors];
+    const warnings = baseResult.warnings.filter(
+      (warning) => warning !== "baseUrl should start with http:// or https://",
+    );
+    const scenarios = Array.isArray(config.scenarios) ? config.scenarios : [];
+    const requestedScenarioKeys = Array.isArray(scenarioKeys)
+      ? scenarioKeys.filter(Boolean)
+      : [];
+    const selectedScenarios = requestedScenarioKeys.length
+      ? scenarios.filter((scenario) => requestedScenarioKeys.includes(scenario.key))
+      : scenarios;
+    const missingScenarioKeys = requestedScenarioKeys.filter(
+      (key) => !scenarios.some((scenario) => scenario.key === key),
+    );
+
+    if (missingScenarioKeys.length > 0) {
+      errors.push(
+        `Unknown scenario key(s): ${missingScenarioKeys.join(", ")}. ` +
+          `Available scenarios: ${scenarios.map((scenario) => scenario.key).join(", ") || "none"}`,
+      );
+    }
+
+    if (config.baseUrl) {
+      try {
+        const parsedUrl = new URL(config.baseUrl);
+        if (!["http:", "https:"].includes(parsedUrl.protocol)) {
+          errors.push(
+            `baseUrl must use http:// or https:// (received ${parsedUrl.protocol})`,
+          );
+        }
+      } catch (error) {
+        errors.push(
+          `baseUrl must be a valid absolute URL. Received: ${config.baseUrl}`,
+        );
+      }
+    }
+
+    const settings = readSettingsSafe();
+    const configuredVariables = {
+      ...(settings?.urlVariables || {}),
+    };
+    if (!configuredVariables.PROJECT_ID && settings?.projectId) {
+      configuredVariables.PROJECT_ID = settings.projectId;
+    }
+
+    const unresolvedVariables = [];
+    for (const scenario of selectedScenarios) {
+      for (const variableName of collectTemplateVariables(scenario.url)) {
+        if (!configuredVariables[variableName] && !process.env[variableName]) {
+          unresolvedVariables.push(`${scenario.key}:${variableName}`);
+        }
+      }
+    }
+
+    if (unresolvedVariables.length > 0) {
+      errors.push(
+        `Unresolved URL variable(s): ${unresolvedVariables.join(", ")}. ` +
+          `Set them in .reshot/settings.json under urlVariables or as environment variables.`,
+      );
+    }
+
+    const shouldRequireReadyContract =
+      requireReadyContract || config.target?.tier === "certified";
+    if (shouldRequireReadyContract) {
+      const missingReadyContract = selectedScenarios
+        .filter((scenario) => !hasDeterministicReadyContract(scenario))
+        .map((scenario) => scenario.key);
+
+      if (missingReadyContract.length > 0) {
+        errors.push(
+          `Deterministic readiness is required for: ${missingReadyContract.join(", ")}. ` +
+            `Add ready.selector, ready.expression, readySelector, or a waitForSelector step.`,
+        );
+      }
+    }
+
+    const authScenarioCount = selectedScenarios.filter(
+      (scenario) => scenario.captureClass === "live-auth" || scenario.requiresAuth,
+    ).length;
+    const liveAuthScenarioCount = selectedScenarios.filter(
+      (scenario) => scenario.captureClass === "live-auth",
+    ).length;
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+      details: {
+        baseUrl: config.baseUrl || null,
+        selectedScenarioKeys: selectedScenarios.map((scenario) => scenario.key),
+        missingScenarioKeys,
+        unresolvedVariables,
+        requiresReadyContract: shouldRequireReadyContract,
+        authScenarioCount,
+        liveAuthScenarioCount,
+      },
+    };
   } catch (e) {
     return {
       valid: false,
       errors: [e.message],
       warnings: [],
+      details: {
+        baseUrl: null,
+        selectedScenarioKeys: [],
+        missingScenarioKeys: [],
+        unresolvedVariables: [],
+        requiresReadyContract: requireReadyContract,
+        authScenarioCount: 0,
+        liveAuthScenarioCount: 0,
+      },
     };
   }
 }
@@ -1230,8 +1333,10 @@ module.exports = {
   // Mode & validation
   getModeInfo,
   validateConfig,
-  // DocSync configuration
-  readDocSyncConfig,
+  // Lenient config read (no scenario validation)
+  readConfigLenient,
+  // Certified target contract helpers
+  getCertifiedScenarioKeys,
   // Paths
   SETTINGS_PATH,
   SETTINGS_DIR,

package/src/lib/dom-capture.js

@@ -0,0 +1,64 @@
+// dom-capture.js — CLI integration layer for the Tier-3 DOM-capture engine.
+//
+// The capture techniques (m7 hybrid primary, m4 CDP DOMSnapshot fallback) live in
+// @reshot/compose/capture so they can reuse the deterministic renderer + the
+// calibrated verify evaluator and be gated under `pnpm --dir packages/compose
+// test`. This module is the thin CLI-side wrapper: it loads that engine (with a
+// monorepo dist fallback, mirroring commands/compose.js) and exposes the two
+// entry points the CLI needs.
+
+const path = require("path");
+const fs = require("fs-extra");
+const { composeDistDir } = require("./compose-runtime");
+
+function loadCaptureEngine() {
+  return require(path.join(composeDistDir(), "capture.cjs"));
+}
+
+/**
+ * Capture a DOM artifact from an ALREADY-NAVIGATED live page and write it next to
+ * the other capture outputs. Returns the metadata.domArtifact block (or null if
+ * capture failed — capture is additive and must never break the video path).
+ *
+ * @param {object} args
+ * @param {import('playwright').Page} args.page  live page (capture as-is)
+ * @param {string} args.outputDir
+ * @param {string} args.slug
+ * @param {string|null} [args.csp]
+ */
+async function captureDomArtifact({ page, outputDir, slug, csp = null }) {
+  try {
+    const { captureDom, writeArtifact } = loadCaptureEngine();
+    const snapshot = await captureDom(page, { csp });
+    const base = path.join(outputDir, slug);
+    const paths = await writeArtifact(snapshot, base);
+    return { path: paths.html, method: snapshot.method, sidecars: snapshot.surfaces };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`  ⚠ DOM capture skipped: ${message}`);
+    return null;
+  }
+}
+
+/**
+ * Standalone capture of a URL: navigates, captures, remounts, and writes the
+ * artifact + remounted.png + live.png into outDir. Returns a result summary.
+ */
+async function captureDomFromUrl({ url, outDir, slug = "capture", settings }) {
+  const { captureUrl, writeArtifact } = loadCaptureEngine();
+  await fs.ensureDir(outDir);
+  const result = await captureUrl(url, settings ? { settings } : {});
+  const paths = await writeArtifact(result.snapshot, path.join(outDir, slug));
+  await fs.writeFile(path.join(outDir, "remounted.png"), result.remountPng);
+  await fs.writeFile(path.join(outDir, "live.png"), result.livePng);
+  return {
+    method: result.method,
+    artifact: paths.html,
+    meta: paths.meta,
+    remounted: path.join(outDir, "remounted.png"),
+    live: path.join(outDir, "live.png"),
+    sidecars: result.snapshot.surfaces,
+  };
+}
+
+module.exports = { loadCaptureEngine, captureDomArtifact, captureDomFromUrl };

package/src/lib/ensure-browser.js

@@ -0,0 +1,147 @@
+// ensure-browser.js - Guarantees the correct Playwright browser build is present
+//
+// The CLI bundles a specific version of Playwright, which is pinned to an exact
+// browser build. Telling users to run a bare `npx playwright install` can resolve
+// a DIFFERENT Playwright version (and therefore a different browser build),
+// leaving the bundled launcher unable to find its executable. To make the build
+// match 1:1, we drive the BUNDLED Playwright's own installer.
+
+const path = require("path");
+const fs = require("fs");
+const { spawnSync } = require("child_process");
+
+// Matches Playwright's "missing executable" launch error.
+const MISSING_EXECUTABLE_RE = /Executable doesn't exist|please run the following command to download new browsers|browserType\.launch.*Executable/i;
+
+let installAttempted = false;
+
+/**
+ * Resolve the bundled Playwright's CLI entrypoint and version.
+ * We resolve relative to the package.json so the path matches whatever
+ * Playwright build this CLI actually depends on.
+ * @returns {{ cliPath: string|null, version: string|null }}
+ */
+function resolveBundledPlaywright() {
+  for (const pkg of ["playwright", "playwright-core"]) {
+    try {
+      const pkgJsonPath = require.resolve(`${pkg}/package.json`);
+      const cliPath = path.join(path.dirname(pkgJsonPath), "cli.js");
+      if (fs.existsSync(cliPath)) {
+        let version = null;
+        try {
+          version = require(pkgJsonPath).version;
+        } catch (_) {
+          /* ignore */
+        }
+        return { cliPath, version, pkg };
+      }
+    } catch (_) {
+      // try next package name
+    }
+  }
+  return { cliPath: null, version: null, pkg: null };
+}
+
+/**
+ * Build the EXACT install command that matches the bundled Playwright build.
+ * Used both to run the install and as the fallback message shown to the user.
+ * @returns {string}
+ */
+function getInstallCommandString() {
+  const { cliPath } = resolveBundledPlaywright();
+  if (cliPath) {
+    return `node "${cliPath}" install chromium`;
+  }
+  return "npx playwright install chromium";
+}
+
+/**
+ * Install the chromium browser using the BUNDLED Playwright's own installer,
+ * so the browser build can never mismatch the bundled Playwright version.
+ * @param {(msg: string) => void} logger
+ * @returns {boolean} whether the install command ran successfully
+ */
+function installBundledChromium(logger = console.log) {
+  const { cliPath, version } = resolveBundledPlaywright();
+  if (!cliPath) {
+    return false;
+  }
+
+  logger(
+    `\n⬇️  Installing the Chromium build for Playwright${
+      version ? ` ${version}` : ""
+    } (one-time setup)...`
+  );
+
+  // Install both the headless shell and full chromium so any launch path works.
+  const result = spawnSync(
+    process.execPath,
+    [cliPath, "install", "chromium", "chromium-headless-shell"],
+    { stdio: "inherit" }
+  );
+
+  if (result.error || result.status !== 0) {
+    logger(
+      `\n⚠ Automatic browser install failed. Please run this command manually:\n    ${getInstallCommandString()}\n`
+    );
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Determine whether an error is Playwright's "missing browser executable" error.
+ * @param {Error} err
+ * @returns {boolean}
+ */
+function isMissingExecutableError(err) {
+  return !!err && MISSING_EXECUTABLE_RE.test(err.message || "");
+}
+
+/**
+ * Launch chromium, auto-installing the matching browser build on first run if
+ * the executable is missing. Retries the launch exactly once after installing.
+ *
+ * @param {import('playwright').BrowserType} chromium - the bundled chromium type
+ * @param {Object} launchOptions - options passed to chromium.launch()
+ * @param {(msg: string) => void} [logger]
+ * @returns {Promise<import('playwright').Browser>}
+ */
+async function launchChromium(chromium, launchOptions = {}, logger = console.log) {
+  try {
+    return await chromium.launch(launchOptions);
+  } catch (err) {
+    if (!isMissingExecutableError(err)) {
+      throw err;
+    }
+
+    // Only attempt the auto-install once per process to avoid loops.
+    if (installAttempted) {
+      const e = new Error(
+        `${err.message}\n\nThe Chromium build for this CLI is missing. Run:\n    ${getInstallCommandString()}`
+      );
+      throw e;
+    }
+    installAttempted = true;
+
+    const installed = installBundledChromium(logger);
+    if (!installed) {
+      const e = new Error(
+        `${err.message}\n\nThe Chromium build for this CLI is missing. Run:\n    ${getInstallCommandString()}`
+      );
+      throw e;
+    }
+
+    // Retry once now that the matching browser build is installed.
+    return await chromium.launch(launchOptions);
+  }
+}
+
+module.exports = {
+  launchChromium,
+  installBundledChromium,
+  isMissingExecutableError,
+  getInstallCommandString,
+  resolveBundledPlaywright,
+};

package/src/lib/output-path-template.js

@@ -54,8 +54,8 @@ const TEMPLATE_PRESETS = {
   // GitHub Pages / Static site friendly
   "static-site": "./public/screenshots/{{locale}}/{{scenario}}/{{name}}.{{ext}}",
   
-  // CI/CD artifacts
-  ci: "./artifacts/screenshots/{{scenario}}/{{viewport}}/{{variant}}/{{name}}.{{ext}}",
+  // Local CLI artifacts
+  cli: "./artifacts/screenshots/{{scenario}}/{{viewport}}/{{variant}}/{{name}}.{{ext}}",
 };
 
 /**
@@ -291,7 +291,7 @@ function getTemplatePresets() {
     { name: "docs", template: TEMPLATE_PRESETS.docs, description: "Simple docs asset structure" },
     { name: "variant-matrix", template: TEMPLATE_PRESETS["variant-matrix"], description: "Hierarchical by variant dimensions" },
     { name: "static-site", template: TEMPLATE_PRESETS["static-site"], description: "GitHub Pages / static site friendly" },
-    { name: "ci", template: TEMPLATE_PRESETS.ci, description: "CI/CD artifact organization" },
+    { name: "cli", template: TEMPLATE_PRESETS.cli, description: "Local CLI artifact organization" },
   ];
 }