autokap 1.3.2 → 1.3.3

package/dist/cli-config.d.ts

@@ -8,6 +8,7 @@ declare const DEFAULT_WS_URL = "wss://autokap.app/ws";
 declare const LOCAL_API_BASE_URL = "http://localhost:3000";
 declare const LOCAL_WS_URL = "ws://localhost:3000/ws";
 declare const API_KEY_ENV_VAR = "AUTOKAP_API_KEY";
+declare const RUN_TOKEN_ENV_VAR = "AUTOKAP_RUN_TOKEN";
 declare const API_BASE_URL_ENV_VAR = "AUTOKAP_API_BASE_URL";
 declare const WS_URL_ENV_VAR = "AUTOKAP_WS_URL";
 declare const ALLOW_UNSAFE_SERVER_ORIGIN_ENV_VAR = "AUTOKAP_ALLOW_UNSAFE_SERVER_ORIGIN";
@@ -19,4 +20,4 @@ export declare function readConfig(): Promise<AutokapConfig | null>;
 export declare function writeConfig(config: AutokapConfig): Promise<void>;
 export declare function deleteConfig(): Promise<void>;
 export declare function requireConfig(): Promise<AutokapConfig>;
-export { DEFAULT_API_BASE_URL, DEFAULT_WS_URL, LOCAL_API_BASE_URL, LOCAL_WS_URL, API_KEY_ENV_VAR, API_BASE_URL_ENV_VAR, WS_URL_ENV_VAR, ALLOW_UNSAFE_SERVER_ORIGIN_ENV_VAR, };
+export { DEFAULT_API_BASE_URL, DEFAULT_WS_URL, LOCAL_API_BASE_URL, LOCAL_WS_URL, API_KEY_ENV_VAR, RUN_TOKEN_ENV_VAR, API_BASE_URL_ENV_VAR, WS_URL_ENV_VAR, ALLOW_UNSAFE_SERVER_ORIGIN_ENV_VAR, };

package/dist/cli-config.js

@@ -7,6 +7,7 @@ const DEFAULT_WS_URL = 'wss://autokap.app/ws';
 const LOCAL_API_BASE_URL = 'http://localhost:3000';
 const LOCAL_WS_URL = 'ws://localhost:3000/ws';
 const API_KEY_ENV_VAR = 'AUTOKAP_API_KEY';
+const RUN_TOKEN_ENV_VAR = 'AUTOKAP_RUN_TOKEN';
 const API_BASE_URL_ENV_VAR = 'AUTOKAP_API_BASE_URL';
 const WS_URL_ENV_VAR = 'AUTOKAP_WS_URL';
 const ALLOW_UNSAFE_SERVER_ORIGIN_ENV_VAR = 'AUTOKAP_ALLOW_UNSAFE_SERVER_ORIGIN';
