@reshotdev/screenshot 0.0.1-beta.1 → 0.0.1-beta.10

package/README.md

@@ -21,20 +21,47 @@ Requires Node.js >= 18. Playwright browsers are installed automatically on first
 # 1. Interactive setup wizard
 reshot setup
 
-# 2. Capture screenshots from your config
+# 2. Start your app with a production-like local server
+npm run build
+npm run start
+
+# 3. Capture screenshots from your config
 reshot run
 
-# 3. Review captures in the web UI
+# 4. Review captures in the web UI
 reshot studio
+
+# 5. Publish when you want hosted assets
+reshot publish
 ```
 
+For launch-grade reliability, do not treat `next dev` as the supported capture
+runtime. Use a production-like local server and see the
+[Supported Environments guide](https://reshot.dev/docs/cli/getting-started/supported-environments).
+
+## Certified Targets
+
+This release adds a **Certified Targets** contract for apps that need stronger guarantees than ad hoc capture. Certified targets declare their readiness selectors, auth mode, required routes, and expected published assets in `reshot.config.json`, then pass the full doctor/capture/publish/delivery pipeline before release.
+
 ## Configuration
 
-Create `docsync.config.json` in your project root:
+Create `reshot.config.json` in your project root:
 
 ```json
 {
   "baseUrl": "http://localhost:3000",
+  "target": {
+    "key": "docs-app",
+    "displayName": "Docs App",
+    "tier": "certified",
+    "owner": "Docs Team",
+    "baseUrl": "http://localhost:3000",
+    "captureSafe": false,
+    "supportedLocalCommand": "npm run build && npm run start",
+    "defaultAuthMode": "fixture",
+    "requiredEnv": ["PROJECT_ID"],
+    "certificationScenarioKeys": ["dashboard"]
+  },
   "assetDir": ".reshot/output",
   "concurrency": 2,
   "viewport": { "width": 1280, "height": 720 },
@@ -55,6 +82,15 @@ Create `docsync.config.json` in your project root:
       "name": "Dashboard",
       "url": "/dashboard",
       "requiresAuth": true,
+      "captureClass": "fixture-auth",
+      "ready": {
+        "selector": "[data-loaded='true']",
+        "expression": "window.__APP_READY__ === true"
+      },
+      "requiredRoutes": ["/dashboard"],
+      "requiredSelectors": ["[data-testid='dashboard-content']"],
+      "expectedArtifacts": ["overview", "analytics"],
+      "publishPolicy": "required",
       "readySelector": "[data-loaded='true']",
       "steps": [
         { "action": "screenshot", "key": "overview", "description": "Dashboard overview" },
@@ -76,15 +112,30 @@ Create `docsync.config.json` in your project root:
 | `reshot record [title]` | Interactive recording via Chrome DevTools | `--browser`, `--url`, `--port` |
 | `reshot sync` | Upload traces/docs to Reshot platform | `--trace-dir`, `--dry-run` |
 | `reshot studio` | Launch web management UI | `--port`, `--no-open` |
-| `reshot validate` | Check config and bindings | `--strict`, `--fix` |
 | `reshot status` | View project status and sync history | `--jobs`, `--drifts`, `--json` |
 | `reshot publish` | Upload assets with versioning | `--tag`, `--message`, `--dry-run` |
 | `reshot pull` | Generate asset map for builds | `--format json\|ts\|csv`, `--output`, `--status` |
+| `reshot doctor target` | Audit target routes, readiness, and auth contract | `--scenarios`, `--json` |
+| `reshot verify publish` | Validate publish, pull/export, and hosted delivery | `--scenarios`, `--tag`, `--json` |
+| `reshot certify` | Run the full certified-target pipeline | `--scenarios`, `--tag`, `--json` |
 | `reshot drifts` | Manage visual drift notifications | `approve`, `reject`, `ignore`, `approve-all` |
 | `reshot import-tests` | Import Playwright tests as scenarios | `--dry-run`, `--no-interactive` |
 | `reshot ci setup` | Generate CI/CD workflow files | — |
 | `reshot ci run` | Capture + publish in one step (CI) | `--tag`, `--no-publish`, `--dry-run` |
 
+## Certification Workflow
+
+Use these commands when a target app needs release-grade verification:
+
+```bash
+reshot doctor target
+reshot run --scenarios dashboard
+reshot verify publish --tag v1.0.0
+reshot certify --tag v1.0.0
+```
+
+Certification reports are written to `.reshot/reports/certification.json`.
+
 ## Step Types
 
 Steps define a sequence of browser actions within a scenario:
@@ -221,16 +272,23 @@ During recording:
 - Press **C** to start/stop a video clip
 - Press **Q** to quit and save
 
-The recorded scenario is appended to `docsync.config.json` automatically.
+The recorded scenario is appended to `reshot.config.json` automatically.
 
 ## Authentication
 
-### Storage State (from Playwright)
+### Storage State
+
+The CLI stores browser session state at `~/.reshot/session-state.json` (global).
+This is automatically captured when you run `reshot record`.
+
+To manually generate it:
 
 ```bash
-npx playwright codegen http://localhost:3000 --save-storage=.reshot/auth-state.json
+npx playwright codegen http://localhost:3000 --save-storage=$HOME/.reshot/session-state.json
 ```
 
+Or reference a project-local path in your config:
+
 ```json
 {
   "storageStatePath": ".reshot/auth-state.json"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reshotdev/screenshot",
-  "version": "0.0.1-beta.1",
+  "version": "0.0.1-beta.10",
   "description": "CI/CD screenshot and video capture CLI",
   "author": "Reshot <hello@reshot.dev>",
   "license": "MIT",
@@ -13,7 +13,14 @@
   "publishConfig": {
     "access": "public"
   },
-  "keywords": ["screenshots", "ci-cd", "documentation", "visual-testing", "automation", "playwright"],
+  "keywords": [
+    "screenshots",
+    "ci-cd",
+    "documentation",
+    "visual-testing",
+    "automation",
+    "playwright"
+  ],
   "bin": {
     "reshot": "./src/index.js"
   },

package/src/commands/auth.js

@@ -14,6 +14,7 @@ const pkg = require("../../package.json");
 
 const DEFAULT_CALLBACK_PORT = 3721;
 const POLL_INTERVAL_MS = 2000;
+const DEFAULT_AUTH_TIMEOUT_MS = 120000;
 
 const unwrapResponse = (payload) => {
   if (!payload) {
@@ -95,15 +96,27 @@ function startLocalStatusServer(requestedPort, options = {}) {
   });
 }
 
-async function waitForCompletion(apiBaseUrl, authToken, expiresAtIso) {
+async function waitForCompletion(
+  apiBaseUrl,
+  authToken,
+  expiresAtIso,
+  options = {},
+) {
+  const httpClient = options.httpClient || axios;
+  const spinnerFactory = options.spinnerFactory || ora;
   const expiresAt = expiresAtIso
     ? Date.parse(expiresAtIso)
     : Date.now() + 5 * 60 * 1000;
-  const statusSpinner = ora("Waiting for browser authentication…").start();
+  const timeoutMs = Math.max(
+    1,
+    Number(options.timeoutMs || DEFAULT_AUTH_TIMEOUT_MS),
+  );
+  const deadline = Math.min(expiresAt, Date.now() + timeoutMs);
+  const statusSpinner = spinnerFactory("Waiting for browser authentication…").start();
 
   try {
-    while (Date.now() < expiresAt) {
-      const statusResponse = await axios.get(`${apiBaseUrl}/auth/cli/status`, {
+    while (Date.now() < deadline) {
+      const statusResponse = await httpClient.get(`${apiBaseUrl}/auth/cli/status`, {
         params: { token: authToken },
       });
       const payload = unwrapResponse(statusResponse.data);
@@ -127,39 +140,70 @@ async function waitForCompletion(apiBaseUrl, authToken, expiresAtIso) {
       await wait(POLL_INTERVAL_MS);
     }
 
-    throw new Error("Authentication timed out before completion.");
+    throw new Error(
+      "Authentication timed out before completion. Re-run `reshot auth` and use the printed auth URL if the browser handoff stalls.",
+    );
   } catch (error) {
     statusSpinner.fail("Browser authentication failed");
     throw error;
   }
 }
 
-async function verifyApiKey(apiBaseUrl, apiKey) {
-  await axios.get(`${apiBaseUrl}/auth/cli/verify`, {
+async function verifyApiKey(apiBaseUrl, apiKey, httpClient = axios) {
+  await httpClient.get(`${apiBaseUrl}/auth/cli/verify`, {
     headers: {
       Authorization: `Bearer ${apiKey}`,
     },
   });
 }
 
-async function authCommand() {
-  const apiBaseUrl = getApiBaseUrl();
+async function authCommand(options = {}) {
+  // Support non-interactive auth via environment variables (for CI/CD)
+  const envApiKey = process.env.RESHOT_API_KEY;
+  const envProjectId = process.env.RESHOT_PROJECT_ID;
+  const httpClient = options.httpClient || axios;
+  const openFn = options.openFn || open;
+  const writeSettingsFn = options.writeSettingsFn || writeSettings;
+  const startLocalStatusServerFn =
+    options.startLocalStatusServerFn || startLocalStatusServer;
+  const waitForCompletionFn = options.waitForCompletionFn || waitForCompletion;
+  const verifyApiKeyFn = options.verifyApiKeyFn || verifyApiKey;
+  const spinnerFactory = options.spinnerFactory || ora;
+  const timeoutMs = Number(options.timeoutMs || DEFAULT_AUTH_TIMEOUT_MS);
+  if (envApiKey && envProjectId) {
+    const platformUrl = process.env.RESHOT_PLATFORM_URL || "https://reshot.dev";
+    writeSettingsFn({
+      projectId: envProjectId,
+      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(`  Platform: ${platformUrl}`));
+    return {
+      mode: "cloud-connected",
+      projectId: envProjectId,
+      platformUrl,
+    };
+  }
+
+  const apiBaseUrl = options.apiBaseUrl || getApiBaseUrl();
   const explicitPortEnv =
-    process.env.RESHOT_CLI_CALLBACK_PORT ||
-    process.env.DOCSYNC_CLI_CALLBACK_PORT ||
-    "";
+    process.env.RESHOT_CLI_CALLBACK_PORT || "";
   const basePort = parseInt(explicitPortEnv || `${DEFAULT_CALLBACK_PORT}`, 10);
   const hasExplicitPort = Boolean(explicitPortEnv);
 
   let localServer;
   let callbackPort;
-  const spinner = ora("Requesting authentication session…").start();
+  const spinner = spinnerFactory("Requesting authentication session…").start();
 
   try {
     if (hasExplicitPort) {
       // Respect an explicitly configured port and fail fast with a clear error
       // if it is not available.
-      const { server, port } = await startLocalStatusServer(basePort, {
+      const { server, port } = await startLocalStatusServerFn(basePort, {
         explicit: true,
       });
       localServer = server;
@@ -169,12 +213,12 @@ async function authCommand() {
       // but automatically fall back to any available port so users never have
       // to think about port conflicts.
       try {
-        const { server, port } = await startLocalStatusServer(basePort);
+        const { server, port } = await startLocalStatusServerFn(basePort);
         localServer = server;
         callbackPort = port;
       } catch (error) {
         if (error && error.code === "EADDRINUSE") {
-          const { server, port } = await startLocalStatusServer(0);
+          const { server, port } = await startLocalStatusServerFn(0);
           localServer = server;
           callbackPort = port;
           console.log(
@@ -188,7 +232,7 @@ async function authCommand() {
       }
     }
 
-    const initiateResponse = await axios.post(
+    const initiateResponse = await httpClient.post(
       `${apiBaseUrl}/auth/cli/initiate`,
       {
         callbackPort,
@@ -207,21 +251,47 @@ async function authCommand() {
     spinner.succeed("Authentication session created");
     console.log(chalk.gray(`Token expires at ${expiresAt || "unknown time"}`));
     console.log(chalk.gray(`Settings will be stored in ${SETTINGS_PATH}`));
-
-    await open(authUrl, { wait: false });
+    console.log(chalk.gray("Auth URL:"));
+    console.log(chalk.cyan(authUrl));
     console.log(
-      chalk.blue(
-        "A browser window has been opened. Complete the flow to continue."
-      )
+      chalk.gray(
+        "If the browser did not open, copy the URL above into a browser and complete the approval flow there.",
+      ),
     );
 
-    const status = await waitForCompletion(apiBaseUrl, authToken, expiresAt);
-    await verifyApiKey(apiBaseUrl, status.project.apiKey);
+    let browserOpened = false;
+    try {
+      await openFn(authUrl, { wait: false });
+      browserOpened = true;
+      console.log(
+        chalk.blue(
+          "A browser window has been opened. Approve the session there to continue.",
+        )
+      );
+    } catch (error) {
+      console.log(
+        chalk.yellow(
+          `Could not open a browser automatically: ${error.message}`,
+        ),
+      );
+      console.log(
+        chalk.gray(
+          "Continue by opening the auth URL manually. The CLI will keep waiting for approval.",
+        ),
+      );
+    }
+
+    const status = await waitForCompletionFn(apiBaseUrl, authToken, expiresAt, {
+      httpClient,
+      spinnerFactory,
+      timeoutMs,
+    });
+    await verifyApiKeyFn(apiBaseUrl, status.project.apiKey, httpClient);
 
     // Derive platformUrl from apiBaseUrl (remove /api suffix)
-    const platformUrl = apiBaseUrl.replace(/\/api\/?$/, '') || 'http://localhost:3000';
+    const platformUrl = apiBaseUrl.replace(/\/api\/?$/, '') || 'https://reshot.dev';
 
-    writeSettings({
+    writeSettingsFn({
       projectId: status.project.id,
       projectName: status.project.name,
       apiKey: status.project.apiKey,
@@ -249,6 +319,15 @@ async function authCommand() {
       )
     );
     console.log(chalk.gray(`Settings saved to ${SETTINGS_PATH}`));
+    console.log(chalk.gray("Mode: cloud-connected"));
+    return {
+      mode: "cloud-connected",
+      browserOpened,
+      authUrl,
+      projectId: status.project.id,
+      projectName: status.project.name,
+      platformUrl,
+    };
   } finally {
     if (localServer) {
       localServer.close();
@@ -257,3 +336,6 @@ async function authCommand() {
 }
 
 module.exports = authCommand;
+module.exports.waitForCompletion = waitForCompletion;
+module.exports.verifyApiKey = verifyApiKey;
+module.exports.startLocalStatusServer = startLocalStatusServer;

package/src/commands/certify.js

@@ -0,0 +1,62 @@
+"use strict";
+
+const chalk = require("chalk");
+const { runCertification } = require("../lib/certification");
+
+async function certifyCommand(options = {}) {
+  const scenarioKeys = options.scenarios
+    ? String(options.scenarios)
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean)
+    : null;
+
+  const report = await runCertification({
+    scenarioKeys,
+    tag: options.tag,
+    message: options.message,
+    skipReleaseDoctor: options.skipReleaseDoctor,
+  });
+
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(chalk.cyan("\n🏅 Certified Target Verification\n"));
+    console.log(chalk.gray(`Target: ${report.target.displayName}`));
+    console.log(
+      report.ok
+        ? chalk.green(`  ✔ Final status: ${report.finalStatus}`)
+        : chalk.red(`  ✖ Final status: ${report.finalStatus}`),
+    );
+    console.log(
+      report.releaseDoctor?.skipped
+        ? chalk.gray("  • Release doctor skipped")
+        : report.releaseDoctor?.ok
+          ? chalk.green("  ✔ Release doctor passed")
+          : chalk.red("  ✖ Release doctor failed"),
+    );
+    console.log(
+      report.doctor.ok
+        ? chalk.green("  ✔ Doctor passed")
+        : chalk.red("  ✖ Doctor failed"),
+    );
+    console.log(
+      report.capture.success
+        ? chalk.green("  ✔ Capture passed")
+        : chalk.red("  ✖ Capture failed"),
+    );
+    console.log(
+      report.publishVerification.ok
+        ? chalk.green("  ✔ Publish verification passed")
+        : chalk.red("  ✖ Publish verification failed"),
+    );
+  }
+
+  if (!report.ok) {
+    process.exitCode = 1;
+  }
+
+  return report;
+}
+
+module.exports = certifyCommand;

package/src/commands/ci-run.js

@@ -5,7 +5,14 @@ const path = require("path");
 const { detectCI, getCIMetadata } = require("../lib/ci-detect");
 
 async function ciRunCommand(options = {}) {
-  const { config: configPath, tag, message, dryRun, publish: shouldPublish = true } = options;
+  const {
+    config: configPath,
+    tag,
+    message,
+    dryRun,
+    publish: shouldPublish = true,
+    skipReleaseDoctor = false,
+  } = options;
 
   // Disable colors in CI for cleaner logs
   const { isCI, provider } = detectCI();
@@ -33,12 +40,47 @@ async function ciRunCommand(options = {}) {
   }
 
   const ciResult = {
+    releaseDoctor: null,
     run: { success: false, scenariosRun: 0, scenariosFailed: 0 },
     publish: null,
     ci: ciMeta,
     timestamp: new Date().toISOString(),
   };
 
+  if (!skipReleaseDoctor) {
+    console.log(chalk.cyan("━━━ Step 0: Release Doctor ━━━\n"));
+    try {
+      const { runReleaseDoctor } = require("../lib/release-doctor");
+      const releaseDoctor = await runReleaseDoctor({});
+      ciResult.releaseDoctor = {
+        success: releaseDoctor.ok,
+        reportPath: releaseDoctor.reportPath || null,
+      };
+
+      if (!releaseDoctor.ok) {
+        console.error(chalk.red("Release doctor failed. Skipping capture and publish."));
+        const outputDir = path.join(process.cwd(), ".reshot", "output");
+        fs.ensureDirSync(outputDir);
+        const resultPath = path.join(outputDir, "ci-result.json");
+        fs.writeJsonSync(resultPath, ciResult, { spaces: 2 });
+        process.exitCode = 1;
+        return ciResult;
+      }
+    } catch (error) {
+      console.error(chalk.red(`Release doctor failed: ${error.message}`));
+      ciResult.releaseDoctor = { success: false, error: error.message };
+      const outputDir = path.join(process.cwd(), ".reshot", "output");
+      fs.ensureDirSync(outputDir);
+      const resultPath = path.join(outputDir, "ci-result.json");
+      fs.writeJsonSync(resultPath, ciResult, { spaces: 2 });
+      process.exitCode = 1;
+      return ciResult;
+    }
+  } else {
+    ciResult.releaseDoctor = { skipped: true, success: true };
+    console.log(chalk.gray("Skipping release doctor (--skip-release-doctor)\n"));
+  }
+
   // Step 1: Run capture scenarios
   console.log(chalk.cyan("━━━ Step 1: Capture ━━━\n"));
   try {
@@ -70,6 +112,7 @@ async function ciRunCommand(options = {}) {
         dryRun,
         force: true, // Skip prompts in CI
         outputJson: true,
+        skipReleaseDoctor: true,
       });
 
       ciResult.publish = {
@@ -98,6 +141,15 @@ async function ciRunCommand(options = {}) {
 
   // Summary
   console.log(chalk.cyan("\n━━━ CI Summary ━━━\n"));
+  if (ciResult.releaseDoctor) {
+    const doctorIcon = ciResult.releaseDoctor.success ? chalk.green("✔") : chalk.red("✖");
+    const doctorLabel = ciResult.releaseDoctor.skipped
+      ? "skipped"
+      : ciResult.releaseDoctor.success
+        ? "passed"
+        : "failed";
+    console.log(`  ${doctorIcon} Release doctor: ${doctorLabel}`);
+  }
   const runIcon = ciResult.run.success ? chalk.green("✔") : chalk.red("✖");
   console.log(`  ${runIcon} Capture: ${ciResult.run.scenariosRun} scenario(s), ${ciResult.run.scenariosFailed} failed`);
 
@@ -112,7 +164,10 @@ async function ciRunCommand(options = {}) {
   console.log();
 
   // Exit with appropriate code
-  const overallSuccess = ciResult.run.success && (!ciResult.publish || ciResult.publish.success);
+  const overallSuccess =
+    (ciResult.releaseDoctor?.success ?? true) &&
+    ciResult.run.success &&
+    (!ciResult.publish || ciResult.publish.success);
   if (!overallSuccess) {
     process.exitCode = 1;
   }

package/src/commands/ci-setup.js

@@ -29,7 +29,7 @@ jobs:
         run: npm install
       
       - name: Install Reshot CLI
-        run: npm install -g @reshot/cli
+        run: npm install -g @reshotdev/screenshot
       
       - name: Install Playwright browsers
         run: npx playwright install chromium
@@ -37,7 +37,7 @@ jobs:
       - name: Install ffmpeg
         run: sudo apt-get update && sudo apt-get install -y ffmpeg
       
-      # Generate visual assets from docsync.config.json blueprint
+      # Generate visual assets from reshot.config.json blueprint
       # Only runs if features.visuals is enabled for the project
       - name: Run Reshot scenarios
         env:
@@ -85,7 +85,7 @@ jobs:
           name: Install dependencies
           command: |
             npm install
-            npm install -g @reshot/cli
+            npm install -g @reshotdev/screenshot
       
       - run:
           name: Install Playwright browsers
@@ -130,7 +130,7 @@ docs:
     - apt-get update && apt-get install -y ffmpeg
     - npm install
     - npx playwright install chromium
-    - npm install -g @reshot/cli
+    - npm install -g @reshotdev/screenshot
   
   script:
     - reshot run
@@ -205,7 +205,7 @@ async function ciSetupCommand() {
 
   switch (provider) {
     case 'github':
-      workflowPath = path.join(process.cwd(), '.github', 'workflows', 'docsync.yml');
+      workflowPath = path.join(process.cwd(), '.github', 'workflows', 'reshot.yml');
       workflowContent = GITHUB_ACTIONS_WORKFLOW(secretNames);
       break;
     

package/src/commands/doctor-release.js

@@ -0,0 +1,67 @@
+"use strict";
+
+const chalk = require("chalk");
+const { runReleaseDoctor } = require("../lib/release-doctor");
+
+async function doctorReleaseCommand(options = {}) {
+  const report = await runReleaseDoctor(options);
+
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(chalk.cyan("\n🧪 Release Doctor\n"));
+    console.log(
+      report.ok
+        ? chalk.green("  ✔ Release gate checks passed")
+        : chalk.red("  ✖ Release gate checks failed"),
+    );
+
+    console.log(
+      report.runPreflight.ok
+        ? chalk.green("  ✔ Run preflight healthy")
+        : chalk.red("  ✖ Run preflight failed"),
+    );
+
+    if (report.targetDoctor.skipped) {
+      console.log(chalk.gray("  • Target doctor skipped (non-certified target)"));
+    } else {
+      console.log(
+        report.targetDoctor.ok
+          ? chalk.green("  ✔ Target doctor healthy")
+          : chalk.red("  ✖ Target doctor failed"),
+      );
+    }
+
+    if (report.docsAssetMap.skipped) {
+      console.log(chalk.gray("  • Docs asset map skipped"));
+    } else {
+      console.log(
+        report.docsAssetMap.ok
+          ? chalk.green("  ✔ Docs asset map healthy")
+          : chalk.red("  ✖ Docs asset map failed"),
+      );
+      if (report.docsAssetMap.path) {
+        console.log(chalk.gray(`    ${report.docsAssetMap.path}`));
+      }
+    }
+
+    const blockingIssues = report.summary?.blockingIssues || [];
+    if (blockingIssues.length > 0) {
+      for (const issue of blockingIssues.slice(0, 10)) {
+        console.log(chalk.red(`  ✖ ${issue.scope}: ${issue.message}`));
+      }
+    }
+
+    if (report.reportPath) {
+      console.log(chalk.gray(`\n  Report: ${report.reportPath}`));
+    }
+  }
+
+  if (!report.ok) {
+    process.exitCode = 1;
+  }
+
+  return report;
+}
+
+module.exports = doctorReleaseCommand;