retiam 1.0.0 → 1.0.2

package/bin/cli.js

@@ -1,209 +1,213 @@
-#!/usr/bin/env node
-
-// =========================================================================
-// File: bin/cli.js - Retiam Unified CLI Entrypoint
-// =========================================================================
-
-import { spawn } from 'child_process';
-import path from 'path';
-import { fileURLToPath } from 'url';
-import { createRequire } from 'module';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-const args = process.argv.slice(2);
-const command = args[0];
-
-const renderScript = path.join(__dirname, 'render.js');
-const exportScript = path.join(__dirname, 'export.js');
-const lintScript = path.join(__dirname, 'lint.js');
-const snapshotScript = path.join(__dirname, 'snapshot.js');
-const initScript = path.join(__dirname, 'init.js');
-
-function runScript(scriptPath, scriptArgs) {
-    if (scriptPath === renderScript || scriptPath === snapshotScript) {
-        try {
-            createRequire(import.meta.url).resolve('puppeteer');
-        } catch {
-            console.error('Retiam render and snapshot require the optional Puppeteer dependency. Install it in your project with: npm install --save-dev puppeteer');
-            process.exit(1);
-        }
-    }
-    const child = spawn(process.execPath, [scriptPath, ...scriptArgs], { stdio: 'inherit' });
-    child.on('error', (error) => {
-        console.error(`Unable to start Retiam command: ${error.message}`);
-        process.exit(1);
-    });
-    child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
-}
-
-function printRootHelp() {
-    console.log(`
-🎬 Retiam WebGPU Engine CLI (Agent-Native Edition)
-
-Usage:
-  npx retiam <command> [file] [options]
-  npx retiam [file] [options]               (shortcut for render)
-  npx retiam help <command>                 (detailed help for a single command)
-
-Commands Overview:
-  init, create     Initialize a complete Retiam WebGPU animation skeleton project
-  lint             Statically analyze scenes for runtime hazards and async timing bugs
-  snapshot         Capture multi-timestamp visual PNG keyframes via headless WebGPU
-  render           Render high-fidelity video (MP4/WebM) via WebGPU & FFmpeg
-  export           Bundle scene into an embeddable <retiam-scene> Web Component
-
-================================================================================
-1. RENDER (npx retiam render [file] [options])
-   Render a scene into an MP4/WebM video via headless Chrome and FFmpeg.
-
-   Arguments:
-     [file]                    Target scene TypeScript file (default: src/main.ts)
-
-   Options:
-     -w, --width <px>          Output video width (default: 1920)
-     -h, --height <px>         Output video height (default: 1080)
-     -f, --fps <num>           Render frame rate (default: 60)
-     -d, --duration <ms>       Maximum rendering duration limit in milliseconds
-     -o, --out <dir>           Output directory for video (default: ./outputs/video)
-     --raytrace [true|false]   Enable or disable hardware raytracing
-     --no-raytrace             Explicitly disable raytracing
-     --denoiser <format>       Denoiser pipeline ('none', 'spatial', 'oidn', 'native')
-     --raw                     Use native raw HDR frame buffer export
-     --replay <file.json>      Replay recorded interactions JSON during rendering
-     --help                    Show render-specific help
-
-   Examples:
-     npx retiam render src/scenes/AStarScene.ts
-     npx retiam render MyScene.ts -w 1920 -h 1080 -f 60
-     npx retiam render MyScene.ts -d 15000 --raytrace false
-
-================================================================================
-2. SNAPSHOT (npx retiam snapshot <file> [options])
-   Capture visual PNG keyframe snapshots at specific timeline seconds.
-
-   Arguments:
-     <file>                    Target scene TypeScript file (e.g. MyScene.ts)
-
-   Options:
-     --times <sec,sec,...>     Comma-separated timeline seconds (default: 1.0, 2.5)
-     -w, --width <px>          Snapshot width in pixels (default: 1280)
-     -h, --height <px>         Snapshot height in pixels (default: 720)
-     -o, --out <dir>           Output directory for images (default: ./outputs/snapshot)
-     --json                    Output structured JSON for agents & CI automation
-     --help                    Show snapshot-specific help
-
-   Examples:
-     npx retiam snapshot MyScene.ts
-     npx retiam snapshot MyScene.ts --times 1.0,3.5,7.0 -w 1920 -h 1080
-     npx retiam snapshot MyScene.ts --times 5.0 --out ./outputs/snapshot --json
-
-================================================================================
-3. INIT / CREATE (npx retiam init [directory] [options])
-   Initialize a complete, ready-to-run Retiam WebGPU animation project skeleton.
-
-   Arguments:
-     [directory]               Destination directory (default: ./retiam-animation)
-
-   Options:
-     -n, --name <name>         Project name for package.json (default: directory name)
-     --title <text>            Hero text for starter Hello World scene (default: Hello World)
-     --pm <manager>            Package manager: npm, pnpm, yarn, bun (default: auto or npm)
-     -f, --force               Overwrite destination directory if files already exist
-     -y, --yes                 Skip interactive prompts and use defaults
-     --install                 Automatically install dependencies after initialization
-     --git                     Initialize a Git repository (git init)
-     --json                    Output structured JSON for agents & CI automation
-     --help, -h                Show init-specific help
-
-   Examples:
-     npx retiam init
-     npx retiam init my-animation
-     npx retiam create quantum-viz --title "Quantum Mechanics" --pm pnpm
-     npx retiam init intro-scene -y --install
-
-================================================================================
-4. LINT (npx retiam lint <file> [options])
-   Static analyzer and AST validator detecting common animation bugs and timing hazards.
-
-   Arguments:
-     <file>                    Target scene file to analyze (e.g. MyScene.ts)
-
-   Options:
-     --json                    Output machine-readable JSON with line numbers & suggested fixes
-     --help, -h                Show lint-specific help
-
-   Checks Performed:
-     - Validates Scene class structure and async run() contract
-     - Detects un-awaited this.play() or this.wait() timing races
-     - Warns about dangling entities not attached to scene graph
-     - Catches Three.js / Python Manim hallucinations
-     - Flags extreme world coordinates exceeding standard camera frustum
-
-   Examples:
-     npx retiam lint MyScene.ts
-     npx retiam lint MyScene.ts --json
-
-================================================================================
-5. EXPORT (npx retiam export [file] [outDir] [options])
-   Compile the scene into a standalone, zero-dependency <retiam-scene> Web Component.
-
-   Arguments:
-     [file]                    Source scene file to bundle (default: src/main.ts)
-     [outDir]                  Target distribution folder (default: outputs/embed)
-
-   Options:
-     -o, --out <dir>           Target distribution folder (default: outputs/embed)
-     --help, -h                Show export-specific help
-
-   Examples:
-     npx retiam export MyScene.ts
-     npx retiam export MyScene.ts ./outputs/embed
-`);
-}
-
-if (command === 'lint') {
-    // Usage: npx retiam lint src/MyScene.ts [--json]
-    runScript(lintScript, args.slice(1));
-}
-else if (command === 'snapshot') {
-    // Usage: npx retiam snapshot src/MyScene.ts [--times 1.0,2.5] [--out ./outputs/snapshot] [--json]
-    runScript(snapshotScript, args.slice(1));
-}
-else if (command === 'init' || command === 'create' || command === 'scaffold') {
-    // Usage: npx retiam init [directory] [options]
-    runScript(initScript, args.slice(1));
-}
-else if (command === 'export') {
-    // Usage: npx retiam export src/main.ts
-    runScript(exportScript, args.slice(1));
-} 
-else if (command === 'render') {
-    // Usage: npx retiam render src/main.ts
-    runScript(renderScript, args.slice(1));
-} 
-else if (command === 'help') {
-    const sub = args[1];
-    if (sub === 'lint') {
-        runScript(lintScript, ['--help']);
-    } else if (sub === 'snapshot') {
-        runScript(snapshotScript, ['--help']);
-    } else if (sub === 'init' || sub === 'create' || sub === 'scaffold') {
-        runScript(initScript, ['--help']);
-    } else if (sub === 'export') {
-        runScript(exportScript, ['--help']);
-    } else if (sub === 'render') {
-        runScript(renderScript, ['--help']);
-    } else {
-        printRootHelp();
-    }
-} 
-else if (command === '-h' || command === '--help' || !command) {
-    printRootHelp();
-} 
-else {
-    // Fallback: Default to rendering if a file path or flag is passed directly
-    // Usage: npx retiam src/main.ts
-    runScript(renderScript, args);
-}
+#!/usr/bin/env node
+
+// =========================================================================
+// File: bin/cli.js - Retiam Unified CLI Entrypoint
+// =========================================================================
+
+import { spawn } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+const renderScript = path.join(__dirname, 'render.js');
+const exportScript = path.join(__dirname, 'export.js');
+const lintScript = path.join(__dirname, 'lint.js');
+const snapshotScript = path.join(__dirname, 'snapshot.js');
+const initScript = path.join(__dirname, 'init.js');
+
+function runScript(scriptPath, scriptArgs) {
+    if (scriptPath === renderScript || scriptPath === snapshotScript) {
+        try {
+            createRequire(import.meta.url).resolve('puppeteer');
+        } catch {
+            console.error('Retiam installation is incomplete: its required Puppeteer dependency is missing. Reinstall Retiam in your project with: npm install retiam');
+            process.exit(1);
+        }
+    }
+    const child = spawn(process.execPath, [scriptPath, ...scriptArgs], { stdio: 'inherit' });
+    child.on('error', (error) => {
+        console.error(`Unable to start Retiam command: ${error.message}`);
+        process.exit(1);
+    });
+    child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
+}
+
+function printRootHelp() {
+    console.log(`
+🎬 Retiam WebGPU Engine CLI (Agent-Native Edition)
+
+Usage:
+  npx retiam <command> [file] [options]
+  npx retiam [file] [options]               (shortcut for render)
+  npx retiam help <command>                 (detailed help for a single command)
+
+Commands Overview:
+  init, create     Initialize a complete Retiam WebGPU animation skeleton project
+  lint             Statically analyze scenes for runtime hazards and async timing bugs
+  snapshot         Capture multi-timestamp visual PNG keyframes via headless WebGPU
+  render           Render high-fidelity video (MP4/WebM) via WebGPU & FFmpeg
+  export           Bundle scene into an embeddable <retiam-scene> Web Component
+
+================================================================================
+1. RENDER (npx retiam render [file] [options])
+   Render a scene into an MP4/WebM video via headless Chrome and FFmpeg.
+
+   Arguments:
+     [file]                    Target scene TypeScript file (default: src/main.ts)
+
+   Options:
+     -w, --width <px>          Output video width (default: 1920)
+     -h, --height <px>         Output video height (default: 1080)
+     -f, --fps <num>           Render frame rate (default: 60)
+     -d, --duration <ms>       Maximum rendering duration limit in milliseconds
+     -o, --out <dir>           Output directory for video (default: ./outputs/video)
+     --raytrace [true|false]   Enable or disable hardware raytracing
+     --no-raytrace             Explicitly disable raytracing
+     --denoiser <format>       Denoiser pipeline ('none', 'spatial', 'oidn', 'native')
+     --raw                     Use native raw HDR frame buffer export
+     --replay <file.json>      Replay recorded interactions JSON during rendering
+     --help                    Show render-specific help
+
+   Examples:
+     npx retiam render src/scenes/AStarScene.ts
+     npx retiam render MyScene.ts -w 1920 -h 1080 -f 60
+     npx retiam render MyScene.ts -d 15000 --raytrace false
+
+   Configuration:
+     Reads config.js in the project root (retiam.config.js takes priority).
+     Command-line flags override file settings.
+
+================================================================================
+2. SNAPSHOT (npx retiam snapshot <file> [options])
+   Capture visual PNG keyframe snapshots at specific timeline seconds.
+
+   Arguments:
+     <file>                    Target scene TypeScript file (e.g. MyScene.ts)
+
+   Options:
+     --times <sec,sec,...>     Comma-separated timeline seconds (default: 1.0, 2.5)
+     -w, --width <px>          Snapshot width in pixels (default: 1280)
+     -h, --height <px>         Snapshot height in pixels (default: 720)
+     -o, --out <dir>           Output directory for images (default: ./outputs/snapshot)
+     --json                    Output structured JSON for agents & CI automation
+     --help                    Show snapshot-specific help
+
+   Examples:
+     npx retiam snapshot MyScene.ts
+     npx retiam snapshot MyScene.ts --times 1.0,3.5,7.0 -w 1920 -h 1080
+     npx retiam snapshot MyScene.ts --times 5.0 --out ./outputs/snapshot --json
+
+================================================================================
+3. INIT / CREATE (npx retiam init [directory] [options])
+   Initialize a complete, ready-to-run Retiam WebGPU animation project skeleton.
+
+   Arguments:
+     [directory]               Destination directory (default: ./retiam-animation)
+
+   Options:
+     -n, --name <name>         Project name for package.json (default: directory name)
+     --title <text>            Hero text for starter Hello World scene (default: Hello World)
+     --pm <manager>            Package manager: npm, pnpm, yarn, bun (default: auto or npm)
+     -f, --force               Overwrite destination directory if files already exist
+     -y, --yes                 Skip interactive prompts and use defaults
+     --install                 Automatically install dependencies after initialization
+     --git                     Initialize a Git repository (git init)
+     --json                    Output structured JSON for agents & CI automation
+     --help, -h                Show init-specific help
+
+   Examples:
+     npx retiam init
+     npx retiam init my-animation
+     npx retiam create quantum-viz --title "Quantum Mechanics" --pm pnpm
+     npx retiam init intro-scene -y --install
+
+================================================================================
+4. LINT (npx retiam lint <file> [options])
+   Static analyzer and AST validator detecting common animation bugs and timing hazards.
+
+   Arguments:
+     <file>                    Target scene file to analyze (e.g. MyScene.ts)
+
+   Options:
+     --json                    Output machine-readable JSON with line numbers & suggested fixes
+     --help, -h                Show lint-specific help
+
+   Checks Performed:
+     - Validates Scene class structure and async run() contract
+     - Detects un-awaited this.play() or this.wait() timing races
+     - Warns about dangling entities not attached to scene graph
+     - Catches Three.js / Python Manim hallucinations
+     - Flags extreme world coordinates exceeding standard camera frustum
+
+   Examples:
+     npx retiam lint MyScene.ts
+     npx retiam lint MyScene.ts --json
+
+================================================================================
+5. EXPORT (npx retiam export [file] [outDir] [options])
+   Compile the scene into a standalone, zero-dependency <retiam-scene> Web Component.
+
+   Arguments:
+     [file]                    Source scene file to bundle (default: src/main.ts)
+     [outDir]                  Target distribution folder (default: outputs/embed)
+
+   Options:
+     -o, --out <dir>           Target distribution folder (default: outputs/embed)
+     --help, -h                Show export-specific help
+
+   Examples:
+     npx retiam export MyScene.ts
+     npx retiam export MyScene.ts ./outputs/embed
+`);
+}
+
+if (command === 'lint') {
+    // Usage: npx retiam lint src/MyScene.ts [--json]
+    runScript(lintScript, args.slice(1));
+}
+else if (command === 'snapshot') {
+    // Usage: npx retiam snapshot src/MyScene.ts [--times 1.0,2.5] [--out ./outputs/snapshot] [--json]
+    runScript(snapshotScript, args.slice(1));
+}
+else if (command === 'init' || command === 'create' || command === 'scaffold') {
+    // Usage: npx retiam init [directory] [options]
+    runScript(initScript, args.slice(1));
+}
+else if (command === 'export') {
+    // Usage: npx retiam export src/main.ts
+    runScript(exportScript, args.slice(1));
+} 
+else if (command === 'render') {
+    // Usage: npx retiam render src/main.ts
+    runScript(renderScript, args.slice(1));
+} 
+else if (command === 'help') {
+    const sub = args[1];
+    if (sub === 'lint') {
+        runScript(lintScript, ['--help']);
+    } else if (sub === 'snapshot') {
+        runScript(snapshotScript, ['--help']);
+    } else if (sub === 'init' || sub === 'create' || sub === 'scaffold') {
+        runScript(initScript, ['--help']);
+    } else if (sub === 'export') {
+        runScript(exportScript, ['--help']);
+    } else if (sub === 'render') {
+        runScript(renderScript, ['--help']);
+    } else {
+        printRootHelp();
+    }
+} 
+else if (command === '-h' || command === '--help' || !command) {
+    printRootHelp();
+} 
+else {
+    // Fallback: Default to rendering if a file path or flag is passed directly
+    // Usage: npx retiam src/main.ts
+    runScript(renderScript, args);
+}