autokap 1.3.31 → 1.4.2

package/assets/skill/SKILL.md

@@ -19,6 +19,8 @@ Normal navigation and interaction stay deterministic. Runtime AI is limited to n
 
 This installed skill is the **source of truth** for the AutoKap contract: opcode schema, login rules, variant handling, persistence, and validation. The copied prompt from the AutoKap dashboard is only the **preset-specific brief** (project URL, variants, template goal, mock data guidance, etc.).
 
+> **Compatibility note.** The dashboard prompts now embed a mini AutoKap mental-model so they remain useful for assistants that don't have this skill installed (Cursor without the bundle, Codex, Copilot, plain Claude Code). When this skill IS installed, **the rules below override anything that contradicts them in the inline mental-model** — the inline version is necessarily a summary.
+
 ## When To Use This Skill
 
 - User wants to capture screenshots or clips of their web app
@@ -54,6 +56,7 @@ Load these only when the request actually needs them:
 - **Opcode parameters** — [OPCODE-REFERENCE.md](OPCODE-REFERENCE.md)
 - **Mock data** — [references/mock-data.md](references/mock-data.md)
 - **Complete examples** — [references/examples.md](references/examples.md)
+- **Prompt charter** — [references/STANDARDS.md](references/STANDARDS.md) — defines the structure every dashboard-generated prompt now follows. Use it when authoring new prompts, when extending existing builders, or to understand why a copied prompt is shaped the way it is.
 
 Keep the core `SKILL.md` for the non-negotiable contract. Reach for the
 references only after you know which mode or advanced feature the user needs.
@@ -565,6 +568,12 @@ autokap run <preset-id> --headed
 
 # Save the artifacts to a local directory in addition to uploading them:
 autokap run <preset-id> --output ./screenshots
