@reshotdev/screenshot 0.0.1-beta.15 → 0.0.1-beta.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reshotdev/screenshot",
-  "version": "0.0.1-beta.15",
+  "version": "0.0.1-beta.17",
   "description": "Screenshot and video capture CLI",
   "author": "Reshot <hello@reshot.dev>",
   "license": "MIT",

package/src/commands/auth.js

@@ -150,11 +150,12 @@ async function waitForCompletion(
 }
 
 async function verifyApiKey(apiBaseUrl, apiKey, httpClient = axios) {
-  await httpClient.get(`${apiBaseUrl}/auth/cli/verify`, {
+  const response = await httpClient.get(`${apiBaseUrl}/auth/cli/verify`, {
     headers: {
       Authorization: `Bearer ${apiKey}`,
     },
   });
+  return response?.data || null;
 }
 
 async function authCommand(options = {}) {
@@ -172,19 +173,35 @@ async function authCommand(options = {}) {
   const timeoutMs = Number(options.timeoutMs || DEFAULT_AUTH_TIMEOUT_MS);
   if (envApiKey && envProjectId) {
     const platformUrl = process.env.RESHOT_PLATFORM_URL || "https://reshot.dev";
+    // Best-effort resolve the project name so settings + the setup report
+    // don't record `projectName: null` on this non-interactive path.
+    let projectName = null;
+    try {
+      const apiBaseUrl = options.apiBaseUrl || getApiBaseUrl();
+      const verified = await verifyApiKeyFn(apiBaseUrl, envApiKey, httpClient);
+      // /auth/cli/verify wraps its payload in an { data: … } envelope.
+      const payload = verified?.data || verified;
+      projectName = payload?.project?.name || null;
+    } catch {
+      // Verification is best-effort here; keep going without the name.
+    }
     writeSettingsFn({
       projectId: envProjectId,
+      projectName,
       apiKey: envApiKey,
       platformUrl,
       linkedAt: new Date().toISOString(),
       cliVersion: pkg.version,
     });
     console.log(chalk.green("✔ Authenticated via environment variables"));
-    console.log(chalk.gray(`  Project: ${envProjectId}`));
+    console.log(
+      chalk.gray(`  Project: ${projectName || envProjectId}`),
+    );
     console.log(chalk.gray(`  Platform: ${platformUrl}`));
     return {
       mode: "cloud-connected",
       projectId: envProjectId,
+      projectName,
       platformUrl,
     };
   }

package/src/commands/publish.js

@@ -666,6 +666,7 @@ async function publishWithTransactionalFlow(
   let successCount = 0;
   let failCount = 0;
   let skippedCount = 0;
+  let reviewPendingCount = 0;
   let viewUrl = null;
 
   // Flatten all assets with metadata
@@ -878,7 +879,16 @@ async function publishWithTransactionalFlow(
           contentType: file.contentType,
         });
 
-        console.log(chalk.green(`     ✔ Uploaded ${file.visualKey}`));
+        // Label the artifact type so PNG + MHTML-sidecar lines for the same
+        // visual don't read as a duplicate-upload bug (audit run-10 F3).
+        const artifactLabel = file._isThumbnail
+          ? "thumbnail"
+          : file._isDomScene
+            ? "dom scene .mhtml"
+            : (path.extname(file.path || "").replace(/^\./, "") || "asset");
+        console.log(
+          chalk.green(`     ✔ Uploaded ${file.visualKey} (${artifactLabel})`),
+        );
         return { success: true, file, s3Path: urlInfo.path };
       } catch (err) {
         console.log(
@@ -1008,6 +1018,10 @@ async function publishWithTransactionalFlow(
       // Unwrap API envelope: response may be { data: { results, ... } } or { results, ... }
       const batchResult = rawBatchResult.data || rawBatchResult;
 
+      // Count only NEWLY-pending (new/changed) captures, so the final summary
+      // doesn't imply a re-publish reset already-live captures (audit F1).
+      reviewPendingCount += batchResult.reviewQueueItems || 0;
+
       for (const r of batchResult.results || []) {
         if (r.status === "ok") {
           const count = r.assetsProcessed || 0;
@@ -1051,7 +1065,14 @@ async function publishWithTransactionalFlow(
     }
   }
 
-  return { successCount, failCount, skippedCount, viewUrl, failedUploadKeys };
+  return {
+    successCount,
+    failCount,
+    skippedCount,
+    reviewPendingCount,
+    viewUrl,
+    failedUploadKeys,
+  };
 }
 
 /**
@@ -1697,6 +1718,7 @@ async function publishCommand(options = {}) {
       let successCount = 0;
       let failCount = 0;
       let skippedCount = 0;
+      let reviewPendingCount = 0;
       let viewUrl = null;
 
       // Load diff manifests for attaching diff data to screenshot assets
@@ -1743,6 +1765,7 @@ async function publishCommand(options = {}) {
             successCount = result.successCount;
             failCount = result.failCount;
             skippedCount = result.skippedCount || 0;
+            reviewPendingCount = result.reviewPendingCount || 0;
             viewUrl = result.viewUrl || null;
           } catch (txError) {
             // Fall back to legacy flow if transactional fails
@@ -1809,21 +1832,40 @@ async function publishCommand(options = {}) {
       }
 
       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.",
-          ),
-        );
+        // Only NEW/CHANGED captures await review; unchanged captures dedup to
+        // their existing (often already-approved) version and stay live. Report
+        // the accurate pending count so a re-publish doesn't look like it reset
+        // already-approved work (audit run-10 F1).
+        const pending = reviewPendingCount;
+        const keptLive = Math.max(0, successCount - pending);
+        if (pending > 0) {
+          console.log(
+            chalk.cyan(
+              `\n  ℹ ${pending} new/changed visual${pending === 1 ? "" : "s"} awaiting review (PENDING)`,
+            ),
+          );
+          if (keptLive > 0) {
+            console.log(
+              chalk.gray(
+                `    ${keptLive} unchanged visual${keptLive === 1 ? "" : "s"} stayed live (no re-approval needed).`,
+              ),
+            );
+          }
+          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."),
+          );
+        } else {
+          console.log(
+            chalk.cyan(
+              `\n  ℹ No new captures to review — all ${successCount} published visual${successCount === 1 ? "" : "s"} were unchanged and stayed live.`,
+            ),
+          );
+        }
       }
 
       // Helpful guidance about diff percentages

package/src/commands/pull.js

@@ -109,6 +109,23 @@ function normalizeAssetMap(assets) {
   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];
+      return { group, visualKey, context };
+    }
+  }
+  return null;
+}
+
 function validateHostedAssetUrl(urlString) {
   if (!urlString || typeof urlString !== "string") {
     return;
@@ -456,6 +473,13 @@ 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";
+
     // Show format-specific usage instructions
     if (format === "ts") {
       console.log(chalk.blue("━━━ TypeScript Usage ━━━\n"));
@@ -463,10 +487,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"));
       }
@@ -476,10 +499,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}.src}`));
+      console.log(chalk.cyan(`    width={assets.assets.${sGroup}.${sVisual}.${sCtx}.width}`));
+      console.log(chalk.cyan(`    height={assets.assets.${sGroup}.${sVisual}.${sCtx}.height}`));
+      console.log(chalk.cyan(`    alt={assets.assets.${sGroup}.${sVisual}.${sCtx}.alt}`));
       console.log(chalk.cyan("  />\n"));
     } else if (format === "csv") {
       console.log(chalk.blue("━━━ CSV Usage ━━━\n"));

package/src/index.js

@@ -159,6 +159,7 @@ program
   .command("run [target]")
   .description("Execute visual capture scenarios from config")
   .option("-s, --scenarios <keys>", "Comma-separated list of scenario keys")
+  .option("--scenario <keys>", "Alias for --scenarios")
   .option("--no-headless", "Run browser in visible mode")
   .option("--variant <json>", "Override variant configuration as JSON")
   .option("--all-variants", "Run all configured variant combinations")
@@ -431,7 +432,24 @@ program
   });
 
 // Doctor: Validate target contract and readiness
-const doctor = program.command("doctor").description("Validate target configuration and readiness");
+const doctor = program
+  .command("doctor")
+  .description("Validate target configuration and readiness")
+  .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) => {
+    // Bare `reshot doctor` runs the target readiness audit by default instead
+    // of just printing help (audit run-10 F5). Use `doctor release` for the
+    // full release gate.
+    try {
+      const doctorTargetCommand = require("./commands/doctor-target");
+      await doctorTargetCommand(options || {});
+    } catch (error) {
+      console.error(chalk.red("Error:"), error.message);
+      process.exit(1);
+    }
+  });
 
 doctor
   .command("target")
@@ -640,8 +658,11 @@ function resolveRecordClipScenarioKeys(target, options = {}) {
 }
 
 function resolveScenarioKeysFromTarget(target, options = {}) {
-  if (options.scenarios) {
-    return options.scenarios.split(",").map((value) => value.trim()).filter(Boolean);
+  // Accept the singular `--scenario` as an alias for `--scenarios` — an easy
+  // trap that otherwise hard-fails the run (audit run-10 F2).
+  const scenarioList = options.scenarios || options.scenario;
+  if (scenarioList) {
+    return scenarioList.split(",").map((value) => value.trim()).filter(Boolean);
   }
 
   if (!target) {