@@ -23,6 +24,17 @@ export function getDefaultWsUrl(apiBaseUrl = getDefaultApiBaseUrl()) {
     return normalizeUrl(process.env[WS_URL_ENV_VAR]) ?? deriveWsUrl(apiBaseUrl);
 }
 export async function readConfig() {
+    const envRunToken = normalizeApiKey(process.env[RUN_TOKEN_ENV_VAR]);
+    if (envRunToken) {
+        const apiBaseUrl = getDefaultApiBaseUrl();
+        const wsUrl = getDefaultWsUrl(apiBaseUrl);
+        assertAllowedApiOrigin(apiBaseUrl, DEFAULT_API_BASE_URL, API_BASE_URL_ENV_VAR);
+        return {
+            apiKey: envRunToken,
+            apiBaseUrl,
+            wsUrl,
+        };
+    }
     const envApiKey = normalizeApiKey(process.env[API_KEY_ENV_VAR]);
     if (envApiKey) {
         const apiBaseUrl = getDefaultApiBaseUrl();
@@ -159,5 +171,5 @@ function assertAllowedApiOrigin(candidateUrl, baselineUrl, envVar) {
     }
     throw new Error(`Refusing unsafe server override to ${candidateOrigin}. Set ${ALLOW_UNSAFE_SERVER_ORIGIN_ENV_VAR}=1 to allow ${envVar ?? 'this override'} explicitly.`);
 }
-export { DEFAULT_API_BASE_URL, DEFAULT_WS_URL, LOCAL_API_BASE_URL, LOCAL_WS_URL, API_KEY_ENV_VAR, API_BASE_URL_ENV_VAR, WS_URL_ENV_VAR, ALLOW_UNSAFE_SERVER_ORIGIN_ENV_VAR, };
+export { DEFAULT_API_BASE_URL, DEFAULT_WS_URL, LOCAL_API_BASE_URL, LOCAL_WS_URL, API_KEY_ENV_VAR, RUN_TOKEN_ENV_VAR, API_BASE_URL_ENV_VAR, WS_URL_ENV_VAR, ALLOW_UNSAFE_SERVER_ORIGIN_ENV_VAR, };
 //# sourceMappingURL=cli-config.js.map

package/dist/cli-contract.js

@@ -52,7 +52,7 @@ export const CLI_PUBLIC_COMMANDS = [
     {
         id: "auto-recapture",
         command: "autokap auto-recapture --project <project-id> --env local",
-        summary: "Run every preset enabled for CI auto-recapture in a project",
+        summary: "Run every preset enabled for Recapture Cloud in a project",
         docsDescriptionKey: "cliCmdAutoRecapture",
     },
     {

package/dist/cli-runner-local.js

@@ -57,6 +57,17 @@ export async function runLocal(presetId, opts) {
                 case 'breaker_trip':
                     logger.error(`${prefix} CIRCUIT BREAKER: ${event.message}`);
                     break;
+                case 'upload_start':
+                    logger.info('[capture] Uploading artifacts and telemetry');
+                    break;
+                case 'upload_end':
+                    if (event.status === 'failed') {
+                        logger.error(`[capture] Upload failed: ${event.message}`);
+                    }
+                    else {
+                        logger.info('[capture] Upload complete');
+                    }
+                    break;
             }
         },
     });

package/dist/cli-runner.d.ts

@@ -40,6 +40,7 @@ export interface CLIRunnerOptions {
 }
 export interface CLIRunResult {
     success: boolean;
+    runId?: string;
     runResult?: RunResult;
     error?: string;
 }

package/dist/cli-runner.js

@@ -156,12 +156,12 @@ export async function runCapture(options) {
         assertProgramNavigationScope(program, resolvedProgram.security);
     }
     catch (error) {
-        return { success: false, error: error instanceof Error ? error.message : String(error) };
+        return { success: false, runId, error: error instanceof Error ? error.message : String(error) };
     }
     if (!options.program && program.mediaMode === 'video') {
         const prepareResult = await prepareVideoSpeechForRun(config, options.presetId, runId);
         if (!prepareResult.success) {
-            return { success: false, error: prepareResult.error };
+            return { success: false, runId, error: prepareResult.error };
         }
         program = applyVideoSpeechDurations(program, prepareResult.durationsByStepId);
         videoAudioAssets = prepareResult.audioAssets;
@@ -170,7 +170,7 @@ export async function runCapture(options) {
             program = normalizeVideoCaptureProgram(parseProgram(program));
         }
         catch (err) {
-            return { success: false, error: `prepared video program validation failed: ${err instanceof Error ? err.message : String(err)}` };
+            return { success: false, runId, error: `prepared video program validation failed: ${err instanceof Error ? err.message : String(err)}` };
         }
     }
     logger.info(`[capture] Running preset "${options.presetId}" — ${program.steps.length} opcodes, ${program.variants.length} variant(s)`);