+
+# Dry run: validate the opcode program end-to-end without capturing or
+# uploading anything (0 credits charged). Use this right after generating
+# or updating a preset to confirm navigation, clicks, and postconditions
+# work before spending credits on a real capture.
+autokap run <preset-id> --dry
 ```
 
 ## Complete Examples

package/assets/skill/references/STANDARDS.md

@@ -0,0 +1,236 @@
+# AutoKap Prompt Standards
+
+This document defines the contract every user-facing prompt produced by AutoKap must follow. It is the single source of truth referenced by `web/lib/prompts/blocks/*` and the prompt builders that compose them.
+
+---
+
+## Why this charter exists
+
+AutoKap generates prompts that the user copy-pastes into their IDE so an AI assistant can:
+
+- inspect the user's codebase and add `data-ak` attributes
+- generate or edit a deterministic `ExecutionProgram`
+- scaffold a proxy, embed assets, or build a video demo
+
+The recipient assistant is rarely "AutoKap-aware":
+
+- it may be Cursor, Codex, GitHub Copilot, or Claude Code without the `autokap-preset` skill installed
+- it has no prior context about AutoKap's runtime model, opcode contract, or CLI
+
+When prompts are inconsistent, the assistant invents selectors, generates programs before inspecting the codebase, drops the CLI, and ignores the user's brief. We fix that by enforcing a **single, predictable structure across every prompt**.
+
+Two design principles flow from this:
+
+1. **Self-sufficient** — every prompt embeds a mini mental-model so the assistant can succeed even without the skill installed.
+2. **Predictable** — every prompt uses the same nine blocks in the same order. The assistant learns the shape once and applies it everywhere.
+
+---
+
+## The nine blocks
+
+Every user-facing prompt is composed from the following blocks, in this order. Blocks are skipped only when explicitly marked optional.
+
+### 1. Header (required)
+
+3-5 lines. Names the product, the runtime model in one sentence, the task. Mentions the optional skill.
+
+```
+You are working on AutoKap, a screenshot-and-video automation tool. AutoKap presets
+are deterministic JSON programs (opcodes for Playwright) that the AutoKap CLI runs
+locally — there is no LLM at capture runtime. Your job here is to <one-line task>.
+If a skill named `autokap-preset` is installed in your environment, treat it as the
+source of truth — the rules below override anything that contradicts it.
+```
+
+The header replaces the implicit assumption that the assistant already knows AutoKap. It is the same in every prompt; only the `<one-line task>` changes.
+
+### 2. Before you write anything (required for any prompt that touches code)
+
+A numbered checklist of 3-5 actions the assistant must perform before generating the artifact. Always includes:
+
+- inspect the codebase
+- plan
+- ask the user when ambiguous
+- never invent UI details, selectors, or copy
+- search for existing `data-ak` before adding new ones (when applicable)
+
+```
+## Before you write anything
+
+1. Inspect the codebase: routes, auth, theme/locale system, components you may need to tag.
+2. Plan in your head (or in your planning tool if you have one) before generating.
+3. If anything is ambiguous (auth flow, target route, data shape), STOP and ask the user.
+   Do not invent UI details, selectors, or copy.
+4. Search for existing `data-ak` attributes first; only add new ones if none exist.
+5. If your environment supports parallel subagents, you may run codebase inspection
+   and program drafting in parallel — but do not skip step 3.
+```
+
+This block sits **immediately after the header**, before any technical detail. The assistant must read it before being tempted by the project context or the brief.
+
+### 3. User guidance (required and visible)
+
+The user's brief, isolated in its own section. The section name varies by task: `## User guidance`, `## What the user wants`, `## Preset brief`, `## What the demo should show`. The content is always the user's free-form input.
+
+When the user provided no guidance:
+
+```
+## User guidance
+
+_The user has not provided specific guidance for this task. Use sensible defaults
+based on the project context above._
+```
+
+When the user provided partial guidance (e.g. mock data guidance only), each piece appears in its own clearly-labelled subsection.
+
+This block sits **immediately after "Before you write anything"**, before any constraint. The assistant has just been told to inspect; the brief is the next thing it sees so it shapes inspection.
+
+### 4. Project context (required when applicable)
+
+Compact key/value list. Project name, project ID, base URL, credentials account ID, locale defaults. No prose.
+
+```
+## Project context
+
+- **Name**: Acme Dashboard
+- **ID**: `proj_abc123`
+- **Base URL**: `https://acme.example.com`
+- **Credentials account ID**: `cred_xyz789`
+```
+
+### 5. Hard constraints (required)
+
+Non-negotiable values: viewport variants, capture mode, mediaMode, baseUrl rules, etc. The "Variants (use these EXACTLY)" pattern is the canonical example. Use **bold** for emphasis on critical numbers and `code` for identifiers.
+
+### 6. Specific reminders (required when applicable)
+
+Auth, mock data, locale/theme handling, etc. — only the reminders that apply to the current mode. Anti-patterns are presented as `Don't / Do instead` tables, never bullets:
+
+```
+| Don't | Do instead |
+|---|---|
+| Use a CSS selector you guessed (`.btn-primary`) | Add a `data-ak="login-btn"` attribute and target `[data-ak="login-btn"]` |
+| Hardcode the auth cookie | Use `credentialsId` and let the runtime inject the right session |
+```
+
+### 7. How to persist (required for prompts that produce an artifact)
+
+CLI commands first. Useful flags listed (`--dry`, `--headed`, `--output`). Fallbacks (JSON file, dashboard import) explicitly labelled "fallback only".
+
+### 8. If you get stuck (required for any prompt that touches code)
+
+3 concrete scenarios minimum. Tells the assistant what to do at the failure points where it would otherwise improvise:
+
+```
+## If you get stuck
+
+- If you can't find a stable selector → ask the user before guessing.
+- If a CLI command fails → run with `--dry` first to validate, then re-run without `--dry`.
+- If the program runs but captures the wrong screen → report back with the AutoKap run log;
+  don't try to patch by adding more opcodes blindly.
+```
+
+### 9. Subagents hint (optional, multi-phase prompts only)
+
+A suggestion (never a requirement) for assistants that support parallel subagents. Always qualified with "if your environment supports..." so single-agent assistants are not derailed.
+
+```
+## If you have parallel subagents available
+
+This prompt has multiple phases (inspect → tag → generate → persist → integrate). If
+your environment supports subagents (Claude Code, multi-agent Cursor, etc.), consider
+parallelizing: agent 1 inspects the codebase and tags `data-ak`; agent 2 drafts the
+`ExecutionProgram` from the tagged components; you merge their outputs.
+```
+
+---
+
+## Cross-cutting rules
+
+### Tone
+
+Direct imperative: `Do`, `Use`, `Never`, `Ask`. Never "you may want to consider", "perhaps", "if you wish". The assistant should know exactly what the prompt expects.
+
+### Markdown
+
+- `**bold**` for emphasis on critical values
+- `` `code` `` for identifiers, file paths, CLI flags
+- Tables for matrices and anti-patterns
+- Fenced code blocks (with language tag) for examples
+- `## Section` / `### Subsection` for hierarchy — the assistant should be able to refer to sections by name
+
+### No emojis
+
+Anywhere in any prompt. They look unprofessional and clutter terminal output when the prompt is shown verbatim.
+
+### Examples are concrete
+
+Every prompt that asks the assistant to produce an artifact contains at least one fully-formed example: a JSON snippet for opcodes, a bash one-liner for CLI commands, a JSX block for `data-ak` placement.
+
+### Anti-patterns are tables, not bullets
+
+```
+| Don't | Why / Do instead |
+|---|---|
+| ... | ... |
+```
+
+### Section names are stable
+
+The assistant should be able to refer to "the User guidance section" or "the Hard constraints section" and have it mean the same thing across all prompts.
+
+---
+
+## Block composition pattern
+
+Each block exposes a `make*` function returning `string[]` (lines). Builders compose blocks by concatenating arrays and joining with `"\n"` at the end:
+
+```typescript
+import { joinBlocks } from "@/lib/prompts";
+import { makeHeader } from "@/lib/prompts/blocks/header";
+import { makeBeforeAnythingChecklist } from "@/lib/prompts/blocks/before-anything";
+import { makeUserGuidanceSection } from "@/lib/prompts/blocks/user-guidance";
+
+export function buildPresetPrompt(input: PresetPromptInput): string {
+  return joinBlocks([
+    makeHeader({ task: "generate an ExecutionProgram for this preset" }),
+    makeBeforeAnythingChecklist({ touchesCode: true, supportsSubagents: true }),
+    makeUserGuidanceSection({ brief: input.userBrief, label: "Preset brief" }),
+    // ... other blocks
+  ]);
+}
+```
+
+Blocks must:
+
+- accept typed parameters; never read environment variables or globals
+- be deterministic (same input → same output)
+- handle all "missing optional" cases internally (empty guidance, no credentials, etc.)
+- never add a trailing newline (the joiner handles spacing)
+
+---
+
+## When the prompt does NOT touch code
+
+Some prompts do not produce code (e.g. an image-generation prompt for the Studio composition flow). For those:
+
+- Header is still required
+- Block 2 ("Before you write anything") is skipped
+- Block 8 ("If you get stuck") is skipped
+- Block 9 ("Subagents hint") is skipped
+- The remaining blocks apply if relevant
+
+These prompts are out of scope for the current refactor and follow a lighter contract.
+
+---
+
+## Versioning and divergence
+
+This document is mirrored in `assets/skill/references/STANDARDS.md` so the installed skill has access to the same charter. When the charter changes:
+
+1. Update `web/lib/prompts/STANDARDS.md` first.
+2. Mirror the change to `assets/skill/references/STANDARDS.md`.
+3. Update the affected blocks in `web/lib/prompts/blocks/`.
+4. Re-run the snapshot tests on the builders to surface any drift.
+
+The blocks are the source of truth for what the prompts emit. This document is the source of truth for what the blocks should look like.

package/dist/cli-contract.d.ts

@@ -15,6 +15,7 @@ export declare const CLI_FALLBACK_PROGRAM_COMMAND = "autokap run <preset-id> --p
 export declare function buildCliRunCommand(presetId: string, options?: {
     local?: boolean;
     env?: string;
+    dry?: boolean;
 }): string;
 export declare function buildCliInstalledSetupCommand(cliKey: string): string;
 export declare const CLI_PUBLIC_COMMANDS: CliPublicCommandDescriptor[];

package/dist/cli-contract.js

@@ -7,7 +7,12 @@ export const CLI_DEFAULT_SETUP_COMMAND = "npx autokap@latest init --cli-key <you
 export const CLI_ADVANCED_SKILL_COMMAND = "autokap skill --agent <agent>";
 export const CLI_FALLBACK_PROGRAM_COMMAND = "autokap run <preset-id> --program <file>";
 export function buildCliRunCommand(presetId, options = {}) {
-    return `autokap run${options.local ? " --local" : ""}${options.env ? ` --env ${options.env}` : ""} ${presetId}`;
+    const flags = [
+        options.local ? " --local" : "",
+        options.env ? ` --env ${options.env}` : "",
+        options.dry ? " --dry" : "",
+    ].join("");
+    return `autokap run${flags} ${presetId}`;
 }
 export function buildCliInstalledSetupCommand(cliKey) {
     return `autokap init --cli-key ${cliKey}`;
@@ -61,6 +66,12 @@ export const CLI_PUBLIC_COMMANDS = [
         summary: "Show the browser window for debugging",
         docsDescriptionKey: "cliCmdHeaded",
     },
+    {
+        id: "run-dry",
+        command: "autokap run <preset-id> --dry",
+        summary: "Dry run: execute the opcode program without capturing or uploading (0 credits charged)",
+        docsDescriptionKey: "cliCmdRunDry",
+    },
     {
         id: "project-list",
         command: "autokap project list",

package/dist/cli-runner-local.d.ts

@@ -11,4 +11,5 @@ export declare function runLocal(presetId: string, opts: {
     debug?: boolean;
     env?: string;
     allowUploadFailure?: boolean;
+    dry?: boolean;
 }): Promise<void>;

package/dist/cli-runner-local.js

@@ -22,11 +22,15 @@ export async function runLocal(presetId, opts) {
             process.exit(1);
         }
     }
+    if (opts.dry) {
+        logger.info('[capture] DRY RUN — opcodes will execute but no captures or uploads');
+    }
     const run = await runCapture({
         presetId,
         env: opts.env,
         program,
         allowUploadFailure: opts.allowUploadFailure,
+        dryRun: opts.dry,
         headed: opts.headed,
         onProgress: (event) => {
             const prefix = `[capture][${event.variantId}]`;

package/dist/cli-runner.d.ts

@@ -29,6 +29,8 @@ export interface CLIRunnerOptions {
     program?: ExecutionProgram;
     /** Keep the legacy success result when upload/telemetry persistence fails */
     allowUploadFailure?: boolean;
