@scenerok/cli 2.2.0

package/README.md

@@ -0,0 +1,173 @@
+# SceneRok CLI
+
+Create videos from your terminal and agent workflows.
+
+## Installation
+
+```bash
+npm install -g @scenerok/cli
+```
+
+Or use with `npx`:
+```bash
+npx @scenerok/cli auth login
+```
+
+## Quick Start
+
+```bash
+# Authenticate
+scenerok auth login
+
+# Validate a VidScript
+scenerok validate video.vidscript
+
+# Render a video
+scenerok render video.vidscript --resolution 1080x1920 --watch
+
+# Upload a local project and assets
+scenerok project upload video.vidscript --assets ./assets
+
+# Upload, render, watch, and download
+scenerok project upload video.vidscript --assets ./assets --render --watch --download ./renders
+
+# Pull generated asset cache
+scenerok cache pull
+
+# Check render status
+scenerok status 42
+```
+
+## Commands
+
+### `auth`
+
+```bash
+scenerok auth login        # Log in via browser
+scenerok auth status       # Check auth status
+scenerok auth logout       # Remove credentials
+```
+
+### `skills`
+
+```bash
+scenerok skills install <platform> [--sync]  # Install router skill (+ optional full sync)
+scenerok skills sync                         # Download remote skill bundle
+scenerok skills check [--json]               # Compare local vs remote manifest
+scenerok skills update                       # Refresh outdated skills
+scenerok skills list                         # List remote skills + local status
+scenerok skills platforms                    # List supported agent platforms
+```
+
+Supported platforms: `opencode`, `claude`, `codex`, `cursor`, `aider`
+
+Remote skills are served from https://scenerok.com/.well-known/agent-skills/ and updated on every deploy — no CLI release needed for skill content changes.
+
+### `validate`
+
+```bash
+scenerok validate <file.vidscript>
+scenerok validate <file.vidscript> --generate-assets --report-json
+scenerok validate <file.vidscript> --render --cost medium
+```
+
+Validates VidScript syntax and returns scene count, duration, and warnings.
+
+Options:
+- `--generate-assets` - Real compile: plugins execute, assets generate + cache, durations and text geometry are measured (billed; requires auth)
+- `--render` - Full pipeline: validate with generated assets → render → validate the output MP4 (ffprobe + LLM frame review, billed). Exit code 0 only when every stage passes — built for agent write→lint→render→lint loops
+- `--cost <tier>` / `--frames <n>` - Frame-grab budget for the MP4 review (see `lint-video`)
+- `--budget <usd>` - Total USD cap for the whole `--render` pipeline (plugin generation + render + MP4 review); the pipeline aborts before any billed call if the free dry-run estimate exceeds it, and the MP4 review draws only from what remains
+- `--render-budget <usd>` - USD cap on plugin generation + render spend alone
+- `--validation-budget <usd>` - USD cap on the MP4 LLM review; frame count is clamped to fit
+- `--resolution <resolution>` - Output resolution for `--render`
+- `--report-json` - Print reports as JSON (for agents)
+
+### `lint-video`
+
+```bash
+scenerok lint-video <render-id> [--cost low|medium|high] [--frames <n>] [--budget <usd>] [--json]
+```
+
+Validates a completed render's actual MP4:
+1. **ffprobe checks** (free): readable container, video stream present, duration/aspect/audio vs the VidScript
+2. **Frame review** (billed by token usage): frames are grabbed at timestamps where the script says content appears (text midpoints, clip midpoints, opening, ending) and a vision LLM compares each frame with what the script expects — missing/illegible text, blank frames, artifacts
+
+`--cost` sets the frame budget (low=4, medium=8, high=14); `--frames` sets it exactly (max 20); `--budget <usd>` is a hard USD cap that clamps the frame count to the most that fit. More frames cost more and cover more. All LLM cost is billed to your token balance and itemized in the output.
+
+### `render`
+
+```bash
+scenerok render <file.vidscript> [options]
+```
+
+Options:
+- `-r, --resolution <resolution>` - Output resolution (e.g. 1080x1920)
+- `-p, --project-id <id>` - Attach the render to an uploaded project
+- `-w, --watch` - Watch render status until complete
+- `--download [dir]` - Download the completed MP4
+- `--validate [cost]` - After rendering, validate the output MP4 (implies watching; billed frame review, cost tier low/medium/high)
+- `--validation-budget <usd>` - Hard USD cap on the MP4 review when using `--validate`
+
+### `status`
+
+```bash
+scenerok status <render-id>
+```
+
+Check the status of a render job.
+
+Use `scenerok status <render-id> --download ./renders` to download a completed render.
+
+### `project`
+
+```bash
+scenerok project upload <file.vidscript> --assets ./assets
+scenerok project upload <file.vidscript> --assets ./assets --render --watch --download ./renders
+scenerok project list
+scenerok project render <project-id> --watch --download ./renders
+```
+
+`project upload` creates a private SceneRok project on the main server, uploads referenced local assets, rewrites local `input` paths to server asset URLs, and returns a project id. Project renders are visible on the website.
+
+### `cache`
+
+```bash
+scenerok cache pull
+scenerok cache pull --plugin @scenerok/xai --output ~/.scenerok/cache/assets
+```
+
+Downloads cached generated assets and writes a `manifest.json` to the output folder.
+
+## Configuration
+
+Config is stored in `~/.scenerok/config.json`:
+
+```json
+{
+  "apiToken": "rf_...",
+  "baseUrl": "https://scenerok.com"
+}
+```
+
+## VidScript
+
+VidScript is a declarative language for describing video compositions.
+
+```vidscript
+import motion from "@scenerok/basic-animations"
+
+input hero = "./assets/hero.mp4"
+
+[0s .. 5s] = hero
+[0.4s .. 3s] = text "Hello World", font: "Inter Bold", size: 72, x: "50%", y: "50%", align: center, animate: [motion.fadeIn(0.6s), motion.slideY(40, 0, 0.8s)]
+
+output to "video.mp4", resolution: "1080x1920", fps: 30
+```
+
+Animation helpers are package functions: `motion.fadeIn`, `motion.fadeOut`, `motion.slideX`, `motion.slideY`, `motion.popIn`, `motion.riseIn`, `motion.swingIn`, `motion.glitchIn`, `motion.float`, `motion.typewriter`.
+
+## Links
+
+- Website: https://scenerok.com
+- Docs: https://scenerok.com/agents/get-started.md