@@ -264,19 +264,37 @@ export async function runCapture(options) {
     }
     try {
         logger.info('[capture] Saving captures, might take a few seconds...');
+        options.onProgress?.({
+            type: 'upload_start',
+            variantId: 'run',
+            message: 'saving captures',
+        });
         const uploadOutcome = await uploadResults(config, program, runResult, runId);
         if (program.mediaMode === 'video' && runResult.success) {
             await signalVideoComplete(config, program, runResult, uploadOutcome.runId, videoAudioAssets, videoAudioAssetsByLocale);
         }
         const totalDurationSec = ((Date.now() - captureStart) / 1000).toFixed(1);
         logger.info(`[capture] Captures saved successfully — total ${totalDurationSec}s`);
+        options.onProgress?.({
+            type: 'upload_end',
+            variantId: 'run',
+            status: 'ok',
+            message: 'captures saved',
+        });
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         logger.error(`[capture] Failed to upload results: ${message}`);
+        options.onProgress?.({
+            type: 'upload_end',
+            variantId: 'run',
+            status: 'failed',
+            message,
+        });
         if (!options.allowUploadFailure) {
             return {
                 success: false,
+                runId,
                 runResult,
                 error: runResult.success
                     ? `upload failed: ${message}`
@@ -285,7 +303,7 @@ export async function runCapture(options) {
         }
         logger.warn('[capture] Continuing after upload failure because --allow-upload-failure was set');
     }
-    return { success: runResult.success, runResult };
+    return { success: runResult.success, runId, runResult };
 }
 // ── Server communication ────────────────────────────────────────────
 async function fetchProgram(config, presetId, environmentName) {
@@ -1067,6 +1085,17 @@ function logProgress(event) {
         case 'breaker_trip':
             logger.error(`${prefix} Circuit breaker tripped: ${event.message}`);
             break;
+        case 'upload_start':
+            logger.info('[capture] Uploading artifacts and telemetry');
+            break;
+        case 'upload_end':
+            if (event.status === 'failed') {
+                logger.error(`[capture] Upload failed: ${event.message}`);
+            }
+            else {
+                logger.info('[capture] Upload complete');
+            }
+            break;
     }
 }
 //# sourceMappingURL=cli-runner.js.map

package/dist/cli.js

@@ -233,7 +233,7 @@ program
 // ── auto-recapture command ─────────────────────────────────────────
 program
     .command('auto-recapture')
-    .description('Run every preset enabled for CI auto-recapture in a project')
+    .description('Run every preset enabled for Recapture Cloud in a project')
     .requiredOption('--project <id>', 'Project ID')
     .option('--env <name>', "Project environment to capture against. Falls back to the project's default environment when omitted.")
     .option('--headed', 'Show browser window for debugging', false)
@@ -262,6 +262,34 @@ program
     // so the `capture_runs` row flips out of `queued` — without this the
     // backend rate-limiter blocks future cloud recaptures.
     const cloudRunId = process.env.AUTOKAP_RUN_ID;
+    const checkpointUrl = cloudRunId
+        ? buildApiUrl(config, `/api/cli/cloud-recapture/${cloudRunId}/checkpoint`)
+        : null;
+    let lastProgressCheckpointAt = 0;
+    const postCloudCheckpoint = async (body, options = {}) => {
+        if (!checkpointUrl)
+            return;
+        if (options.throttle) {
+            const now = Date.now();
+            if (now - lastProgressCheckpointAt < 750)
+                return;
+            lastProgressCheckpointAt = now;
+        }
+        try {
+            const response = await fetch(checkpointUrl, {
+                method: 'POST',
+                headers: { ...authHeaders(config), 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+            });
+            if (!response.ok) {
+                const bodyText = await response.text().catch(() => response.statusText);
+                logger.warn(`[auto-recapture] Cloud checkpoint non-OK (${response.status}): ${bodyText}`);
+            }
+        }
+        catch (err) {
+            logger.warn(`[auto-recapture] Cloud checkpoint failed (best-effort): ${err.message}`);
+        }
+    };
     /**
      * Best-effort: tell the AutoKap backend whether this cloud run finished
      * cleanly. Failures here do NOT change the CLI exit code — the artifact
@@ -289,6 +317,13 @@ program
         }
     };
     const data = await requestJson(config, `/api/cli/projects/${opts.project}/auto-recapture-presets`, { headers: authHeaders(config) }, 'Failed to list auto-recapture presets');
+    await postCloudCheckpoint({
+        type: 'run_plan',
+        totalPresets: data.presets.length,
+        completedPresets: 0,
+        failedPresets: 0,
+        message: `planned ${data.presets.length} preset(s)`,
+    });
     if (data.presets.length === 0) {
         logger.info(`[auto-recapture] No presets enabled for project ${opts.project}`);
         await notifyCloudCallback('completed', { totalPresets: 0, failedPresets: 0 });
@@ -296,19 +331,83 @@ program
     }
     const { runCapture } = await import('./cli-runner.js');
     const failures = [];
-    for (const preset of data.presets) {
+    await postCloudCheckpoint({
+        type: 'run_start',
+        totalPresets: data.presets.length,
+        completedPresets: 0,
+        failedPresets: 0,
+        message: `starting ${data.presets.length} preset(s)`,
+    });
+    for (const [index, preset] of data.presets.entries()) {
         const label = preset.name ? `${preset.name} (${preset.id})` : preset.id;
         logger.info(`[auto-recapture] Running ${label}`);
+        await postCloudCheckpoint({
+            type: 'preset_start',
+            presetId: preset.id,
+            presetName: preset.name ?? null,
+            presetIndex: index,
+            totalPresets: data.presets.length,
+            completedPresets: index,
+            failedPresets: failures.length,
+            message: `running ${preset.name ?? preset.id}`,
+        });
         const result = await runCapture({
             presetId: preset.id,
             env: opts.env,
             headed: opts.headed,
             allowUploadFailure: opts.allowUploadFailure,
+            onProgress: (event) => {
+                const checkpointType = event.type === 'upload_start'
+                    ? 'upload_start'
+                    : event.type === 'upload_end'
+                        ? 'upload_end'
+                        : 'preset_progress';
+                void postCloudCheckpoint({
+                    type: checkpointType,
+                    presetId: preset.id,
+                    presetName: preset.name ?? null,
+                    presetIndex: index,
+                    totalPresets: data.presets.length,
+                    completedPresets: index,
+                    failedPresets: failures.length,
+                    message: event.message,
+                    progressEvent: event,
+                    status: event.status === 'failed' ? 'running' : undefined,
+                }, { throttle: checkpointType === 'preset_progress' });
+            },
         });
+        const childRunId = result.runId;
         if (!result.success) {
             const error = result.error ?? result.runResult?.error ?? 'capture failed';
             failures.push({ id: preset.id, name: preset.name, error });
             logger.error(`[auto-recapture] Failed ${label}: ${error}`);
+            await postCloudCheckpoint({
+                type: 'preset_end',
+                presetId: preset.id,
+                presetName: preset.name ?? null,
+                presetIndex: index,
+                totalPresets: data.presets.length,
+                completedPresets: index + 1,
+                failedPresets: failures.length,
+                childRunId,
+                status: 'failed',
+                errorMessage: error,
+                message: `failed ${preset.name ?? preset.id}`,
+            });
+        }
+        else {
+            await postCloudCheckpoint({
+                type: 'preset_end',
+                presetId: preset.id,
+                presetName: preset.name ?? null,
+                presetIndex: index,
+                totalPresets: data.presets.length,
+                completedPresets: index + 1,
+                failedPresets: failures.length,
+                childRunId,
+                status: 'completed',
+                message: `completed ${preset.name ?? preset.id}`,
+            });
         }
     }
     if (failures.length > 0) {
@@ -316,6 +415,15 @@ program
             .map((failure) => failure.name ?? failure.id)
             .join(', ')}`;
         logger.error(`[auto-recapture] ${errorMessage}`);
+        await postCloudCheckpoint({
+            type: 'error',
+            totalPresets: data.presets.length,
+            completedPresets: data.presets.length,
+            failedPresets: failures.length,
+            status: 'failed',
+            errorMessage,
+            message: errorMessage,
+        });
         await notifyCloudCallback('failed', {
             totalPresets: data.presets.length,
             failedPresets: failures.length,
@@ -324,6 +432,14 @@ program
         process.exit(1);
     }
     logger.success(`[auto-recapture] ${data.presets.length} preset(s) recaptured successfully`);
+    await postCloudCheckpoint({
+        type: 'run_end',
+        totalPresets: data.presets.length,
+        completedPresets: data.presets.length,
+        failedPresets: 0,
+        status: 'completed',
+        message: 'cloud recapture completed',
+    });
     await notifyCloudCallback('completed', {
         totalPresets: data.presets.length,
         failedPresets: 0,

package/dist/clip-capture-loop.js

@@ -37,7 +37,7 @@ export class ClipCaptureLoop {
         // Linux default is 8 fps to stay safe on 2 vCPU CI runners. Cloud runners
         // (AUTOKAP_CLOUD_RUNNER=1, set by the Fly.io image and the `--cloud` CLI
         // flag) get the same 15 fps default as macOS/Windows since they have
-        // ≥ 4 vCPU. Callers can still override via opts.targetFps.
+        // dedicated 8 vCPU capacity. Callers can still override via opts.targetFps.
         const isCloudRunner = process.env.AUTOKAP_CLOUD_RUNNER === '1';
         const linuxDefault = isCloudRunner ? 15 : 8;
         const platformDefault = process.platform === 'linux' ? linuxDefault : 15;

package/dist/opcode-runner.d.ts

@@ -43,7 +43,7 @@ export interface RunOptions {
     presetName?: string;
 }
 export interface ProgressEvent {
-    type: 'variant_start' | 'variant_end' | 'opcode_start' | 'opcode_end' | 'recovery' | 'breaker_trip';
+    type: 'variant_start' | 'variant_end' | 'opcode_start' | 'opcode_end' | 'recovery' | 'breaker_trip' | 'upload_start' | 'upload_end';
     variantId: string;
     opcodeIndex?: number;
     opcodeKind?: string;

package/dist/server-credit-usage.d.ts

@@ -1,5 +1,5 @@
 import type { SupabaseClient } from '@supabase/supabase-js';
-export type CreditUsageType = 'screenshot' | 'clip' | 'video' | 'preset_analysis' | 'ai_chat' | 'studio_creation' | 'studio_iteration';
+export type CreditUsageType = 'screenshot' | 'clip' | 'video' | 'preset_analysis' | 'cloud_recapture' | 'ai_chat' | 'studio_creation' | 'studio_iteration';
 export declare function recordCreditUsage(supabase: SupabaseClient, params: {
     userId: string;
     projectId: string | null;

package/dist/web-playwright-local.js

@@ -344,7 +344,7 @@ export class WebPlaywrightLocal {
         await fs.mkdir(framesDir, { recursive: true });
         // Linux defaults are conservative because GitHub Actions free runners
         // (2 vCPU) can't sustain 30 fps. AUTOKAP_CLOUD_RUNNER=1 signals that the
-        // process is running on managed cloud infra (Fly.io machines, ≥4 vCPU)
+        // process is running on managed cloud infra (Fly.io machines, 8 vCPU)
         // where the cap can safely lift to 30 fps for clips too. Set by the
         // `--cloud` flag and by the cloud-runner Docker image.
         const isCloudRunner = process.env.AUTOKAP_CLOUD_RUNNER === '1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autokap",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "description": "AI-powered CLI tool for capturing clean screenshots of websites",
   "type": "module",
   "main": "./dist/index.js",

package/readme.md

@@ -16,19 +16,30 @@ cp .env.example .env.local
 npm run dev
 ```
 
-## CLI in CI/CD
+## Recapture Cloud in CI/CD
 
-AutoKap can run non-interactively in CI by reading the CLI key from
-`AUTOKAP_API_KEY`; no local `~/.autokap/config.json` is required.
+The official CI/CD flow is Recapture Cloud. Generate a signed webhook secret
+from the project Recapture page, store it in your CI secret manager, then call
+the webhook on deploy. CI never needs an AutoKap CLI key.
 
 ```bash
-AUTOKAP_API_KEY=ak_cli_... autokap run <preset-id> --env staging
-AUTOKAP_API_KEY=ak_cli_... autokap auto-recapture --project <project-id> --env local
+BODY='{"env":"staging"}'
+SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$AUTOKAP_WEBHOOK_SECRET" -binary | xxd -p -c 256)
+curl -X POST "https://autokap.app/api/webhooks/cloud-recapture/<project-id>" \
+  -H "Content-Type: application/json" \
+  -H "X-AutoKap-Signature: sha256=$SIG" \
+  -d "$BODY"
 ```
 
 Use project environments in the dashboard to map `local`, `staging`, and
 `production` to different base URLs without duplicating presets.
 
+The local CLI remains available for advanced debugging:
+
+```bash
+AUTOKAP_API_KEY=ak_cli_... autokap run <preset-id> --env staging
+```
+
 ## Auth Setup (Supabase)
 
 AutoKap uses Supabase Auth for user authentication. You need to configure the following providers in your Supabase dashboard: