@vorec/cli 0.10.0

package/README.md

@@ -0,0 +1,86 @@
+# @vorec/cli
+
+Turn any web app into a narrated tutorial video. Record your screen, track user actions, and let AI generate professional voice-over narration automatically.
+
+## What It Does
+
+- Records your web app in 1080p using Playwright
+- Tracks every click, keystroke, and navigation with precise coordinates
+- Converts to MP4 and uploads to [Vorec](https://vorec.ai)
+- AI analyzes the video and writes natural narration
+- Generates voice-over audio in multiple languages and styles
+- Returns an editor URL to preview, adjust, and export
+
+## Quick Start
+
+```bash
+npx @vorec/cli@latest init
+npx @vorec/cli@latest run vorec.json --auto
+```
+
+## Requirements
+
+- **Node.js** 18+
+- **Playwright** — `npm install playwright && npx playwright install chromium`
+- **FFmpeg** — `brew install ffmpeg` (macOS) or `apt install ffmpeg` (Linux)
+- **Vorec API key** — create one at [vorec.ai](https://vorec.ai) → Settings → API Keys
+
+## Manifest Format
+
+Create a `vorec.json` file describing the actions to record:
+
+```json
+{
+  "title": "How to create a project",
+  "url": "http://localhost:3000/dashboard",
+  "viewport": { "width": 1920, "height": 1080 },
+  "language": "en",
+  "narrationStyle": "tutorial",
+  "actions": [
+    { "type": "click", "selector": "button.new-project", "description": "Open the create dialog" },
+    { "type": "type", "selector": "#name", "text": "My Project", "description": "Enter the project name" },
+    { "type": "click", "selector": "button[type=submit]", "description": "Save the project" }
+  ]
+}
+```
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `vorec init` | Save your API key |
+| `vorec run <manifest>` | Record and upload |
+| `vorec run <manifest> --auto` | Record, upload, and generate narration |
+| `vorec run <manifest> --auto --skip-record` | Resume an existing project |
+| `vorec upload <video>` | Upload a video file directly |
+| `vorec status` | Check project status |
+
+## Narration Styles
+
+| Style | Tone |
+|-------|------|
+| `tutorial` | Step-by-step, clear, helpful |
+| `professional` | Polished, enterprise-ready |
+| `conversational` | Casual, like explaining to a colleague |
+| `storytelling` | Engaging, narrative-driven |
+| `concise` | Minimal, just the essentials |
+| `exact` | Neutral, factual, technical |
+
+## Claude Code Plugin
+
+For the best experience, install the Vorec plugin for Claude Code. Your AI agent will research the codebase, generate the manifest, and run the CLI automatically.
+
+```
+1. In Claude Code, run /plugin
+2. Go to Marketplaces → Add Marketplace
+3. Enter: MustaphaSteph/vorec-plugins
+4. Select record-tutorial and install it
+5. Enable auto-update
+```
+
+Then just say: *"record a tutorial showing how to create a project"*
+
+## Links
+
+- [Vorec](https://vorec.ai) — AI-narrated tutorial videos
+- [Plugin repo](https://github.com/MustaphaSteph/vorec-plugins) — Claude Code plugin

package/bin/vorec.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/index.js');

package/dist/api.d.ts

@@ -0,0 +1,3 @@
+import type { ApiResponse } from './types.js';
+export declare function apiCall(action: string, body?: Record<string, any>): Promise<ApiResponse>;
+export declare function uploadVideo(uploadUrl: string, videoPath: string, contentType?: string): Promise<void>;

package/dist/api.js

@@ -0,0 +1,33 @@
+import { loadConfig, requireApiKey } from './config.js';
+export async function apiCall(action, body = {}) {
+    const config = loadConfig();
+    const apiKey = requireApiKey();
+    const res = await fetch(config.apiBase, {
+        method: 'POST',
+        headers: {
+            'Authorization': `Bearer ${apiKey}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ action, ...body }),
+    });
+    const data = await res.json();
+    if (!res.ok && !data.error) {
+        throw new Error(`API error ${res.status}`);
+    }
+    if (data.error) {
+        throw new Error(data.error);
+    }
+    return data;
+}
+export async function uploadVideo(uploadUrl, videoPath, contentType = 'video/webm') {
+    const { readFileSync } = await import('node:fs');
+    const videoData = readFileSync(videoPath);
+    const res = await fetch(uploadUrl, {
+        method: 'PUT',
+        headers: { 'Content-Type': contentType },
+        body: videoData,
+    });
+    if (!res.ok) {
+        throw new Error(`Upload failed: ${res.status} ${res.statusText}`);
+    }
+}

package/dist/commands/init.d.ts

@@ -0,0 +1 @@
+export declare function initCommand(): Promise<void>;

package/dist/commands/init.js

@@ -0,0 +1,18 @@
+import { createInterface } from 'node:readline';
+import { saveConfig, loadConfig } from '../config.js';
+export async function initCommand() {
+    const config = loadConfig();
+    if (config.apiKey) {
+        console.log(`Current key: ${config.apiKey.slice(0, 17)}${'*'.repeat(24)}`);
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (q) => new Promise(r => rl.question(q, r));
+    const key = await ask('Enter your Vorec API key (vrc_live_...): ');
+    rl.close();
+    if (!key.startsWith('vrc_live_')) {
+        console.error('Invalid key format. Keys start with vrc_live_');
+        process.exit(1);
+    }
+    saveConfig({ apiKey: key.trim() });
+    console.log('API key saved to ~/.vorec/config.json');
+}

package/dist/commands/record.d.ts

@@ -0,0 +1,8 @@
+interface RecordOptions {
+    url: string;
+    actions: string;
+    viewport: string;
+    output: string;
+}
+export declare function recordCommand(opts: RecordOptions): Promise<void>;
+export {};

package/dist/commands/record.js

@@ -0,0 +1,108 @@
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+export async function recordCommand(opts) {
+    let pw;
+    try {
+        // @ts-ignore — playwright is an optional peer dependency
+        pw = await import('playwright');
+    }
+    catch {
+        try {
+            const { createRequire } = await import('node:module');
+            const req = createRequire(process.cwd() + '/package.json');
+            pw = req('playwright');
+        }
+        catch {
+            console.error('Playwright is required for recording.\n' +
+                'Install it with: npm install playwright && npx playwright install chromium');
+            process.exit(1);
+        }
+    }
+    const { readFileSync, mkdirSync } = await import('node:fs');
+    const actions = JSON.parse(readFileSync(opts.actions, 'utf-8'));
+    const [vw, vh] = opts.viewport.split('x').map(Number);
+    const viewport = { width: vw || 1920, height: vh || 1080 };
+    console.log(`Recording ${opts.url} (${viewport.width}x${viewport.height})...`);
+    console.log(`Actions: ${actions.length}`);
+    mkdirSync('.vorec/recordings', { recursive: true });
+    const browser = await pw.chromium.launch({ headless: false });
+    const context = await browser.newContext({
+        viewport,
+        recordVideo: { dir: resolve('.vorec/recordings'), size: viewport },
+    });
+    const page = await context.newPage();
+    const startTime = Date.now();
+    const tracked = [];
+    await page.goto(opts.url, { waitUntil: 'networkidle' });
+    for (const [i, action] of actions.entries()) {
+        try {
+            await page.waitForSelector(action.selector, { timeout: 10000 });
+            const element = await page.$(action.selector);
+            if (!element)
+                throw new Error(`Element not found: ${action.selector}`);
+            const box = await element.boundingBox();
+            const timestamp = (Date.now() - startTime) / 1000;
+            const coords = box ? {
+                x: Math.round((box.x + box.width / 2) / viewport.width * 1000),
+                y: Math.round((box.y + box.height / 2) / viewport.height * 1000),
+            } : { x: 500, y: 500 };
+            switch (action.type) {
+                case 'click':
+                    await element.click();
+                    break;
+                case 'type':
+                    await element.click();
+                    if (action.text)
+                        await page.keyboard.type(action.text, { delay: 50 });
+                    break;
+                case 'select':
+                    if (action.value)
+                        await page.selectOption(action.selector, action.value);
+                    break;
+                case 'hover':
+                    await element.hover();
+                    break;
+                case 'scroll':
+                    await page.mouse.wheel(0, 300);
+                    break;
+                case 'wait':
+                    await page.waitForTimeout(action.delay || 1000);
+                    break;
+                case 'navigate':
+                    if (action.text)
+                        await page.goto(action.text, { waitUntil: 'networkidle' });
+                    break;
+            }
+            tracked.push({
+                type: action.type,
+                timestamp,
+                coordinates: coords,
+                target: action.selector || '',
+                interaction_type: action.type === 'type' ? 'click' : action.type,
+            });
+            console.log(`  [${i + 1}/${actions.length}] ${action.type} ${action.selector} @ ${timestamp.toFixed(1)}s`);
+            if (action.delay)
+                await page.waitForTimeout(action.delay);
+            else {
+                await page.waitForLoadState('networkidle').catch(() => { });
+                await page.waitForTimeout(500);
+            }
+        }
+        catch (err) {
+            console.error(`  [${i + 1}] Failed: ${err.message}`);
+        }
+    }
+    await page.waitForTimeout(1000);
+    const video = page.video();
+    await page.close();
+    await context.close();
+    await browser.close();
+    const videoPath = video ? await video.path() : null;
+    // Output: video path + tracked actions
+    const output = { video: videoPath, actions: tracked, recorded_at: new Date().toISOString() };
+    writeFileSync(opts.output, JSON.stringify(output, null, 2));
+    console.log(`\nRecording complete!`);
+    if (videoPath)
+        console.log(`Video: ${videoPath}`);
+    console.log(`Actions: ${opts.output}`);
+}

package/dist/commands/run.d.ts

@@ -0,0 +1,8 @@
+interface RunOptions {
+    auto: boolean;
+    skipRecord: boolean;
+    video: string;
+    trackedActions: string;
+}
+export declare function runCommand(manifestPath: string, opts: RunOptions): Promise<void>;
+export {};

package/dist/commands/run.js

@@ -0,0 +1,314 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import ora from 'ora';
+import chalk from 'chalk';
+import { loadManifest } from '../manifest.js';
+import { apiCall, uploadVideo } from '../api.js';
+import { saveProjectState, loadProjectState } from '../config.js';
+export async function runCommand(manifestPath, opts) {
+    const manifest = loadManifest(manifestPath);
+    console.log(chalk.bold(`Vorec: ${manifest.title}`));
+    console.log(`Actions: ${manifest.actions.length}, URL: ${manifest.url}\n`);
+    // Check if we're resuming an existing project (--skip-record with saved state)
+    const savedState = loadProjectState();
+    const resuming = opts.skipRecord && savedState?.projectId && savedState?.status === 'analyzing';
+    if (resuming) {
+        // Resume: skip recording + upload, go straight to analysis
+        console.log(`Resuming project: ${savedState.projectId}`);
+        if (opts.auto) {
+            await runAnalysis(savedState.projectId, manifest);
+        }
+        else {
+            const status = await apiCall('get-status', { projectId: savedState.projectId });
+            console.log(`\n${chalk.bold('Editor:')} ${status.editor_url}`);
+        }
+        return;
+    }
+    // Fresh run: record → upload → (optionally analyze)
+    let videoPath = opts.video;
+    let trackedActions = [];
+    let videoDuration = 0;
+    let videoWidth = manifest.viewport?.width || 1920;
+    let videoHeight = manifest.viewport?.height || 1080;
+    // Step 1: Record with Playwright
+    if (!opts.skipRecord && !videoPath) {
+        const spinner = ora('Recording...').start();
+        try {
+            const result = await recordAndTrack(manifest);
+            videoPath = result.videoPath;
+            trackedActions = result.actions;
+            videoDuration = result.duration;
+            videoWidth = result.viewport.width;
+            videoHeight = result.viewport.height;
+            spinner.succeed(`Recorded: ${videoPath} (${trackedActions.length} actions, ${videoDuration.toFixed(1)}s)`);
+        }
+        catch (err) {
+            spinner.fail(`Recording failed: ${err.message}`);
+            process.exit(1);
+        }
+    }
+    else if (opts.trackedActions) {
+        try {
+            const raw = JSON.parse(readFileSync(opts.trackedActions, 'utf-8'));
+            trackedActions = Array.isArray(raw) ? raw : (raw.actions || []);
+            console.log(`Loaded ${trackedActions.length} tracked actions from ${opts.trackedActions}`);
+        }
+        catch (err) {
+            console.error(`Failed to load tracked actions: ${err.message}`);
+        }
+    }
+    if (!videoPath || !existsSync(videoPath)) {
+        console.error('No video file. Use --video or enable recording.');
+        process.exit(1);
+    }
+    const fileSize = statSync(videoPath).size;
+    const ext = videoPath.split('.').pop()?.toLowerCase() || 'mp4';
+    const mimeMap = { mp4: 'video/mp4', webm: 'video/webm', mov: 'video/quicktime', mkv: 'video/x-matroska' };
+    const contentType = mimeMap[ext] || 'video/mp4';
+    // Step 2: Create project + upload
+    const spinner = ora('Creating project...').start();
+    const createResult = await apiCall('create-project', {
+        title: manifest.title,
+        contentType,
+        fileSize,
+        actions: trackedActions.map(a => ({
+            type: a.interaction_type || a.type,
+            timestamp: a.timestamp,
+            coordinates: a.coordinates,
+            target: a.target,
+            description: a.description,
+            context: a.context,
+            typed_text: a.typed_text,
+            selected_value: a.selected_value,
+        })),
+    });
+    spinner.text = 'Uploading video...';
+    await uploadVideo(createResult.upload_url, videoPath, contentType);
+    spinner.text = 'Confirming upload...';
+    await apiCall('confirm-upload', {
+        projectId: createResult.projectId,
+        storage_key: createResult.storage_key,
+        video_duration: videoDuration || undefined,
+        video_width: videoWidth,
+        video_height: videoHeight,
+    });
+    saveProjectState({
+        projectId: createResult.projectId,
+        storageKey: createResult.storage_key,
+        videoPath,
+        status: 'analyzing',
+    });
+    spinner.succeed(`Project created: ${createResult.projectId}`);
+    if (!opts.auto) {
+        const status = await apiCall('get-status', { projectId: createResult.projectId });
+        console.log(`\nVideo uploaded. Run with --auto to continue processing.`);
+        console.log(`${chalk.bold('Editor:')} ${status.editor_url}`);
+        return;
+    }
+    // Auto mode: continue with analysis
+    await runAnalysis(createResult.projectId, manifest);
+}
+async function runAnalysis(projectId, manifest) {
+    // Analyze video
+    const descSpinner = ora('Analyzing video...').start();
+    try {
+        const descResult = await apiCall('describe-video', {
+            projectId,
+            videoContext: manifest.videoContext,
+        });
+        descSpinner.succeed(`Video analyzed (${descResult.description?.length || 0} chars)`);
+    }
+    catch (err) {
+        descSpinner.fail(`Analysis failed: ${err.message}`);
+        process.exit(1);
+    }
+    // Generate narration
+    const narrSpinner = ora('Writing narration...').start();
+    try {
+        const narrResult = await apiCall('generate-narration', {
+            projectId,
+            language: manifest.language,
+            narrationStyle: manifest.narrationStyle,
+            customPrompt: manifest.customPrompt,
+            includeIntro: false,
+        });
+        narrSpinner.succeed(`${narrResult.segments_created} narration segments`);
+        if (narrResult.segments) {
+            for (const seg of narrResult.segments) {
+                console.log(chalk.dim(`  [${seg.sort_order}] ${seg.timestamp_seconds.toFixed(1)}s — ${seg.action_name}`));
+            }
+        }
+    }
+    catch (err) {
+        narrSpinner.fail(`Narration failed: ${err.message}`);
+        process.exit(1);
+    }
+    // Done
+    const finalStatus = await apiCall('get-status', { projectId });
+    console.log(`\n${chalk.bold.green('Done!')} ${finalStatus.segments?.length || 0} segments ready`);
+    console.log(`${chalk.bold('Editor:')} ${finalStatus.editor_url}`);
+    console.log(chalk.dim('Open the editor to preview narration and generate audio.'));
+    // Clear state so next run creates a fresh project
+    saveProjectState({ projectId, status: 'complete' });
+}
+async function recordAndTrack(manifest) {
+    let pw;
+    try {
+        // @ts-ignore — playwright is an optional peer dependency
+        pw = await import('playwright');
+    }
+    catch {
+        try {
+            const { createRequire } = await import('node:module');
+            const req = createRequire(process.cwd() + '/package.json');
+            pw = req('playwright');
+        }
+        catch {
+            throw new Error('Playwright required. Run: npm install playwright && npx playwright install chromium');
+        }
+    }
+    const { execSync } = await import('node:child_process');
+    try {
+        execSync('ffmpeg -version', { stdio: 'pipe' });
+    }
+    catch {
+        throw new Error('FFmpeg required. Install it: brew install ffmpeg (macOS) or apt install ffmpeg (Linux)');
+    }
+    const { mkdirSync, writeFileSync } = await import('node:fs');
+    const { resolve } = await import('node:path');
+    const viewport = manifest.viewport || { width: 1920, height: 1080 };
+    mkdirSync('.vorec/recordings', { recursive: true });
+    const browser = await pw.chromium.launch({ headless: false });
+    const contextOpts = {
+        viewport,
+        recordVideo: { dir: resolve('.vorec/recordings'), size: viewport },
+    };
+    if (manifest.storageState && existsSync(manifest.storageState)) {
+        contextOpts.storageState = manifest.storageState;
+        console.log('  Using saved auth session:', manifest.storageState);
+    }
+    const context = await browser.newContext(contextOpts);
+    const page = await context.newPage();
+    const startTime = Date.now();
+    const tracked = [];
+    await page.goto(manifest.url, { waitUntil: 'networkidle' });
+    for (const [i, action] of manifest.actions.entries()) {
+        try {
+            if (action.type === 'wait') {
+                await page.waitForTimeout(action.delay || 1000);
+                continue;
+            }
+            if (action.type === 'narrate') {
+                const timestamp = (Date.now() - startTime) / 1000;
+                tracked.push({
+                    type: 'narrate', timestamp,
+                    coordinates: { x: 500, y: 500 }, target: '',
+                    interaction_type: 'narrate',
+                    description: action.description || 'Scene description',
+                    context: action.context,
+                });
+                console.log(`  [${i + 1}/${manifest.actions.length}] ${action.description || 'Narrate'} @ ${timestamp.toFixed(1)}s`);
+                await page.waitForTimeout(action.delay || 3000);
+                continue;
+            }
+            if (action.type === 'navigate') {
+                if (action.text)
+                    await page.goto(action.text, { waitUntil: 'networkidle' });
+                tracked.push({
+                    type: 'navigate', timestamp: (Date.now() - startTime) / 1000,
+                    coordinates: { x: 500, y: 500 }, target: action.text || manifest.url,
+                    interaction_type: 'click',
+                    description: action.description || `Navigate to ${action.text || 'page'}`,
+                });
+                continue;
+            }
+            if (action.type === 'scroll') {
+                await page.mouse.wheel(0, 300);
+                tracked.push({
+                    type: 'scroll', timestamp: (Date.now() - startTime) / 1000,
+                    coordinates: { x: 500, y: 500 }, target: 'page',
+                    interaction_type: 'scroll',
+                    description: action.description || 'Scroll down',
+                });
+                if (action.delay)
+                    await page.waitForTimeout(action.delay);
+                continue;
+            }
+            await page.waitForSelector(action.selector, { timeout: 10000 });
+            const el = await page.$(action.selector);
+            const box = el ? await el.boundingBox() : null;
+            const timestamp = (Date.now() - startTime) / 1000;
+            const coords = box ? {
+                x: Math.round((box.x + box.width / 2) / viewport.width * 1000),
+                y: Math.round((box.y + box.height / 2) / viewport.height * 1000),
+            } : { x: 500, y: 500 };
+            switch (action.type) {
+                case 'click':
+                    await el?.click();
+                    break;
+                case 'type':
+                    await el?.click();
+                    if (action.text)
+                        await page.keyboard.type(action.text, { delay: 50 });
+                    break;
+                case 'select':
+                    if (action.value)
+                        await page.selectOption(action.selector, action.value);
+                    break;
+                case 'hover':
+                    await el?.hover();
+                    break;
+            }
+            let desc = action.description || '';
+            if (!desc) {
+                if (action.type === 'type')
+                    desc = `Type '${action.text || ''}' into ${action.selector}`;
+                else if (action.type === 'select')
+                    desc = `Select '${action.value || ''}' from ${action.selector}`;
+                else
+                    desc = `${action.type} ${action.selector}`;
+            }
+            tracked.push({
+                type: action.type,
+                timestamp,
+                coordinates: coords,
+                target: action.selector,
+                interaction_type: action.type === 'type' ? 'type' : action.type,
+                description: desc,
+                context: action.context,
+                typed_text: action.type === 'type' ? action.text : undefined,
+                selected_value: action.type === 'select' ? action.value : undefined,
+            });
+            console.log(`  [${i + 1}/${manifest.actions.length}] ${desc} @ ${timestamp.toFixed(1)}s`);
+            if (action.delay) {
+                await page.waitForTimeout(action.delay);
+            }
+            else {
+                await page.waitForLoadState('networkidle').catch(() => { });
+                await page.waitForTimeout(500);
+            }
+        }
+        catch (err) {
+            console.error(`  [${i + 1}] Failed: ${err.message}`);
+        }
+    }
+    await page.waitForTimeout(1000);
+    const duration = (Date.now() - startTime) / 1000;
+    const video = page.video();
+    await page.close();
+    await context.close();
+    await browser.close();
+    const webmPath = video ? await video.path() : '';
+    if (duration < 10) {
+        throw new Error(`Recording too short (${duration.toFixed(1)}s). Minimum is 10 seconds. Add more actions or increase delays.`);
+    }
+    console.log('  Converting to MP4...');
+    const mp4Path = webmPath.replace(/\.webm$/, '.mp4');
+    execSync(`ffmpeg -y -i "${webmPath}" -c:v libx264 -preset fast -crf 23 -c:a aac "${mp4Path}"`, { stdio: 'pipe' });
+    try {
+        const { unlinkSync } = await import('node:fs');
+        unlinkSync(webmPath);
+    }
+    catch { }
+    writeFileSync('.vorec/tracked-actions.json', JSON.stringify(tracked, null, 2));
+    return { videoPath: mp4Path, actions: tracked, duration, viewport };
+}

package/dist/commands/status.d.ts

@@ -0,0 +1,5 @@
+interface StatusOptions {
+    project?: string;
+}
+export declare function statusCommand(opts: StatusOptions): Promise<void>;
+export {};

package/dist/commands/status.js

@@ -0,0 +1,17 @@
+import chalk from 'chalk';
+import { apiCall } from '../api.js';
+import { loadProjectState } from '../config.js';
+export async function statusCommand(opts) {
+    const projectId = opts.project || loadProjectState()?.projectId;
+    if (!projectId) {
+        console.error('No project ID. Use --project <id> or run `vorec run` first.');
+        process.exit(1);
+    }
+    const data = await apiCall('get-status', { projectId });
+    console.log(chalk.bold(data.title || 'Untitled'));
+    console.log(`Status:   ${data.status}`);
+    console.log(`Segments: ${data.segments?.length || 0}`);
+    console.log(`Clicks:   ${data.clicks?.length || 0}`);
+    if (data.editor_url)
+        console.log(`Editor:   ${data.editor_url}`);
+}

package/dist/commands/upload.d.ts

@@ -0,0 +1,5 @@
+interface UploadOptions {
+    title?: string;
+}
+export declare function uploadCommand(videoPath: string, opts: UploadOptions): Promise<void>;
+export {};

package/dist/commands/upload.js

@@ -0,0 +1,41 @@
+import { existsSync } from 'node:fs';
+import ora from 'ora';
+import { apiCall, uploadVideo } from '../api.js';
+import { saveProjectState } from '../config.js';
+export async function uploadCommand(videoPath, opts) {
+    if (!existsSync(videoPath)) {
+        console.error(`File not found: ${videoPath}`);
+        process.exit(1);
+    }
+    const title = opts.title || videoPath.replace(/\.[^.]+$/, '').replace(/[_-]/g, ' ');
+    const spinner = ora('Creating project...').start();
+    try {
+        // Create project
+        const result = await apiCall('create-project', { title });
+        spinner.text = 'Uploading video...';
+        // Upload to R2
+        await uploadVideo(result.upload_url, videoPath);
+        spinner.text = 'Confirming upload...';
+        // Confirm
+        const status = await apiCall('confirm-upload', {
+            projectId: result.projectId,
+            storage_key: result.storage_key,
+        });
+        // Save state
+        saveProjectState({
+            projectId: result.projectId,
+            storageKey: result.storage_key,
+            videoPath,
+            status: status.status,
+        });
+        spinner.succeed(`Project created: ${result.projectId}`);
+        console.log(`Status: ${status.status}`);
+        if (status.status === 'analyzing') {
+            console.log('Gemini analysis started. Run `vorec status` to check progress.');
+        }
+    }
+    catch (err) {
+        spinner.fail(err.message);
+        process.exit(1);
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+import type { VorecConfig } from './types.js';
+export declare function loadConfig(): VorecConfig;
+export declare function saveConfig(config: Partial<VorecConfig>): void;
+export declare function requireApiKey(): string;
+export declare function loadProjectState(): any;
+export declare function saveProjectState(state: any): void;

package/dist/config.js

@@ -0,0 +1,47 @@
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+const CONFIG_DIR = join(homedir(), '.vorec');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+const DEFAULTS = {
+    apiKey: '',
+    apiBase: process.env.VOREC_API_BASE || 'https://api.vorec.ai/agent',
+};
+export function loadConfig() {
+    try {
+        const raw = readFileSync(CONFIG_FILE, 'utf-8');
+        return { ...DEFAULTS, ...JSON.parse(raw) };
+    }
+    catch {
+        return { ...DEFAULTS };
+    }
+}
+export function saveConfig(config) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    const current = loadConfig();
+    const merged = { ...current, ...config };
+    writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2) + '\n');
+}
+export function requireApiKey() {
+    const config = loadConfig();
+    if (!config.apiKey) {
+        console.error('No API key configured. Run: vorec init');
+        process.exit(1);
+    }
+    return config.apiKey;
+}
+// Per-project state
+const PROJECT_DIR = '.vorec';
+const PROJECT_FILE = join(PROJECT_DIR, 'project.json');
+export function loadProjectState() {
+    try {
+        return JSON.parse(readFileSync(PROJECT_FILE, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveProjectState(state) {
+    mkdirSync(PROJECT_DIR, { recursive: true });
+    writeFileSync(PROJECT_FILE, JSON.stringify(state, null, 2) + '\n');
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,41 @@
+import { Command } from 'commander';
+import { initCommand } from './commands/init.js';
+import { recordCommand } from './commands/record.js';
+import { uploadCommand } from './commands/upload.js';
+import { runCommand } from './commands/run.js';
+import { statusCommand } from './commands/status.js';
+const program = new Command()
+    .name('vorec')
+    .description('Turn screen recordings into narrated tutorials')
+    .version('0.10.0');
+program
+    .command('init')
+    .description('Save your Vorec API key')
+    .action(initCommand);
+program
+    .command('record')
+    .description('Record a screen session with Playwright')
+    .requiredOption('--url <url>', 'URL to navigate to')
+    .requiredOption('--actions <path>', 'Path to actions JSON file')
+    .option('--viewport <size>', 'Viewport size (WxH)', '1920x1080')
+    .option('--output <path>', 'Output manifest path', 'vorec-recording.json')
+    .action(recordCommand);
+program
+    .command('upload <video>')
+    .description('Upload a video and create a project')
+    .option('--title <title>', 'Project title')
+    .action(uploadCommand);
+program
+    .command('run <manifest>')
+    .description('Full pipeline: record → upload → narrate → audio')
+    .option('--auto', 'Wait for processing and generate audio', false)
+    .option('--skip-record', 'Skip Playwright recording (use --video)', false)
+    .option('--video <path>', 'Use existing video file instead of recording')
+    .option('--tracked-actions <path>', 'JSON file with tracked actions (for --skip-record)')
+    .action(runCommand);
+program
+    .command('status')
+    .description('Check project status')
+    .option('--project <id>', 'Project ID')
+    .action(statusCommand);
+program.parse();

package/dist/manifest.d.ts

@@ -0,0 +1,2 @@
+import type { Manifest } from './types.js';
+export declare function loadManifest(path: string): Manifest;

package/dist/manifest.js

@@ -0,0 +1,21 @@
+import { readFileSync } from 'node:fs';
+export function loadManifest(path) {
+    const raw = readFileSync(path, 'utf-8');
+    const manifest = JSON.parse(raw);
+    if (!manifest.title)
+        throw new Error('Manifest missing "title"');
+    if (!manifest.url)
+        throw new Error('Manifest missing "url"');
+    if (!manifest.actions || manifest.actions.length === 0) {
+        throw new Error('Manifest missing "actions" array');
+    }
+    for (const [i, action] of manifest.actions.entries()) {
+        if (!action.type)
+            throw new Error(`Action ${i} missing "type"`);
+        const noSelectorNeeded = ['wait', 'navigate', 'scroll', 'narrate'];
+        if (!action.selector && !noSelectorNeeded.includes(action.type)) {
+            throw new Error(`Action ${i} missing "selector"`);
+        }
+    }
+    return manifest;
+}

package/dist/types.d.ts

@@ -0,0 +1,60 @@
+export interface VorecConfig {
+    apiKey: string;
+    apiBase: string;
+}
+export interface Manifest {
+    title: string;
+    url: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    storageState?: string;
+    language?: string;
+    narrationStyle?: string;
+    videoContext?: string;
+    customPrompt?: string;
+    includeIntro?: boolean;
+    actions: ManifestAction[];
+}
+export interface ManifestAction {
+    type: 'click' | 'type' | 'select' | 'hover' | 'scroll' | 'wait' | 'navigate' | 'narrate';
+    selector?: string;
+    text?: string;
+    value?: string;
+    delay?: number;
+    description?: string;
+    context?: string;
+}
+export interface TrackedAction {
+    type: string;
+    timestamp: number;
+    coordinates: {
+        x: number;
+        y: number;
+    };
+    target: string;
+    interaction_type: string;
+    description?: string;
+    context?: string;
+    typed_text?: string;
+    selected_value?: string;
+}
+export interface ProjectState {
+    projectId: string;
+    storageKey?: string;
+    uploadUrl?: string;
+    videoPath?: string;
+    status?: string;
+}
+export interface ApiResponse {
+    projectId?: string;
+    upload_url?: string;
+    storage_key?: string;
+    status?: string;
+    error?: string;
+    segments?: any[];
+    clicks?: any[];
+    editor_url?: string;
+    [key: string]: any;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@vorec/cli",
+  "version": "0.10.0",
+  "description": "Turn screen recordings into narrated tutorials — CLI for AI coding agents",
+  "type": "module",
+  "bin": {
+    "vorec": "./bin/vorec.mjs"
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "ora": "^8.1.0"
+  },
+  "peerDependencies": {
+    "playwright": "^1.40.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "vorec",
+    "screen-recording",
+    "tutorial",
+    "narration",
+    "ai-agent"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.5.0"
+  }
+}