@reshotdev/screenshot 0.0.1-beta.1 → 0.0.1-beta.11

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",
@@ -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 });
 }
 
 /**
@@ -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/record-cdp.js

@@ -2,6 +2,9 @@
 const { chromium } = require("playwright");
 const chalk = require("chalk");
 const http = require("http");
+const fs = require("fs-extra");
+const path = require("path");
+const os = require("os");
 
 /**
  * Check if Chrome CDP endpoint is available
@@ -418,15 +421,14 @@ async function saveSessionState(outputPath) {
       console.log(chalk.gray(`    Sanitized cookies: ${stats.fixed} fixed, ${stats.removed} removed, ${stats.stripped} stripped`));
     }
 
-    // Ensure directory exists
-    const fs = require("fs-extra");
-    const path = require("path");
-    fs.ensureDirSync(path.dirname(outputPath));
-
-    // Write storage state to file
-    fs.writeJsonSync(outputPath, storageState, { spaces: 2 });
+    const activePageUrl = page?.url?.() || null;
+    const artifactInfo = writeSessionArtifacts(outputPath, storageState, {
+      pageUrl: activePageUrl,
+      baseUrl: activePageUrl,
+    });
 
     console.log(chalk.green(`  ✔ Session saved to: ${outputPath}`));
+    console.log(chalk.gray(`    Metadata: ${artifactInfo.metadataPath}`));
     console.log(chalk.gray(`    Cookies: ${storageState.cookies?.length || 0}`));
     console.log(chalk.gray(`    Origins with localStorage: ${storageState.origins?.length || 0}`));
     
@@ -445,11 +447,249 @@ async function saveSessionState(outputPath) {
  * @returns {string}
  */
 function getDefaultSessionPath() {
-  const path = require("path");
-  const os = require("os");
   return path.join(os.homedir(), ".reshot", "session-state.json");
 }
 
