rollberry 0.1.5 → 0.1.9

package/CHANGELOG.md

@@ -5,13 +5,48 @@ All notable changes to this project will be documented in this file.
 The format is based on Keep a Changelog and the project stays on the `v0.x.x`
 line until the CLI surface and capture behavior settle.
 
-## [0.1.5] - 2026-03-18
+## [0.1.9] - 2026-03-20
+
+### Added
+
+- TTY-aware progress bar during frame rendering; falls back to milestone
+  percentages in non-TTY environments.
+- `--force` flag to overwrite an existing output file.
+- `--version` / `-V` flag to print the current version.
+- `--help` / `-h` at both top-level and subcommand level.
+- Graceful cancellation via SIGINT / SIGTERM with partial-output cleanup.
+- Capture summary printed to stderr on completion (file size, duration, frame
+  count, pages, manifest path).
+- FFmpeg availability pre-check with platform-specific install instructions.
+- Frame-count safety limit (36 000 frames) and FPS cap (120) to prevent
+  runaway captures.
+- `--hide-selector` input validation (rejects selectors containing `{` or `}`).
+- URL credential sanitization — userinfo is stripped from all logs and
+  manifests.
+
+### Changed
+
+- Font loading now times out after 10 s instead of waiting indefinitely.
+- Preflight page measurement stops after 20 iterations to avoid infinite loops
+  on dynamically-loading pages.
+- Browser session properly closes when context creation fails.
+- FFmpeg encoder supports abort with SIGTERM → SIGKILL escalation.
+- Manifest `status` field now includes a `cancelled` value.
+- Error messages throughout the CLI include actionable hints and expected
+  formats.
+- Help text now shows default values, max constraints, and usage examples.
+
+## [0.1.8] - 2026-03-19
+
+### Added
+
+- Multi-page capture support.
 
 ### Changed
 
 - Reduced default auto-scroll speed from 1800 px/s to 800 px/s for better
   readability during capture.
-- Republished under new maintainer account.
+- GitHub Actions publish workflow now uses token-based authentication.
 
 ## [0.1.3] - 2026-03-15
 

package/dist/capture/browser-install.js

@@ -13,7 +13,7 @@ export async function ensureChromiumInstalled(logger) {
     await logger.warn('browser.install.start', 'Chromium was not found. Installing Playwright Chromium.', { executablePath });
     await installPlaywrightChromium(resolvePlaywrightCliPath());
     if (!(await hasExecutable(executablePath))) {
-        throw new Error(`Chromium のインストール後も実行ファイルが見つかりません: ${executablePath}`);
+        throw new Error(`Chromium executable not found after installation: ${executablePath}\n  Try running: npx playwright install chromium`);
     }
     await logger.info('browser.install.complete', 'Playwright Chromium installation finished.', { executablePath });
 }

package/dist/capture/browser.js

