@reshotdev/screenshot 0.0.1-beta.12 → 0.0.1-beta.14

package/src/commands/variation.js

@@ -0,0 +1,194 @@
+// variation.js - Render variations from a captured DOM scene.
+//
+// Workflow:
+//   1. Resolve the source MHTML — either from the local .reshot/output tree
+//      or by downloading from the platform CDN (R2 public URL stored on
+//      the VisualVersion as domSceneS3Path).
+//   2. Open the MHTML in a fresh headless Chromium.
+//   3. Apply the variation manifest (JS mutations + viewport).
+//   4. Screenshot.
+//
+// This is the v1 marketing-operator entry point. The dashboard UI on top
+// of it is the next deliverable; the CLI exists so the loop is usable
+// the moment Phase 1 ships.
+//
+// Manifest format (JSON):
+//
+//   {
+//     "viewport": { "width": 1440, "height": 900, "deviceScaleFactor": 2 },
+//     "colorScheme": "light" | "dark",
+//     "mutations": [
+//       { "remove": "aside, nav" },                          // delete elements
+//       { "replaceText": [
+//           { "find": "ari@tempo.example", "with": "alice@acme.com" }
+//       ]},
+//       { "limit": { "selector": "tbody tr", "count": 5 } }, // keep first N
+//       { "setText": { "selector": "[data-author]", "text": "alice@acme.com" } },
+//       { "setAttr": { "selector": "img.logo", "name": "src", "value": "..." } },
+//       { "evaluate": "/* arbitrary page.evaluate script */" }
+//     ]
+//   }
+
+const fs = require("fs-extra");
+const path = require("node:path");
+const chalk = require("chalk");
+const { chromium } = require("playwright");
+
+/**
+ * Runs in the browser context. Pure function — no closures over Node
+ * state. `manifestJson` is the only input. Keep this synchronous; if
+ * the page has React rehydration scripts, give them time before calling
+ * by waiting in the caller, then apply mutations as the *last* DOM
+ * write so they aren't immediately overwritten.
+ */
+function applyMutationsInBrowser(manifestJson) {
+  const m = JSON.parse(manifestJson);
+  for (const mut of m.mutations || []) {
+    if (mut.remove) {
+      document.querySelectorAll(mut.remove).forEach((el) => el.remove());
+    }
+    if (mut.replaceText) {
+      for (const r of mut.replaceText) {
+        document.body.innerHTML = document.body.innerHTML
+          .split(r.find)
+          .join(r.with);
+      }
+    }
+    if (mut.limit) {
+      const els = document.querySelectorAll(mut.limit.selector);
+      els.forEach((el, i) => {
+        if (i >= mut.limit.count) el.remove();
+      });
+    }
+    if (mut.setText) {
+      document.querySelectorAll(mut.setText.selector).forEach((el) => {
+        el.textContent = mut.setText.text;
+      });
+    }
+    if (mut.setAttr) {
+      document.querySelectorAll(mut.setAttr.selector).forEach((el) => {
+        el.setAttribute(mut.setAttr.name, mut.setAttr.value);
+      });
+    }
+    if (mut.evaluate) {
+      // eslint-disable-next-line no-new-func
+      new Function(mut.evaluate)();
+    }
+  }
+}
+
+async function resolveSourceMhtml({ source, scenarioKey, captureKey, theme }) {
+  // 1) Explicit HTTPS URL → download to tmp, return local path. The local
+  // file MUST end in .mhtml — Chromium detects MHTML by extension, not by
+  // sniffing magic bytes, and our CDN serves under .related (the extension
+  // derived from multipart/related contentType).
+  if (source && /^https?:\/\//.test(source)) {
+    const tmpDir = path.join(require("os").tmpdir(), "reshot-variation");
+    fs.ensureDirSync(tmpDir);
+    const localPath = path.join(tmpDir, `${Date.now()}-variation.mhtml`);
+    const res = await fetch(source);
+    if (!res.ok) {
+      throw new Error(`Failed to fetch source MHTML: ${res.status} ${res.statusText}`);
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    await fs.writeFile(localPath, buf);
+    return { kind: "remote", path: localPath };
+  }
+
+  // 2) Explicit local path
+  if (source && fs.existsSync(source)) {
+    return { kind: "local", path: source };
+  }
+
+  // 3) Look in .reshot/output tree
+  if (scenarioKey && captureKey) {
+    const root = path.join(process.cwd(), ".reshot", "output", scenarioKey);
+    if (fs.existsSync(root)) {
+      const runs = fs.readdirSync(root)
+        .filter((d) => /^\d{4}-\d{2}-\d{2}/.test(d))
+        .sort()
+        .reverse();
+      for (const run of runs) {
+        const candidate = path.join(
+          root,
+          run,
+          theme ? `theme-${theme}` : "default",
+          `${captureKey}.mhtml`,
+        );
+        if (fs.existsSync(candidate)) {
+          return { kind: "local", path: candidate };
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+async function variationCommand(options) {
+  const {
+    source,
+    scenario,
+    capture,
+    theme = "light",
+    manifest: manifestPath,
+    output,
+    headless = true,
+  } = options;
+
+  if (!manifestPath || !fs.existsSync(manifestPath)) {
+    throw new Error(`Manifest not found: ${manifestPath}`);
+  }
+  if (!output) {
+    throw new Error("--output <path.png> is required");
+  }
+
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  const viewport = manifest.viewport || {
+    width: 1440,
+    height: 900,
+    deviceScaleFactor: 2,
+  };
+
+  console.log(chalk.cyan("🎨 Variation render"));
+  console.log(chalk.gray(`   manifest: ${manifestPath}`));
+
+  const sourceRef = await resolveSourceMhtml({
+    source,
+    scenarioKey: scenario,
+    captureKey: capture,
+    theme,
+  });
+  if (!sourceRef) {
+    throw new Error(
+      "Could not resolve source MHTML. Provide --source <path> or --scenario <key> --capture <key>.",
+    );
+  }
+  console.log(chalk.gray(`   source: ${sourceRef.path}`));
+
+  const browser = await chromium.launch({ headless });
+  const ctx = await browser.newContext({
+    viewport: { width: viewport.width, height: viewport.height },
+    deviceScaleFactor: viewport.deviceScaleFactor || 2,
+    colorScheme: manifest.colorScheme === "dark" ? "dark" : "light",
+    javaScriptEnabled: true,
+  });
+  const page = await ctx.newPage();
+
+  const fileUrl = `file://${path.resolve(sourceRef.path)}`;
+  await page.goto(fileUrl, { waitUntil: "domcontentloaded" });
+  await page.waitForLoadState("load");
+  await page.waitForTimeout(400);
+
+  if (manifest.mutations?.length) {
+    await page.evaluate(applyMutationsInBrowser, JSON.stringify(manifest));
+    await page.waitForTimeout(200);
+  }
+
+  fs.ensureDirSync(path.dirname(output));
+  await page.screenshot({ path: output });
+  console.log(chalk.green(`✔ Rendered: ${output}`));
+  await browser.close();
+}
+
+module.exports = variationCommand;

package/src/index.js

@@ -8,6 +8,8 @@ require("dotenv").config({
 
 const { Command } = require("commander");
 const chalk = require("chalk");
+const fs = require("fs-extra");
+const path = require("path");
 const pkg = require("../package.json");
 
 const program = new Command();
@@ -26,18 +28,59 @@ program
   .command("setup")
   .description("Set up the local or hosted workflow from scratch")
   .option("--offline", "Stay local-only and skip hosted authentication")
+  .option("--project <id>", "Connect setup to an existing Reshot project")
+  .option("--token <token>", "Publish token for non-interactive project linking")
   .option("--no-studio", "Skip offering to launch Studio after setup")
   .option("--force", "Force re-initialization even if already set up")
   .action(async (options) => {
     try {
       const setupWizard = require("./commands/setup-wizard");
-      await setupWizard(options);
+      // Commander stores `--no-studio` as `options.studio === false`, not
+      // `options.noStudio`. Normalize it so the flag is honored end-to-end.
+      await setupWizard({ ...options, noStudio: options.studio === false });
     } catch (error) {
       console.error(chalk.red("Error:"), error.message);
       process.exit(1);
     }
   });
 
+program
+  .command("record-clip [target]")
+  .description("Record a scenario as a summary MP4 (alias for `reshot run --format summary-video`)")
+  .option("-s, --scenarios <keys>", "Comma-separated scenario keys")
+  .option("--out <dir>", "Copy the generated MP4 and metadata into this directory")
+  .option("--no-headless", "Run browser in visible mode")
+  .option("--debug", "Enable verbose debug logging")
+  .action(async (target, options) => {
+    if (options.debug) {
+      process.env.RESHOT_DEBUG = "1";
+    }
+    try {
+      const runCommand = require("./commands/run");
+      const scenarioKeys = resolveRecordClipScenarioKeys(target, options);
+      const result = await runCommand({
+        scenarioKeys,
+        headless: options.headless,
+        format: "summary-video",
+        noExit: true,
+      });
+
+      if (options.out && result?.success !== false) {
+        await copyRecordClipOutputs(result, target, options.out);
+      }
+
+      if (result?.success === false) {
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error(chalk.red("Error:"), error.message);
+      if (options.debug && error.stack) {
+        console.error(chalk.gray(error.stack));
+      }
+      process.exit(1);
+    }
+  });
+
 program.addHelpText(
   "after",
   `
@@ -113,7 +156,7 @@ program
 
 // Run: Execute scenarios from config (automated visual capture)
 program
-  .command("run")
+  .command("run [target]")
   .description("Execute visual capture scenarios from config")
   .option("-s, --scenarios <keys>", "Comma-separated list of scenario keys")
   .option("--no-headless", "Run browser in visible mode")
@@ -135,15 +178,13 @@ program
   .option("--no-style", "Disable style processing")
   .option("--cloud", "Compare against cloud baselines")
   .option("--debug", "Enable verbose debug logging")
-  .action(async (options) => {
+  .action(async (target, options) => {
     if (options.debug) {
       process.env.RESHOT_DEBUG = "1";
     }
     try {
       const runCommand = require("./commands/run");
-      const scenarioKeys = options.scenarios
-        ? options.scenarios.split(",").map((s) => s.trim())
-        : null;
+      const scenarioKeys = resolveScenarioKeysFromTarget(target, options);
       await runCommand({
         scenarioKeys,
         headless: options.headless,
@@ -297,6 +338,18 @@ program
     }
   });
 
+// Compose: Render a local JSX composition into a video pack
+const { registerCompose } = require("./commands/compose");
+registerCompose(program);
+
+// Capture-DOM: Capture a self-contained DOM reconstruction artifact from a URL
+const { registerCaptureDom } = require("./commands/capture-dom");
+registerCaptureDom(program);
+
+// Refresh: Phase 5 auto-update loop — recapture, drift-check, re-publish or flag
+const { registerRefresh } = require("./commands/refresh");
+registerRefresh(program);
+
 // ============================================================================
 // PUBLISHING & INTEGRATION COMMANDS
 // ============================================================================
@@ -317,12 +370,37 @@ program
   .action(async (options) => {
     try {
       const publishCommand = require("./commands/publish");
-      await publishCommand({
+      const result = await publishCommand({
         ...options,
         outputJson: options.outputJson,
         autoApprove: options.autoApprove,
         skipReleaseDoctor: options.skipReleaseDoctor,
       });
+      if (result && result.success === false) {
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error(chalk.red("Error:"), error.message);
+      process.exit(1);
+    }
+  });
+
+// Variation: Render a variation from a captured DOM scene (MHTML).
+// Beta — see docs/variation-pipeline.md.
+program
+  .command("variation")
+  .description("Render a variation from a captured DOM scene (beta)")
+  .option("-s, --source <path>", "Path to source .mhtml (overrides --scenario/--capture)")
+  .option("--scenario <key>", "Scenario key under .reshot/output/")
+  .option("--capture <key>", "Capture key (e.g., 'observation-detail')")
+  .option("--theme <name>", "Theme variant: light | dark", "light")
+  .option("-m, --manifest <path>", "Path to variation manifest (.json)")
+  .option("-o, --output <path>", "Output PNG path")
+  .option("--no-headless", "Run browser visibly for debugging")
+  .action(async (options) => {
+    try {
+      const variationCommand = require("./commands/variation");
+      await variationCommand(options);
     } catch (error) {
       console.error(chalk.red("Error:"), error.message);
       process.exit(1);
@@ -336,7 +414,7 @@ program
   .option("-f, --format <format>", "Output format: json, ts, csv", "json")
   .option("-o, --output <path>", "Output file path")
   .option("--full", "Include full metadata in TypeScript output")
-  .option("--status <status>", "Filter: approved, pending, all", "approved")
+  .option("--status <status>", "Filter: approved, pending, all", "all")
   .action(async (options) => {
     try {
       const pullCommand = require("./commands/pull");
@@ -359,6 +437,7 @@ doctor
   .command("target")
   .description("Audit the certified target contract before capture")
   .option("-s, --scenarios <keys>", "Comma-separated list of scenario keys")
+  .option("--timeout <ms>", "Per-step timeout in milliseconds (default 15000)")
   .option("--json", "Output JSON report")
   .action(async (options) => {
     try {
@@ -469,7 +548,23 @@ Actions:
 // Auth: Standalone authentication (for re-auth scenarios)
 const auth = program
   .command("auth")
-  .description("Authenticate with Reshot Cloud (or set RESHOT_API_KEY + RESHOT_PROJECT_ID env vars)")
+  .description(
+    "Link this CLI to a Reshot project. Opens a browser to approve the session and stores a project API key locally.",
+  )
+  .addHelpText(
+    "after",
+    `
+Authentication paths:
+  Interactive (default)   Opens your browser, you approve the session, and the
+                          CLI saves a project API key to .reshot/settings.json.
+  Non-interactive (CI)    Set RESHOT_API_KEY and RESHOT_PROJECT_ID and the CLI
+                          links without any browser or prompt.
+
+Examples:
+  reshot auth                                  Browser-based login
+  RESHOT_API_KEY=… RESHOT_PROJECT_ID=… reshot auth   Headless / CI login
+`,
+  )
   .action(async () => {
     try {
       const authCommand = require("./commands/auth");
@@ -482,7 +577,24 @@ const auth = program
 
 auth
   .command("login")
-  .description("Compatibility alias for `reshot auth`")
+  .description(
+    "Alias for `reshot auth` — opens the browser approval flow (or uses RESHOT_API_KEY in CI).",
+  )
+  .action(async () => {
+    try {
+      const authCommand = require("./commands/auth");
+      await authCommand();
+    } catch (error) {
+      console.error(chalk.red("Error:"), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("login")
+  .description(
+    "Alias for `reshot auth` — link this CLI to a project via browser approval (or RESHOT_API_KEY in CI).",
+  )
   .action(async () => {
     try {
       const authCommand = require("./commands/auth");
@@ -523,4 +635,72 @@ program
     }
   });
 
+function resolveRecordClipScenarioKeys(target, options = {}) {
+  return resolveScenarioKeysFromTarget(target, options);
+}
+
+function resolveScenarioKeysFromTarget(target, options = {}) {
+  if (options.scenarios) {
+    return options.scenarios.split(",").map((value) => value.trim()).filter(Boolean);
+  }
+
+  if (!target) {
+    return null;
+  }
+
+  const absoluteTarget = path.resolve(process.cwd(), target);
+  if (!fs.existsSync(absoluteTarget)) {
+    return [target];
+  }
+
+  const source = fs.readFileSync(absoluteTarget, "utf8");
+  const config = require("./lib/config").readConfig();
+  const scenarios = config.scenarios || [];
+  const mentioned = scenarios.find((scenario) => source.includes(scenario.key));
+  if (mentioned) {
+    return [mentioned.key];
+  }
+
+  const basename = path.basename(target).replace(/\.(spec\.)?[cm]?[tj]sx?$/i, "");
+  const byName = scenarios.find((scenario) => {
+    const normalizedKey = String(scenario.key || "").replace(/^dogfood-/, "");
+    return scenario.key === basename || normalizedKey === basename;
+  });
+  if (byName) {
+    return [byName.key];
+  }
+
+  throw new Error(
+    `Could not map ${target} to a configured scenario. Add the scenario key to the spec file or pass --scenarios <key>.`,
+  );
+}
+
+async function copyRecordClipOutputs(result, target, outDir) {
+  const firstScenario = (result.results || []).find((item) => item?.success !== false);
+  const outputDir = firstScenario?.outputDir;
+  if (!outputDir) {
+    throw new Error("No summary-video output directory was produced.");
+  }
+
+  const slug = target
+    ? path.basename(target).replace(/\.(spec\.)?[cm]?[tj]sx?$/i, "")
+    : firstScenario.key || "summary-video";
+  const destinationDir = path.resolve(process.cwd(), outDir);
+  await fs.ensureDir(destinationDir);
+
+  const copies = [
+    ["summary-video.mp4", `${slug}.mp4`],
+    ["summary-video.metadata.json", `${slug}.metadata.json`],
+    ["sentinels.json", `${slug}.sentinels.json`],
+  ];
+
+  for (const [fromName, toName] of copies) {
+    const sourcePath = path.join(outputDir, fromName);
+    if (await fs.pathExists(sourcePath)) {
+      await fs.copy(sourcePath, path.join(destinationDir, toName));
+      console.log(chalk.gray(`  copied ${toName}`));
+    }
+  }
+}
+
 program.parse(process.argv);

package/src/lib/api-client.js

@@ -119,6 +119,17 @@ async function withRetry(fn, options = {}) {
         throw error;
       }
 
+      // Respect Retry-After header on 429 rate limit responses
+      const retryAfterHeader = error.response?.headers?.["retry-after"];
+      if (retryAfterHeader && statusCode === 429) {
+        const retryMs = (parseInt(retryAfterHeader, 10) || 5) * 1000;
+        console.log(
+          `  ⚠ Rate limited (attempt ${attempt}/${maxRetries}), retrying in ${retryMs / 1000}s...`,
+        );
+        await sleep(retryMs);
+        continue;
+      }
+
       // Calculate delay with exponential backoff + jitter
       const delay = Math.min(
         initialDelay * Math.pow(2, attempt - 1) + Math.random() * 1000,
@@ -649,17 +660,21 @@ async function publishBatch(apiKey, payload) {
     throw new Error("API key is required to publish");
   }
 
-  const response = await axios.post(`${baseUrl}/v1/publish/batch`, payload, {
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: `Bearer ${apiKey}`,
+  return withRetry(
+    async () => {
+      const response = await axios.post(`${baseUrl}/v1/publish/batch`, payload, {
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`,
+        },
+        timeout: 60000,
+        maxBodyLength: Infinity,
+        maxContentLength: Infinity,
+      });
+      return response.data;
     },
-    timeout: 60000,
-    maxBodyLength: Infinity,
-    maxContentLength: Infinity,
-  });
-
-  return response.data;
+    { maxRetries: 2, retryOn: [500, 502, 503, 504, 429, "ECONNRESET", "ETIMEDOUT"] },
+  );
 }
 
 /**
@@ -809,40 +824,49 @@ async function commitIngest(apiKey, projectId, uploadResults, git, cli) {
  * Get drift records for a project
  */
 async function getDrifts(apiKey, projectId, options = {}) {
-  return withRetry(async () => {
-    const params = new URLSearchParams();
-    if (options.status) params.set("status", options.status);
-    if (options.journeyKey) params.set("journeyKey", options.journeyKey);
+  const params = new URLSearchParams();
+  if (options.status) params.set("status", options.status);
+  if (options.journeyKey) params.set("journeyKey", options.journeyKey);
+  const endpoint = `${baseUrl}/v1/projects/${projectId}/drifts?${params.toString()}`;
 
-    const response = await axios.get(
-      `${baseUrl}/v1/projects/${projectId}/drifts?${params.toString()}`,
-      {
+  try {
+    return await withRetry(async () => {
+      const response = await axios.get(endpoint, {
         headers: { Authorization: `Bearer ${apiKey}` },
         timeout: 30000,
-      },
-    );
-    return response.data;
-  });
+      });
+      return response.data;
+    });
+  } catch (error) {
+    // Surface HTTP status + endpoint + server message instead of axios's
+    // bare "Request failed with status code N".
+    throw createApiError("Drifts request failed", endpoint, error);
+  }
 }
 
 /**
  * Get sync jobs for a project
  */
 async function getSyncJobs(apiKey, projectId, options = {}) {
-  return withRetry(async () => {
-    const response = await axios.post(
-      `${baseUrl}/v1/projects/${projectId}/sync-jobs`,
-      {
-        limit: options.limit || 10,
-        status: options.status,
-      },
-      {
-        headers: { Authorization: `Bearer ${apiKey}` },
-        timeout: 30000,
-      },
-    );
-    return response.data;
-  });
+  const endpoint = `${baseUrl}/v1/projects/${projectId}/sync-jobs`;
+  try {
+    return await withRetry(async () => {
+      const response = await axios.post(
+        endpoint,
+        {
+          limit: options.limit || 10,
+          status: options.status,
+        },
+        {
+          headers: { Authorization: `Bearer ${apiKey}` },
+          timeout: 30000,
+        },
+      );
+      return response.data;
+    });
+  } catch (error) {
+    throw createApiError("Sync jobs request failed", endpoint, error);
+  }
 }
 
 /**
@@ -898,4 +922,6 @@ module.exports = {
   getDrifts,
   getSyncJobs,
   driftAction,
+  // Testing
+  withRetry,
 };