+function getSessionMetadataPath(sessionPath = getDefaultSessionPath()) {
+  if (sessionPath.endsWith(".json")) {
+    return sessionPath.replace(/\.json$/i, ".meta.json");
+  }
+
+  return `${sessionPath}.meta.json`;
+}
+
+function normalizeOrigin(value) {
+  if (!value || typeof value !== "string") {
+    return null;
+  }
+
+  try {
+    return new URL(value).origin.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+function normalizeCookieDomain(domain) {
+  if (!domain || typeof domain !== "string") {
+    return null;
+  }
+
+  return domain.replace(/^\./, "").toLowerCase();
+}
+
+function extractSessionEvidence(storageState) {
+  const storageOrigins = Array.from(
+    new Set(
+      (storageState?.origins || [])
+        .map((origin) => normalizeOrigin(origin?.origin))
+        .filter(Boolean),
+    ),
+  );
+
+  const cookieDomains = Array.from(
+    new Set(
+      (storageState?.cookies || [])
+        .map((cookie) => normalizeCookieDomain(cookie?.domain))
+        .filter(Boolean),
+    ),
+  );
+
+  return { storageOrigins, cookieDomains };
+}
+
+function buildSessionMetadata(options = {}) {
+  const {
+    baseUrl = null,
+    pageUrl = null,
+    storageState = null,
+    capturedAt = new Date().toISOString(),
+  } = options;
+  const evidence = extractSessionEvidence(storageState);
+
+  return {
+    version: 1,
+    capturedAt,
+    sourceUrl: pageUrl || baseUrl || null,
+    sourceOrigin:
+      normalizeOrigin(pageUrl) ||
+      normalizeOrigin(baseUrl) ||
+      evidence.storageOrigins[0] ||
+      null,
+    storageOrigins: evidence.storageOrigins,
+    cookieDomains: evidence.cookieDomains,
+  };
+}
+
+function writeSessionArtifacts(sessionPath, storageState, options = {}) {
+  const metadataPath = getSessionMetadataPath(sessionPath);
+  const metadata = buildSessionMetadata({ ...options, storageState });
+
+  fs.ensureDirSync(path.dirname(sessionPath));
+  fs.writeJsonSync(sessionPath, storageState, { spaces: 2 });
+  fs.writeJsonSync(metadataPath, metadata, { spaces: 2 });
+
+  return { sessionPath, metadataPath, metadata };
+}
+
+function readSessionMetadata(sessionPath = getDefaultSessionPath()) {
+  const metadataPath = getSessionMetadataPath(sessionPath);
+
+  if (!fs.existsSync(metadataPath)) {
+    return {
+      exists: false,
+      metadataPath,
+      metadata: null,
+      error: null,
+    };
+  }
+
+  try {
+    return {
+      exists: true,
+      metadataPath,
+      metadata: fs.readJsonSync(metadataPath),
+      error: null,
+    };
+  } catch (error) {
+    return {
+      exists: true,
+      metadataPath,
+      metadata: null,
+      error: error.message,
+    };
+  }
+}
+
+function sessionHostMatchesCookieDomains(hostname, cookieDomains) {
+  if (!hostname) {
+    return false;
+  }
+
+  return cookieDomains.some(
+    (domain) => hostname === domain || hostname.endsWith(`.${domain}`),
+  );
+}
+
+function assessSessionHealth(
+  sessionPath = getDefaultSessionPath(),
+  baseUrl = null,
+  options = {},
+) {
+  const maxAgeMinutes = Number.isFinite(options.maxAgeMinutes)
+    ? options.maxAgeMinutes
+    : 360;
+  const expectedOrigin = normalizeOrigin(baseUrl);
+  const result = {
+    ok: false,
+    exists: fs.existsSync(sessionPath),
+    sessionPath,
+    metadataPath: getSessionMetadataPath(sessionPath),
+    expectedOrigin,
+    compatible: true,
+    stale: false,
+    ageMinutes: null,
+    metadata: null,
+    warnings: [],
+    issues: [],
+    evidence: {
+      sourceOrigin: null,
+      storageOrigins: [],
+      cookieDomains: [],
+      matchSource: null,
+    },
+  };
+
+  if (!result.exists) {
+    return result;
+  }
+
+  let storageState = null;
+  try {
+    storageState = fs.readJsonSync(sessionPath);
+  } catch (error) {
+    result.compatible = false;
+    result.issues.push(`Cached session file is unreadable: ${error.message}`);
+    return result;
+  }
+
+  const metadataInfo = readSessionMetadata(sessionPath);
+  if (metadataInfo.error) {
+    result.warnings.push(`Session metadata is unreadable: ${metadataInfo.error}`);
+  } else if (!metadataInfo.exists) {
+    result.warnings.push(
+      "Session metadata is missing; compatibility was inferred from stored cookies and origins.",
+    );
+  }
+
+  const inferredEvidence = extractSessionEvidence(storageState);
+  const metadata = metadataInfo.metadata || null;
+  const storageOrigins =
+    metadata?.storageOrigins
+      ?.map((origin) => normalizeOrigin(origin))
+      .filter(Boolean) || inferredEvidence.storageOrigins;
+  const cookieDomains =
+    metadata?.cookieDomains
+      ?.map((domain) => normalizeCookieDomain(domain))
+      .filter(Boolean) || inferredEvidence.cookieDomains;
+  const sourceOrigin =
+    normalizeOrigin(metadata?.sourceOrigin) ||
+    normalizeOrigin(metadata?.sourceUrl) ||
+    inferredEvidence.storageOrigins[0] ||
+    null;
+
+  result.metadata = metadata;
+  result.evidence = {
+    sourceOrigin,
+    storageOrigins,
+    cookieDomains,
+    matchSource: null,
+  };
+
+  const capturedAtMs = Date.parse(metadata?.capturedAt || "");
+  const sessionStat = fs.statSync(sessionPath);
+  const referenceTime = Number.isFinite(capturedAtMs)
+    ? capturedAtMs
+    : sessionStat.mtimeMs;
+  result.ageMinutes = Math.max(
+    0,
+    Math.round((Date.now() - referenceTime) / 60000),
+  );
+  result.stale = result.ageMinutes >= maxAgeMinutes;
+
+  if (expectedOrigin) {
+    const expectedHost = new URL(baseUrl).hostname.toLowerCase();
+    const matchesSourceOrigin = sourceOrigin === expectedOrigin;
+    const matchesStorageOrigin = storageOrigins.includes(expectedOrigin);
+    const matchesCookieDomain = sessionHostMatchesCookieDomains(
+      expectedHost,
+      cookieDomains,
+    );
+
+    result.evidence.matchSource = matchesSourceOrigin
+      ? "sourceOrigin"
+      : matchesStorageOrigin
+        ? "storageOrigins"
+        : matchesCookieDomain
+          ? "cookieDomains"
+          : null;
+
+    const hasEvidence =
+      Boolean(sourceOrigin) ||
+      storageOrigins.length > 0 ||
+      cookieDomains.length > 0;
+    if (hasEvidence && !result.evidence.matchSource) {
+      result.compatible = false;
+      result.issues.push(
+        `Cached session targets ${sourceOrigin || storageOrigins[0] || cookieDomains[0]}, not ${expectedOrigin}.`,
+      );
+    }
+  }
+
+  result.ok = result.compatible && result.issues.length === 0;
+  return result;
+}
+
 /**
  * Quietly check if CDP is available and sync the session if so.
  * This is called automatically before captures to use the live browser session.
@@ -459,13 +699,24 @@ function getDefaultSessionPath() {
  */
 async function autoSyncSessionFromCDP(outputPath = null, logger = null) {
   const log = logger || (() => {}); // Quiet by default
-  const fs = require("fs-extra");
-  const path = require("path");
-  const os = require("os");
-  
+
+  // Allow disabling CDP sync via env var (useful when session was created programmatically)
+  if (process.env.RESHOT_SKIP_CDP_SYNC === "1") {
+    return { synced: false, reason: "disabled" };
+  }
+
   const sessionPath = outputPath || path.join(os.homedir(), ".reshot", "session-state.json");
-  
+
   try {
+    // Skip sync if cached session is very recent (likely just generated programmatically)
+    if (fs.existsSync(sessionPath)) {
+      const cachedAge = Date.now() - fs.statSync(sessionPath).mtimeMs;
+      if (cachedAge < 5 * 60 * 1000) {
+        log(chalk.gray("  → Cached session is fresh (<5min), skipping CDP sync"));
+        return { synced: false, reason: "cached_fresh" };
+      }
+    }
+
     // Step 1: Check if CDP endpoint is available (quietly)
     const endpointCheck = await checkCdpEndpoint("localhost", 9222);
     
@@ -513,9 +764,25 @@ async function autoSyncSessionFromCDP(outputPath = null, logger = null) {
         return { synced: false, reason: "empty_session" };
       }
 
+      const activePage =
+        context
+          .pages()
+          .find((candidate) => {
+            const currentUrl = candidate.url();
+            return (
+              currentUrl &&
+              !currentUrl.startsWith("chrome://") &&
+              !currentUrl.startsWith("devtools://") &&
+              !currentUrl.startsWith("chrome-extension://")
+            );
+          }) || context.pages()[0] || null;
+      const activePageUrl = activePage?.url?.() || null;
+
       // Step 4: Save to file
-      fs.ensureDirSync(path.dirname(sessionPath));
-      fs.writeJsonSync(sessionPath, storageState, { spaces: 2 });
+      writeSessionArtifacts(sessionPath, storageState, {
+        pageUrl: activePageUrl,
+        baseUrl: activePageUrl,
+      });
 
       log(chalk.green(`  ✔ Auto-synced session from CDP browser`));
       log(chalk.gray(`    Cookies: ${storageState.cookies?.length || 0}, localStorage origins: ${storageState.origins?.length || 0}`));
@@ -607,6 +874,11 @@ module.exports = {
   printChromeInstructions,
   saveSessionState,
   getDefaultSessionPath,
+  getSessionMetadataPath,
   autoSyncSessionFromCDP,
   sanitizeStorageState,
+  buildSessionMetadata,
+  writeSessionArtifacts,
+  readSessionMetadata,
+  assessSessionHealth,
 };

package/src/lib/record-config.js

@@ -600,7 +600,7 @@ async function finalizeScenarioAndWriteConfig(
 
   console.log(
     chalk.green(
-      "\n✔ docsync.config.json has been updated. Please review and commit the changes to your repository.\n"
+      "\n✔ reshot.config.json has been updated. Please review and commit the changes to your repository.\n"
     )
   );
   console.log(chalk.gray(`Scenario: ${result.scenarioName}`));