package/dist/commands/auth.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare const authCommand: Command;
+//# sourceMappingURL=auth.d.ts.map

package/dist/commands/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,eAAO,MAAM,WAAW,SA2GrB,CAAC"}

package/dist/commands/auth.js

@@ -0,0 +1,94 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { readConfig, writeConfig, isAuthenticated } from '../lib/config.js';
+import { initiateDeviceAuth, pollDeviceAuth } from '../lib/api.js';
+import { getBaseUrl } from '../lib/config.js';
+import { formatApiErrorMessage } from '../lib/format-api-error.js';
+import { getLogFilePath, isVerbose, logError } from '../lib/logger.js';
+export const authCommand = new Command('auth')
+    .description('Authenticate with SceneRok')
+    .addCommand(new Command('login')
+    .description('Log in to SceneRok via browser')
+    .option('-n, --name <name>', 'Device name', 'CLI')
+    .option('-u, --base-url <url>', 'SceneRok API base URL (overrides ~/.scenerok/config.json and SCENEROK_BASE_URL)')
+    .option('-v, --verbose', 'Print debug output and log API calls to ~/.scenerok/logs/cli.log')
+    .action(async (options) => {
+    if (options.baseUrl) {
+        const config = readConfig();
+        config.baseUrl = options.baseUrl.replace(/\/$/, '');
+        writeConfig(config);
+    }
+    console.log(chalk.cyan('\n🔐 SceneRok Authentication\n'));
+    console.log(chalk.dim(`API: ${getBaseUrl()}`));
+    if (options.verbose || isVerbose()) {
+        console.log(chalk.dim(`Log file: ${getLogFilePath()}\n`));
+    }
+    const spinner = ora('Initiating device auth...').start();
+    try {
+        const auth = await initiateDeviceAuth(options.name);
+        spinner.succeed('Device auth initiated');
+        console.log(chalk.yellow('\n1. Open this URL in your browser:'));
+        console.log(chalk.underline(auth.verification_uri));
+        console.log('');
+        console.log(chalk.yellow('2. Enter this code if prompted:'));
+        console.log(chalk.bold(`   ${auth.user_code}`));
+        console.log('');
+        console.log(chalk.yellow('3. Or run this command:'));
+        console.log(`   open "${auth.verification_uri}"`);
+        console.log('');
+        console.log(chalk.dim(`Waiting for authentication... (expires in ${auth.expires_in}s)\n`));
+        const startTime = Date.now();
+        const expiresIn = auth.expires_in * 1000;
+        while (Date.now() - startTime < expiresIn) {
+            await new Promise((resolve) => setTimeout(resolve, auth.interval * 1000));
+            const result = await pollDeviceAuth(auth.device_code);
+            if (result.status === 'complete' && result.access_token) {
+                const config = readConfig();
+                config.apiToken = result.access_token;
+                writeConfig(config);
+                console.log(chalk.green('\n✅ Successfully authenticated with SceneRok!\n'));
+                console.log(chalk.dim('Your API token has been saved to ~/.scenerok/config.json'));
+                return;
+            }
+            if (result.error === 'expired_token') {
+                console.log(chalk.red('\n❌ Authentication expired. Please try again.\n'));
+                process.exit(1);
+            }
+        }
+        console.log(chalk.red('\n❌ Authentication timed out. Please try again.\n'));
+        process.exit(1);
+    }
+    catch (error) {
+        spinner.fail('Authentication failed');
+        logError('auth login failed', {
+            baseUrl: getBaseUrl(),
+            error: formatApiErrorMessage(error),
+        });
+        console.error(chalk.red(formatApiErrorMessage(error)));
+        console.error(chalk.dim(`\nLog: ${getLogFilePath()}`));
+        console.error(chalk.dim('Retry with: scenerok auth login --verbose  (or SCENEROK_VERBOSE=1 scenerok auth login)'));
+        process.exit(1);
+    }
+}))
+    .addCommand(new Command('status')
+    .description('Check authentication status')
+    .action(() => {
+    console.log(chalk.dim(`API: ${getBaseUrl()}`));
+    console.log(chalk.dim(`Log: ${getLogFilePath()}`));
+    if (isAuthenticated()) {
+        console.log(chalk.green('✅ Authenticated with SceneRok'));
+    }
+    else {
+        console.log(chalk.yellow('⚠️  Not authenticated'));
+        console.log(chalk.dim('Run: scenerok auth login'));
+    }
+}))
+    .addCommand(new Command('logout')
+    .description('Log out and remove stored credentials')
+    .action(() => {
+    const config = readConfig();
+    delete config.apiToken;
+    writeConfig(config);
+    console.log(chalk.green('✅ Logged out successfully'));
+}));