@@ -7,16 +7,22 @@ export async function openBrowserSession(options, logger) {
     const browser = await chromium.launch({
         headless: true,
     });
-    const context = await browser.newContext({
-        viewport: options.viewport,
-        ignoreHTTPSErrors: options.urls.some(isLocalUrl),
-    });
-    const page = await context.newPage();
-    page.setDefaultTimeout(options.timeoutMs);
-    await page.addInitScript(() => {
-        history.scrollRestoration = 'manual';
-    });
-    return { browser, page };
+    try {
+        const context = await browser.newContext({
+            viewport: options.viewport,
+            ignoreHTTPSErrors: options.urls.some(isLocalUrl),
+        });
+        const page = await context.newPage();
+        page.setDefaultTimeout(options.timeoutMs);
+        await page.addInitScript(() => {
+            history.scrollRestoration = 'manual';
+        });
+        return { browser, page };
+    }
+    catch (error) {
+        await browser.close();
+        throw error;
+    }
 }
 export async function navigateWithRetry(page, url, timeoutMs) {
     const deadline = Date.now() + timeoutMs;

package/dist/capture/capture.js

@@ -1,14 +1,22 @@
-import { writeFile } from 'node:fs/promises';
+import { unlink, writeFile } from 'node:fs/promises';
 import { navigateWithRetry, openBrowserSession } from './browser.js';
-import { createVideoEncoder } from './ffmpeg.js';
+import { MAX_TOTAL_FRAMES } from './constants.js';
+import { checkFfmpegAvailable, createVideoEncoder, } from './ffmpeg.js';
 import { preflightMeasurePage } from './preflight.js';
 import { buildScrollFrames, resolveDurationSeconds } from './scroll-plan.js';
 import { stabilizePage } from './stabilize.js';
-import { ensureDirectory, ensureParentDirectory, waitForAnimationFrames, } from './utils.js';
-export async function captureVideo(options, logger) {
+import { ensureDirectory, ensureParentDirectory, fileExists, sanitizeUrl, waitForAnimationFrames, } from './utils.js';
+export async function captureVideo(options, logger, progress, signal) {
     if (options.urls.length === 0) {
-        throw new Error('少なくとも1つのURLを指定してください。');
+        throw new Error('At least one URL is required.');
     }
+    if (signal?.aborted) {
+        throw new AbortError();
+    }
+    if (!options.force && (await fileExists(options.outPath))) {
+        throw new Error(`Output file already exists: ${options.outPath}\nUse --force to overwrite, or specify a different --out path.`);
+    }
+    await checkFfmpegAvailable();
     await Promise.all([
         ensureParentDirectory(options.outPath),
         ensureParentDirectory(options.logFilePath),
@@ -18,23 +26,54 @@ export async function captureVideo(options, logger) {
             : undefined,
     ]);
     const { browser, page } = await openBrowserSession(options, logger);
+    let encoder;
+    let encodingFinished = false;
+    let browserClosed = false;
+    const closeBrowser = async () => {
+        if (browserClosed) {
+            return;
+        }
+        browserClosed = true;
+        try {
+            await browser.close();
+        }
+        catch {
+            // Browser may already be closed during cancellation
+        }
+    };
+    const abortHandler = () => {
+        void encoder?.abort();
+        void closeBrowser();
+    };
+    signal?.addEventListener('abort', abortHandler);
     try {
-        const encoder = await createVideoEncoder({
+        if (signal?.aborted) {
+            throw new AbortError();
+        }
+        encoder = await createVideoEncoder({
             fps: options.fps,
             outPath: options.outPath,
         });
+        if (signal?.aborted) {
+            throw new AbortError();
+        }
         const pages = [];
         let totalFrameCount = 0;
         let totalDurationSeconds = 0;
         let frameOffset = 0;
         let anyTruncated = false;
         for (const [urlIndex, url] of options.urls.entries()) {
+            if (signal?.aborted) {
+                throw new AbortError();
+            }
             const { pageResult, lastFrame } = await capturePageFrames({
                 page,
                 url,
                 encoder,
                 options,
                 logger,
+                progress,
+                signal,
                 frameOffset,
                 urlIndex,
             });
@@ -59,6 +98,8 @@ export async function captureVideo(options, logger) {
             }
         }
         await encoder.finish();
+        encodingFinished = true;
+        progress?.onEncodeComplete();
         await logger.info('encode.complete', 'Video encoding finished', {
             outPath: options.outPath,
         });
@@ -70,15 +111,34 @@ export async function captureVideo(options, logger) {
             truncated: anyTruncated,
         };
     }
+    catch (error) {
+        const failure = signal?.aborted && !(error instanceof AbortError)
+            ? new AbortError()
+            : error;
+        if (encoder && !encodingFinished) {
+            await encoder.abort();
+            await cleanupPartialOutput(options.outPath);
+        }
+        throw failure;
+    }
     finally {
-        await browser.close();
+        signal?.removeEventListener('abort', abortHandler);
+        await closeBrowser();
+    }
+}
+export class AbortError extends Error {
+    constructor() {
+        super('Capture was cancelled.');
+        this.name = 'AbortError';
     }
 }
 async function capturePageFrames(input) {
-    const { page, url, encoder, options, logger, urlIndex } = input;
+    const { page, url, encoder, options, logger, progress, signal, urlIndex } = input;
     const { frameOffset } = input;
+    const safeUrl = sanitizeUrl(url);
+    progress?.onPageStart(urlIndex, options.urls.length, safeUrl);
     await logger.info('browser.open', `Opening page ${urlIndex + 1}`, {
-        url: url.toString(),
+        url: safeUrl,
         viewport: options.viewport,
     });
     await navigateWithRetry(page, url, options.timeoutMs);
@@ -87,7 +147,7 @@ async function capturePageFrames(input) {
         waitFor: options.waitFor,
         hideSelectors: options.hideSelectors,
     });
-    const preflight = await preflightMeasurePage(page);
+    const preflight = await preflightMeasurePage(page, logger);
     const plannedDurationSeconds = resolveDurationSeconds(options.duration, preflight.maxScroll);
     const frames = buildScrollFrames({
         fps: options.fps,
@@ -95,22 +155,32 @@ async function capturePageFrames(input) {
         maxScroll: preflight.maxScroll,
         motion: options.motion,
     });
+    assertWithinFrameLimit(frameOffset +
+        frames.length +
+        getReservedGapFrames({
+            fps: options.fps,
+            pageGapSeconds: options.pageGapSeconds,
+            isLastPage: urlIndex === options.urls.length - 1,
+        }));
     const durationSeconds = frames.length / options.fps;
     await logger.info('render.start', `Rendering frames for page ${urlIndex + 1}`, {
         frameCount: frames.length,
         fps: options.fps,
         durationSeconds,
         maxScroll: preflight.maxScroll,
-        url: url.toString(),
+        url: safeUrl,
     });
     if (preflight.truncated) {
         await logger.warn('preflight.truncated', 'Scroll height exceeded capture limit and was truncated', {
             scrollHeight: preflight.scrollHeight,
-            url: url.toString(),
+            url: safeUrl,
         });
     }
     let lastFrame;
     for (const [index, scrollTop] of frames.entries()) {
+        if (signal?.aborted) {
+            throw new AbortError();
+        }
         await page.evaluate((nextScrollTop) => {
             window.scrollTo({ top: nextScrollTop, behavior: 'auto' });
         }, scrollTop);
@@ -127,21 +197,23 @@ async function capturePageFrames(input) {
             await writeFile(`${options.debugFramesDir}/${fileName}`, frame);
         }
         await encoder.writeFrame(frame);
+        progress?.onFrameRendered(index, frames.length);
         if ((index + 1) % Math.max(1, Math.floor(frames.length / 10)) === 0) {
             await logger.info('render.progress', 'Rendered frame batch', {
                 renderedFrames: index + 1,
                 totalFrames: frames.length,
                 scrollTop,
-                url: url.toString(),
+                url: safeUrl,
             });
         }
     }
     if (!lastFrame) {
-        throw new Error(`ページのフレーム取得に失敗しました: ${url.toString()}`);
+        throw new Error(`Failed to capture frames from page: ${safeUrl}`);
     }
+    progress?.onPageComplete(urlIndex);
     return {
         pageResult: {
-            url: url.toString(),
+            url: safeUrl,
             frameCount: frames.length,
             durationSeconds,
             scrollHeight: preflight.scrollHeight,
@@ -150,6 +222,25 @@ async function capturePageFrames(input) {
         lastFrame,
     };
 }
+async function cleanupPartialOutput(outPath) {
+    try {
+        await unlink(outPath);
+    }
+    catch {
+        // Partial output may not exist
+    }
+}
+function assertWithinFrameLimit(frameCount) {
+    if (frameCount > MAX_TOTAL_FRAMES) {
+        throw new Error(`Total frame count ${frameCount} exceeds maximum ${MAX_TOTAL_FRAMES}. Reduce --fps, --duration, --page-gap, or the number of pages.`);
+    }
+}
+function getReservedGapFrames(options) {
+    if (options.isLastPage) {
+        return 0;
+    }
+    return Math.round(options.fps * options.pageGapSeconds);
+}
 async function writeGapFrames(input) {
     const { encoder, frame, fps, gapSeconds, debugFramesDir, frameOffset } = input;
     const gapFrameCount = Math.round(fps * gapSeconds);

package/dist/capture/constants.js

@@ -6,3 +6,7 @@ export const STABILIZE_DELAY_MS = 500;
 export const PREFLIGHT_STEP_DELAY_MS = 120;
 export const PREFLIGHT_STABLE_ROUNDS = 3;
 export const PREFLIGHT_MAX_SCROLL_HEIGHT = 30_000;
+export const MAX_TOTAL_FRAMES = 36_000;
+export const MAX_FPS = 120;
+export const FONT_LOADING_TIMEOUT_MS = 10_000;
+export const MAX_PREFLIGHT_ITERATIONS = 20;

package/dist/capture/ffmpeg.js

@@ -1,5 +1,16 @@
-import { spawn } from 'node:child_process';
-import { once } from 'node:events';
+import { execFile, spawn } from 'node:child_process';
+const FFMPEG_ABORT_TIMEOUT_MS = 1_000;
+export async function checkFfmpegAvailable() {
+    await new Promise((resolve, reject) => {
+        execFile('ffmpeg', ['-version'], (error) => {
+            if (error) {
+                reject(createFfmpegPreflightError(error));
+                return;
+            }
+            resolve();
+        });
+    });
+}
 export async function createVideoEncoder(options) {
     const ffmpeg = spawn('ffmpeg', [
         '-hide_banner',
@@ -33,6 +44,13 @@ export async function createVideoEncoder(options) {
     });
     let spawnError;
     let stderr = '';
+    let closeResult;
+    const closePromise = new Promise((resolve) => {
+        ffmpeg.once('close', (exitCode, signal) => {
+            closeResult = { exitCode, signal };
+            resolve(closeResult);
+        });
+    });
     ffmpeg.on('error', (error) => {
         spawnError = error;
     });
@@ -45,9 +63,12 @@ export async function createVideoEncoder(options) {
             if (spawnError) {
                 throw createEncoderError(spawnError, stderr);
             }
+            if (closeResult) {
+                throw createEncoderError(new Error(`FFmpeg exited before encoding completed (${formatCloseResult(closeResult)})`), stderr);
+            }
             const stdin = ffmpeg.stdin;
             if (stdin.destroyed) {
-                throw createEncoderError(new Error('FFmpeg の標準入力が閉じています。'), stderr);
+                throw createEncoderError(new Error('FFmpeg stdin is closed.'), stderr);
             }
             await new Promise((resolve, reject) => {
                 stdin.write(frame, (error) => {
@@ -63,18 +84,72 @@ export async function createVideoEncoder(options) {
             if (spawnError) {
                 throw createEncoderError(spawnError, stderr);
             }
-            ffmpeg.stdin.end();
-            const [exitCode] = (await once(ffmpeg, 'close'));
-            if (exitCode !== 0) {
-                throw createEncoderError(new Error(`FFmpeg が異常終了しました (exit code: ${exitCode ?? 'null'})`), stderr);
+            if (!ffmpeg.stdin.destroyed && !ffmpeg.stdin.writableEnded) {
+                ffmpeg.stdin.end();
+            }
+            const result = closeResult ?? (await closePromise);
+            if (result.exitCode !== 0) {
+                throw createEncoderError(new Error(`FFmpeg exited with error (${formatCloseResult(result)})`), stderr);
+            }
+        },
+        async abort() {
+            try {
+                if (!ffmpeg.stdin.destroyed && !ffmpeg.stdin.writableEnded) {
+                    ffmpeg.stdin.destroy();
+                }
+            }
+            catch {
+                // stdin may already be closed
+            }
+            if (closeResult) {
+                await closePromise;
+                return;
+            }
+            try {
+                ffmpeg.kill('SIGTERM');
+            }
+            catch {
+                // Process may already be exiting
+            }
+            const exited = await Promise.race([
+                closePromise.then(() => true),
+                new Promise((resolve) => {
+                    setTimeout(resolve, FFMPEG_ABORT_TIMEOUT_MS, false);
+                }),
+            ]);
+            if (!exited && !closeResult) {
+                try {
+                    ffmpeg.kill('SIGKILL');
+                }
+                catch {
+                    // Process may already be exiting
+                }
+                await closePromise;
             }
         },
     };
 }
+function createFfmpegPreflightError(error) {
+    if (error.code === 'ENOENT') {
+        return new Error([
+            'FFmpeg is required but was not found in PATH.',
+            '  macOS:   brew install ffmpeg',
+            '  Ubuntu:  sudo apt install ffmpeg',
+            '  Windows: winget install ffmpeg',
+        ].join('\n'));
+    }
+    return new Error(`Failed to execute FFmpeg: ${error.message}`);
+}
 function createEncoderError(error, stderr) {
     if ('code' in error && error.code === 'ENOENT') {
-        return new Error('FFmpeg が見つかりません。PATH に ffmpeg を追加してください。');
+        return new Error('FFmpeg not found. Please add ffmpeg to your PATH.');
     }
     const detail = stderr.trim();
     return new Error(detail ? `${error.message}\n${detail}` : error.message);
 }
+function formatCloseResult(result) {
+    if (result.signal) {
+        return `signal: ${result.signal}`;
+    }
+    return `exit code: ${result.exitCode ?? 'null'}`;
+}

package/dist/capture/preflight.js

@@ -1,10 +1,16 @@
-import { PREFLIGHT_MAX_SCROLL_HEIGHT, PREFLIGHT_STABLE_ROUNDS, PREFLIGHT_STEP_DELAY_MS, } from './constants.js';
+import { MAX_PREFLIGHT_ITERATIONS, PREFLIGHT_MAX_SCROLL_HEIGHT, PREFLIGHT_STABLE_ROUNDS, PREFLIGHT_STEP_DELAY_MS, } from './constants.js';
 import { delay, measurePage, waitForAnimationFrames } from './utils.js';
-export async function preflightMeasurePage(page) {
+export async function preflightMeasurePage(page, logger) {
     let metrics = await measurePage(page);
     let truncated = metrics.scrollHeight > PREFLIGHT_MAX_SCROLL_HEIGHT;
     let stableRounds = metrics.maxScroll === 0 ? PREFLIGHT_STABLE_ROUNDS : 0;
+    let iterations = 0;
     while (!truncated && stableRounds < PREFLIGHT_STABLE_ROUNDS) {
+        iterations += 1;
+        if (iterations > MAX_PREFLIGHT_ITERATIONS) {
+            await logger?.warn('preflight.max_iterations', `Preflight measurement stopped after ${MAX_PREFLIGHT_ITERATIONS} iterations (page content may still be loading)`);
+            break;
+        }
         let position = 0;
         while (position < metrics.maxScroll) {
             position = Math.min(position + metrics.viewportHeight, metrics.maxScroll);

package/dist/capture/progress.js

@@ -0,0 +1,50 @@
+export function createProgressReporter() {
+    const isTTY = process.stderr.isTTY === true;
+    let lastUpdateTime = 0;
+    let lastReportedMilestone = -1;
+    function clearLine() {
+        if (isTTY) {
+            process.stderr.write('\r\x1b[K');
+        }
+    }
+    return {
+        onPageStart(pageIndex, totalPages, url) {
+            clearLine();
+            lastReportedMilestone = -1;
+            const displayUrl = url.length > 60 ? `${url.slice(0, 57)}...` : url;
+            process.stderr.write(`Capturing page ${pageIndex + 1}/${totalPages}: ${displayUrl}\n`);
+        },
+        onFrameRendered(frameIndex, totalFrames) {
+            const now = Date.now();
+            const isLast = frameIndex + 1 === totalFrames;
+            if (!isLast && now - lastUpdateTime < 100) {
+                return;
+            }
+            lastUpdateTime = now;
+            const progress = (frameIndex + 1) / totalFrames;
+            const percent = Math.round(progress * 100);
+            if (isTTY) {
+                const barWidth = 20;
+                const filled = Math.round(barWidth * progress);
+                const bar = '#'.repeat(filled) + '-'.repeat(barWidth - filled);
+                process.stderr.write(`\r  [${bar}] ${percent}% (${frameIndex + 1}/${totalFrames} frames)`);
+                if (isLast) {
+                    process.stderr.write('\n');
+                }
+            }
+            else {
+                const milestone = Math.floor(percent / 25) * 25;
+                if (isLast || (milestone > lastReportedMilestone && milestone > 0)) {
+                    lastReportedMilestone = milestone;
+                    process.stderr.write(`  Progress: ${percent}% (${frameIndex + 1}/${totalFrames} frames)\n`);
+                }
+            }
+        },
+        onPageComplete(_pageIndex) {
+            // Line already advanced after last frame render
+        },
+        onEncodeComplete() {
+            // Summary is printed by cli.ts
+        },
+    };
+}

package/dist/capture/scroll-plan.js

@@ -1,4 +1,4 @@
-import { AUTO_DURATION_MAX_SECONDS, AUTO_DURATION_MIN_SECONDS, AUTO_DURATION_PIXELS_PER_SECOND, } from './constants.js';
+import { AUTO_DURATION_MAX_SECONDS, AUTO_DURATION_MIN_SECONDS, AUTO_DURATION_PIXELS_PER_SECOND, MAX_TOTAL_FRAMES, } from './constants.js';
 import { clamp } from './utils.js';
 export function resolveDurationSeconds(requestedDuration, maxScroll) {
     if (requestedDuration !== 'auto') {
@@ -8,6 +8,9 @@ export function resolveDurationSeconds(requestedDuration, maxScroll) {
 }
 export function buildScrollFrames(options) {
     const frameCount = Math.max(1, Math.ceil(options.durationSeconds * options.fps));
+    if (frameCount > MAX_TOTAL_FRAMES) {
+        throw new Error(`Frame count ${frameCount} exceeds maximum ${MAX_TOTAL_FRAMES}. Reduce --fps or --duration.`);
+    }
     if (frameCount === 1) {
         return [0];
     }

package/dist/capture/stabilize.js

@@ -1,5 +1,5 @@
-import { STABILIZE_DELAY_MS } from './constants.js';
-import { delay, waitForAnimationFrames } from './utils.js';
+import { FONT_LOADING_TIMEOUT_MS, STABILIZE_DELAY_MS } from './constants.js';
+import { delay, validateHideSelector, waitForAnimationFrames, } from './utils.js';
 export async function stabilizePage(options) {
     await options.page.addStyleTag({
         content: buildStabilizingCss(options.hideSelectors),
@@ -13,6 +13,9 @@ export async function stabilizePage(options) {
     await waitForAnimationFrames(options.page);
 }
 function buildStabilizingCss(hideSelectors) {
+    for (const selector of hideSelectors) {
+        validateHideSelector(selector);
+    }
     const hiddenSelectorBlock = hideSelectors.length > 0
         ? `${hideSelectors.join(', ')} { display: none !important; visibility: hidden !important; }\n`
         : '';
@@ -47,10 +50,13 @@ async function waitForRequestedCondition(page, waitFor) {
     await delay(waitFor.ms);
 }
 async function waitForFonts(page) {
-    await page.evaluate(async () => {
+    await page.evaluate(async (timeoutMs) => {
         if (!('fonts' in document)) {
             return;
         }
-        await document.fonts.ready;
-    });
+        await Promise.race([
+            document.fonts.ready,
+            new Promise((resolve) => setTimeout(resolve, timeoutMs)),
+        ]);
+    }, FONT_LOADING_TIMEOUT_MS);
 }

package/dist/capture/utils.js

@@ -1,4 +1,4 @@
-import { mkdir } from 'node:fs/promises';
+import { access, mkdir } from 'node:fs/promises';
 import { dirname } from 'node:path';
 const LOCALHOST_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
 export function clamp(value, min, max) {
@@ -13,13 +13,40 @@ export function parseCaptureUrl(rawUrl) {
         url = new URL(rawUrl);
     }
     catch {
-        throw new Error(`無効なURLです: ${rawUrl}`);
+        throw new Error(`Invalid URL: ${rawUrl}\n  Expected format: http://example.com or https://localhost:3000`);
     }
     if (url.protocol !== 'http:' && url.protocol !== 'https:') {
-        throw new Error(`サポート対象外のURLです: ${rawUrl} (http/https のみ対応)`);
+        throw new Error(`Unsupported URL: ${rawUrl} (only http:// and https:// are supported)`);
     }
     return url;
 }
+export function sanitizeUrl(url) {
+    const sanitized = new URL(url.toString());
+    sanitized.username = '';
+    sanitized.password = '';
+    return sanitized.toString();
+}
+export function formatFileSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+export function validateHideSelector(selector) {
+    if (selector.includes('{') || selector.includes('}')) {
+        throw new Error(`Invalid CSS selector for --hide-selector: "${selector}". Selectors must not contain { or } characters.`);
+    }
+}
+export async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export async function ensureParentDirectory(filePath) {
     await mkdir(dirname(filePath), { recursive: true });
 }

package/dist/cli.js

@@ -1,13 +1,66 @@
 #!/usr/bin/env node
-import { CliError, formatUsage, parseCliArgs } from './options.js';
+import { statSync } from 'node:fs';
+import { basename } from 'node:path';
+import { AbortError } from './capture/capture.js';
+import { createProgressReporter } from './capture/progress.js';
+import { formatFileSize } from './capture/utils.js';
+import { CliError, formatUsage, HelpRequest, parseCliArgs, VersionRequest, } from './options.js';
 import { runCaptureCommand } from './run-capture.js';
 async function main() {
     try {
         const options = parseCliArgs();
-        const result = await runCaptureCommand(options);
-        process.stdout.write(`${result.capture.outPath}\n`);
+        const controller = new AbortController();
+        const onSignal = () => {
+            controller.abort();
+        };
+        process.on('SIGINT', onSignal);
+        process.on('SIGTERM', onSignal);
+        const progress = createProgressReporter();
+        try {
+            const result = await runCaptureCommand(options, progress, controller.signal);
+            process.stdout.write(`${result.capture.outPath}\n`);
+            const fileName = basename(result.capture.outPath);
+            let fileSizeStr = '';
+            try {
+                const stat = statSync(result.capture.outPath);
+                fileSizeStr = formatFileSize(stat.size);
+            }
+            catch {
+                // File size unavailable
+            }
+            const lines = [
+                '',
+                `Capture complete: ${fileName}`,
+                `  Duration:  ${result.capture.durationSeconds.toFixed(1)}s (${result.capture.frameCount} frames at ${options.fps}fps)`,
+            ];
+            if (fileSizeStr) {
+                lines.push(`  File size: ${fileSizeStr}`);
+            }
+            if (result.capture.pages.length > 1) {
+                lines.push(`  Pages:     ${result.capture.pages.length}`);
+            }
+            lines.push(`  Manifest:  ${basename(result.manifestPath)}`);
+            process.stderr.write(`${lines.join('\n')}\n`);
+        }
+        finally {
+            process.off('SIGINT', onSignal);
+            process.off('SIGTERM', onSignal);
+        }
     }
     catch (error) {
+        if (error instanceof HelpRequest) {
+            process.stdout.write(`${error.message}\n`);
+            return;
+        }
+        if (error instanceof VersionRequest) {
+            process.stdout.write(`${error.version}\n`);
+            return;
+        }
+        if (error instanceof AbortError) {
+            process.stderr.write('\nCapture cancelled.\n');
+            process.exitCode = 130;
+            return;
+        }
         if (error instanceof CliError) {
             process.stderr.write(`${error.message}\n`);
             if (error.showUsage) {
@@ -16,7 +69,7 @@ async function main() {
             process.exitCode = 1;
             return;
         }
-        process.stderr.write(`${error instanceof Error ? error.message : '予期しないエラーが発生しました。'}\n`);
+        process.stderr.write(`${error instanceof Error ? error.message : 'An unexpected error occurred.'}\n`);
         process.exitCode = 1;
     }
 }

package/dist/options.js

@@ -1,6 +1,8 @@
 import { resolve } from 'node:path';
 import { parseArgs } from 'node:util';
-import { parseCaptureUrl } from './capture/utils.js';
+import { MAX_FPS } from './capture/constants.js';
+import { parseCaptureUrl, validateHideSelector } from './capture/utils.js';
+import { VERSION } from './version.js';
 const DEFAULT_OUT_FILE = 'rollberry.mp4';
 const DEFAULT_VIEWPORT = '1440x900';
 const DEFAULT_FPS = 60;
@@ -15,13 +17,35 @@ export class CliError extends Error {
         this.name = 'CliError';
     }
 }
+export class HelpRequest extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HelpRequest';
+    }
+}
+export class VersionRequest extends Error {
+    version = VERSION;
+    constructor() {
+        super(VERSION);
+        this.name = 'VersionRequest';
+    }
+}
 export function parseCliArgs(argv = process.argv.slice(2)) {
     const [command, ...rest] = argv;
+    if (command === '--help' || command === '-h') {
+        throw new HelpRequest(formatUsage());
+    }
+    if (command === '--version' || command === '-V') {
+        throw new VersionRequest();
+    }
     if (!command) {
-        throw new CliError('サブコマンドが必要です。', true);
+        throw new CliError('A subcommand is required.\n\nAvailable commands:\n  capture    Capture a scroll video from one or more URLs\n\nRun rollberry --help for more information.');
     }
     if (command !== 'capture') {
-        throw new CliError(`未知のサブコマンドです: ${command}`, true);
+        throw new CliError(`Unknown subcommand: ${command}\n\nAvailable commands:\n  capture    Capture a scroll video from one or more URLs\n\nRun rollberry --help for more information.`);
+    }
+    if (rest.includes('--help') || rest.includes('-h')) {
+        throw new HelpRequest(formatUsage());
     }
     const parsed = parseArgs({
         args: rest,
@@ -64,19 +88,30 @@ export function parseCliArgs(argv = process.argv.slice(2)) {
             'log-file': {
                 type: 'string',
             },
+            force: {
+                type: 'boolean',
+            },
         },
         strict: true,
     });
     if (parsed.positionals.length === 0) {
-        throw new CliError('capture にはURLが必要です。', true);
+        throw new CliError('capture requires at least one URL.', true);
     }
     const urls = parsed.positionals.map((raw) => parseWithCliError(raw, parseCaptureUrl));
     const durationOption = parsed.values.duration ?? DEFAULT_DURATION;
     if (durationOption !== 'auto' && Number.isNaN(Number(durationOption))) {
-        throw new CliError(`--duration は "auto" または数値で指定してください: ${durationOption}`);
+        throw new CliError(`--duration must be "auto" or a positive number (e.g. --duration 5): ${durationOption}`);
     }
     const outPath = resolveOutPath(parsed.values.out ?? DEFAULT_OUT_FILE);
     const pageGapSeconds = parseWithCliError(parsed.values['page-gap'] ?? '0', parseNonNegativeNumber);
+    const hideSelectors = parsed.values['hide-selector'] ?? [];
+    for (const selector of hideSelectors) {
+        parseWithCliError(selector, validateHideSelector);
+    }
+    const fps = parseWithCliError(parsed.values.fps ?? String(DEFAULT_FPS), parsePositiveInt);
+    if (fps > MAX_FPS) {
+        throw new CliError(`--fps must be at most ${MAX_FPS}: ${fps}`);
+    }
     return {
         urls: toNonEmptyArray(urls),
         outPath,
@@ -87,44 +122,55 @@ export function parseCliArgs(argv = process.argv.slice(2)) {
             ? resolveOutPath(parsed.values['log-file'])
             : deriveSidecarPath(outPath, '.log.jsonl'),
         viewport: parseWithCliError(parsed.values.viewport ?? DEFAULT_VIEWPORT, parseViewport),
-        fps: parseWithCliError(parsed.values.fps ?? String(DEFAULT_FPS), parsePositiveInt),
+        fps,
         duration: durationOption === 'auto'
             ? 'auto'
             : parseWithCliError(durationOption, parsePositiveNumber),
         motion: parseWithCliError(parsed.values.motion ?? DEFAULT_MOTION, parseMotion),
         timeoutMs: parseWithCliError(parsed.values.timeout ?? String(DEFAULT_TIMEOUT_MS), parsePositiveInt),
         waitFor: parseWithCliError(parsed.values['wait-for'] ?? 'load', parseWaitFor),
-        hideSelectors: parsed.values['hide-selector'] ?? [],
+        hideSelectors,
         pageGapSeconds,
         debugFramesDir: parsed.values['debug-frames-dir']
             ? resolveOutPath(parsed.values['debug-frames-dir'])
             : undefined,
+        force: parsed.values.force === true,
     };
 }
 function toNonEmptyArray(items) {
     if (items.length === 0) {
-        throw new CliError('capture にはURLが必要です。', true);
+        throw new CliError('capture requires at least one URL.', true);
     }
     return items;
 }
 export function formatUsage() {
     return [
+        `rollberry v${VERSION} — Capture smooth scroll videos from web pages`,
+        '',
         'Usage:',
         '  rollberry capture <url...> [options]',
+        '  rollberry --help | -h',
+        '  rollberry --version | -V',
         '',
         'Options:',
         '  --out <file>                Output MP4 path (default: ./rollberry.mp4)',
         '  --viewport <WxH>           Viewport size (default: 1440x900)',
-        '  --fps <n>                  Frames per second (default: 60)',
+        `  --fps <n>                  Frames per second (default: 60, max: ${MAX_FPS})`,
         '  --duration <seconds|auto>  Capture duration (default: auto)',
-        '  --motion <curve>           ease-in-out-sine | linear',
+        '  --motion <curve>           ease-in-out-sine | linear (default: ease-in-out-sine)',
         '  --timeout <ms>             Navigation timeout (default: 30000)',
-        '  --wait-for <mode>          load | selector:<css> | ms:<n>',
-        '  --hide-selector <css>      Hide CSS selector before capture',
+        '  --wait-for <mode>          load | selector:<css> | ms:<n> (default: load)',
+        '  --hide-selector <css>      Hide CSS selector before capture (repeatable)',
+        '  --force                    Overwrite output file if it already exists',
         '  --debug-frames-dir <dir>   Save raw PNG frames for debugging',
         '  --page-gap <seconds>       Pause between pages (default: 0)',
         '  --manifest <file>          Manifest JSON path (default: <out>.manifest.json)',
         '  --log-file <file>          Log JSONL path (default: <out>.log.jsonl)',
+        '',
+        'Examples:',
+        '  rollberry capture http://localhost:3000',
+        '  rollberry capture https://example.com --out demo.mp4 --viewport 1920x1080',
+        '  rollberry capture https://example.com --duration 10 --fps 30 --force',
     ].join('\n');
 }
 function parseWithCliError(rawValue, parser) {
@@ -135,7 +181,7 @@ function parseWithCliError(rawValue, parser) {
         if (error instanceof CliError) {
             throw error;
         }
-        throw new CliError(error instanceof Error ? error.message : '引数の解析に失敗しました。');
+        throw new CliError(error instanceof Error ? error.message : 'Failed to parse arguments.');
     }
 }
 function resolveOutPath(path) {
@@ -151,33 +197,33 @@ function deriveSidecarPath(path, suffix) {
 function parseViewport(rawViewport) {
     const match = /^(?<width>\d+)x(?<height>\d+)$/u.exec(rawViewport);
     if (!match?.groups) {
-        throw new Error(`--viewport は "1440x900" の形式で指定してください: ${rawViewport}`);
+        throw new Error(`--viewport must be in "WxH" format (e.g. "1440x900"): ${rawViewport}`);
     }
     const width = Number(match.groups.width);
     const height = Number(match.groups.height);
     if (width <= 0 || height <= 0) {
-        throw new Error(`--viewport の値が不正です: ${rawViewport}`);
+        throw new Error(`--viewport dimensions must be positive (e.g. "1440x900"): ${rawViewport}`);
     }
     return { width, height };
 }
 function parsePositiveInt(rawValue) {
     const value = Number(rawValue);
     if (!Number.isInteger(value) || value <= 0) {
-        throw new Error(`正の整数を指定してください: ${rawValue}`);
+        throw new Error(`Expected a positive integer (e.g. "60"): ${rawValue}`);
     }
     return value;
 }
 function parsePositiveNumber(rawValue) {
     const value = Number(rawValue);
     if (!Number.isFinite(value) || value <= 0) {
-        throw new Error(`正の数値を指定してください: ${rawValue}`);
+        throw new Error(`Expected a positive number (e.g. "5.0"): ${rawValue}`);
     }
     return value;
 }
 function parseNonNegativeNumber(rawValue) {
     const value = Number(rawValue);
     if (!Number.isFinite(value) || value < 0) {
-        throw new Error(`0以上の数値を指定してください: ${rawValue}`);
+        throw new Error(`Expected a non-negative number (e.g. "0" or "1.5"): ${rawValue}`);
     }
     return value;
 }
@@ -185,7 +231,7 @@ function parseMotion(rawMotion) {
     if (rawMotion === 'ease-in-out-sine' || rawMotion === 'linear') {
         return rawMotion;
     }
-    throw new Error(`--motion は ease-in-out-sine または linear です: ${rawMotion}`);
+    throw new Error(`--motion must be "ease-in-out-sine" or "linear": ${rawMotion}`);
 }
 function parseWaitFor(rawWaitFor) {
     if (rawWaitFor === 'load') {
@@ -194,7 +240,7 @@ function parseWaitFor(rawWaitFor) {
     if (rawWaitFor.startsWith('selector:')) {
         const selector = rawWaitFor.slice('selector:'.length).trim();
         if (!selector) {
-            throw new Error('--wait-for selector:<css> の CSS セレクタが空です。');
+            throw new Error('--wait-for selector:<css> requires a non-empty CSS selector.');
         }
         return {
             kind: 'selector',
@@ -207,5 +253,5 @@ function parseWaitFor(rawWaitFor) {
             ms: parsePositiveInt(rawWaitFor.slice('ms:'.length)),
         };
     }
-    throw new Error(`--wait-for は load / selector:<css> / ms:<n> のいずれかです: ${rawWaitFor}`);
+    throw new Error(`--wait-for must be "load", "selector:<css>", or "ms:<n>": ${rawWaitFor}`);
 }

package/dist/run-capture.js

@@ -1,24 +1,26 @@
 import { writeFile } from 'node:fs/promises';
-import { captureVideo } from './capture/capture.js';
+import { AbortError, captureVideo } from './capture/capture.js';
 import { createCaptureLogger } from './capture/logger.js';
-export async function runCaptureCommand(options) {
+import { sanitizeUrl } from './capture/utils.js';
+export async function runCaptureCommand(options, progress, signal) {
     const logger = createCaptureLogger(options.logFilePath);
     const startedAt = new Date();
+    let capture;
+    const sanitizedUrls = options.urls.map((u) => sanitizeUrl(u));
     await logger.info('capture.start', 'Capture started', {
-        urls: options.urls.map((u) => u.toString()),
+        urls: sanitizedUrls,
         outPath: options.outPath,
         manifestPath: options.manifestPath,
         logFilePath: options.logFilePath,
     });
     try {
-        const capture = await captureVideo(options, logger);
+        capture = await captureVideo(options, logger, progress, signal);
         const finishedAt = new Date();
-        const warnings = capture.truncated
-            ? ['scroll_height_truncated']
-            : [];
+        const warnings = capture.truncated ? ['scroll_height_truncated'] : [];
         const manifest = buildManifest({
             status: 'succeeded',
             options,
+            sanitizedUrls,
             startedAt,
             finishedAt,
             warnings,
@@ -40,16 +42,22 @@ export async function runCaptureCommand(options) {
     }
     catch (error) {
         const finishedAt = new Date();
+        const isCancelled = error instanceof AbortError;
+        const warnings = capture?.truncated ? ['scroll_height_truncated'] : [];
         const manifest = buildManifest({
-            status: 'failed',
+            status: isCancelled ? 'cancelled' : 'failed',
             options,
+            sanitizedUrls,
             startedAt,
             finishedAt,
-            warnings: [],
-            videoCreated: false,
-            error,
+            warnings,
+            videoCreated: capture !== undefined,
+            result: capture,
+            error: isCancelled ? undefined : error,
         });
-        await logger.error('capture.failed', 'Capture failed', {
+        const logEvent = isCancelled ? 'capture.cancelled' : 'capture.failed';
+        const logMessage = isCancelled ? 'Capture cancelled' : 'Capture failed';
+        await logger.error(logEvent, logMessage, {
             name: manifest.error?.name,
             message: manifest.error?.message,
             manifestPath: options.manifestPath,
@@ -77,7 +85,7 @@ function buildManifest(input) {
             arch: process.arch,
         },
         options: {
-            urls: input.options.urls.map((u) => u.toString()),
+            urls: input.sanitizedUrls,
             viewport: input.options.viewport,
             fps: input.options.fps,
             duration: input.options.duration,

package/dist/version.js

@@ -0,0 +1 @@
+export const VERSION = '0.1.9';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rollberry",
-  "version": "0.1.5",
+  "version": "0.1.9",
   "description": "CLI to capture smooth top-to-bottom scroll videos from web pages, including localhost URLs.",
   "type": "module",
   "packageManager": "pnpm@10.15.0",