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

package/src/lib/certification.js

@@ -372,7 +372,12 @@ async function runDoctorTarget(options = {}) {
   const docSyncConfig = config.readConfig();
   const target = docSyncConfig.target;
   const scenarios = getSelectedScenarios(docSyncConfig, options.scenarioKeys);
-  const timeoutMs = options.timeoutMs || 30_000;
+  const timeoutMs = options.timeoutMs || 15_000;
+  // Overall budget so the command fails fast instead of grinding through every
+  // scenario at the full per-step timeout (which read as an indefinite hang).
+  const overallTimeoutMs = options.overallTimeoutMs || Math.max(timeoutMs * 4, 60_000);
+  const startedAt = Date.now();
+  const overBudget = () => Date.now() - startedAt > overallTimeoutMs;
   const onProgress =
     typeof options.onProgress === "function" ? options.onProgress : null;
 
@@ -402,7 +407,23 @@ async function runDoctorTarget(options = {}) {
   const advisories = [];
   const info = [];
 
+  let budgetExceeded = false;
   for (const scenario of scenarios) {
+    if (overBudget()) {
+      budgetExceeded = true;
+      onProgress?.(
+        `Overall doctor budget (${overallTimeoutMs}ms) exceeded — stopping before "${scenario.key}".`,
+      );
+      blockingIssues.push(
+        createIssue(
+          "blocking",
+          "doctor_timeout",
+          `Target doctor exceeded its overall time budget of ${overallTimeoutMs}ms. Remaining scenarios were not audited.`,
+          { auditedScenarios: readinessAudits.length, totalScenarios: scenarios.length },
+        ),
+      );
+      break;
+    }
     onProgress?.(`Auditing routes for ${scenario.key}...`);
     const routeResults = [];
     for (const route of scenario.requiredRoutes || []) {
@@ -544,6 +565,7 @@ async function runDoctorTarget(options = {}) {
   }
 
   const ok =
+    !budgetExceeded &&
     requiredEnv.every((item) => item.present) &&
     (fixture.skipped || fixture.ok) &&
     captureSafe.ok &&

package/src/lib/compose-context.js

@@ -0,0 +1,156 @@
+"use strict";
+
+const path = require("path");
+const fs = require("fs-extra");
+
+const DEFAULT_FORMATS = ["mp4", "webm", "poster"];
+const VALID_FORMATS = new Set(["mp4", "webm", "poster", "gif"]);
+
+async function resolveComposeContext(file, options = {}) {
+  const compositionPath = path.resolve(process.cwd(), file);
+  if (!(await fs.pathExists(compositionPath))) {
+    throw new Error(
+      `Composition file not found: ${compositionPath}\n` +
+        "Pass the path to a .compose.tsx file.",
+    );
+  }
+
+  const slug = options.slug || deriveSlug(compositionPath);
+  const compositionDir = path.dirname(compositionPath);
+  const metadataPath = resolveMetadataPath(compositionDir, slug);
+  const metadata = await readMetadata(metadataPath, slug);
+  const capturePath = resolveCapturePath({
+    metadata,
+    compositionDir,
+    slug,
+  });
+  await assertCaptureExists(capturePath, slug);
+
+  return {
+    compositionPath,
+    slug,
+    compositionDir,
+    metadataPath,
+    metadata,
+    capturePath,
+  };
+}
+
+function deriveSlug(filePath) {
+  const filename = path.basename(filePath);
+  const withoutKnownSuffix = filename.replace(/\.(compose\.)?[cm]?[tj]sx?$/i, "");
+  return withoutKnownSuffix || path.basename(filePath, path.extname(filePath));
+}
+
+function resolveOutBase(compositionPath, out) {
+  return path.resolve(
+    process.cwd(),
+    out || path.join(path.dirname(compositionPath), `${deriveSlug(compositionPath)}.composed`),
+  );
+}
+
+function resolveMetadataPath(compositionDir, slug) {
+  return path.join(compositionDir, `${slug}.metadata.json`);
+}
+
+async function readMetadata(metadataPath, slug) {
+  if (!(await fs.pathExists(metadataPath))) {
+    throw new Error(
+      `Missing metadata file for slug "${slug}": ${metadataPath}\n` +
+        `Expected a sibling ${slug}.metadata.json file. Re-record the clip with metadata enabled or pass --slug matching an existing metadata file.`,
+    );
+  }
+
+  try {
+    const metadata = await fs.readJson(metadataPath);
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+      throw new Error("metadata must be a JSON object");
+    }
+    return metadata;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Could not read metadata file: ${metadataPath}\n${message}`);
+  }
+}
+
+function resolveCapturePath({ metadata, compositionDir, slug }) {
+  const declaredPath =
+    metadata.capturePath ||
+    metadata.workflowCapturePath ||
+    metadata.capture?.path ||
+    metadata.source?.capturePath ||
+    metadata.source?.path;
+
+  if (typeof declaredPath === "string" && declaredPath.trim()) {
+    return path.resolve(compositionDir, declaredPath);
+  }
+
+  return path.join(compositionDir, `workflow-capture-${slug}.mp4`);
+}
+
+async function assertCaptureExists(capturePath, slug) {
+  if (await fs.pathExists(capturePath)) {
+    return;
+  }
+
+  throw new Error(
+    `Missing workflow capture for slug "${slug}": ${capturePath}\n` +
+      `Expected workflow-capture-${slug}.mp4 next to the composition, or a capturePath in ${slug}.metadata.json.`,
+  );
+}
+
+function parseSize(value) {
+  const match = /^(\d+)x(\d+)$/i.exec(String(value || "").trim());
+  if (!match) {
+    throw new Error(`Invalid --size "${value}". Use WIDTHxHEIGHT, for example 1440x900.`);
+  }
+
+  const width = Number(match[1]);
+  const height = Number(match[2]);
+  if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width <= 0 || height <= 0) {
+    throw new Error(`Invalid --size "${value}". Width and height must be positive integers.`);
+  }
+
+  return { width, height };
+}
+
+function parseFormats(value, includeGif = false) {
+  const rawFormats = value == null || value === "" ? DEFAULT_FORMATS : String(value).split(",");
+  const formats = [];
+
+  for (const rawFormat of rawFormats) {
+    const format = rawFormat.trim().toLowerCase();
+    if (!format) continue;
+    if (!VALID_FORMATS.has(format)) {
+      throw new Error(
+        `Unknown compose format "${rawFormat}". Supported formats: ${Array.from(VALID_FORMATS).join(", ")}.`,
+      );
+    }
+    if (!formats.includes(format)) {
+      formats.push(format);
+    }
+  }
+
+  if (includeGif && !formats.includes("gif")) {
+    formats.push("gif");
+  }
+
+  if (formats.length === 0) {
+    throw new Error(`No compose formats selected. Use --formats=${DEFAULT_FORMATS.join(",")}.`);
+  }
+
+  return formats;
+}
+
+module.exports = {
+  DEFAULT_FORMATS,
+  assertCaptureExists,
+  deriveSlug,
+  parseFormats,
+  parseSize,
+  readMetadata,
+  resolveCapturePath,
+  resolveComposeContext,
+  resolveMetadataPath,
+  resolveOutBase,
+};

package/src/lib/compose-pack.js

@@ -0,0 +1,42 @@
+"use strict";
+
+const fs = require("fs-extra");
+
+async function packFromExistingOutputs(outBase) {
+  const pack = {
+    mp4: `${outBase}.mp4`,
+    webm: `${outBase}.webm`,
+    poster: `${outBase}.webp`,
+  };
+  const gifPath = `${outBase}.gif`;
+  if (await fs.pathExists(gifPath)) {
+    pack.gif = gifPath;
+  }
+  return pack;
+}
+
+async function assertUploadPackExists(pack, skipRender) {
+  const required = [
+    ["rendered_mp4", pack.mp4],
+    ["rendered_webm", pack.webm],
+    ["rendered_poster", pack.poster],
+  ];
+
+  for (const [field, filePath] of required) {
+    if (!filePath || !(await fs.pathExists(filePath))) {
+      const rerenderHint = skipRender
+        ? " Run `reshot compose <file>` first or remove --skip-render."
+        : "";
+      throw new Error(`Missing ${field} output: ${filePath || "(not produced)"}.${rerenderHint}`);
+    }
+  }
+
+  if (pack.gif && !(await fs.pathExists(pack.gif))) {
+    throw new Error(`Missing rendered_gif output: ${pack.gif}.`);
+  }
+}
+
+module.exports = {
+  assertUploadPackExists,
+  packFromExistingOutputs,
+};

package/src/lib/compose-runtime.js

@@ -0,0 +1,34 @@
+// compose-runtime.js — locate the @reshot/compose build the CLI ships with.
+//
+// The compose engine is vendored (self-contained: motion-core and the pure-JS
+// image deps are inlined; only esbuild + playwright-core stay external and are
+// declared as CLI dependencies). The published package ships vendor/compose/dist;
+// when developing inside the monorepo we fall back to the live package build.
+
+const path = require("path");
+const fs = require("fs-extra");
+
+let cached;
+
+/** Absolute path to the compose dist directory (capture.cjs, render.mjs, …). */
+function composeDistDir() {
+  if (cached) return cached;
+  const candidates = [
+    // Shipped with the published CLI (also present in the standalone repo).
+    path.resolve(__dirname, "../../vendor/compose/dist"),
+    // Monorepo development: packages/compose/dist.
+    path.resolve(__dirname, "../../../../packages/compose/dist"),
+  ];
+  for (const dir of candidates) {
+    if (fs.existsSync(dir)) {
+      cached = dir;
+      return dir;
+    }
+  }
+  throw new Error(
+    "@reshot/compose build not found. Expected vendor/compose/dist " +
+      "(shipped with the CLI) or packages/compose/dist (monorepo dev).",
+  );
+}
+
+module.exports = { composeDistDir };

package/src/lib/compose-upload.js

@@ -0,0 +1,142 @@
+"use strict";
+
+const fs = require("fs-extra");
+const axios = require("axios");
+const FormData = require("form-data");
+const config = require("./config");
+const apiClient = require("./api-client");
+
+function resolveComposeProjectContext({ projectOption, settings }) {
+  const resolvedSettings =
+    settings !== undefined ? settings : readSettingsSafe();
+  const apiKey = process.env.RESHOT_API_KEY || resolvedSettings?.apiKey;
+  const projectId =
+    projectOption ||
+    process.env.RESHOT_PROJECT_ID ||
+    resolvedSettings?.projectId;
+
+  if (!apiKey) {
+    throw new Error(
+      "No API key found. Set RESHOT_API_KEY or run `reshot auth` to create .reshot/settings.json.",
+    );
+  }
+
+  if (!projectId) {
+    throw new Error(
+      "No project ID found. Pass --project, set RESHOT_PROJECT_ID, or authenticate with `reshot auth`.",
+    );
+  }
+
+  return { apiKey, projectId };
+}
+
+function readSettingsSafe() {
+  try {
+    return config.readSettings();
+  } catch {
+    return null;
+  }
+}
+
+async function uploadComposition({
+  apiBaseUrl,
+  apiKey,
+  projectId,
+  name,
+  slug,
+  sourceTsx,
+  metadataJson,
+  pack,
+  autoApprove = false,
+  httpClient = axios,
+}) {
+  const formData = new FormData();
+  formData.append("name", name);
+  formData.append("slug", slug);
+  formData.append("source_tsx", sourceTsx);
+  formData.append("metadata_json", metadataJson);
+  if (autoApprove) {
+    formData.append("auto_approve", "true");
+  }
+  formData.append("rendered_mp4", fs.createReadStream(pack.mp4));
+  formData.append("rendered_webm", fs.createReadStream(pack.webm));
+  formData.append("rendered_poster", fs.createReadStream(pack.poster));
+  if (pack.gif) {
+    formData.append("rendered_gif", fs.createReadStream(pack.gif));
+  }
+
+  const endpoint = `${apiBaseUrl.replace(/\/+$/, "")}/projects/${encodeURIComponent(projectId)}/compositions`;
+  const response = await httpClient.post(endpoint, formData, {
+    headers: {
+      ...formData.getHeaders(),
+      Authorization: `Bearer ${apiKey}`,
+    },
+    timeout: 180000,
+    maxBodyLength: Infinity,
+    maxContentLength: Infinity,
+  });
+
+  const data = unwrapApiResponse(response.data);
+  const attributionWarning = readResponseHeader(
+    response.headers,
+    "x-reshot-attribution-warning",
+  );
+
+  if (attributionWarning) {
+    return { ...data, attributionWarning };
+  }
+
+  return data;
+}
+
+function unwrapApiResponse(body) {
+  if (body && typeof body === "object" && body.success && body.data !== undefined) {
+    return body.data;
+  }
+  return body;
+}
+
+function readResponseHeader(headers, name) {
+  if (!headers) return null;
+  if (typeof headers.get === "function") {
+    return headers.get(name);
+  }
+  return headers[name] || headers[name.toLowerCase()] || null;
+}
+
+function buildDashboardUrl(response, apiBaseUrl, projectId) {
+  const platformUrl = apiBaseUrl.replace(/\/api\/?$/, "");
+  const dashboardUrl =
+    response?.dashboardUrl ||
+    response?.composition?.dashboardUrl ||
+    response?.render?.dashboardUrl;
+  if (dashboardUrl) {
+    return dashboardUrl;
+  }
+
+  const compositionId = response?.composition?.id || response?.id;
+  const base = `${platformUrl}/app/projects/${encodeURIComponent(projectId)}/compositions`;
+  return compositionId ? `${base}/${encodeURIComponent(compositionId)}` : base;
+}
+
+function humanizeName(slug) {
+  return String(slug)
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[-_]+/g, " ")
+    .trim() || slug;
+}
+
+function getComposeApiBaseUrl(explicitApiBaseUrl) {
+  return explicitApiBaseUrl || apiClient.getApiBaseUrl();
+}
+
+module.exports = {
+  buildDashboardUrl,
+  getComposeApiBaseUrl,
+  humanizeName,
+  readResponseHeader,
+  readSettingsSafe,
+  resolveComposeProjectContext,
+  unwrapApiResponse,
+  uploadComposition,
+};

package/src/lib/config.js

@@ -330,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) {

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,
+};