package/dist/commands/cache.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare const cacheCommand: Command;
+//# sourceMappingURL=cache.d.ts.map

package/dist/commands/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/commands/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwBpC,eAAO,MAAM,YAAY,SA6CtB,CAAC"}

package/dist/commands/cache.js

@@ -0,0 +1,65 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { basename, extname, join, resolve } from 'node:path';
+import fetch from 'node-fetch';
+import { getAssetCache } from '../lib/api.js';
+import { getCacheDir, isAuthenticated } from '../lib/config.js';
+function safeName(value) {
+    return value.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 120);
+}
+function filenameFor(url, cacheKey) {
+    try {
+        const parsed = new URL(url);
+        const fromUrl = basename(parsed.pathname);
+        if (fromUrl && extname(fromUrl))
+            return safeName(fromUrl);
+    }
+    catch {
+        // fall through
+    }
+    return `${safeName(cacheKey)}.bin`;
+}
+export const cacheCommand = new Command('cache')
+    .description('Manage local SceneRok asset cache')
+    .addCommand(new Command('pull')
+    .description('Download cached generated assets to a local folder')
+    .option('-o, --output <dir>', 'Output directory', join(getCacheDir(), 'assets'))
+    .option('--plugin <name>', 'Filter by plugin name')
+    .option('--limit <count>', 'Maximum assets to pull', '100')
+    .action(async (options) => {
+    if (!isAuthenticated()) {
+        console.log(chalk.yellow('Not authenticated'));
+        console.log(chalk.dim('Run: scenerok auth login'));
+        process.exit(1);
+    }
+    const outputDir = resolve(options.output);
+    mkdirSync(outputDir, { recursive: true });
+    const spinner = ora('Fetching asset cache manifest...').start();
+    try {
+        const manifest = await getAssetCache({
+            plugin: options.plugin,
+            limit: Number.parseInt(options.limit, 10) || 100,
+        });
+        spinner.text = `Downloading ${manifest.entries.length} cached asset${manifest.entries.length === 1 ? '' : 's'}...`;
+        const downloaded = [];
+        for (const entry of manifest.entries) {
+            const response = await fetch(entry.r2Url);
+            if (!response.ok)
+                continue;
+            const filename = filenameFor(entry.r2Url, entry.cacheKey);
+            const filePath = join(outputDir, filename);
+            writeFileSync(filePath, Buffer.from(await response.arrayBuffer()));
+            downloaded.push({ ...entry, filePath });
+        }
+        writeFileSync(join(outputDir, 'manifest.json'), JSON.stringify(downloaded, null, 2));
+        spinner.succeed(`Downloaded ${downloaded.length} cached asset${downloaded.length === 1 ? '' : 's'}`);
+        console.log(chalk.dim(`Manifest: ${join(outputDir, 'manifest.json')}`));
+    }
+    catch (error) {
+        spinner.fail('Asset cache pull failed');
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+}));

package/dist/commands/lint-video.d.ts

@@ -0,0 +1,21 @@
+import { Command } from 'commander';
+import { type VideoLintResult } from '../lib/api.js';
+export declare const LINT_COST_CHOICES: string[];
+export declare function parseLintOptions(opts: {
+    cost?: string;
+    frames?: string;
+    budget?: string;
+}): {
+    cost?: string;
+    frames?: number;
+    budgetUsd?: number;
+};
+export declare function printVideoLintResult(result: VideoLintResult, jsonMode?: boolean): void;
+export declare function runVideoLint(renderId: number, options: {
+    cost?: string;
+    frames?: number;
+    budgetUsd?: number;
+    json?: boolean;
+}): Promise<boolean>;
+export declare const lintVideoCommand: Command;
+//# sourceMappingURL=lint-video.d.ts.map

package/dist/commands/lint-video.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint-video.d.ts","sourceRoot":"","sources":["../../src/commands/lint-video.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAGrE,eAAO,MAAM,iBAAiB,UAA4B,CAAC;AAE3D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAC3F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAsBA;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,eAAe,EAAE,QAAQ,UAAQ,GAAG,IAAI,CA8DpF;AAED,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9E,OAAO,CAAC,OAAO,CAAC,CAgBlB;AAED,eAAO,MAAM,gBAAgB,SAqBzB,CAAC"}

package/dist/commands/lint-video.js

@@ -0,0 +1,122 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { validateRender } from '../lib/api.js';
+import { isAuthenticated } from '../lib/config.js';
+export const LINT_COST_CHOICES = ['low', 'medium', 'high'];
+export function parseLintOptions(opts) {
+    if (opts.cost && !LINT_COST_CHOICES.includes(opts.cost)) {
+        console.log(chalk.red(`❌ Invalid --cost "${opts.cost}" — use ${LINT_COST_CHOICES.join(', ')}`));
+        process.exit(1);
+    }
+    let frames;
+    if (opts.frames !== undefined) {
+        frames = Number.parseInt(opts.frames, 10);
+        if (Number.isNaN(frames) || frames < 1) {
+            console.log(chalk.red('❌ --frames must be a positive integer'));
+            process.exit(1);
+        }
+    }
+    let budgetUsd;
+    if (opts.budget !== undefined) {
+        budgetUsd = Number.parseFloat(opts.budget);
+        if (Number.isNaN(budgetUsd) || budgetUsd <= 0) {
+            console.log(chalk.red('❌ --budget must be a positive USD amount'));
+            process.exit(1);
+        }
+    }
+    return { cost: opts.cost, frames, budgetUsd };
+}
+export function printVideoLintResult(result, jsonMode = false) {
+    if (jsonMode) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(result.valid
+        ? chalk.green('\n✅ Rendered video passed validation\n')
+        : chalk.red('\n❌ Rendered video failed validation\n'));
+    if (result.probe) {
+        const p = result.probe;
+        console.log(chalk.cyan('  Probe:'));
+        console.log(`    ${p.width}x${p.height} @ ${p.fps?.toFixed(1) ?? '?'}fps, ` +
+            `${p.durationSeconds?.toFixed(2) ?? '?'}s, ${p.videoCodec ?? 'unknown codec'}, ` +
+            `audio: ${p.hasAudio ? 'yes' : 'no'}`);
+    }
+    for (const error of result.errors ?? []) {
+        console.log(chalk.red(`  ✗ ${error}`));
+    }
+    for (const warning of result.warnings ?? []) {
+        console.log(chalk.yellow(`  ⚠ ${warning}`));
+    }
+    const review = result.llmReview;
+    if (review) {
+        console.log(chalk.cyan(`\n  Frame review (${result.framesAnalyzed} frames, score ${review.overallScore}/100):`));
+        for (const frame of review.frames) {
+            const mark = frame.matches ? chalk.green('✓') : chalk.red('✗');
+            console.log(`    ${mark} ${frame.timestamp.toFixed(1)}s — ${frame.observed}`);
+            for (const issue of frame.issues) {
+                console.log(chalk.red(`        ${issue}`));
+            }
+        }
+        if (review.summary) {
+            console.log(`\n  ${review.summary}`);
+        }
+        if (review.suggestions.length > 0) {
+            console.log(chalk.cyan('\n  Suggestions:'));
+            for (const suggestion of review.suggestions) {
+                console.log(`    • ${suggestion}`);
+            }
+        }
+    }
+    else if (result.note) {
+        console.log(chalk.dim(`\n  ${result.note}`));
+    }
+    if (result.billing) {
+        if (result.billing.budgetUsd !== undefined) {
+            console.log(chalk.dim(`\n  Budget: $${result.billing.budgetUsd.toFixed(4)} cap`));
+        }
+        console.log(chalk.dim(`${result.billing.budgetUsd !== undefined ? '' : '\n'}  LLM cost: $${result.billing.costUsd.toFixed(4)} ` +
+            `(${result.billing.totalTokens} LLM tokens, $${(result.billing.tokenUnitsCharged / 1000).toFixed(3)} wallet)`));
+    }
+    console.log('');
+}
+export async function runVideoLint(renderId, options) {
+    const spinner = options.json ? null : ora('Validating rendered video (probe + frame review)...').start();
+    try {
+        const result = await validateRender(renderId, {
+            cost: options.cost,
+            frames: options.frames,
+            budgetUsd: options.budgetUsd,
+        });
+        spinner?.stop();
+        printVideoLintResult(result, options.json);
+        return result.valid;
+    }
+    catch (error) {
+        spinner?.fail('Video validation failed');
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        return false;
+    }
+}
+export const lintVideoCommand = new Command('lint-video')
+    .description('Validate a completed render\'s MP4: ffprobe checks plus LLM review of frame grabs compared against the VidScript (billed by usage)')
+    .argument('<renderId>', 'Completed render job ID')
+    .option('--cost <tier>', `Frame-grab budget: ${LINT_COST_CHOICES.join(', ')} (more frames = higher LLM cost, better coverage)`, 'medium')
+    .option('--frames <n>', 'Exact number of frame grabs (overrides --cost, max 20)')
+    .option('--budget <usd>', 'Hard USD cap: clamp frame grabs to the most that fit this budget')
+    .option('--json', 'Print the full report as JSON (for agents)')
+    .action(async (renderIdArg, opts) => {
+    if (!isAuthenticated()) {
+        console.log(chalk.yellow('⚠️  Not authenticated'));
+        console.log(chalk.dim('Run: scenerok auth login'));
+        process.exit(1);
+    }
+    const renderId = Number.parseInt(renderIdArg, 10);
+    if (Number.isNaN(renderId)) {
+        console.log(chalk.red('❌ Invalid render ID'));
+        process.exit(1);
+    }
+    const { cost, frames, budgetUsd } = parseLintOptions(opts);
+    const passed = await runVideoLint(renderId, { cost, frames, budgetUsd, json: opts.json });
+    process.exit(passed ? 0 : 1);
+});

package/dist/commands/project.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare const projectCommand: Command;
+//# sourceMappingURL=project.d.ts.map

package/dist/commands/project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../src/commands/project.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuCpC,eAAO,MAAM,cAAc,SA+JxB,CAAC"}