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

package/src/commands/publish.js

@@ -15,7 +15,10 @@ const {
   getStorageMode,
   isPlatformAvailable,
 } = require("../lib/storage-providers");
-const { getLatestSuccessfulRunManifest } = require("../lib/run-manifest");
+const {
+  getLatestSuccessfulRunManifest,
+  getLatestUsableRunManifest,
+} = require("../lib/run-manifest");
 const pkg = require("../../package.json");
 
 // Check if transactional flow should be used (R2 configured on server)
@@ -505,9 +508,9 @@ function collectAssetFilesFromDirectories(directories) {
 }
 
 function resolveManifestScopedScreenshotFiles(outputBaseDir, latestRunManifest) {
-  if (!latestRunManifest?.success) {
+  if (!latestRunManifest) {
     throw new Error(
-      "No successful run manifest is available. Run `reshot run` first or use `reshot publish --all-output` to publish from the full output tree.",
+      "No run manifest is available. Run `reshot run` first or use `reshot publish --all-output` to publish from the full output tree.",
     );
   }
 
@@ -518,7 +521,7 @@ function resolveManifestScopedScreenshotFiles(outputBaseDir, latestRunManifest)
 
   if (scenarioDirs.length === 0) {
     throw new Error(
-      "The latest successful run manifest does not contain any scenario output directories.",
+      "The run manifest does not contain any successful scenario output directories.",
     );
   }
 
@@ -677,6 +680,52 @@ async function publishWithTransactionalFlow(
     }
   }
 
+  // ── DOM scene sidecars (MHTML bundles next to each PNG) ─────────────
+  // The CLI emits an .mhtml alongside each PNG when scenario.domScene !==
+  // false. We upload them as sidecar assets linked to the parent PNG's
+  // visual version via _parentVisualKey, so the server can persist the
+  // sidecar's s3Path on the same VisualVersion row.
+  const domSceneSidecars = [];
+  for (const f of allFiles) {
+    // Only attach MHTML to PNG screenshots (not videos, not other sidecars).
+    if (path.extname(f.path).toLowerCase() !== ".png") continue;
+    if (f._isThumbnail || f._isDomScene) continue;
+
+    const candidate =
+      (f.asset && f.asset.domScenePath) ||
+      f.path.replace(/\.png$/i, ".mhtml");
+    if (!fs.existsSync(candidate)) continue;
+
+    const sidecarStat = fs.statSync(candidate);
+    domSceneSidecars.push({
+      group: f.group,
+      asset: {
+        captureKey: f.asset.captureKey,
+        path: candidate,
+        filename: path.basename(candidate),
+      },
+      scenarioConfig: f.scenarioConfig,
+      key: f.key,
+      visualKey: f.visualKey,
+      path: candidate,
+      size: sidecarStat.size,
+      contentType: "multipart/related",
+      hash: null,
+      diffData: null,
+      thumbnailPath: null,
+      _isDomScene: true,
+      _parentVisualKey: f.visualKey,
+    });
+  }
+  if (domSceneSidecars.length > 0) {
+    console.log(
+      chalk.gray(
+        `  Attaching ${domSceneSidecars.length} DOM scene sidecar(s)...`,
+      ),
+    );
+    allFiles.push(...domSceneSidecars);
+  }
+
   // Generate thumbnails for video files (first frame as PNG)
   const videoExts = new Set([".mp4", ".webm", ".mov"]);
   const videoFiles = allFiles.filter((f) =>
@@ -776,7 +825,10 @@ async function publishWithTransactionalFlow(
 
   // Step 3: Upload files directly to R2 (parallel with concurrency limit)
   console.log(chalk.gray("  Uploading files directly to R2..."));
-  const CONCURRENCY = 5;
+  const CONCURRENCY = Math.min(
+    Math.max(parseInt(process.env.RESHOT_UPLOAD_CONCURRENCY || "10", 10), 1),
+    20,
+  );
   const uploadQueue = [...allFiles];
   const uploadResults = [];
 
@@ -818,21 +870,33 @@ async function publishWithTransactionalFlow(
 
   // Build a map of thumbnail s3Paths keyed by parent visualKey
   const thumbnailS3Paths = new Map();
+  // Build a map of DOM-scene MHTML s3Paths keyed by parent visualKey.
+  // The server attaches these to the parent VisualVersion as a sidecar.
+  const domSceneS3Paths = new Map();
+  const domSceneSizes = new Map();
   for (const result of uploadResults) {
-    if (result.success && result.file._isThumbnail) {
+    if (!result.success) continue;
+    if (result.file._isThumbnail) {
       thumbnailS3Paths.set(result.file._parentVisualKey, result.s3Path);
+    } else if (result.file._isDomScene) {
+      domSceneS3Paths.set(result.file._parentVisualKey, result.s3Path);
+      domSceneSizes.set(result.file._parentVisualKey, result.file.size);
     }
   }
 
-  // Group successful uploads by scenario/variant (skip thumbnails — they're metadata)
+  // Group successful uploads by scenario/variant (skip thumbnails + DOM
+  // sidecars — they're metadata attached to their parent asset).
+  const failedUploadKeys = [];
   const groupMap = new Map();
   for (const result of uploadResults) {
     if (!result.success) {
-      if (!result.file._isThumbnail) failCount++;
+      if (!result.file._isThumbnail && !result.file._isDomScene) {
+        failCount++;
+        failedUploadKeys.push(result.file.visualKey);
+      }
       continue;
     }
-    // Thumbnails are attached to their parent asset, not committed separately
-    if (result.file._isThumbnail) continue;
+    if (result.file._isThumbnail || result.file._isDomScene) continue;
 
     const groupKey = `${result.file.group.scenarioKey}::${result.file.group.variationSlug}`;
     if (!groupMap.has(groupKey)) {
@@ -854,6 +918,10 @@ async function publishWithTransactionalFlow(
       diffStatus: result.file.diffData?.diffStatus ?? null,
       // Attach thumbnail for video assets
       thumbnailS3Path: thumbnailS3Paths.get(result.file.visualKey) ?? null,
+      // Attach DOM scene sidecar (MHTML) — the source of truth for
+      // marketing-team variations.
+      domSceneS3Path: domSceneS3Paths.get(result.file.visualKey) ?? null,
+      domSceneSize: domSceneSizes.get(result.file.visualKey) ?? null,
     });
   }
 
@@ -942,7 +1010,7 @@ async function publishWithTransactionalFlow(
     }
   }
 
-  return { successCount, failCount, skippedCount, viewUrl };
+  return { successCount, failCount, skippedCount, viewUrl, failedUploadKeys };
 }
 
 /**
@@ -1482,7 +1550,37 @@ async function publishCommand(options = {}) {
       if (allOutput) {
         screenshotFiles = findAssetFiles(outputBaseDir);
       } else {
-        const latestRunManifest = getLatestSuccessfulRunManifest();
+        const usable = getLatestUsableRunManifest();
+        if (!usable) {
+          throw new Error(
+            "No run manifest with successful scenarios found. Run `reshot run` first or use `reshot publish --all-output` to publish from the full output tree.",
+          );
+        }
+        const { manifest: latestRunManifest, isFallback, isPartialSuccess } = usable;
+
+        if (isFallback) {
+          const age = latestRunManifest.generatedAt
+            ? `generated ${latestRunManifest.generatedAt}`
+            : "unknown age";
+          console.log(
+            chalk.yellow(
+              `\n  WARNING: Latest run has no successful scenarios. Falling back to older manifest (${age}).` +
+                `\n  The published screenshots may be STALE. Run \`reshot run\` to capture fresh screenshots.\n`,
+            ),
+          );
+        } else if (isPartialSuccess) {
+          const allScenarios = latestRunManifest.scenarios || [];
+          const failed = allScenarios.filter((s) => s.success === false);
+          const succeeded = allScenarios.filter((s) => s.success !== false);
+          console.log(
+            chalk.yellow(
+              `\n  WARNING: Latest run had partial failures (${succeeded.length} passed, ${failed.length} failed).` +
+                `\n  Publishing only the ${succeeded.length} successful scenario(s).` +
+                `\n  Failed: ${failed.map((s) => s.key).join(", ")}\n`,
+            ),
+          );
+        }
+
         const manifestScoped = resolveManifestScopedScreenshotFiles(
           outputBaseDir,
           latestRunManifest,
@@ -1627,11 +1725,38 @@ async function publishCommand(options = {}) {
       }
       if (failCount > 0) {
         console.log(chalk.red(`  ✖ Failed: ${failCount}`));
+        const failedKeys = viewUrl ? [] : (publishResult.failedUploadKeys || []);
+        if (failedKeys.length > 0) {
+          for (const key of failedKeys.slice(0, 5)) {
+            console.log(chalk.red(`    - ${key}`));
+          }
+          if (failedKeys.length > 5) {
+            console.log(chalk.red(`    ... and ${failedKeys.length - 5} more`));
+          }
+        }
       }
       if (viewUrl) {
         console.log(chalk.cyan(`\n  🔗 View in platform: ${viewUrl}`));
       }
 
+      if (!autoApprove && successCount > 0) {
+        console.log(
+          chalk.cyan(
+            `\n  ℹ ${successCount} visual${successCount === 1 ? "" : "s"} awaiting review (PENDING)`,
+          ),
+        );
+        console.log(
+          chalk.gray(
+            "    To skip review for first-time captures, re-run with `reshot publish --auto-approve`",
+          ),
+        );
+        console.log(
+          chalk.gray(
+            "    or approve them in the studio link above.",
+          ),
+        );
+      }
+
       // Helpful guidance about diff percentages
       if (diffManifests && diffManifests.size > 0) {
         console.log(

package/src/commands/pull.js

@@ -255,7 +255,7 @@ async function pullCommand(options = {}) {
     format = "json",
     output = null,
     full = false,
-    status = "approved",
+    status = "all",
     noExit = false,
   } = options;
 
@@ -273,7 +273,10 @@ async function pullCommand(options = {}) {
     return { success: false, error: "No reshot.config.json found" };
   }
 
-  let projectId = projectConfig._metadata?.projectId || projectConfig.projectId;
+  let projectId =
+    process.env.RESHOT_PROJECT_ID ||
+    projectConfig._metadata?.projectId ||
+    projectConfig.projectId;
   if (!projectId) {
     // Fall back to reading projectId from .reshot/settings.json (written by `reshot auth`)
     try {
@@ -315,7 +318,7 @@ async function pullCommand(options = {}) {
   if (settings.projectId && projectId !== settings.projectId) {
     console.warn(
       chalk.yellow(
-        `  ⚠ Project ID mismatch: config uses ${projectId}, but authenticated project is ${settings.projectId}.`
+        `  ⚠ Project ID mismatch: active project is ${projectId}, but authenticated project is ${settings.projectId}.`
       )
     );
     console.warn(
@@ -356,9 +359,11 @@ async function pullCommand(options = {}) {
       console.log(chalk.gray(`  Possible reasons:`));
       if (status === "approved") {
         console.log(chalk.gray(`    • No visuals approved yet. Try: reshot pull --status all`));
+      } else if (status === "pending") {
+        console.log(chalk.gray(`    • No pending visuals. Try: reshot pull --status all`));
       }
       console.log(chalk.gray(`    • No visuals published. Run: reshot publish`));
-      console.log(chalk.gray(`    • Wrong project. Config uses: ${projectId}`));
+      console.log(chalk.gray(`    • Wrong project. Active project: ${projectId}`));
       console.log(chalk.gray(`    • Check: ${settings.platformUrl || "https://reshot.dev"}\n`));
     } else {
       console.log(chalk.green(`  ✓ Fetched ${assetCount} visuals\n`));

package/src/commands/refresh.js

@@ -0,0 +1,166 @@
+// refresh.js — Phase 5 auto-update loop (CI-runnable).
+//
+// `reshot refresh --composition <id>` or `reshot refresh --project <id>`:
+// recapture each composition's source screen, run the calibrated drift check, and
+// either re-publish (data changed, structure-stable) or flag for human review
+// (structural redesign / lost eligibility). Idempotent: a re-run with no source
+// changes is a no-op (0 renders, 0 review items).
+
+const fs = require("fs");
+const chalk = require("chalk");
+const { refresh, registerComposition, setScene } = require("../lib/auto-update/refresh");
+
+// Read + parse the --scene <path> JSON (the spec.scene render config: camera/motion
+// /timeline/targets/...). Returns undefined when no path was given.
+function readSceneFile(scenePath) {
+  if (!scenePath) return undefined;
+  let raw;
+  try {
+    raw = fs.readFileSync(scenePath, "utf8");
+  } catch (error) {
+    throw new Error(`--scene: cannot read ${scenePath}: ${error.message}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`--scene: ${scenePath} is not valid JSON: ${error.message}`);
+  }
+}
+
+function parseViewport(spec) {
+  if (!spec) return undefined;
+  const m = /^(\d+)x(\d+)(?:@(\d+(?:\.\d+)?))?$/.exec(String(spec).trim());
+  if (!m) throw new Error(`Invalid --viewport "${spec}" (expected WxH or WxH@scale, e.g. 1280x900 or 1280x900@2)`);
+  return { width: Number(m[1]), height: Number(m[2]), deviceScaleFactor: m[3] ? Number(m[3]) : 2 };
+}
+
+// Build the capture-auth config (stored on the spec, re-resolved on every recapture)
+// so the loop can reach authenticated /app screens. --storage-state wins if both set.
+function buildAuth(options) {
+  if (options.storageState) return { mode: "storage-state", path: options.storageState };
+  if (options.demoAuth) {
+    return { mode: "demo-bootstrap", email: typeof options.demoAuth === "string" ? options.demoAuth : "demo@example.com" };
+  }
+  return undefined;
+}
+
+const ACTION_LABEL = {
+  publish: chalk.green("published"),
+  flag: chalk.yellow("flagged"),
+  skip: chalk.gray("skipped"),
+  error: chalk.red("errored"),
+};
+
+function printSummary(result) {
+  console.log(chalk.cyan("\nReshot refresh — per-composition result\n"));
+  for (const s of result.summaries) {
+    const label = ACTION_LABEL[s.action] || s.action;
+    const metrics = s.metrics
+      ? ` diff=${s.metrics.pixelDiffPct}% ssim=${s.metrics.ssim}`
+      : "";
+    console.log(
+      `  ${label}  ${chalk.bold(s.slug)} (${s.compositionId})\n` +
+        `      route=${s.route} eligible=${s.eligible} structureStable=${s.structureStable} quality=${s.qualityPass}${metrics}\n` +
+        `      ${chalk.gray(s.reason)}`,
+    );
+  }
+  console.log(
+    chalk.cyan(
+      `\nrendersCreated=${result.rendersCreated} reviewItemsCreated=${result.reviewItemsCreated} ` +
+        `published=${result.published} flagged=${result.flagged} skipped=${result.skipped} errors=${result.errors}`,
+    ),
+  );
+}
+
+async function refreshCommand(options = {}) {
+  // Attach/update the crisp <Scene>+motion render config on an already-enrolled
+  // composition (so the loop renders it animated instead of the video fallback).
+  if (options.setScene) {
+    const result = await setScene(options.composition, readSceneFile(options.scene));
+    if (options.json) console.log(JSON.stringify(result, null, 2));
+    else console.log(chalk.green("scene set ") + chalk.bold(result.compositionId) + ` (render=${result.mode})`);
+    return result;
+  }
+
+  if (options.register) {
+    const result = await registerComposition({
+      compositionId: options.composition,
+      projectId: options.project || process.env.RESHOT_PROJECT_ID,
+      url: options.url,
+      viewport: parseViewport(options.viewport),
+      composePath: options.compose,
+      slug: options.slug,
+      name: options.name,
+      scene: readSceneFile(options.scene),
+      auth: buildAuth(options),
+    });
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(
+        chalk.green("registered ") +
+          chalk.bold(result.slug || result.compositionId) +
+          ` (route=${result.route}, eligible=${result.eligible}, render=${result.render})`,
+      );
+    }
+    return result;
+  }
+
+  if (!options.composition && !options.project) {
+    throw new Error("Pass --composition <id> or --project <id> (or --register to enroll one).");
+  }
+
+  const result = await refresh({
+    compositionId: options.composition,
+    projectId: options.project,
+  });
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printSummary(result);
+  }
+  return result;
+}
+
+function registerRefresh(program) {
+  program
+    .command("refresh")
+    .description("Recapture composition source screens and auto re-publish or flag drift for review")
+    .option("--composition <id>", "Refresh a single composition by id")
+    .option("--project <id>", "Refresh every composition with a stored spec in this project")
+    .option("--register", "Enroll a composition into the loop: capture its source screen as the accepted baseline")
+    .option("--set-scene", "Attach/update the crisp <Scene>+motion render config on an enrolled composition (with --composition + --scene)")
+    .option("--scene <path>", "[--register|--set-scene] JSON file with the scene render config (camera/motion/timeline/targets); without it the loop renders video")
+    .option("--url <url>", "[--register] source screen URL to recapture")
+    .option("--viewport <WxH>", "[--register] capture viewport, e.g. 1280x900 or 1280x900@2")
+    .option("--compose <path>", "[--register] path to the composition's .compose.tsx for re-rendering on publish")
+    .option("--slug <slug>", "[--register] composition slug (for the upload route + public URL)")
+    .option("--name <name>", "[--register] composition display name")
+    .option("--demo-auth [email]", "[--register] authenticate the capture via the seeded demo bootstrap (default email demo@example.com) — reaches /app screens")
+    .option("--storage-state <path>", "[--register] authenticate the capture with a Playwright storageState JSON exported from a real session")
+    .option("--json", "Output the structured result as JSON")
+    .option("--fail-on-error", "Exit non-zero (2) if any composition errored — for CI gating")
+    .action(async (options) => {
+      try {
+        const result = await refreshCommand(options);
+        if (shouldFailOnError(options, result)) {
+          console.error(chalk.red(`Refresh completed with ${result.errors} error(s) (--fail-on-error).`));
+          process.exit(2);
+        }
+      } catch (error) {
+        console.error(chalk.red("Error:"), error.message);
+        process.exit(1);
+      }
+    });
+}
+
+// CI gating: a completed refresh that had per-composition errors (a screen failed
+// to capture/upload) still exits 0 by default (the batch is isolated, fail-safe).
+// With --fail-on-error, CI can treat that as a non-zero (exit 2) — distinct from a
+// hard crash (exit 1). Pure + exported so it is unit-testable without process.exit.
+function shouldFailOnError(options, result) {
+  return Boolean(options && options.failOnError && result && result.errors > 0);
+}
+
+module.exports = { refreshCommand, registerRefresh, printSummary, shouldFailOnError };

package/src/commands/setup-wizard.js

@@ -153,7 +153,13 @@ function writeSetupReport({
  * Main setup wizard
  */
 async function setupWizard(options = {}) {
-  const { offline = false, force = false, noStudio = false } = options;
+  const {
+    offline = false,
+    force = false,
+    noStudio = false,
+    project: linkedProjectId,
+    token: linkedToken,
+  } = options;
 
   console.log(chalk.cyan.bold("\n🚀 Reshot Setup\n"));
 
@@ -182,8 +188,35 @@ async function setupWizard(options = {}) {
     // No existing config
   }
 
+  let didLinkFromOptions = false;
+  if (linkedProjectId && linkedToken && !offline) {
+    const authCommand = require("./auth");
+    const authResult = await authCommand({
+      projectId: linkedProjectId,
+      apiKey: linkedToken,
+    });
+    existingSettings = config.readSettings();
+    isAlreadyAuthed = !!(
+      existingSettings?.apiKey && existingSettings?.projectId
+    );
+    didLinkFromOptions = true;
+    console.log(
+      chalk.green("\n✔ Connected to"),
+      chalk.cyan(existingSettings.projectName || existingSettings.projectId),
+    );
+    if (authResult?.mode) {
+      console.log(chalk.gray(`  Mode: ${authResult.mode}`));
+    }
+  } else if (linkedProjectId && !linkedToken && !offline) {
+    console.log(
+      chalk.gray(
+        `Setup will target project ${linkedProjectId}. Complete browser authentication when prompted.`,
+      ),
+    );
+  }
+
   // If already set up and not forcing, show status and offer options
-  if ((isAlreadyAuthed || existingConfig) && !force) {
+  if ((isAlreadyAuthed || existingConfig) && !force && !didLinkFromOptions) {
     console.log(
       chalk.yellow("⚠ Reshot is already configured in this project.\n"),
     );

package/src/commands/status.js

@@ -215,7 +215,7 @@ async function fetchJobsData(apiKey, projectId, limit = 5) {
 async function fetchDriftsData(apiKey, projectId) {
   try {
     const response = await apiClient.getDrifts(apiKey, projectId, {
-      status: "PENDING",
+      status: "pending",
     });
     return {
       drifts: response.drifts || [],
@@ -304,6 +304,26 @@ async function buildStatusReport(options = {}) {
   report.auth.hasApiKey = Boolean(apiKey);
   report.auth.hasProjectId = Boolean(projectId);
 
+  // Loudly warn when the linked session (settings.json) and the committed
+  // config (reshot.config.json) disagree on the project — settings.json wins,
+  // so an edited/stale config projectId would otherwise be silently ignored.
+  const configProjectId =
+    reshotConfig?.projectId || reshotConfig?._metadata?.projectId || null;
+  if (
+    projectId &&
+    configProjectId &&
+    configProjectId !== projectId &&
+    !process.env.RESHOT_PROJECT_ID
+  ) {
+    report.issues.push(
+      createIssue(
+        "config",
+        "warning",
+        `Project ID mismatch: using ${projectId} (from .reshot/settings.json) but reshot.config.json declares ${configProjectId}. Run \`reshot setup\` to reconcile.`,
+      ),
+    );
+  }
+
   if (!apiKey) {
     report.issues.push(
       createIssue(
@@ -386,7 +406,7 @@ async function displayDrifts(apiKey, projectId, limit = 10) {
   console.log(chalk.bold("\n🔄 Drift Queue\n"));
 
   try {
-    const response = await apiClient.getDrifts(apiKey, projectId, { status: "PENDING" });
+    const response = await apiClient.getDrifts(apiKey, projectId, { status: "pending" });
     const drifts = response.drifts || [];
     const stats = response.stats || {};
     renderDrifts(drifts, stats, projectId, limit);