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

package/src/lib/record-clip.js

@@ -8,13 +8,27 @@ const { chromium } = require('playwright');
 const { updateBrowserMode } = require('./record-browser-injection');
 const { runPolishedClip } = require('./polished-clip');
 const { saveScenarioProgress } = require('./record-config');
+const { resolveTargets } = require('./resolve-targets');
+const { captureDomArtifact } = require('./dom-capture');
 
 /**
  * Start clip recording flow
  * @param {Object} sessionState - Recording session state
  * @param {Page} page - Playwright page object
  */
-async function startClipRecording(sessionState, page) {
+async function startClipRecording(sessionState, page, config = {}) {
+  const metadataRecorder = config.emitMetadata
+    ? createClipMetadataRecorder({
+        slug: config.slug || sessionState.visualKey,
+        captureSize: config.captureSize || { width: 1280, height: 720 },
+      })
+    : null;
+
+  if (metadataRecorder) {
+    sessionState.logEvent = metadataRecorder.logEvent;
+    metadataRecorder.logEvent('workflow_start');
+  }
+
   // Ask about container element
   const { useContainer } = await inquirer.prompt([
     {
@@ -127,6 +141,10 @@ async function startClipRecording(sessionState, page) {
   
   // Set up action replay handler to sync video with real user actions
   sessionState.replayActionToRecording = async (action, selector, text) => {
+    if (metadataRecorder) {
+      metadataRecorder.logEvent(action, { selector, text });
+    }
+
     try {
       if (action === 'click') {
         await recordingPage.click(selector);
@@ -233,6 +251,17 @@ async function startClipRecording(sessionState, page) {
   
   sessionState.capturedSteps.push(clipStep);
   await saveScenarioProgress(sessionState, page, { finalize: false });
+
+  if (metadataRecorder) {
+    await writeClipMetadata({
+      page,
+      outputDir: config.outputDir || sessionState.outputDir || process.cwd(),
+      slug: metadataRecorder.slug,
+      captureSize: metadataRecorder.captureSize,
+      timeline: metadataRecorder.timeline,
+      targets: config.targets,
+    });
+  }
   
   // Clean up temp video
   fs.removeSync(rawVideoPath);
@@ -242,6 +271,9 @@ async function startClipRecording(sessionState, page) {
   sessionState.clipEvents = null;
   sessionState.recordingStart = null;
   sessionState.stopClipRecording = false;
+  if (metadataRecorder) {
+    delete sessionState.logEvent;
+  }
   
   console.log(
     chalk.green(
@@ -250,6 +282,53 @@ async function startClipRecording(sessionState, page) {
   );
 }
 
+function createClipMetadataRecorder({ slug, captureSize }) {
+  const startedAt = Date.now();
+  const timeline = [];
+
+  return {
+    slug,
+    captureSize,
+    timeline,
+    logEvent(type, payload = {}) {
+      timeline.push({
+        tMs: Date.now() - startedAt,
+        type,
+        payload,
+      });
+    },
+  };
+}
+
+async function writeClipMetadata({
+  page,
+  outputDir,
+  slug,
+  captureSize,
+  timeline,
+  targets,
+}) {
+  const resolvedTargets = targets ? await resolveTargets(page, targets) : {};
+
+  // Tier-3: alongside the video, emit a self-contained DOM reconstruction
+  // artifact (<slug>.dom.html + sidecars) for eligible screens. Additive and
+  // best-effort — it must never break the video path, so failures are swallowed.
+  await fs.ensureDir(outputDir);
+  const domArtifact = await captureDomArtifact({ page, outputDir, slug });
+
+  const metadata = {
+    slug,
+    version: 1,
+    captureSize,
+    timeline,
+    targets: resolvedTargets,
+    ...(domArtifact ? { domArtifact } : {}),
+  };
+  const metadataPath = path.join(outputDir, `${slug}.metadata.json`);
+  await fs.writeJson(metadataPath, metadata, { spaces: 2 });
+  return metadataPath;
+}
+
 /**
  * Run subtitle editor mini-server
  * @param {Array} events - Clip events with timestamps
@@ -338,6 +417,7 @@ function buildClipKey(visualKey, filename) {
 }
 
 module.exports = {
-  startClipRecording
+  createClipMetadataRecorder,
+  startClipRecording,
+  writeClipMetadata
 };
-

package/src/lib/record-config.js

@@ -492,10 +492,6 @@ async function persistFinalScenario(sessionState, page, options = {}) {
   // Default output configuration for automatic step-by-step image generation
   const defaultOutput = {
     format: "step-by-step-images",
-    highlight: {
-      color: "rgba(255, 255, 0, 0.5)",
-      style: "box",
-    },
   };
 
   // Parse groupPath from session state or existing scenario

package/src/lib/release-doctor.js

@@ -275,13 +275,21 @@ async function runReleaseDoctor(options = {}) {
   for (const issue of targetDoctor.summary?.advisories || []) {
     advisories.push({ scope: "target-doctor", ...issue });
   }
-  if (!docsAssetMap.skipped) {
+  // A stale/mismatched docs asset map (e.g. src/data/reshot-assets.json left
+  // behind by an earlier `reshot pull`) describes a generated artifact, not the
+  // config being published. It must NOT hard-block a publish of the current
+  // config — surface it as an advisory with a concrete remedy instead.
+  if (!docsAssetMap.skipped && !docsAssetMap.ok) {
+    const remedy =
+      docsAssetMap.path
+        ? `Re-run \`reshot pull\` to regenerate it, or delete ${docsAssetMap.path}.`
+        : "Re-run `reshot pull` to regenerate it, or delete the stale src/data/reshot-assets.json.";
     for (const issue of docsAssetMap.issues) {
-      blockingIssues.push({ scope: "docs-asset-map", message: issue });
+      advisories.push({ scope: "docs-asset-map", message: `${issue} ${remedy}` });
     }
   }
 
-  const ok = preflight.ok && targetDoctor.ok && (docsAssetMap.skipped || docsAssetMap.ok);
+  const ok = preflight.ok && targetDoctor.ok;
   const report = {
     type: "ReleaseDoctorReport",
     stage: "doctor-release",

package/src/lib/resolve-targets.js

@@ -0,0 +1,60 @@
+// resolve-targets.js - Resolve compose target coordinates from a Playwright page
+
+async function resolveTargets(page, targets = {}) {
+  const resolved = {};
+
+  for (const [name, config] of Object.entries(targets || {})) {
+    const target = normalizeTarget(config);
+
+    for (const step of target.navigate) {
+      if (step.clickText) {
+        await page.getByText(step.clickText, { exact: true }).first().click();
+      } else if (step.selector) {
+        await page.locator(step.selector).first().click();
+      }
+      if (step.waitMs) {
+        await page.waitForTimeout(step.waitMs);
+      }
+    }
+
+    const locator = page.locator(target.selector).first();
+    await locator.waitFor({ state: 'visible', timeout: target.timeoutMs });
+    const box = await locator.boundingBox();
+    if (!box) {
+      throw new Error(`Could not resolve target "${name}"`);
+    }
+
+    resolved[name] = {
+      x: Math.round(box.x),
+      y: Math.round(box.y),
+      w: Math.round(box.width),
+      h: Math.round(box.height),
+    };
+  }
+
+  return resolved;
+}
+
+function normalizeTarget(config) {
+  if (typeof config === 'string') {
+    return {
+      selector: config,
+      navigate: [],
+      timeoutMs: 10000,
+    };
+  }
+
+  if (!config || typeof config !== 'object' || !config.selector) {
+    throw new Error('Target config must be a selector string or an object with selector');
+  }
+
+  return {
+    selector: config.selector,
+    navigate: Array.isArray(config.navigate) ? config.navigate : [],
+    timeoutMs: config.timeoutMs || 10000,
+  };
+}
+
+module.exports = {
+  resolveTargets,
+};

package/src/lib/run-manifest.js

@@ -91,6 +91,50 @@ function getLatestSuccessfulRunManifest() {
   return null;
 }
 
+/**
+ * Returns the latest run manifest that has at least one successful scenario,
+ * even if the overall run was not fully successful. This prevents falling back
+ * to stale manifests when only some scenarios failed.
+ *
+ * Returns { manifest, isFallback, isPartialSuccess } where:
+ * - isFallback: true if the returned manifest is NOT the latest run
+ * - isPartialSuccess: true if the manifest has both succeeded and failed scenarios
+ */
+function getLatestUsableRunManifest() {
+  const latest = readRunManifest(LATEST_RUN_MANIFEST_PATH);
+
+  if (latest) {
+    const successfulScenarios = (latest.scenarios || []).filter(
+      (s) => s.success !== false,
+    );
+    if (successfulScenarios.length > 0) {
+      return {
+        manifest: latest,
+        isFallback: false,
+        isPartialSuccess: !latest.success,
+      };
+    }
+  }
+
+  // Latest has zero successful scenarios — search historical manifests
+  for (const manifestPath of listRunManifestPaths()) {
+    const manifest = readRunManifest(manifestPath);
+    if (!manifest) continue;
+    const successfulScenarios = (manifest.scenarios || []).filter(
+      (s) => s.success !== false,
+    );
+    if (successfulScenarios.length > 0) {
+      return {
+        manifest,
+        isFallback: true,
+        isPartialSuccess: !manifest.success,
+      };
+    }
+  }
+
+  return null;
+}
+
 module.exports = {
   RUN_MANIFEST_DIR,
   LATEST_RUN_MANIFEST_PATH,
@@ -99,5 +143,6 @@ module.exports = {
   readRunManifest,
   listRunManifestPaths,
   getLatestSuccessfulRunManifest,
+  getLatestUsableRunManifest,
   normalizeScenarioResults,
 };

package/src/lib/ui-api-helpers.js

@@ -0,0 +1,118 @@
+const path = require("path");
+const config = require("./config");
+
+/**
+ * Get the platform URL from settings, falling back to production.
+ * @param {Object} settings - CLI settings object
+ * @returns {string} Platform URL
+ */
+function getPlatformUrl(settings) {
+  if (settings?.platformUrl) {
+    return settings.platformUrl;
+  }
+
+  const envUrl = process.env.RESHOT_API_BASE_URL;
+  if (envUrl) {
+    return envUrl.replace(/\/api\/?$/, "");
+  }
+
+  return "https://reshot.dev";
+}
+
+/**
+ * Handle API errors and detect if re-auth is needed.
+ * @param {Error} error - The error from API call
+ * @param {Object} res - Express response object
+ * @returns {Object|null} Response if error was handled, null otherwise
+ */
+function handleApiError(error, res) {
+  if (config.isAuthError(error)) {
+    const errorMsg =
+      error.response?.data?.error ||
+      error.message ||
+      "API key is invalid or expired";
+    return res.status(401).json(config.createAuthErrorResponse(errorMsg));
+  }
+
+  return null;
+}
+
+/**
+ * Generate all possible variant combinations from dimensions.
+ * @param {Object} dimensions - Variant dimensions config
+ * @param {string[]} dimensionKeys - Which dimensions to include
+ * @returns {Array<Object>} Array of variant objects
+ */
+function generateVariantCombinations(dimensions, dimensionKeys = []) {
+  if (!dimensions || dimensionKeys.length === 0) {
+    return [];
+  }
+
+  const dimensionOptions = dimensionKeys
+    .map((key) => {
+      const dim = dimensions[key];
+      if (!dim?.options) return [];
+      return Object.keys(dim.options).map((optKey) => ({
+        dimension: key,
+        option: optKey,
+      }));
+    })
+    .filter((opts) => opts.length > 0);
+
+  if (dimensionOptions.length === 0) {
+    return [];
+  }
+
+  const combinations = cartesian(...dimensionOptions);
+
+  return combinations.map((combo) => {
+    const variant = {};
+    for (const { dimension, option } of combo) {
+      variant[dimension] = option;
+    }
+    return variant;
+  });
+}
+
+function cartesian(...arrays) {
+  return arrays.reduce(
+    (acc, arr) => acc.flatMap((combo) => arr.map((item) => [...combo, item])),
+    [[]],
+  );
+}
+
+/**
+ * Validate a path segment to prevent directory traversal attacks.
+ * @param {string} segment - Path segment to validate
+ * @returns {boolean} True if safe, false if potentially malicious
+ */
+function isValidPathSegment(segment) {
+  if (!segment || typeof segment !== "string") return false;
+  if (segment === "." || segment === "..") return false;
+  if (segment.includes("/") || segment.includes("\\")) return false;
+  if (segment.includes("\0")) return false;
+  return true;
+}
+
+/**
+ * Validate that a resolved path stays within the expected base directory.
+ * @param {string} resolvedPath - Fully resolved path
+ * @param {string} baseDir - Expected base directory
+ * @returns {boolean} True if path is within base, false otherwise
+ */
+function isPathWithinBase(resolvedPath, baseDir) {
+  const normalizedBase = path.resolve(baseDir);
+  const normalizedPath = path.resolve(resolvedPath);
+  return (
+    normalizedPath.startsWith(normalizedBase + path.sep) ||
+    normalizedPath === normalizedBase
+  );
+}
+
+module.exports = {
+  generateVariantCombinations,
+  getPlatformUrl,
+  handleApiError,
+  isPathWithinBase,
+  isValidPathSegment,
+};