screenci 0.0.10 → 0.0.11

package/dist/cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env -S npx tsx
+#!/usr/bin/env node
 import { spawn, spawnSync } from 'child_process';
 import { createReadStream } from 'fs';
 import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, } from 'fs';
@@ -6,14 +6,99 @@ import { createHash } from 'crypto';
 import { createServer } from 'http';
 import { mkdir, readdir, readFile, stat, writeFile } from 'fs/promises';
 import { dirname, relative as pathRelative, resolve } from 'path';
-import { createInterface } from 'readline/promises';
 import { fileURLToPath } from 'url';
+import { Command, CommanderError } from 'commander';
+import { input, confirm } from '@inquirer/prompts';
+import ora from 'ora';
+import pc from 'picocolors';
 import { logger } from './src/logger.js';
-function writeInline(msg) {
-    process.stdout.write(msg);
+function resolveRecordingFileCandidates(filePath, configDir) {
+    return [
+        filePath,
+        resolve(configDir, 'videos', filePath),
+        resolve(configDir, pathRelative('/app', filePath)),
+    ];
 }
-function completeInline(msg) {
-    process.stdout.write(`\r\x1b[K${msg}\n`);
+async function readRecordingFile(filePath, configDir) {
+    for (const candidate of resolveRecordingFileCandidates(filePath, configDir)) {
+        try {
+            return { buffer: await readFile(candidate), resolvedPath: candidate };
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return null;
+}
+function contentTypeForPath(filePath) {
+    const ext = filePath.split('.').pop()?.toLowerCase() ?? 'bin';
+    const contentTypeMap = {
+        png: 'image/png',
+        jpg: 'image/jpeg',
+        jpeg: 'image/jpeg',
+        gif: 'image/gif',
+        webp: 'image/webp',
+        mp4: 'video/mp4',
+        webm: 'video/webm',
+        mp3: 'audio/mpeg',
+        svg: 'image/svg+xml',
+    };
+    return contentTypeMap[ext] ?? 'application/octet-stream';
+}
+class UploadCancelledError extends Error {
+    constructor(message = 'Upload cancelled') {
+        super(message);
+        this.name = 'UploadCancelledError';
+    }
+}
+function isUploadCancelledError(err) {
+    return (err instanceof UploadCancelledError ||
+        (err instanceof Error &&
+            (err.name === 'AbortError' || err.name === 'UploadCancelledError')));
+}
+function createUploadAbortController(activityLabel) {
+    const controller = new AbortController();
+    let cleanedUp = false;
+    const cleanup = () => {
+        if (cleanedUp)
+            return;
+        cleanedUp = true;
+        process.off('SIGINT', handleSigint);
+        process.off('SIGTERM', handleSigterm);
+        process.stdin.off('data', handleStdinData);
+    };
+    const abortUpload = (signal) => {
+        if (controller.signal.aborted)
+            return;
+        logger.info(`Received ${signal}, stopping ${activityLabel}...`);
+        cleanup();
+        controller.abort(new UploadCancelledError(`${activityLabel} cancelled`));
+        process.kill(process.pid, signal);
+    };
+    const handleStdinData = (chunk) => {
+        const bytes = typeof chunk === 'string'
+            ? Buffer.from(chunk, 'utf8')
+            : Buffer.from(chunk);
+        if (bytes.includes(0x03)) {
+            abortUpload('SIGINT');
+        }
+    };
+    const handleSigint = () => abortUpload('SIGINT');
+    const handleSigterm = () => abortUpload('SIGTERM');
+    process.on('SIGINT', handleSigint);
+    process.on('SIGTERM', handleSigterm);
+    process.stdin.on('data', handleStdinData);
+    return {
+        signal: controller.signal,
+        throwIfAborted: () => {
+            if (controller.signal.aborted) {
+                throw controller.signal.reason instanceof Error
+                    ? controller.signal.reason
+                    : new UploadCancelledError(`${activityLabel} cancelled`);
+            }
+        },
+        cleanup,
+    };
 }
 function parseDockerfileVersion(dockerfilePath) {
     let content;
@@ -31,20 +116,183 @@ function parseDockerfileVersion(dockerfilePath) {
     const match = fromLine.match(/:([^\s@]+)/);
     return match?.[1] ?? 'unknown';
 }
-function spawnSilent(cmd, args) {
+const CONTAINER_RUNTIME_DOCS_URL = 'https://screenci.com/guides/getting-started/#prerequisites';
+function prerequisitesMessage() {
+    return `See prerequisites: ${pc.blue(CONTAINER_RUNTIME_DOCS_URL)}`;
+}
+const MIN_CONTAINER_RUNTIME_MAJOR_VERSION = {
+    podman: 5,
+    docker: 28,
+};
+function parseContainerRuntimeMajorVersion(versionOutput) {
+    const match = versionOutput.match(/(\d+)(?:\.\d+){0,2}/);
+    if (!match)
+        return null;
+    const majorVersion = Number.parseInt(match[1] ?? '', 10);
+    return Number.isNaN(majorVersion) ? null : majorVersion;
+}
+function checkContainerRuntime(runtime) {
+    const result = spawnSync(runtime, ['--version'], { encoding: 'utf8' });
+    if (result.status !== 0 || result.error !== undefined) {
+        return null;
+    }
+    const version = `${result.stdout ?? ''}${result.stderr ?? ''}`.trim();
+    return {
+        runtime,
+        version,
+        majorVersion: parseContainerRuntimeMajorVersion(version),
+    };
+}
+function getPreferredContainerRuntime() {
+    const podman = checkContainerRuntime('podman');
+    if (podman)
+        return podman;
+    return checkContainerRuntime('docker');
+}
+function exitContainerRuntimeNotFound(runtime) {
+    logger.error(`Error: ${runtime} not found.`);
+    logger.error(`Install ${runtime} or remove the --${runtime} flag.`);
+    logger.error(prerequisitesMessage());
+    process.exit(1);
+}
+function warnIfContainerRuntimeVersionIsOld(runtimeCheck) {
+    const minimumVersion = MIN_CONTAINER_RUNTIME_MAJOR_VERSION[runtimeCheck.runtime];
+    if (runtimeCheck.majorVersion !== null &&
+        runtimeCheck.majorVersion < minimumVersion) {
+        logger.warn(`${runtimeCheck.runtime} ${minimumVersion}+ recommended (detected: ${runtimeCheck.version}). Most likely this still works, continuing.`);
+        logger.warn(prerequisitesMessage());
+    }
+}
+function spawnSilent(cmd, args, cwd) {
     return new Promise((resolve, reject) => {
-        const child = spawn(cmd, args, { stdio: 'pipe' });
-        child.on('close', (code) => {
-            if (code === 0) {
+        const child = spawn(cmd, args, { stdio: 'pipe', ...(cwd ? { cwd } : {}) });
+        const childSignals = forwardChildSignals(child, cmd);
+        child.on('close', (code, signal) => {
+            const forwardedSignal = childSignals.getForwardedSignal();
+            childSignals.cleanup();
+            if (forwardedSignal) {
+                process.kill(process.pid, forwardedSignal);
+                return;
+            }
+            if (signal) {
+                process.kill(process.pid, signal);
+                return;
+            }
+            else if (code === 0) {
                 resolve();
             }
             else {
                 reject(new Error(`${cmd} exited with code ${code}`));
             }
         });
-        child.on('error', reject);
+        child.on('error', (err) => {
+            childSignals.cleanup();
+            reject(err);
+        });
+    });
+}
+function spawnCaptured(cmd, args, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, { stdio: 'pipe', ...(cwd ? { cwd } : {}) });
+        const childSignals = forwardChildSignals(child, cmd);
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on('close', (code, signal) => {
+            const forwardedSignal = childSignals.getForwardedSignal();
+            childSignals.cleanup();
+            if (forwardedSignal) {
+                process.kill(process.pid, forwardedSignal);
+                return;
+            }
+            if (signal) {
+                process.kill(process.pid, signal);
+                return;
+            }
+            resolve({ code, stdout, stderr });
+        });
+        child.on('error', (err) => {
+            childSignals.cleanup();
+            reject(err);
+        });
     });
 }
+function forwardChildSignals(child, activityLabel) {
+    let forwardedSignal = null;
+    let forceKillTimer = null;
+    const forwardSignal = (signal) => {
+        if (forwardedSignal !== null)
+            return;
+        forwardedSignal = signal;
+        if (process.env.SCREENCI_SIGNAL_LOGGING !== 'silent') {
+            logger.info(`Received ${signal}, stopping ${activityLabel}...`);
+        }
+        if (!child.killed) {
+            child.kill(signal);
+        }
+        forceKillTimer = setTimeout(() => {
+            if (child.exitCode === null) {
+                if (process.env.SCREENCI_SIGNAL_LOGGING !== 'silent') {
+                    logger.info(`Forcing ${activityLabel} to stop after timeout...`);
+                }
+                child.kill('SIGKILL');
+            }
+        }, 3000);
+        forceKillTimer.unref();
+    };
+    const handleSigint = () => forwardSignal('SIGINT');
+    const handleSigterm = () => forwardSignal('SIGTERM');
+    process.on('SIGINT', handleSigint);
+    process.on('SIGTERM', handleSigterm);
+    return {
+        cleanup: () => {
+            if (forceKillTimer !== null) {
+                clearTimeout(forceKillTimer);
+            }
+            process.off('SIGINT', handleSigint);
+            process.off('SIGTERM', handleSigterm);
+        },
+        getForwardedSignal: () => forwardedSignal,
+    };
+}
+async function getPlaywrightChromiumInstallStatus(projectDir, verbose = false) {
+    try {
+        if (verbose) {
+            logger.info('Checking Playwright Chromium install with: npx playwright install --list');
+        }
+        const list = await spawnCaptured('npx', ['playwright', 'install', '--list'], projectDir);
+        if (verbose) {
+            if (list.stdout.trim() !== '')
+                logger.info(list.stdout.trimEnd());
+            if (list.stderr.trim() !== '')
+                logger.info(list.stderr.trimEnd());
+            logger.info(`Check result: exit code ${list.code ?? 'null'}`);
+        }
+        const output = `${list.stdout}\n${list.stderr}`;
+        const versionMatch = output.match(/\bchromium-(\d+)\b/i);
+        if (list.code === 0 && versionMatch) {
+            if (verbose) {
+                logger.info(`Chromium check result: Chromium found in Playwright install list (version ${versionMatch[1]})`);
+            }
+            return { needed: false, version: versionMatch[1] ?? null };
+        }
+        if (verbose) {
+            logger.info('Chromium check result: Chromium not found in Playwright install list');
+        }
+    }
+    catch {
+        // If the probe fails, default to asking.
+    }
+    if (verbose) {
+        logger.info('Chromium check result: unable to verify, install still recommended');
+    }
+    return { needed: true, version: null };
+}
 const CONTAINER_LOG_FILTER = [
     /^Running ScreenCI /,
     /^Using config:/,
@@ -60,6 +308,7 @@ const CONTAINER_LOG_FILTER = [
 function spawnContainerRecording(cmd, args) {
     return new Promise((resolve, reject) => {
         const child = spawn(cmd, args, { stdio: ['inherit', 'pipe', 'pipe'] });
+        const childSignals = forwardChildSignals(child, 'screenci record');
         function forwardFiltered(chunk, out) {
             const lines = chunk.toString().split('\n');
             for (const line of lines) {
@@ -72,15 +321,28 @@ function spawnContainerRecording(cmd, args) {
         }
         child.stdout?.on('data', (chunk) => forwardFiltered(chunk, process.stdout));
         child.stderr?.on('data', (chunk) => forwardFiltered(chunk, process.stderr));
-        child.on('close', (code) => {
-            if (code === 0) {
+        child.on('close', (code, signal) => {
+            const forwardedSignal = childSignals.getForwardedSignal();
+            childSignals.cleanup();
+            if (forwardedSignal) {
+                process.kill(process.pid, forwardedSignal);
+                return;
+            }
+            if (signal) {
+                process.kill(process.pid, signal);
+                return;
+            }
+            else if (code === 0) {
                 resolve();
             }
             else {
                 reject(new Error(`${cmd} exited with code ${code}`));
             }
         });
-        child.on('error', reject);
+        child.on('error', (err) => {
+            childSignals.cleanup();
+            reject(err);
+        });
     });
 }
 function clearDirectory(dir) {
@@ -119,54 +381,6 @@ function findRepoRoot(startDir) {
         current = parent;
     }
 }
-function parseArgs(args) {
-    const command = args[0];
-    if (command === undefined) {
-        logger.error('Error: No command provided');
-        logger.error('Available commands: record, dev, upload-latest, init');
-        process.exit(1);
-    }
-    let configPath;
-    let noContainer = false;
-    let imageTag;
-    let verbose = false;
-    const otherArgs = [];
-    for (let i = 1; i < args.length; i++) {
-        const arg = args[i];
-        if (arg === '--config' || arg === '-c') {
-            const nextArg = args[i + 1];
-            if (nextArg !== undefined) {
-                configPath = nextArg;
-                i++; // skip next arg
-            }
-            else {
-                logger.error('Error: --config requires a path argument');
-                process.exit(1);
-            }
-        }
-        else if (arg === '--no-container') {
-            noContainer = true;
-        }
-        else if (arg === '--verbose' || arg === '-v') {
-            verbose = true;
-        }
-        else if (arg === '--tag') {
-            const nextArg = args[i + 1];
-            if (nextArg !== undefined) {
-                imageTag = nextArg;
-                i++; // skip next arg
-            }
-            else {
-                logger.error('Error: --tag requires a tag argument');
-                process.exit(1);
-            }
-        }
-        else if (arg !== undefined) {
-            otherArgs.push(arg);
-        }
-    }
-    return { command, configPath, noContainer, imageTag, verbose, otherArgs };
-}
 async function findLatestEntry(screenciDir) {
     let entries;
     try {
@@ -192,58 +406,260 @@ async function findLatestEntry(screenciDir) {
     }
     return latestEntry;
 }
-async function uploadAssets(data, apiUrl, secret, recordingId, configDir) {
-    const assetEvents = data.events.filter((e) => e.type === 'assetStart');
-    if (assetEvents.length === 0)
-        return;
-    // Deduplicate by name — each unique asset name is uploaded once
-    const seenNames = new Set();
-    for (const event of assetEvents) {
-        const assetPath = event.path;
-        if (seenNames.has(event.name))
-            continue;
-        seenNames.add(event.name);
-        // Resolve the asset file. Recording runs in a Docker container where configDir → /app,
-        // so stored paths may be container-internal absolute or relative paths.
-        // Resolution order:
-        //   1. Path as-is (works for absolute host paths)
-        //   2. Relative path resolved from configDir/videos (the video scripts directory)
-        //   3. Container path translated: /some/path → configDir/../some/path
-        const candidates = [
-            assetPath,
-            resolve(configDir, 'videos', assetPath),
-            resolve(configDir, pathRelative('/app', assetPath)),
-        ];
-        let fileBuffer;
-        let resolvedPath = assetPath;
-        for (const candidate of candidates) {
-            try {
-                fileBuffer = await readFile(candidate);
-                resolvedPath = candidate;
-                break;
+async function hashFile(filePath) {
+    return new Promise((resolveHash, reject) => {
+        const hash = createHash('sha256');
+        const stream = createReadStream(filePath);
+        stream.on('data', (chunk) => hash.update(chunk));
+        stream.on('error', reject);
+        stream.on('end', () => resolveHash(hash.digest('hex')));
+    });
+}
+async function prepareCustomVoiceAssets(data, configDir) {
+    const customVoiceRefsByPath = new Map();
+    for (const event of data.events) {
+        if (event.type === 'captionStart' && event.translations) {
+            for (const translation of Object.values(event.translations)) {
+                if (typeof translation.voice === 'object' &&
+                    translation.voice !== null &&
+                    'assetPath' in translation.voice &&
+                    typeof translation.voice.assetPath === 'string') {
+                    const voiceRef = translation.voice;
+                    const refs = customVoiceRefsByPath.get(voiceRef.assetPath) ?? [];
+                    refs.push(voiceRef);
+                    customVoiceRefsByPath.set(voiceRef.assetPath, refs);
+                }
             }
-            catch {
-                // try next
+        }
+        if (event.type === 'videoCaptionStart' && event.translations) {
+            for (const translation of Object.values(event.translations)) {
+                if ('text' in translation &&
+                    typeof translation.voice === 'object' &&
+                    translation.voice !== null &&
+                    'assetPath' in translation.voice &&
+                    typeof translation.voice.assetPath === 'string') {
+                    const voiceRef = translation.voice;
+                    const refs = customVoiceRefsByPath.get(voiceRef.assetPath) ?? [];
+                    refs.push(voiceRef);
+                    customVoiceRefsByPath.set(voiceRef.assetPath, refs);
+                }
             }
         }
-        if (fileBuffer === undefined) {
-            logger.warn(`Asset file not found, skipping upload: ${assetPath}`);
+    }
+    const preparedAssets = [];
+    for (const [voicePath, refs] of customVoiceRefsByPath) {
+        const resolvedFile = await readRecordingFile(voicePath, configDir);
+        if (resolvedFile === null) {
+            const existingHash = refs.find((ref) => typeof ref.assetHash === 'string')?.assetHash;
+            if (!existingHash) {
+                throw new Error(`Custom voice file not found and no cached assetHash available: ${voicePath}`);
+            }
+            logger.warn(`Custom voice file not found locally, assuming previously uploaded recording asset is valid: ${voicePath}`);
+            for (const ref of refs) {
+                ref.assetHash = existingHash;
+            }
+            preparedAssets.push({
+                fileHash: existingHash,
+                path: voicePath,
+                size: 0,
+                contentType: contentTypeForPath(voicePath),
+            });
+            continue;
+        }
+        const { buffer: fileBuffer, resolvedPath } = resolvedFile;
+        const assetHash = createHash('sha256').update(fileBuffer).digest('hex');
+        const contentType = contentTypeForPath(resolvedPath);
+        for (const ref of refs) {
+            ref.assetHash = assetHash;
+        }
+        preparedAssets.push({
+            fileHash: assetHash,
+            path: voicePath,
+            size: fileBuffer.byteLength,
+            fileBuffer,
+            contentType,
+        });
+    }
+    return preparedAssets;
+}
+async function collectUploadAssets(data, configDir) {
+    const assets = new Map();
+    for (const event of data.events) {
+        if (event.type === 'assetStart') {
+            if (assets.has(`name:${event.name}`))
+                continue;
+            const resolvedFile = await readRecordingFile(event.path, configDir);
+            if (resolvedFile === null) {
+                logger.warn(`Asset file not found, skipping upload: ${event.path}`);
+                continue;
+            }
+            const { buffer: fileBuffer, resolvedPath } = resolvedFile;
+            assets.set(`name:${event.name}`, {
+                fileHash: createHash('sha256').update(fileBuffer).digest('hex'),
+                path: event.path,
+                name: event.name,
+                size: fileBuffer.byteLength,
+                fileBuffer,
+                contentType: contentTypeForPath(resolvedPath),
+            });
             continue;
         }
-        const sha256 = createHash('sha256').update(fileBuffer).digest('hex');
-        const ext = assetPath.split('.').pop()?.toLowerCase() ?? 'bin';
-        const contentTypeMap = {
-            png: 'image/png',
-            jpg: 'image/jpeg',
-            jpeg: 'image/jpeg',
-            gif: 'image/gif',
-            webp: 'image/webp',
-            mp4: 'video/mp4',
-            webm: 'video/webm',
-            svg: 'image/svg+xml',
-        };
-        const contentType = contentTypeMap[ext] ?? 'application/octet-stream';
+        if (event.type === 'videoCaptionStart') {
+            // Single-language: hash already computed during recording, use assetPath to read file
+            if (typeof event.assetHash === 'string' &&
+                !assets.has(`hash:${event.assetHash}`)) {
+                const resolvedFile = typeof event.assetPath === 'string'
+                    ? await readRecordingFile(event.assetPath, configDir)
+                    : null;
+                assets.set(`hash:${event.assetHash}`, {
+                    fileHash: event.assetHash,
+                    path: event.assetPath ?? event.assetHash,
+                    size: resolvedFile?.buffer.byteLength ?? 0,
+                    ...(resolvedFile !== null && {
+                        fileBuffer: resolvedFile.buffer,
+                        contentType: contentTypeForPath(resolvedFile.resolvedPath),
+                    }),
+                });
+            }
+            // Multi-language: each translation carries its own hash
+            if (event.translations) {
+                for (const translation of Object.values(event.translations)) {
+                    if (typeof translation === 'object' &&
+                        translation !== null &&
+                        'assetHash' in translation &&
+                        typeof translation.assetHash === 'string' &&
+                        !assets.has(`hash:${translation.assetHash}`)) {
+                        const resolvedFile = 'assetPath' in translation &&
+                            typeof translation.assetPath === 'string'
+                            ? await readRecordingFile(translation.assetPath, configDir)
+                            : null;
+                        assets.set(`hash:${translation.assetHash}`, {
+                            fileHash: translation.assetHash,
+                            path: translation.assetPath ??
+                                translation.assetHash,
+                            size: resolvedFile?.buffer.byteLength ?? 0,
+                            ...(resolvedFile !== null && {
+                                fileBuffer: resolvedFile.buffer,
+                                contentType: contentTypeForPath(resolvedFile.resolvedPath),
+                            }),
+                        });
+                    }
+                }
+            }
+        }
+    }
+    for (const asset of await prepareCustomVoiceAssets(data, configDir)) {
+        assets.set(`path:${asset.path}`, asset);
+    }
+    return [...assets.values()];
+}
+export function stripVoicePath(voice) {
+    if (typeof voice !== 'string') {
+        return { assetHash: voice.assetHash };
+    }
+    return voice;
+}
+export function annotateRecordingDataWithAssetHashes(data, assets) {
+    const byName = new Map();
+    for (const asset of assets) {
+        if (typeof asset.name === 'string')
+            byName.set(asset.name, asset.fileHash);
+    }
+    return {
+        ...data,
+        events: data.events.map((event) => {
+            if (event.type === 'assetStart') {
+                const fileHash = byName.get(event.name);
+                return fileHash ? { ...event, fileHash } : event;
+            }
+            if (event.type === 'captionStart' && event.translations) {
+                const translations = Object.fromEntries(Object.entries(event.translations).map(([language, translation]) => {
+                    if (translation.voice === undefined) {
+                        return [language, translation];
+                    }
+                    return [
+                        language,
+                        {
+                            ...translation,
+                            voice: stripVoicePath(translation.voice),
+                        },
+                    ];
+                }));
+                return { ...event, translations };
+            }
+            if (event.type !== 'videoCaptionStart')
+                return event;
+            // Strip assetPath from translations — hash was already computed during recording
+            if (event.translations) {
+                const translations = Object.fromEntries(Object.entries(event.translations).map(([language, translation]) => {
+                    if ('assetHash' in translation) {
+                        const { assetPath: _removed, ...rest } = translation;
+                        return [language, rest];
+                    }
+                    if ('voice' in translation) {
+                        return [
+                            language,
+                            {
+                                ...translation,
+                                ...(translation.voice !== undefined
+                                    ? { voice: stripVoicePath(translation.voice) }
+                                    : {}),
+                            },
+                        ];
+                    }
+                    return [language, translation];
+                }));
+                return { ...event, translations };
+            }
+            // Single-language: strip assetPath, keep assetHash
+            if (typeof event.assetHash === 'string') {
+                const { assetPath: _removed, ...rest } = event;
+                return rest;
+            }
+            return event;
+        }),
+    };
+}
+function hint401(status, secret) {
+    if (status !== 401 || !secret)
+        return '';
+    const frontendUrl = getDevFrontendUrl();
+    return `\nThe secret may have been deleted or belongs to a different organisation. Check your secrets at ${frontendUrl}/secrets`;
+}
+async function uploadAssets(assets, apiUrl, secret, recordingId, signal, throwIfAborted) {
+    for (const asset of assets) {
+        throwIfAborted();
         try {
+            const checkRes = await fetch(`${apiUrl}/cli/upload/${recordingId}/asset/check`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-ScreenCI-Secret': secret,
+                },
+                body: JSON.stringify({
+                    fileHash: asset.fileHash,
+                    contentType: asset.contentType,
+                    size: asset.size,
+                    path: asset.path,
+                    ...(typeof asset.name === 'string' ? { name: asset.name } : {}),
+                }),
+                signal,
+            });
+            if (!checkRes.ok) {
+                const text = await checkRes.text();
+                logger.warn(`Failed to check asset ${asset.path}: ${checkRes.status} ${text}${hint401(checkRes.status, secret)}`);
+                continue;
+            }
+            const checkBody = (await checkRes.json());
+            if (checkBody.exists) {
+                logger.info(`Asset already exists: ${asset.path}`);
+                continue;
+            }
+            if (!asset.fileBuffer || !asset.contentType) {
+                logger.warn(`Asset bytes not available for upload and backend does not have it yet: ${asset.path}`);
+                continue;
+            }
+            throwIfAborted();
             const res = await fetch(`${apiUrl}/cli/upload/${recordingId}/asset`, {
                 method: 'PUT',
                 headers: {
@@ -251,26 +667,38 @@ async function uploadAssets(data, apiUrl, secret, recordingId, configDir) {
                     'X-ScreenCI-Secret': secret,
                 },
                 body: JSON.stringify({
-                    sha256,
-                    fileBase64: fileBuffer.toString('base64'),
-                    contentType,
-                    assetName: event.name,
+                    fileHash: asset.fileHash,
+                    fileBase64: asset.fileBuffer.toString('base64'),
+                    contentType: asset.contentType,
+                    size: asset.size,
+                    path: asset.path,
+                    ...(typeof asset.name === 'string' ? { name: asset.name } : {}),
                 }),
+                signal,
             });
             if (!res.ok) {
                 const text = await res.text();
-                logger.warn(`Failed to upload asset ${assetPath}: ${res.status} ${text}`);
+                if (res.status === 409 && text.includes('already exists')) {
+                    logger.info(`Asset already exists: ${asset.path}`);
+                }
+                else {
+                    logger.warn(`Failed to upload asset ${asset.path}: ${res.status} ${text}${hint401(res.status, secret)}`);
+                }
             }
             else {
-                logger.info(`Asset uploaded: ${assetPath}`);
+                logger.info(`Asset uploaded: ${asset.path}`);
             }
         }
         catch (err) {
-            logger.warn(`Network error uploading asset ${assetPath}:`, err);
+            if (isUploadCancelledError(err)) {
+                throw err;
+            }
+            logger.warn(`Network error uploading asset ${asset.path}:`, err);
         }
     }
 }
 async function uploadRecordings(screenciDir, projectName, apiUrl, secret, specificEntry) {
+    const uploadAbort = createUploadAbortController('upload');
     let entries;
     try {
         entries = await readdir(screenciDir);
@@ -283,76 +711,165 @@ async function uploadRecordings(screenciDir, projectName, apiUrl, secret, specif
         entries = entries.filter((e) => e === specificEntry);
     }
     let firstProjectId = null;
-    for (const entry of entries) {
-        const dataJsonPath = resolve(screenciDir, entry, 'data.json');
-        if (!existsSync(dataJsonPath))
-            continue;
-        let data;
-        try {
-            const raw = await readFile(dataJsonPath, 'utf-8');
-            data = JSON.parse(raw);
-        }
-        catch {
-            logger.warn(`Failed to read ${dataJsonPath}, skipping`);
-            continue;
-        }
-        const videoName = data.metadata?.videoName ?? entry;
-        writeInline(`Uploading "${videoName}"...`);
-        try {
-            // Step 1: register upload and get recordingId
-            const startResponse = await fetch(`${apiUrl}/cli/upload/start`, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    'X-ScreenCI-Secret': secret,
-                },
-                body: JSON.stringify({ projectName, videoName, data }),
-            });
-            if (!startResponse.ok) {
-                const text = await startResponse.text();
-                process.stdout.write('\n');
-                logger.warn(`Failed to start upload for "${videoName}": ${startResponse.status} ${text}`);
+    try {
+        for (const entry of entries) {
+            uploadAbort.throwIfAborted();
+            const dataJsonPath = resolve(screenciDir, entry, 'data.json');
+            if (!existsSync(dataJsonPath))
                 continue;
+            let data;
+            try {
+                const raw = await readFile(dataJsonPath, 'utf-8');
+                data = JSON.parse(raw);
             }
-            const { recordingId, projectId } = (await startResponse.json());
-            if (firstProjectId === null) {
-                firstProjectId = projectId;
-            }
-            // Step 1b: upload asset files referenced in data.json
-            await uploadAssets(data, apiUrl, secret, recordingId, resolve(screenciDir, '..'));
-            // Step 2: stream the recording video file (if it exists)
-            const recordingPath = resolve(screenciDir, entry, 'recording.mp4');
-            if (existsSync(recordingPath)) {
-                const fileStat = await stat(recordingPath);
-                const stream = createReadStream(recordingPath);
-                const recordingResponse = await fetch(`${apiUrl}/cli/upload/${recordingId}/recording`, {
-                    method: 'PUT',
+            catch {
+                logger.warn(`Failed to read ${dataJsonPath}, skipping`);
+                continue;
+            }
+            const videoName = data.metadata?.videoName ?? entry;
+            const preparedUploadAssets = await collectUploadAssets(data, resolve(screenciDir, '..'));
+            data = annotateRecordingDataWithAssetHashes(data, preparedUploadAssets);
+            const uploadSpinner = ora(`Uploading "${videoName}"`).start();
+            try {
+                uploadAbort.throwIfAborted();
+                const recordingPath = resolve(screenciDir, entry, 'recording.mp4');
+                const recordingHash = existsSync(recordingPath)
+                    ? await hashFile(recordingPath)
+                    : undefined;
+                // Step 1: register upload and get recordingId
+                const startResponse = await fetch(`${apiUrl}/cli/upload/start`, {
+                    method: 'POST',
                     headers: {
-                        'Content-Type': 'video/mp4',
-                        'Content-Length': String(fileStat.size),
+                        'Content-Type': 'application/json',
                         'X-ScreenCI-Secret': secret,
                     },
-                    body: stream,
-                    // @ts-expect-error Node.js fetch supports duplex for streaming
-                    duplex: 'half',
+                    body: JSON.stringify({
+                        projectName,
+                        videoName,
+                        data,
+                        ...(recordingHash !== undefined ? { recordingHash } : {}),
+                        expectedAssets: preparedUploadAssets.map((asset) => ({
+                            fileHash: asset.fileHash,
+                            size: asset.size,
+                            path: asset.path,
+                            ...(typeof asset.contentType === 'string'
+                                ? { contentType: asset.contentType }
+                                : {}),
+                            ...(typeof asset.name === 'string' ? { name: asset.name } : {}),
+                        })),
+                    }),
+                    signal: uploadAbort.signal,
                 });
-                if (!recordingResponse.ok) {
-                    const text = await recordingResponse.text();
-                    process.stdout.write('\n');
-                    logger.warn(`Failed to upload recording for "${videoName}": ${recordingResponse.status} ${text}`);
+                if (!startResponse.ok) {
+                    const text = await startResponse.text();
+                    uploadSpinner.fail(`Failed to upload "${videoName}"`);
+                    logger.warn(`Failed to start upload for "${videoName}": ${startResponse.status} ${text}${hint401(startResponse.status, secret)}`);
                     continue;
                 }
+                const { recordingId, projectId } = (await startResponse.json());
+                if (firstProjectId === null) {
+                    firstProjectId = projectId;
+                }
+                // Step 1b: upload all referenced files via the shared asset flow
+                await uploadAssets(preparedUploadAssets, apiUrl, secret, recordingId, uploadAbort.signal, uploadAbort.throwIfAborted);
+                // Step 2: stream the recording video file (if it exists)
+                if (existsSync(recordingPath)) {
+                    uploadAbort.throwIfAborted();
+                    const fileStat = await stat(recordingPath);
+                    const stream = createReadStream(recordingPath);
+                    const abortStream = () => {
+                        stream.destroy(new UploadCancelledError(`Upload cancelled for "${videoName}"`));
+                    };
+                    uploadAbort.signal.addEventListener('abort', abortStream, {
+                        once: true,
+                    });
+                    try {
+                        const recordingResponse = await fetch(`${apiUrl}/cli/upload/${recordingId}/recording`, {
+                            method: 'PUT',
+                            headers: {
+                                'Content-Type': 'video/mp4',
+                                'Content-Length': String(fileStat.size),
+                                'X-ScreenCI-Secret': secret,
+                            },
+                            body: stream,
+                            signal: uploadAbort.signal,
+                            // @ts-expect-error Node.js fetch supports duplex for streaming
+                            duplex: 'half',
+                        });
+                        if (!recordingResponse.ok) {
+                            const text = await recordingResponse.text();
+                            uploadSpinner.fail(`Failed to upload "${videoName}"`);
+                            logger.warn(`Failed to upload recording for "${videoName}": ${recordingResponse.status} ${text}${hint401(recordingResponse.status, secret)}`);
+                            continue;
+                        }
+                    }
+                    finally {
+                        uploadAbort.signal.removeEventListener('abort', abortStream);
+                    }
+                }
+                uploadSpinner.succeed(`Uploaded "${videoName}"`);
+            }
+            catch (err) {
+                if (isUploadCancelledError(err)) {
+                    uploadSpinner.fail(`Cancelled "${videoName}"`);
+                    throw err;
+                }
+                uploadSpinner.fail(`Error uploading "${videoName}"`);
+                logger.warn(`Network error uploading "${videoName}":`, err);
             }
-            completeInline(`Uploading "${videoName}" ✓`);
-        }
-        catch (err) {
-            process.stdout.write('\n');
-            logger.warn(`Network error uploading "${videoName}":`, err);
         }
+        return firstProjectId;
     }
-    return firstProjectId;
+    finally {
+        uploadAbort.cleanup();
+    }
+}
+export function getDevBackendUrl() {
+    const devBackendPort = process.env.DEV_BACKEND_PORT;
+    return devBackendPort
+        ? `http://localhost:${devBackendPort}`
+        : 'https://api.screenci.com';
+}
+export function getDevFrontendUrl() {
+    const devFrontendPort = process.env.DEV_FRONTEND_PORT;
+    return devFrontendPort
+        ? `http://localhost:${devFrontendPort}`
+        : 'https://app.screenci.com';
 }
 async function uploadLatest(configPath) {
+    const { resolvedConfigPath, screenciConfig } = await loadScreenCIConfigAndEnv(configPath);
+    const apiUrl = getDevBackendUrl();
+    const secret = process.env.SCREENCI_SECRET;
+    if (!secret) {
+        logger.error('No secret configured. Set SCREENCI_SECRET in your .env file (get it from the API Key page in the dashboard).');
+        process.exit(1);
+    }
+    const configDir = dirname(resolvedConfigPath);
+    const screenciDir = resolve(configDir, '.screenci');
+    const latestEntry = await findLatestEntry(screenciDir);
+    if (!latestEntry) {
+        logger.warn('No recordings found in .screenci directory');
+        return;
+    }
+    const appUrl = getDevFrontendUrl();
+    logger.info(`Uploading latest recording: "${latestEntry}"`);
+    let projectId = null;
+    try {
+        projectId = await uploadRecordings(screenciDir, screenciConfig.projectName, apiUrl, secret, latestEntry);
+    }
+    catch (err) {
+        if (isUploadCancelledError(err)) {
+            process.exit(130);
+        }
+        throw err;
+    }
+    if (projectId !== null) {
+        logger.info('');
+        logger.info('Recording finished, results available at:');
+        logger.info(pc.cyan(`${appUrl}/project/${projectId}`));
+    }
+}
+async function loadScreenCIConfigAndEnv(configPath) {
     const resolvedConfigPath = findScreenCIConfig(configPath);
     if (!resolvedConfigPath) {
         const errorMsg = configPath
@@ -379,33 +896,55 @@ async function uploadLatest(configPath) {
             logger.warn(`Failed to load env file ${envFilePath}:`, err);
         }
     }
-    const apiUrl = process.env.DEV_PORT
-        ? `http://localhost:${process.env.DEV_PORT}`
-        : 'https://api.screenci.com';
+    return { resolvedConfigPath, screenciConfig };
+}
+async function requireScreenCISecret(configPath) {
+    const { resolvedConfigPath, screenciConfig } = await loadScreenCIConfigAndEnv(configPath);
     const secret = process.env.SCREENCI_SECRET;
     if (!secret) {
         logger.error('No secret configured. Set SCREENCI_SECRET in your .env file (get it from the API Key page in the dashboard).');
         process.exit(1);
     }
-    const configDir = dirname(resolvedConfigPath);
-    const screenciDir = resolve(configDir, '.screenci');
-    const latestEntry = await findLatestEntry(screenciDir);
-    if (!latestEntry) {
-        logger.warn('No recordings found in .screenci directory');
-        return;
+    return {
+        resolvedConfigPath,
+        screenciConfig,
+        secret,
+        apiUrl: getDevBackendUrl(),
+    };
+}
+async function fetchProjectInfo(configPath) {
+    const { screenciConfig, secret, apiUrl } = await requireScreenCISecret(configPath);
+    const url = new URL(`${apiUrl}/cli/project-info`);
+    url.searchParams.set('projectName', screenciConfig.projectName);
+    const res = await fetch(url.toString(), {
+        headers: {
+            'X-ScreenCI-Secret': secret,
+        },
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Failed to fetch project info: ${res.status} ${text}${hint401(res.status, secret)}`);
     }
-    const appUrl = process.env.SCREENCI_APP_URL
-        ? process.env.SCREENCI_APP_URL
-        : process.env.DEV_PORT
-            ? `http://localhost:${process.env.DEV_PORT}`
-            : 'https://app.screenci.com';
-    logger.info(`Uploading latest recording: "${latestEntry}"`);
-    const projectId = await uploadRecordings(screenciDir, screenciConfig.projectName, apiUrl, secret, latestEntry);
-    if (projectId !== null) {
-        logger.info('');
-        logger.info('Recording finished, results available at:');
-        logger.info(`${appUrl}/project/${projectId}`);
+    return (await res.json());
+}
+async function printProjectInfo(configPath) {
+    const info = await fetchProjectInfo(configPath);
+    process.stdout.write(`${JSON.stringify(info, null, 2)}\n`);
+}
+async function updateVideoVisibility(videoId, isPublic, configPath) {
+    const { secret, apiUrl } = await requireScreenCISecret(configPath);
+    const method = isPublic ? 'PUT' : 'DELETE';
+    const res = await fetch(`${apiUrl}/cli/public-video/${videoId}`, {
+        method,
+        headers: {
+            'X-ScreenCI-Secret': secret,
+        },
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Failed to ${isPublic ? 'make public' : 'make private'}: ${res.status} ${text}${hint401(res.status, secret)}`);
     }
+    logger.info(`${isPublic ? 'Made public' : 'Made private'}: ${videoId}`);
 }
 function generateConfig(projectName) {
     return `import { defineConfig } from 'screenci'
@@ -433,11 +972,18 @@ export default defineConfig({
 })
 `;
 }
-function generatePackageJson(projectName, localPackagePath) {
+function generatePackageJson(projectName, localPackagePath, includePlaywrightCli = false) {
     const npmName = projectName.toLowerCase().replace(/[^a-z0-9-]/g, '-');
     const screenciVersion = localPackagePath
         ? `file:${localPackagePath}`
         : 'latest';
+    const devDependencies = {
+        '@types/node': '^25.0.0',
+        tsx: '^4.21.0',
+    };
+    if (includePlaywrightCli) {
+        devDependencies['@playwright/cli'] = 'latest';
+    }
     return (JSON.stringify({
         name: npmName,
         version: '1.0.0',
@@ -445,16 +991,13 @@ function generatePackageJson(projectName, localPackagePath) {
         type: 'module',
         scripts: {
             record: 'screenci record',
-            'upload-latest': 'screenci upload-latest',
+            retry: 'screenci retry',
             dev: 'screenci dev',
         },
         dependencies: {
             screenci: screenciVersion,
         },
-        devDependencies: {
-            '@types/node': '^25.0.0',
-            tsx: '^4.21.0',
-        },
+        devDependencies,
     }, null, 2) + '\n');
 }
 function generateDockerfile() {
@@ -549,7 +1092,7 @@ async function performBrowserLogin(appUrl) {
             const callbackUrl = `http://localhost:${port}/callback`;
             const loginUrl = `${appUrl}/cli-auth?callback=${encodeURIComponent(callbackUrl)}`;
             logger.info(`If the browser does not open automatically, visit:`);
-            logger.info(loginUrl);
+            logger.info(pc.cyan(loginUrl));
             logger.info('');
             openBrowser(loginUrl);
         });
@@ -569,34 +1112,14 @@ video('Example video', async ({ page }) => {
 })
 `;
 }
-async function promptLine(question) {
-    const rl = createInterface({
-        input: process.stdin,
-        output: process.stdout,
-    });
-    try {
-        const answer = await rl.question(question);
-        return answer.trim();
-    }
-    finally {
-        rl.close();
-    }
-}
 async function promptProjectName() {
-    return promptLine('Project name: ');
+    return input({ message: 'Project name:' });
 }
-function toKebabCase(name) {
-    return name
-        .toLowerCase()
-        .replace(/\s+/g, '-')
-        .replace(/[^a-z0-9-]/g, '-')
-        .replace(/-+/g, '-')
-        .replace(/^-|-$/g, '');
+function getProjectDirName(name) {
+    return name.toLowerCase().replace(/\s+/g, '-');
 }
 async function runInitAuth() {
-    const devPort = process.env.DEV_PORT;
-    const appUrl = process.env.SCREENCI_APP_URL ??
-        (devPort ? `http://localhost:${devPort}` : 'https://app.screenci.com');
+    const appUrl = getDevFrontendUrl();
     try {
         const secret = await performBrowserLogin(appUrl);
         const savePath = resolve(process.cwd(), '.env');
@@ -616,8 +1139,9 @@ function checkNodeVersion() {
         process.exit(1);
     }
 }
-async function runInit(projectNameArg, localPackagePath) {
+async function runInit(projectNameArg, localPackagePath, verbose = false) {
     checkNodeVersion();
+    checkContainerRuntimeForInit();
     let projectName = projectNameArg?.trim();
     if (!projectName) {
         projectName = await promptProjectName();
@@ -626,21 +1150,25 @@ async function runInit(projectNameArg, localPackagePath) {
         logger.error('Error: Project name is required');
         process.exit(1);
     }
-    const dirName = toKebabCase(projectName);
+    const dirName = getProjectDirName(projectName);
     const projectDir = resolve(process.cwd(), dirName);
     if (existsSync(projectDir)) {
         logger.error(`Error: Directory "${dirName}" already exists`);
         process.exit(1);
     }
+    const shouldAddPlaywrightCli = await confirm({
+        message: 'Do you want to write videos with an AI agent based on a URL? playwright-cli is recommended and will be added as a dev dependency.',
+        default: true,
+    });
     await mkdir(resolve(projectDir, 'videos'), { recursive: true });
     await mkdir(resolve(projectDir, '.github', 'workflows'), { recursive: true });
     await writeFile(resolve(projectDir, 'screenci.config.ts'), generateConfig(projectName));
-    await writeFile(resolve(projectDir, 'package.json'), generatePackageJson(dirName, localPackagePath));
+    await writeFile(resolve(projectDir, 'package.json'), generatePackageJson(dirName, localPackagePath, shouldAddPlaywrightCli));
     await writeFile(resolve(projectDir, 'Dockerfile'), generateDockerfile());
     await writeFile(resolve(projectDir, '.gitignore'), generateGitignore());
     await writeFile(resolve(projectDir, 'videos', 'example.video.ts'), generateExampleVideo());
     await writeFile(resolve(projectDir, '.github', 'workflows', 'record.yml'), generateGithubAction());
-    logger.info(`Initialized screenci project "${projectName}" in ${dirName}/`);
+    logger.info(`Initialized screenci project "${projectName}" in ${projectDir}/`);
     logger.info('Files created:');
     logger.info('  screenci.config.ts');
     logger.info('  package.json');
@@ -649,149 +1177,401 @@ async function runInit(projectNameArg, localPackagePath) {
     logger.info('  videos/example.video.ts');
     logger.info('  .github/workflows/record.yml');
     logger.info('');
-    logger.info('Running npm install...');
-    await spawnInherited('npm', ['install', '--prefix', projectDir]);
+    logger.info('screenci requires dependencies to be installed.');
+    const shouldInstallSkills = await confirm({
+        message: "Add ScreenCI skills now with 'npx --yes skills add screenci/screenci --skill screenci --skill playwright-cli -y'?",
+        default: true,
+    });
+    if (shouldInstallSkills) {
+        if (verbose) {
+            logger.info("Running 'npx --yes skills add screenci/screenci --skill screenci --skill playwright-cli -y'...");
+            await spawnInherited('npx', [
+                '--yes',
+                'skills',
+                'add',
+                'screenci/screenci',
+                '--skill',
+                'screenci',
+                '--skill',
+                'playwright-cli',
+                '-y',
+            ], projectDir, 'screenci init');
+        }
+        else {
+            const spinner = ora('Adding ScreenCI skills...').start();
+            try {
+                await spawnSilent('npx', [
+                    '--yes',
+                    'skills',
+                    'add',
+                    'screenci/screenci',
+                    '--skill',
+                    'screenci',
+                    '--skill',
+                    'playwright-cli',
+                    '-y',
+                ], projectDir);
+                spinner.succeed('ScreenCI skills added');
+            }
+            catch (err) {
+                spinner.fail('ScreenCI skills install failed');
+                throw err;
+            }
+        }
+    }
+    const shouldInstall = await confirm({
+        message: "Run 'npm install' now?",
+        default: true,
+    });
+    let chromiumReady = false;
+    if (shouldInstall) {
+        if (verbose) {
+            logger.info("Running 'npm install'...");
+            await spawnInherited('npm', ['install'], projectDir, 'screenci init');
+        }
+        else {
+            const spinner = ora('Running npm install...').start();
+            try {
+                await spawnSilent('npm', ['install', '--prefix', projectDir]);
+                spinner.succeed('npm install complete');
+            }
+            catch (err) {
+                spinner.fail('npm install failed');
+                throw err;
+            }
+        }
+        const chromiumInstallStatus = await getPlaywrightChromiumInstallStatus(projectDir, verbose);
+        if (!chromiumInstallStatus.needed) {
+            chromiumReady = true;
+            const versionText = chromiumInstallStatus.version
+                ? `, version ${chromiumInstallStatus.version} already installed.`
+                : ' because it is already installed.';
+            logger.info(`${pc.green('✔')} Skipping Chromium installation${versionText}`);
+        }
+        else {
+            logger.info('Local development requires Chromium for Playwright.');
+            const shouldInstallChromium = await confirm({
+                message: "Run 'npx playwright install chromium --with-deps' now?",
+                default: true,
+            });
+            if (shouldInstallChromium) {
+                logger.info("Running 'npx playwright install chromium --with-deps'...");
+                await spawnInherited('npx', ['playwright', 'install', 'chromium', '--with-deps'], projectDir, 'screenci init');
+                chromiumReady = true;
+            }
+        }
+    }
     logger.info('');
     logger.info('Next steps:');
     logger.info(`  cd ${dirName}`);
-    logger.info('  screenci record');
+    if (!shouldInstallSkills) {
+        logger.info('  npx --yes skills add screenci/screenci --skill screenci --skill playwright-cli -y');
+    }
+    if (!shouldInstall) {
+        logger.info('  npm install');
+    }
+    if (!shouldInstall || !chromiumReady) {
+        logger.info('  npx playwright install chromium --with-deps');
+    }
+    logger.info('  npx screenci record');
 }
 export async function main() {
-    const args = process.argv.slice(2);
-    const { command, configPath, noContainer, imageTag, verbose, otherArgs } = parseArgs(args);
-    switch (command) {
-        case 'record': {
-            const useContainer = !noContainer && process.env.SCREENCI_IN_CONTAINER !== 'true';
-            // Validate early so we don't build the container unnecessarily
-            if (useContainer) {
-                validateArgs(otherArgs);
-            }
-            // On the host, acquire secret before recording if missing
-            if (process.env.SCREENCI_IN_CONTAINER !== 'true') {
-                const resolvedConfigForSecret = findScreenCIConfig(configPath);
-                if (resolvedConfigForSecret) {
-                    let envFilePath = null;
-                    try {
-                        const configModule = await import(resolvedConfigForSecret);
-                        const screenciConfig = configModule.default;
-                        envFilePath = screenciConfig.envFile
-                            ? resolve(dirname(resolvedConfigForSecret), screenciConfig.envFile)
-                            : null;
-                        if (envFilePath) {
-                            try {
-                                process.loadEnvFile(envFilePath);
-                            }
-                            catch {
-                                // env file may not exist yet
-                            }
-                        }
-                    }
-                    catch (err) {
-                        if (!process.env.SCREENCI_SECRET) {
-                            const msg = err instanceof Error ? err.message : String(err);
-                            logger.error(`Failed to acquire secret: ${msg}`);
-                            process.exit(1);
-                        }
-                        // Config import failed but SCREENCI_SECRET is already in env — continue
-                    }
-                    if (!process.env.SCREENCI_SECRET) {
-                        logger.info('No SCREENCI_SECRET in .env file, opening browser for authentication...');
-                        const devPort = process.env.DEV_PORT;
-                        const appUrl = process.env.SCREENCI_APP_URL ??
-                            (devPort
-                                ? `http://localhost:${devPort}`
-                                : 'https://app.screenci.com');
-                        const secret = await performBrowserLogin(appUrl);
-                        const savePath = envFilePath ?? resolve(dirname(resolvedConfigForSecret), '.env');
-                        await writeFile(savePath, `SCREENCI_SECRET=${secret}\n`);
-                        process.env.SCREENCI_SECRET = secret;
-                        logger.info(`Successfully saved SCREENCI_SECRET to ${savePath}`);
-                    }
-                }
-            }
-            if (useContainer) {
-                await runWithContainer(otherArgs, configPath, imageTag, verbose);
-            }
-            else {
-                await run(command, otherArgs, configPath);
-            }
-            // Upload only from the host, not from inside the container
-            if (process.env.SCREENCI_IN_CONTAINER === 'true')
-                break;
-            // After recording, upload results to API if configured
-            const resolvedConfigPath = findScreenCIConfig(configPath);
-            if (resolvedConfigPath) {
+    if (process.argv.length <= 2) {
+        logger.error('Error: No command provided');
+        logger.error('Available commands: record, dev, test, info, make-public, make-private, retry, init');
+        process.exit(1);
+    }
+    const program = new Command();
+    program.name('screenci');
+    program.exitOverride();
+    // record command — playwright args pass through as-is
+    program
+        .command('record [playwrightArgs...]')
+        .description('Record videos using Playwright')
+        .allowUnknownOption(true)
+        .action(async () => {
+        const parsed = parseRecordCliArgs(getSubcommandArgv('record'));
+        if (parsed.forcedRuntime === 'both') {
+            logger.error('Error: --podman and --docker cannot be used together');
+            process.exit(1);
+        }
+        const useContainer = !parsed.noContainer && process.env.SCREENCI_IN_CONTAINER !== 'true';
+        // Validate early so we don't build the container unnecessarily
+        if (useContainer) {
+            validateArgs(parsed.otherArgs);
+        }
+        // On the host, acquire secret before recording if missing
+        if (process.env.SCREENCI_IN_CONTAINER !== 'true') {
+            const resolvedConfigForSecret = findScreenCIConfig(parsed.configPath);
+            if (resolvedConfigForSecret) {
+                let envFilePath = null;
                 try {
-                    const configModule = await import(resolvedConfigPath);
+                    const configModule = await import(resolvedConfigForSecret);
                     const screenciConfig = configModule.default;
-                    if (screenciConfig.envFile) {
-                        const envFilePath = resolve(dirname(resolvedConfigPath), screenciConfig.envFile);
+                    envFilePath = screenciConfig.envFile
+                        ? resolve(dirname(resolvedConfigForSecret), screenciConfig.envFile)
+                        : null;
+                    if (envFilePath) {
                         try {
                             process.loadEnvFile(envFilePath);
                         }
-                        catch (err) {
-                            logger.warn(`Failed to load env file ${envFilePath}:`, err);
+                        catch {
+                            // env file may not exist yet
                         }
                     }
-                    const apiUrl = process.env.DEV_PORT
-                        ? `http://localhost:${process.env.DEV_PORT}`
-                        : 'https://api.screenci.com';
-                    const appUrl = process.env.SCREENCI_APP_URL
-                        ? process.env.SCREENCI_APP_URL
-                        : process.env.DEV_PORT
-                            ? `http://localhost:${process.env.DEV_PORT}`
-                            : 'https://app.screenci.com';
-                    const secret = process.env.SCREENCI_SECRET;
-                    if (!secret) {
-                        logger.info('No secret configured, skipping upload. Set SCREENCI_SECRET in your .env file.');
-                        break;
+                }
+                catch (err) {
+                    if (!process.env.SCREENCI_SECRET) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        logger.error(`Failed to acquire secret: ${msg}`);
+                        process.exit(1);
+                    }
+                    // Config import failed but SCREENCI_SECRET is already in env — continue
+                }
+                if (!process.env.SCREENCI_SECRET) {
+                    logger.info('No SCREENCI_SECRET in .env file, opening browser for authentication...');
+                    const appUrl = getDevFrontendUrl();
+                    const secret = await performBrowserLogin(appUrl);
+                    const savePath = envFilePath ?? resolve(dirname(resolvedConfigForSecret), '.env');
+                    await writeFile(savePath, `SCREENCI_SECRET=${secret}\n`);
+                    process.env.SCREENCI_SECRET = secret;
+                    logger.info(`Successfully saved SCREENCI_SECRET to ${savePath}`);
+                }
+            }
+        }
+        if (useContainer) {
+            await runWithContainer(parsed.otherArgs, parsed.configPath, parsed.imageTag, parsed.verbose, parsed.forcedRuntime);
+        }
+        else {
+            await run('record', parsed.otherArgs, parsed.configPath);
+        }
+        // Upload only from the host, not from inside the container
+        if (process.env.SCREENCI_IN_CONTAINER === 'true')
+            return;
+        // After recording, upload results to API if configured
+        const resolvedConfigPath = findScreenCIConfig(parsed.configPath);
+        if (resolvedConfigPath) {
+            try {
+                const configModule = await import(resolvedConfigPath);
+                const screenciConfig = configModule.default;
+                if (screenciConfig.envFile) {
+                    const envFilePath = resolve(dirname(resolvedConfigPath), screenciConfig.envFile);
+                    try {
+                        process.loadEnvFile(envFilePath);
                     }
-                    const configDir = dirname(resolvedConfigPath);
-                    const screenciDir = resolve(configDir, '.screenci');
-                    const projectId = await uploadRecordings(screenciDir, screenciConfig.projectName, apiUrl, secret);
-                    if (projectId !== null) {
-                        logger.info('');
-                        logger.info('Recording finished, results available at:');
-                        logger.info(`${appUrl}/project/${projectId}`);
+                    catch (err) {
+                        logger.warn(`Failed to load env file ${envFilePath}:`, err);
                     }
                 }
+                const apiUrl = getDevBackendUrl();
+                const appUrl = getDevFrontendUrl();
+                const secret = process.env.SCREENCI_SECRET;
+                if (!secret) {
+                    logger.info('No secret configured, skipping upload. Set SCREENCI_SECRET in your .env file.');
+                    return;
+                }
+                const configDir = dirname(resolvedConfigPath);
+                const screenciDir = resolve(configDir, '.screenci');
+                let projectId = null;
+                try {
+                    projectId = await uploadRecordings(screenciDir, screenciConfig.projectName, apiUrl, secret);
+                }
                 catch (err) {
-                    logger.warn('Failed to load config for upload:', err);
+                    if (isUploadCancelledError(err)) {
+                        process.exit(130);
+                    }
+                    throw err;
                 }
+                if (projectId !== null) {
+                    logger.info('');
+                    logger.info('Recording finished, results available at:');
+                    logger.info(pc.cyan(`${appUrl}/project/${projectId}`));
+                }
+            }
+            catch (err) {
+                logger.warn('Failed to load config for upload:', err);
+            }
+        }
+    });
+    // dev command — playwright args pass through as-is
+    program
+        .command('dev [playwrightArgs...]')
+        .description('Run Playwright in dev/UI mode')
+        .allowUnknownOption(true)
+        .action(async () => {
+        const parsed = parseDevCliArgs(getSubcommandArgv('dev'));
+        await run('dev', parsed.otherArgs, parsed.configPath);
+    });
+    program
+        .command('test [playwrightArgs...]')
+        .description('Run Playwright test with screenci.config.ts')
+        .allowUnknownOption(true)
+        .action(async () => {
+        const parsed = parseDevCliArgs(getSubcommandArgv('test'));
+        await run('test', parsed.otherArgs, parsed.configPath);
+    });
+    program
+        .command('info')
+        .description('Print remote project info as JSON')
+        .option('-c, --config <path>', 'path to screenci.config.ts')
+        .action(async (options) => {
+        await printProjectInfo(options['config']);
+    });
+    program
+        .command('make-public <id>')
+        .description('Enable public URLs for a video; get the id from screenci info')
+        .option('-c, --config <path>', 'path to screenci.config.ts')
+        .action(async (id, options) => {
+        await updateVideoVisibility(id, true, options['config']);
+    });
+    program
+        .command('make-private <id>')
+        .description('Disable public URLs for a video; get the id from screenci info')
+        .option('-c, --config <path>', 'path to screenci.config.ts')
+        .action(async (id, options) => {
+        await updateVideoVisibility(id, false, options['config']);
+    });
+    // retry command
+    program
+        .command('retry')
+        .description('Retry the latest recording upload')
+        .option('-c, --config <path>', 'path to screenci.config.ts')
+        .action(async (options) => {
+        await uploadLatest(options['config']);
+    });
+    // init command
+    program
+        .command('init [name]')
+        .description('Initialize a new screenci project')
+        .option('--local', 'use local package path (for development)')
+        .option('-v, --verbose', 'verbose output')
+        .action(async (name, options) => {
+        if (name === 'auth') {
+            await runInitAuth();
+        }
+        else {
+            let localPackagePath;
+            if (options['local']) {
+                const cliDir = dirname(fileURLToPath(import.meta.url));
+                // cli.ts is at package root; dist/cli.js is one level down
+                localPackagePath = existsSync(resolve(cliDir, 'package.json'))
+                    ? cliDir
+                    : resolve(cliDir, '..');
             }
-            break;
+            await runInit(name, localPackagePath, options['verbose'] ?? false);
         }
-        case 'dev':
-            await run(command, otherArgs, configPath);
-            break;
-        case 'upload-latest':
-            await uploadLatest(configPath);
-            break;
-        case 'init': {
-            if (otherArgs[0] === 'auth') {
-                await runInitAuth();
+    });
+    try {
+        await program.parseAsync(process.argv);
+    }
+    catch (err) {
+        if (err instanceof CommanderError) {
+            if (err.code === 'commander.unknownCommand') {
+                const unknownCmd = process.argv[2] ?? '';
+                logger.error(`Unknown command: ${unknownCmd}`);
+                process.exit(1);
             }
-            else {
-                const localFlagIndex = otherArgs.indexOf('--local');
-                let localPackagePath;
-                let initArgs = otherArgs;
-                if (localFlagIndex !== -1) {
-                    const cliDir = dirname(fileURLToPath(import.meta.url));
-                    // cli.ts is at package root; dist/cli.js is one level down
-                    localPackagePath = existsSync(resolve(cliDir, 'package.json'))
-                        ? cliDir
-                        : resolve(cliDir, '..');
-                    initArgs = otherArgs.filter((_, i) => i !== localFlagIndex);
+            if (err.code === 'commander.optionMissingArgument') {
+                if (err.message.includes('--config') ||
+                    err.message.includes('-c, --config') ||
+                    err.message.includes("'-c'")) {
+                    logger.error('Error: --config requires a path argument');
+                    process.exit(1);
                 }
-                await runInit(initArgs[0], localPackagePath);
+                logger.error(`Error: ${err.message}`);
+                process.exit(1);
             }
-            break;
-        }
-        default:
-            logger.error(`Unknown command: ${command}`);
-            logger.error('Available commands: record, dev, upload-latest, init');
+            if (err.code === 'commander.help' ||
+                err.code === 'commander.helpDisplayed') {
+                return;
+            }
+            logger.error(`Error: ${err.message}`);
             process.exit(1);
+            return;
+        }
+        throw err;
+    }
+}
+function getSubcommandArgv(command) {
+    const argv = process.argv.slice(2);
+    const commandIndex = argv.indexOf(command);
+    return commandIndex === -1 ? [] : argv.slice(commandIndex + 1);
+}
+function parseRecordCliArgs(args) {
+    let configPath;
+    let noContainer = false;
+    let imageTag;
+    let verbose = false;
+    let forcedRuntime;
+    const otherArgs = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === undefined)
+            continue;
+        if (arg === '--config' || arg === '-c') {
+            const nextArg = args[i + 1];
+            if (nextArg === undefined) {
+                logger.error('Error: --config requires a path argument');
+                process.exit(1);
+            }
+            configPath = nextArg;
+            i++;
+        }
+        else if (arg === '--no-container') {
+            noContainer = true;
+        }
+        else if (arg === '--verbose' || arg === '-v') {
+            verbose = true;
+        }
+        else if (arg === '--podman') {
+            forcedRuntime = forcedRuntime === 'docker' ? 'both' : 'podman';
+        }
+        else if (arg === '--docker') {
+            forcedRuntime = forcedRuntime === 'podman' ? 'both' : 'docker';
+        }
+        else if (arg === '--tag') {
+            const nextArg = args[i + 1];
+            if (nextArg === undefined) {
+                logger.error('Error: --tag requires a tag argument');
+                process.exit(1);
+            }
+            imageTag = nextArg;
+            i++;
+        }
+        else {
+            otherArgs.push(arg);
+        }
+    }
+    return {
+        configPath,
+        noContainer,
+        imageTag,
+        verbose,
+        forcedRuntime,
+        otherArgs,
+    };
+}
+function parseDevCliArgs(args) {
+    let configPath;
+    const otherArgs = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === undefined)
+            continue;
+        if (arg === '--config' || arg === '-c') {
+            const nextArg = args[i + 1];
+            if (nextArg === undefined) {
+                logger.error('Error: --config requires a path argument');
+                process.exit(1);
+            }
+            configPath = nextArg;
+            i++;
+        }
+        else {
+            otherArgs.push(arg);
+        }
     }
+    return { configPath, otherArgs };
 }
 function validateArgs(args) {
     const disallowedFlags = ['--fully-parallel', '--workers', '-j', '--retries'];
@@ -812,28 +1592,22 @@ function validateArgs(args) {
         }
     }
 }
-function spawnInherited(cmd, args) {
-    const child = spawn(cmd, args, { stdio: 'inherit' });
-    const forwardSignal = (signal) => {
-        logger.info(`Received ${signal}, stopping...`);
-        if (!child.killed) {
-            child.kill(signal);
-        }
-        const forceKill = setTimeout(() => {
-            if (child.exitCode === null) {
-                logger.info('Forcing kill after timeout...');
-                child.kill('SIGKILL');
-            }
-        }, 3000);
-        forceKill.unref();
-    };
-    process.on('SIGINT', forwardSignal);
-    process.on('SIGTERM', forwardSignal);
+function spawnInherited(cmd, args, cwd, activityLabel = cmd) {
+    const child = spawn(cmd, args, { stdio: 'inherit', ...(cwd ? { cwd } : {}) });
+    const childSignals = forwardChildSignals(child, activityLabel);
     return new Promise((resolve, reject) => {
-        child.on('close', (code) => {
-            process.off('SIGINT', forwardSignal);
-            process.off('SIGTERM', forwardSignal);
-            if (code === 0) {
+        child.on('close', (code, signal) => {
+            const forwardedSignal = childSignals.getForwardedSignal();
+            childSignals.cleanup();
+            if (forwardedSignal) {
+                process.kill(process.pid, forwardedSignal);
+                return;
+            }
+            if (signal) {
+                process.kill(process.pid, signal);
+                return;
+            }
+            else if (code === 0) {
                 resolve();
             }
             else {
@@ -841,44 +1615,55 @@ function spawnInherited(cmd, args) {
             }
         });
         child.on('error', (err) => {
-            process.off('SIGINT', forwardSignal);
-            process.off('SIGTERM', forwardSignal);
+            childSignals.cleanup();
             reject(err);
         });
     });
 }
-export function detectContainerRuntime() {
-    for (const runtime of ['podman', 'docker']) {
-        const result = spawnSync(runtime, ['--version'], { stdio: 'ignore' });
-        if (result.status === 0 && result.error === undefined) {
-            return runtime;
-        }
+export function detectContainerRuntime(forcedRuntime) {
+    const runtimeCheck = forcedRuntime
+        ? checkContainerRuntime(forcedRuntime)
+        : getPreferredContainerRuntime();
+    if (runtimeCheck) {
+        warnIfContainerRuntimeVersionIsOld(runtimeCheck);
+        return runtimeCheck.runtime;
+    }
+    if (forcedRuntime) {
+        exitContainerRuntimeNotFound(forcedRuntime);
     }
     logger.error('Error: Neither podman nor docker found.');
     logger.error('Please install podman (recommended) or docker to use screenci record.');
-    logger.error('  podman: https://podman.io/docs/installation');
-    logger.error('  docker: https://docs.docker.com/get-docker/');
+    logger.error(prerequisitesMessage());
     process.exit(1);
 }
+function checkContainerRuntimeForInit() {
+    const runtimeCheck = getPreferredContainerRuntime();
+    if (!runtimeCheck) {
+        logger.warn('Neither podman nor docker found. Install one before running screenci record.');
+        logger.warn(prerequisitesMessage());
+        return;
+    }
+    warnIfContainerRuntimeVersionIsOld(runtimeCheck);
+}
 async function buildImage(cmd, args, label, verbose) {
     if (verbose) {
         await spawnInherited(cmd, args);
         return;
     }
-    writeInline(`${label}...`);
+    const spinner = ora(label).start();
     try {
         await spawnSilent(cmd, args);
-        completeInline(`${label} ✓`);
+        spinner.succeed(label);
     }
     catch (err) {
-        process.stdout.write('\n');
+        spinner.fail(label);
         const msg = err instanceof Error ? err.message : String(err);
         logger.error(msg);
         logger.error('Run again with --verbose to see the full build output');
         process.exit(1);
     }
 }
-async function runWithContainer(additionalArgs, customConfigPath, imageTag, verbose = false) {
+async function runWithContainer(additionalArgs, customConfigPath, imageTag, verbose = false, forcedRuntime) {
     const configPath = findScreenCIConfig(customConfigPath);
     if (!configPath) {
         const errorMsg = customConfigPath
@@ -899,7 +1684,7 @@ async function runWithContainer(additionalArgs, customConfigPath, imageTag, verb
         logger.error('Error: Could not find repository root (.git or pnpm-workspace.yaml)');
         process.exit(1);
     }
-    const containerRuntime = detectContainerRuntime();
+    const containerRuntime = detectContainerRuntime(forcedRuntime);
     const ghcrImage = 'ghcr.io/screenci/record:latest';
     const dockerfileVersion = parseDockerfileVersion(dockerfilePath);
     if (process.env['SCREENCI_LOCAL_IMAGE']) {
@@ -912,13 +1697,15 @@ async function runWithContainer(additionalArgs, customConfigPath, imageTag, verb
         }).status === 0;
         logger.info(`Using image tag ${imageTag} instead of the version ${dockerfileVersion} from Dockerfile`);
         if (!imageExists) {
-            await buildImage(containerRuntime, ['pull', remoteImage], 'Pulling image', verbose);
+            await buildImage(containerRuntime, ['pull', remoteImage], 'Pulling screenci image', verbose);
         }
         await spawnSilent(containerRuntime, ['tag', remoteImage, ghcrImage]);
     }
     else {
         const cliDir = dirname(fileURLToPath(import.meta.url));
-        const screenciPackageRoot = resolve(cliDir, '..');
+        const screenciPackageRoot = existsSync(resolve(cliDir, 'package.json'))
+            ? cliDir
+            : resolve(cliDir, '..');
         const screenciDockerfilePath = resolve(cliDir, 'Dockerfile');
         if (verbose) {
             await spawnInherited(containerRuntime, [
@@ -928,18 +1715,11 @@ async function runWithContainer(additionalArgs, customConfigPath, imageTag, verb
                 '-t',
                 ghcrImage,
                 screenciPackageRoot,
-            ]);
-            await spawnInherited(containerRuntime, [
-                'build',
-                '-f',
-                dockerfilePath,
-                '-t',
-                'screenci',
-                configDir,
-            ]);
+            ], undefined, 'building screenci image');
+            await spawnInherited(containerRuntime, ['build', '-f', dockerfilePath, '-t', 'screenci', configDir], undefined, 'building project image');
         }
         else {
-            writeInline('Building image...');
+            const spinner = ora('Building screenci image').start();
             try {
                 await spawnSilent(containerRuntime, [
                     'build',
@@ -957,10 +1737,10 @@ async function runWithContainer(additionalArgs, customConfigPath, imageTag, verb
                     'screenci',
                     configDir,
                 ]);
-                completeInline('Building image ✓');
+                spinner.succeed('Building screenci image');
             }
             catch (err) {
-                process.stdout.write('\n');
+                spinner.fail('Building screenci image');
                 const msg = err instanceof Error ? err.message : String(err);
                 logger.error(msg);
                 logger.error('Run again with --verbose to see the full build output');
@@ -969,7 +1749,7 @@ async function runWithContainer(additionalArgs, customConfigPath, imageTag, verb
         }
     }
     if (imageTag !== undefined || process.env['SCREENCI_LOCAL_IMAGE']) {
-        await buildImage(containerRuntime, ['build', '-f', dockerfilePath, '-t', 'screenci', configDir], 'Building image', verbose);
+        await buildImage(containerRuntime, ['build', '-f', dockerfilePath, '-t', 'screenci', configDir], 'Building project image', verbose);
     }
     clearDirectory(resolve(configDir, '.screenci'));
     const secret = process.env['SCREENCI_SECRET'];
@@ -986,6 +1766,8 @@ async function runWithContainer(additionalArgs, customConfigPath, imageTag, verb
         'SCREENCI_RECORD=true',
         '-e',
         `SCREENCI_SECRET=${secret}`,
+        '-e',
+        'SCREENCI_SIGNAL_LOGGING=silent',
         '-v',
         `${configDir}/.screenci:/app/.screenci`,
         '-v',
@@ -1016,7 +1798,13 @@ async function run(command, additionalArgs, customConfigPath) {
     // For dev command: use --ui unless --headed is specified
     const isHeaded = additionalArgs.includes('--headed');
     const shouldUseUI = command === 'dev' && !isHeaded;
-    const mode = command === 'dev' ? (isHeaded ? 'headed mode' : 'UI mode') : 'recorder';
+    const mode = command === 'dev'
+        ? isHeaded
+            ? 'headed mode'
+            : 'UI mode'
+        : command === 'test'
+            ? 'tests'
+            : 'recorder';
     if (process.env.SCREENCI_IN_CONTAINER !== 'true') {
         logger.info(`Running ScreenCI ${mode} with npx...`);
         logger.info(`Using config: ${configPath}`);
@@ -1037,29 +1825,19 @@ async function run(command, additionalArgs, customConfigPath) {
             ...(command === 'record' ? { SCREENCI_RECORD: 'true' } : {}),
         },
     });
-    const forwardSignal = (signal) => {
-        logger.info(`Received ${signal}, stopping recording...`);
-        if (!child.killed) {
-            child.kill(signal);
-        }
-        // Force-kill after 3 s if the child hasn't actually exited yet.
-        // child.killed becomes true as soon as we send the signal, so we check
-        // child.exitCode instead — it stays null until the process truly exits.
-        // unref() so the timer doesn't keep the process alive on its own.
-        const forceKill = setTimeout(() => {
-            if (child.exitCode === null) {
-                logger.info('Forcing kill after timeout...');
-                child.kill('SIGKILL');
-            }
-        }, 3000);
-        forceKill.unref();
-    };
-    process.on('SIGINT', forwardSignal);
-    process.on('SIGTERM', forwardSignal);
+    const childSignals = forwardChildSignals(child, `screenci ${command}`);
     return new Promise((resolve, reject) => {
-        child.on('close', (code) => {
-            process.off('SIGINT', forwardSignal);
-            process.off('SIGTERM', forwardSignal);
+        child.on('close', (code, signal) => {
+            const forwardedSignal = childSignals.getForwardedSignal();
+            childSignals.cleanup();
+            if (forwardedSignal) {
+                process.kill(process.pid, forwardedSignal);
+                return;
+            }
+            if (signal) {
+                process.kill(process.pid, signal);
+                return;
+            }
             if (code === 0) {
                 resolve();
             }
@@ -1068,6 +1846,7 @@ async function run(command, additionalArgs, customConfigPath) {
             }
         });
         child.on('error', (err) => {
+            childSignals.cleanup();
             reject(err);
         });
     });