@reshotdev/screenshot 0.0.1-beta.2 → 0.0.1-beta.20

package/src/commands/pull.js

@@ -1,5 +1,5 @@
 // pull.js - Pull asset map from Reshot platform
-// Generates JSON, TypeScript, or CSV files for consumption in build pipelines
+// Generates JSON, TypeScript, or CSV files for local workflows
 const chalk = require("chalk");
 const fs = require("fs-extra");
 const path = require("path");
@@ -16,6 +16,160 @@ function toCamelCase(str) {
     .replace(/^[A-Z]/, (chr) => chr.toLowerCase());
 }
 
+function normalizeHostedAssetUrl(urlString) {
+  if (!urlString || typeof urlString !== "string") {
+    return urlString;
+  }
+
+  let normalized = urlString;
+  if (!normalized.includes("?") && normalized.includes("&")) {
+    const firstAmp = normalized.indexOf("&");
+    normalized = `${normalized.slice(0, firstAmp)}?${normalized.slice(firstAmp + 1)}`;
+  }
+
+  const parsed = new URL(normalized);
+  const capture = parsed.searchParams.get("capture");
+  if (capture && !parsed.searchParams.get("step")) {
+    parsed.searchParams.set("step", capture);
+  }
+  parsed.searchParams.delete("capture");
+
+  return parsed.toString();
+}
+
+function normalizeHostedAssetUrlWithMeta(urlString) {
+  const normalized = normalizeHostedAssetUrl(urlString);
+  return {
+    url: normalized,
+    repaired: normalized !== urlString,
+  };
+}
+
+function normalizeAssetEntry(entry) {
+  if (!entry || typeof entry !== "object") {
+    return { entry, repairs: 0 };
+  }
+
+  if (Array.isArray(entry.steps)) {
+    return {
+      entry: {
+        ...entry,
+        steps: entry.steps.map((step) => {
+          const src = normalizeHostedAssetUrlWithMeta(step.src);
+          const poster = step.poster
+            ? normalizeHostedAssetUrlWithMeta(step.poster)
+            : null;
+          return {
+            ...step,
+            src: src.url,
+            poster: poster ? poster.url : step.poster,
+          };
+        }),
+      },
+      repairs: entry.steps.reduce((count, step) => {
+        const src = normalizeHostedAssetUrlWithMeta(step.src);
+        const poster = step.poster
+          ? normalizeHostedAssetUrlWithMeta(step.poster)
+          : null;
+        return count + (src.repaired ? 1 : 0) + (poster?.repaired ? 1 : 0);
+      }, 0),
+    };
+  }
+
+  return {
+    entry: {
+      ...entry,
+      src: entry.src ? normalizeHostedAssetUrl(entry.src) : entry.src,
+      poster: entry.poster ? normalizeHostedAssetUrl(entry.poster) : entry.poster,
+    },
+    repairs:
+      (entry.src && normalizeHostedAssetUrlWithMeta(entry.src).repaired ? 1 : 0) +
+      (entry.poster && normalizeHostedAssetUrlWithMeta(entry.poster).repaired ? 1 : 0),
+  };
+}
+
+function normalizeAssetMap(assets) {
+  const normalized = {};
+  let repairs = 0;
+
+  for (const [group, visuals] of Object.entries(assets || {})) {
+    normalized[group] = {};
+
+    for (const [visualKey, variants] of Object.entries(visuals || {})) {
+      normalized[group][visualKey] = {};
+
+      for (const [variant, entry] of Object.entries(variants || {})) {
+        const normalizedEntry = normalizeAssetEntry(entry);
+        normalized[group][visualKey][variant] = normalizedEntry.entry;
+        repairs += normalizedEntry.repairs;
+      }
+    }
+  }
+
+  return { assets: normalized, repairs };
+}
+
+/**
+ * Pick a real {group, visualKey, context} from a normalized asset map so the
+ * printed usage example is copy-pasteable for THIS project (prefers the
+ * "default" context). Returns null if the map is empty.
+ */
+function deriveUsageSample(assets) {
+  for (const group of Object.keys(assets || {})) {
+    for (const visualKey of Object.keys(assets[group] || {})) {
+      const contexts = Object.keys(assets[group][visualKey] || {});
+      if (contexts.length === 0) continue;
+      const context = contexts.includes("default") ? "default" : contexts[0];
+      // A capture entry is either flat ({src,width,height}) or step-based
+      // ({steps:[{src,...}]}). Tell the caller which, so the printed example
+      // references the right path (`.steps[0].src` vs `.src`) and doesn't
+      // produce an undefined src (audit run-12 MED-1).
+      const entry = assets[group][visualKey][context];
+      const stepped = !!(entry && Array.isArray(entry.steps));
+      return { group, visualKey, context, stepped };
+    }
+  }
+  return null;
+}
+
+function validateHostedAssetUrl(urlString) {
+  if (!urlString || typeof urlString !== "string") {
+    return;
+  }
+
+  if (!urlString.includes("?") && (urlString.includes("&step=") || urlString.includes("&poster="))) {
+    throw new Error(`Malformed asset URL emitted without query delimiter: ${urlString}`);
+  }
+
+  const parsed = new URL(urlString);
+  if (parsed.searchParams.has("capture")) {
+    throw new Error(`Legacy capture param emitted in normalized output: ${urlString}`);
+  }
+}
+
+function validateAssetMap(assets) {
+  for (const visuals of Object.values(assets || {})) {
+    for (const variants of Object.values(visuals || {})) {
+      for (const entry of Object.values(variants || {})) {
+        if (entry && typeof entry === "object" && Array.isArray(entry.steps)) {
+          for (const step of entry.steps) {
+            validateHostedAssetUrl(step.src);
+            if (step.poster) {
+              validateHostedAssetUrl(step.poster);
+            }
+          }
+          continue;
+        }
+
+        validateHostedAssetUrl(entry?.src);
+        if (entry?.poster) {
+          validateHostedAssetUrl(entry.poster);
+        }
+      }
+    }
+  }
+}
+
 /**
  * Generate TypeScript code from the assets object
  * This provides type safety - if a visual is deleted, the build will fail
@@ -39,12 +193,27 @@ function generateTypeScript(assets, includeMetadata = false) {
         
         for (const [variant, asset] of Object.entries(variants)) {
           lines.push(`      ${variant}: {`);
-          lines.push(`        src: "${asset.src}",`);
           lines.push(`        type: "${asset.type}",`);
-          if (asset.width) lines.push(`        width: ${asset.width},`);
-          if (asset.height) lines.push(`        height: ${asset.height},`);
           lines.push(`        alt: "${asset.alt.replace(/"/g, '\\"')}",`);
-          if (asset.poster) lines.push(`        poster: "${asset.poster}",`);
+          if (Array.isArray(asset.steps)) {
+            lines.push(`        steps: [`);
+            for (const step of asset.steps) {
+              lines.push("          {");
+              lines.push(`            step: "${step.step}",`);
+              lines.push(`            src: "${step.src}",`);
+              lines.push(`            type: "${step.type}",`);
+              if (step.width) lines.push(`            width: ${step.width},`);
+              if (step.height) lines.push(`            height: ${step.height},`);
+              if (step.poster) lines.push(`            poster: "${step.poster}",`);
+              lines.push("          },");
+            }
+            lines.push("        ],");
+          } else {
+            lines.push(`        src: "${asset.src}",`);
+            if (asset.width) lines.push(`        width: ${asset.width},`);
+            if (asset.height) lines.push(`        height: ${asset.height},`);
+            if (asset.poster) lines.push(`        poster: "${asset.poster}",`);
+          }
           lines.push(`      },`);
         }
         
@@ -67,11 +236,19 @@ function generateTypeScript(assets, includeMetadata = false) {
       for (const [visualKey, variants] of Object.entries(visuals)) {
         // If there's only a default variant, flatten it
         if (Object.keys(variants).length === 1 && variants.default) {
-          lines.push(`    ${visualKey}: "${variants.default.src}",`);
+          if (Array.isArray(variants.default.steps)) {
+            lines.push(`    ${visualKey}: ${JSON.stringify(variants.default.steps)},`);
+          } else {
+            lines.push(`    ${visualKey}: "${variants.default.src}",`);
+          }
         } else {
           lines.push(`    ${visualKey}: {`);
           for (const [variant, asset] of Object.entries(variants)) {
-            lines.push(`      ${variant}: "${asset.src}",`);
+            if (Array.isArray(asset.steps)) {
+              lines.push(`      ${variant}: ${JSON.stringify(asset.steps)},`);
+            } else {
+              lines.push(`      ${variant}: "${asset.src}",`);
+            }
           }
           lines.push(`    },`);
         }
@@ -101,7 +278,8 @@ async function pullCommand(options = {}) {
     format = "json",
     output = null,
     full = false,
-    status = "approved",
+    status = "all",
+    noExit = false,
   } = options;
 
   console.log(chalk.blue("⬇ Pulling asset map from Reshot...\n"));
@@ -112,17 +290,33 @@ async function pullCommand(options = {}) {
     projectConfig = config.readConfig();
   } catch (e) {
     console.error(
-      chalk.red("Error: No docsync.config.json found. Run 'reshot init' first.")
+      chalk.red("Error: No reshot.config.json found. Run 'reshot init' first.")
     );
-    process.exit(1);
+    if (!noExit) process.exit(1);
+    return { success: false, error: "No reshot.config.json found" };
   }
 
-  const projectId = projectConfig._metadata?.projectId || projectConfig.projectId;
+  let projectId =
+    process.env.RESHOT_PROJECT_ID ||
+    projectConfig._metadata?.projectId ||
+    projectConfig.projectId;
   if (!projectId) {
-    console.error(
-      chalk.red("Error: No projectId found in docsync.config.json")
-    );
-    process.exit(1);
+    // Fall back to reading projectId from .reshot/settings.json (written by `reshot auth`)
+    try {
+      const settings = config.readSettings();
+      if (settings?.projectId) {
+        projectId = settings.projectId;
+      }
+    } catch (e) {
+      // No settings file either
+    }
+  }
+  if (!projectId) {
+      console.error(
+        chalk.red("Error: No projectId found. Add it to reshot.config.json or run 'reshot auth' first.")
+      );
+    if (!noExit) process.exit(1);
+    return { success: false, error: "No projectId found" };
   }
 
   // Check authentication
@@ -133,13 +327,28 @@ async function pullCommand(options = {}) {
     console.error(
       chalk.red("Error: Not authenticated. Run 'reshot auth' first.")
     );
-    process.exit(1);
+    if (!noExit) process.exit(1);
+    return { success: false, error: "Not authenticated" };
   }
   if (!settings?.apiKey) {
     console.error(
       chalk.red("Error: Not authenticated. Run 'reshot auth' first.")
     );
-    process.exit(1);
+    if (!noExit) process.exit(1);
+    return { success: false, error: "Not authenticated" };
+  }
+
+  if (settings.projectId && projectId !== settings.projectId) {
+    console.warn(
+      chalk.yellow(
+        `  ⚠ Project ID mismatch: active project is ${projectId}, but authenticated project is ${settings.projectId}.`
+      )
+    );
+    console.warn(
+      chalk.yellow(
+        `    This will cause auth failures. Run 'reshot setup --force' to re-link.\n`
+      )
+    );
   }
 
   try {
@@ -154,16 +363,34 @@ async function pullCommand(options = {}) {
 
     if (!response || !response.assets) {
       console.error(chalk.red("Error: Invalid response from API"));
-      process.exit(1);
+      if (!noExit) process.exit(1);
+      return { success: false, error: "Invalid response from API" };
     }
 
-    const { meta, assets } = response;
-    const assetCount = Object.values(assets).reduce(
+    const normalization = normalizeAssetMap(response.assets);
+    const normalizedAssets = normalization.assets;
+    validateAssetMap(normalizedAssets);
+
+    const { meta } = response;
+    const assetCount = Object.values(normalizedAssets).reduce(
       (count, group) => count + Object.keys(group).length,
       0
     );
 
-    console.log(chalk.green(`  ✓ Fetched ${assetCount} visuals\n`));
+    if (assetCount === 0) {
+      console.log(chalk.yellow(`  ⚠ Fetched 0 visuals.\n`));
+      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. Active project: ${projectId}`));
+      console.log(chalk.gray(`    • Check: ${settings.platformUrl || "https://reshot.dev"}\n`));
+    } else {
+      console.log(chalk.green(`  ✓ Fetched ${assetCount} visuals\n`));
+    }
 
     // Determine output path
     let outputPath = output;
@@ -187,7 +414,7 @@ async function pullCommand(options = {}) {
 
     switch (format) {
       case "ts":
-        content = generateTypeScript(assets, full);
+        content = generateTypeScript(normalizedAssets, full);
         contentType = "TypeScript";
         break;
 
@@ -196,9 +423,28 @@ async function pullCommand(options = {}) {
         const headers = ["Key", "Group", "Name", "Context", "Type", "Unbreakable_URL", "Width", "Height"];
         const rows = [headers.join(",")];
         
-        for (const [group, visuals] of Object.entries(assets)) {
+        for (const [group, visuals] of Object.entries(normalizedAssets)) {
           for (const [visualKey, variants] of Object.entries(visuals)) {
             for (const [variant, asset] of Object.entries(variants)) {
+              if (Array.isArray(asset.steps)) {
+                for (const step of asset.steps) {
+                  const type = step.type.split("/")[0];
+                  rows.push(
+                    [
+                      `${group}/${visualKey}/${step.step}`,
+                      group,
+                      visualKey,
+                      variant,
+                      type,
+                      step.src,
+                      step.width || "",
+                      step.height || "",
+                    ].join(",")
+                  );
+                }
+                continue;
+              }
+
               const type = asset.type.split("/")[0]; // 'image' or 'video'
               rows.push(
                 [
@@ -222,7 +468,7 @@ async function pullCommand(options = {}) {
 
       case "json":
       default:
-        content = JSON.stringify({ meta, assets }, null, 2);
+        content = JSON.stringify({ meta, assets: normalizedAssets }, null, 2);
         contentType = "JSON";
         break;
     }
@@ -233,6 +479,16 @@ async function pullCommand(options = {}) {
     console.log(chalk.green(`✓ Generated ${contentType} file: ${outputPath}`));
     console.log(chalk.gray(`  ${assetCount} visuals exported\n`));
 
+    // Derive a REAL key path from the pulled map so the printed usage example
+    // is copy-pasteable (was hardcoded to a non-existent `dashboard.mainView`).
+    const sample = deriveUsageSample(normalizedAssets);
+    const sGroup = sample?.group ?? "dashboard";
+    const sVisual = sample?.visualKey ?? "mainView";
+    const sCtx = sample?.context ?? "default";
+    // Step-based capture entries nest the fields under `steps[0]`; reference it
+    // so the printed example's src/width/height aren't undefined (run-12 MED-1).
+    const sStep = sample?.stepped ? ".steps[0]" : "";
+
     // Show format-specific usage instructions
     if (format === "ts") {
       console.log(chalk.blue("━━━ TypeScript Usage ━━━\n"));
@@ -240,10 +496,9 @@ async function pullCommand(options = {}) {
       console.log(chalk.cyan('  import { ReshotVisuals } from "./visuals";\n'));
       console.log(chalk.white("Use with full autocomplete support:\n"));
       console.log(chalk.cyan("  // Single context (flattened)"));
-      console.log(chalk.cyan("  <img src={ReshotVisuals.dashboard.mainView} />\n"));
+      console.log(chalk.cyan(`  <img src={ReshotVisuals.${sGroup}.${sVisual}} />\n`));
       console.log(chalk.cyan("  // Multiple contexts (dark mode, locales)"));
-      console.log(chalk.cyan("  <img src={ReshotVisuals.dashboard.mainView.default} />"));
-      console.log(chalk.cyan("  <img src={ReshotVisuals.dashboard.mainView.dark} />\n"));
+      console.log(chalk.cyan(`  <img src={ReshotVisuals.${sGroup}.${sVisual}.${sCtx}} />\n`));
       if (!full) {
         console.log(chalk.gray("  Tip: Use --full flag to include width, height, and alt text\n"));
       }
@@ -253,10 +508,10 @@ async function pullCommand(options = {}) {
       console.log(chalk.cyan('  import assets from "./reshot-assets.json";\n'));
       console.log(chalk.white("Access assets with dot notation:\n"));
       console.log(chalk.cyan("  <img"));
-      console.log(chalk.cyan("    src={assets.assets.dashboard.mainView.default.src}"));
-      console.log(chalk.cyan("    width={assets.assets.dashboard.mainView.default.width}"));
-      console.log(chalk.cyan("    height={assets.assets.dashboard.mainView.default.height}"));
-      console.log(chalk.cyan("    alt={assets.assets.dashboard.mainView.default.alt}"));
+      console.log(chalk.cyan(`    src={assets.assets.${sGroup}.${sVisual}.${sCtx}${sStep}.src}`));
+      console.log(chalk.cyan(`    width={assets.assets.${sGroup}.${sVisual}.${sCtx}${sStep}.width}`));
+      console.log(chalk.cyan(`    height={assets.assets.${sGroup}.${sVisual}.${sCtx}${sStep}.height}`));
+      console.log(chalk.cyan(`    alt={assets.assets.${sGroup}.${sVisual}.${sCtx}${sStep}.alt}`));
       console.log(chalk.cyan("  />\n"));
     } else if (format === "csv") {
       console.log(chalk.blue("━━━ CSV Usage ━━━\n"));
@@ -275,9 +530,9 @@ async function pullCommand(options = {}) {
       console.log(chalk.gray("  • Width/Height  - Dimensions in pixels\n"));
     }
 
-    // CI/CD integration tip
-    console.log(chalk.blue("━━━ CI/CD Integration ━━━\n"));
-    console.log(chalk.white("Add to your build pipeline:\n"));
+    // Workflow integration tip
+    console.log(chalk.blue("━━━ Workflow Integration ━━━\n"));
+    console.log(chalk.white("Add to your local workflow:\n"));
     console.log(chalk.cyan("  # package.json"));
     console.log(chalk.cyan('  "scripts": {'));
     console.log(chalk.cyan(`    "prebuild": "npx reshot pull --format=${format}${output ? ` --output=${output}` : ''}"`));
@@ -285,6 +540,15 @@ async function pullCommand(options = {}) {
     console.log(chalk.gray("  This ensures your build always uses the latest approved visuals."));
     console.log(chalk.gray("  If a visual is deleted, your build will fail (preventing broken images).\n"));
 
+    return {
+      success: true,
+      assetCount,
+      outputPath: path.resolve(outputPath),
+      normalizedAssets,
+      normalizationRepairs: normalization.repairs,
+      meta,
+    };
+
   } catch (error) {
     if (config.isAuthError(error)) {
       console.error(
@@ -296,7 +560,10 @@ async function pullCommand(options = {}) {
         console.error(chalk.gray(error.stack));
       }
     }
-    process.exit(1);
+    if (!noExit) {
+      process.exit(1);
+    }
+    return { success: false, error: error.message };
   }
 }
 

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