+    /** Dry run: skip capture opcodes (CAPTURE_SCREENSHOT/BEGIN_CLIP/END_CLIP) and upload. 0 credits charged. */
+    dryRun?: boolean;
     /** Selector memory map (fetched from server or cached locally) */
     selectorMemory?: Record<string, string[]>;
     /** Show browser window. Default: false (headless) */

package/dist/cli-runner.js

@@ -195,6 +195,7 @@ export async function runCapture(options) {
         maxParallelVariants,
         llmConfig,
         presetName: program.presetId,
+        dryRun: options.dryRun,
         onProgress: (event) => {
             if (!options.onProgress) {
                 logProgress(event);
@@ -262,6 +263,10 @@ export async function runCapture(options) {
     else {
         logger.error(`[capture] Run failed: ${runResult.error}`);
     }
+    if (options.dryRun) {
+        logger.info(`[capture] DRY RUN complete — ${runResult.telemetry.totalOpcodes} opcodes executed, 0 captures, 0 credits charged`);
+        return { success: runResult.success, runId, runResult };
+    }
     try {
         logger.info('[capture] Saving captures, might take a few seconds...');
         options.onProgress?.({

package/dist/cli.js

@@ -6,7 +6,7 @@ import fs from 'node:fs/promises';
 const require = createRequire(import.meta.url);
 const { version } = require('../package.json');
 import { logger } from './logger.js';
-import { writeConfig, deleteConfig, requireConfig, getConfigPath, DEFAULT_API_BASE_URL, getDefaultApiBaseUrl, getDefaultWsUrl, LOCAL_API_BASE_URL, LOCAL_WS_URL, API_KEY_ENV_VAR, API_BASE_URL_ENV_VAR, WS_URL_ENV_VAR, } from './cli-config.js';
+import { writeConfig, readConfig, deleteConfig, requireConfig, getConfigPath, DEFAULT_API_BASE_URL, getDefaultApiBaseUrl, getDefaultWsUrl, LOCAL_API_BASE_URL, LOCAL_WS_URL, API_KEY_ENV_VAR, API_BASE_URL_ENV_VAR, WS_URL_ENV_VAR, } from './cli-config.js';
 import { renderSkillSingleFile, writeSkillExport } from './skill-packaging.js';
 // ── Program definition ──────────────────────────────────────────────
 export const program = new Command();
@@ -249,6 +249,7 @@ program
     .option('--allow-upload-failure', 'Keep a successful capture exit code even if artifact upload fails', false)
     .option('--output <dir>', 'Optional output directory for local artifact copies')
     .option('--program <file>', 'Path to a program JSON file')
+    .option('--dry', 'Dry run: execute all opcodes without capturing or uploading artifacts (0 credits charged)', false)
     .option('--debug', 'Verbose logging: per-substep timing, opcode dumps, recovery strategy traces', false)
     .action(async (presetId, opts) => {
     if (opts.debug) {
@@ -275,6 +276,7 @@ program
     .option('--allow-upload-failure', 'Keep a successful capture exit code even if artifact upload fails', false)
     .option('--debug', 'Verbose logging: per-substep timing, opcode dumps, recovery strategy traces', false)
     .option('--cloud', 'Cloud runner mode: signals 4+ vCPU available, unblocks the conservative Linux FPS default (8 → 30)', false)
+    .option('--preset-ids <ids>', 'Comma-separated preset IDs to capture. When omitted, captures all presets with auto_recapture_enabled=true.')
     .action(async (opts) => {
     if (opts.debug) {
         const { setDebugEnabled } = await import('./logger.js');
@@ -386,7 +388,12 @@ program
     // Fetch the presets list with a hard timeout. Without this, a slow or
     // unreachable dashboard would leave the CLI hanging forever — the
     // dashboard would stay stuck at "machine started" with no error surfaced.
-    const presetsPath = `/api/cli/projects/${opts.project}/auto-recapture-presets`;
+    // When `--preset-ids` is provided, restrict the run to that subset
+    // (per-preset recapture launched from the dashboard).
+    const presetIdsArg = opts.presetIds?.trim();
+    const presetsPath = presetIdsArg
+        ? `/api/cli/projects/${opts.project}/auto-recapture-presets?preset_ids=${encodeURIComponent(presetIdsArg)}`
+        : `/api/cli/projects/${opts.project}/auto-recapture-presets`;
     let data;
     try {
         const response = await fetch(buildApiUrl(config, presetsPath), {
@@ -542,6 +549,52 @@ program
     });
     process.exit(0);
 });
+// ── crm-run command ────────────────────────────────────────────────
+program
+    .command('crm-run')
+    .description('Scrape BetaList launches and feed the CRM (AUT-109 Phase B)')
+    .option('--runId <id>', 'CRM run id (defaults to AUTOKAP_RUN_ID env)')
+    .option('--lookback-days <n>', 'How far back to look for launches', '1')
+    .option('--debug', 'Verbose logging', false)
+    .action(async (opts) => {
+    if (opts.debug) {
+        const { setDebugEnabled } = await import('./logger.js');
+        setDebugEnabled(true);
+        logger.info('[crm-run] Debug mode enabled — verbose logging on');
+    }
+    const runToken = process.env.AUTOKAP_RUN_TOKEN?.trim();
+    const runId = opts.runId?.trim() || process.env.AUTOKAP_RUN_ID?.trim();
+    const config = await readConfig();
+    const apiBaseUrl = process.env.AUTOKAP_API_BASE_URL?.trim().replace(/\/+$/, '') || config?.apiBaseUrl;
+    if (!runToken) {
+        fatal('[crm-run] Missing AUTOKAP_RUN_TOKEN');
+    }
+    if (!runId) {
+        fatal('[crm-run] Missing CRM run id. Set AUTOKAP_RUN_ID or pass --runId <id>.');
+    }
+    if (!apiBaseUrl) {
+        fatal('[crm-run] Missing API base URL. Set AUTOKAP_API_BASE_URL or run autokap init.');
+    }
+    const parsedLookback = Number.parseInt(opts.lookbackDays, 10);
+    const lookbackDays = Math.max(1, Math.min(7, Number.isFinite(parsedLookback) ? parsedLookback : 1));
+    try {
+        const { runCampaign } = await import('./crm/run-campaign.js');
+        const result = await runCampaign({
+            runId,
+            lookbackDays,
+            apiBaseUrl,
+            runToken,
+            logger,
+        });
+        logger.success(`[crm-run] Done — scraped=${result.scraped} inserted=${result.inserted} ` +
+            `disqualified=${result.disqualified} skipped=${result.skipped}`);
+        process.exit(0);
+    }
+    catch (error) {
+        logger.error(`[crm-run] Failed: ${error.message}`);
+        process.exit(1);
+    }
+});
 // ── project commands ───────────────────────────────────────────────
 const projectCmd = program
     .command('project')

package/dist/crm/email-fallback.d.ts

@@ -0,0 +1,16 @@
+export interface EmailFallbackOptions {
+    betaListLaunchUrl: string;
+    productUrl: string | null;
+    logger: {
+        info(msg: string): void;
+        warn(msg: string): void;
+        error(msg: string): void;
+    };
+}
+export declare function findEmail(opts: EmailFallbackOptions): Promise<{
+    email: string | null;
+    handle: string | null;
+    lang: string | null;
+}>;
+export declare function extractEmailsFromText(text: string): string[];
+export declare function pickBestEmail(emails: string[], productHostname: string | null): string | null;