rollberry 0.1.0 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+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.3] - 2026-03-15
+
+### Changed
+
+- README now includes a dedicated `Using With npx` section with version-pinned
+  examples and common usage patterns.
+
+## [0.1.2] - 2026-03-15
+
+### Added
+
+- `SECURITY.md`, `CONTRIBUTING.md`, GitHub issue forms, and a pull request
+  template.
+- Contact guidance pointing users to https://co-r-e.com/contact where private
+  contact is required.
+
+### Changed
+
+- MIT copyright holder is now `CORe Inc.`.
+- Branch protection policy now also covers `develop` and `release/*`, with
+  `mokuwaki` as the only bypass user.
+
+## [0.1.1] - 2026-03-15
+
+### Added
+
+- MIT license metadata and `LICENSE` file for open source distribution.
+- GitHub Actions trusted publishing workflow for npm releases on `v*` tags.
+- Maintainer release process documentation for `npx rollberry ...` distribution.
+
+### Changed
+
+- README rewritten around real `npx` usage, common capture examples, and
+  operational troubleshooting.
+- Package metadata now includes repository, homepage, bug tracker, and keywords.
+
+## [0.1.0] - 2026-03-15
+
+### Added
+
+- Initial public CLI release for smooth top-to-bottom page capture.
+- `localhost`, `127.0.0.1`, and self-signed `https://localhost` support.
+- Sidecar manifest and JSONL log output.
+- Regression suite runner and fixture-backed integration tests.

package/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing to Rollberry
+
+Thank you for contributing to Rollberry.
+
+## Before You Start
+
+- Open an issue for bugs, feature requests, or larger changes before starting
+  implementation.
+- For security issues, do not open a public issue. Use
+  https://co-r-e.com/contact instead.
+- By contributing, you agree that your changes will be distributed under the
+  MIT license used by this repository.
+
+## Development Setup
+
+```bash
+corepack pnpm install
+corepack pnpm exec playwright install chromium
+corepack pnpm check
+corepack pnpm test
+```
+
+## Pull Request Expectations
+
+- Keep changes focused and avoid mixing unrelated work.
+- Update docs when CLI behavior or release/operational workflow changes.
+- Add or update tests when behavior changes.
+- Keep `README.md`, `CHANGELOG.md`, and sample config files aligned with the
+  code when relevant.
+
+## Branch Protection and Reviews
+
+The protected branches are:
+
+- `main`
+- `develop`
+- `release/*`
+
+For contributors other than `mokuwaki`:
+
+- direct push is not allowed on protected branches
+- merge requires at least one approval
+- the latest push must still be approved by someone else
+
+`mokuwaki` is the only configured bypass user for these protected branches.
+
+## Release Notes
+
+Rollberry remains on the `v0.x.x` line for now. Release prep should update:
+
+- `package.json`
+- `CHANGELOG.md`
+- any user-facing docs affected by the release

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CORe Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,21 +1,19 @@
 # Rollberry
 
-Rollberry は、指定した Web ページを上から下まで滑らかにスクロールさせた MP4 を生成する CLI です。`localhost`、`127.0.0.1`、`[::1]` の開発中 URL にも対応します。
+Rollberry is an MIT-licensed open source CLI for turning a web page into a
+smooth top-to-bottom scroll video. It is built for real browser capture, works
+with normal URLs and `localhost`, and is published for direct `npx` usage.
 
-## Requirements
+Maintained by CORe Inc.
 
-- Node.js `24.12.0+`
-- `ffmpeg` / `ffprobe`
-- macOS を優先サポート
+## Quick Start
 
-## Setup
+Requirements:
 
-```bash
-corepack pnpm install
-corepack pnpm exec playwright install chromium
-```
+- Node.js `24.12.0+`
+- `ffmpeg` and `ffprobe` available on `PATH`
 
-## Usage
+Install nothing globally. Run it directly:
 
 ```bash
 npx rollberry capture http://localhost:3000 \
@@ -27,55 +25,185 @@ npx rollberry capture http://localhost:3000 \
   --hide-selector '#cookie-banner'
 ```
 
-リポジトリ内で開発実行する場合は次です。
+On the first run, if Playwright Chromium is missing, Rollberry installs it
+automatically. `ffmpeg` is not auto-installed.
+
+## Using With npx
+
+The normal way to run Rollberry is `npx`.
+
+Use the latest published version:
 
 ```bash
-corepack pnpm dev -- capture http://localhost:3000 \
-  --out ./artifacts/demo.mp4 \
-  --viewport 1440x900 \
-  --fps 60 \
-  --duration auto \
-  --wait-for selector:body \
-  --hide-selector '#cookie-banner'
+npx rollberry capture http://localhost:3000 --out ./artifacts/demo.mp4
+```
+
+Pin a specific version:
+
+```bash
+npx rollberry@0.1.2 capture http://localhost:3000 --out ./artifacts/demo.mp4
 ```
 
-ビルド後は次でも実行できます。
+Capture a local development server:
 
 ```bash
-node dist/cli.js capture https://example.com --out ./artifacts/example.mp4
+npx rollberry capture http://localhost:3000 \
+  --out ./artifacts/local.mp4 \
+  --wait-for selector:body
 ```
 
-初回の `npx rollberry ...` 実行時に Chromium が未導入なら、Rollberry が Playwright Chromium を自動インストールします。`ffmpeg` / `ffprobe` は自動導入しないので、事前に PATH 上で使える必要があります。
+Capture a public page:
+
+```bash
+npx rollberry capture https://playwright.dev \
+  --out ./artifacts/playwright.mp4 \
+  --duration 8
+```
+
+Notes:
+
+- `npx` downloads the published CLI package automatically
+- on the first run, Rollberry installs Playwright Chromium if needed
+- `ffmpeg` and `ffprobe` must already be available on your machine
+- if you want reproducible automation, pin the package version with
+  `npx rollberry@<version> ...`
+
+## What You Get
+
+Each run writes:
 
-## Sidecar Outputs
+- `video.mp4`: the rendered capture
+- `video.manifest.json`: environment, options, result, and failure details
+- `video.log.jsonl`: structured operational logs
 
-各キャプチャのたびに次を出力します。
+You can override the sidecar paths with `--manifest` and `--log-file`.
 
-- `video.mp4`: 本体動画
-- `video.manifest.json`: 実行結果、環境、オプション、失敗内容
-- `video.log.jsonl`: 1 行 1 JSON の運用ログ
+## Common Examples
 
-`--manifest` と `--log-file` で出力先を個別に上書きできます。
+Capture a development site:
+
+```bash
+npx rollberry capture http://localhost:3000 --out ./artifacts/local.mp4
+```
+
+Capture a public site at a fixed duration:
+
+```bash
+npx rollberry capture https://playwright.dev \
+  --out ./artifacts/playwright.mp4 \
+  --duration 8 \
+  --fps 60
+```
+
+Wait for a selector and hide overlays:
+
+```bash
+npx rollberry capture https://example.com \
+  --wait-for selector:main \
+  --hide-selector '#cookie-banner' \
+  --hide-selector '.intercom-lightweight-app'
+```
+
+Dump raw frames for debugging:
+
+```bash
+npx rollberry capture http://localhost:3000 \
+  --out ./artifacts/debug.mp4 \
+  --debug-frames-dir ./artifacts/debug-frames
+```
+
+## CLI Options
+
+```text
+rollberry capture <url>
+
+--out <file>                Output MP4 path
+--viewport <WxH>            Viewport size, example: 1440x900
+--fps <n>                   Frames per second
+--duration <seconds|auto>   Explicit seconds or auto
+--motion <curve>            ease-in-out-sine | linear
+--timeout <ms>              Navigation timeout
+--wait-for <mode>           load | selector:<css> | ms:<n>
+--hide-selector <css>       Hide CSS selector before capture
+--debug-frames-dir <dir>    Save raw PNG frames
+--manifest <file>           Manifest JSON output path
+--log-file <file>           Log JSONL output path
+```
 
 ## Localhost Behavior
 
-- `http://localhost:*`、`https://localhost:*`、`http://127.0.0.1:*`、`http://[::1]:*` を許可
-- `localhost` 系では接続拒否を `--timeout` まで 500ms 間隔で再試行
-- `https://localhost` 系では自己署名証明書を許可
-- dev server の自動起動はしません。URL は事前に起動済みである前提です
+- Supports `http://localhost:*`, `https://localhost:*`,
+  `http://127.0.0.1:*`, and `http://[::1]:*`
+- Retries connection-refused errors until `--timeout`
+- Accepts self-signed certificates for localhost targets only
+- Does not start your dev server for you
+
+## Troubleshooting
+
+If `ffmpeg` is missing:
+
+```bash
+brew install ffmpeg
+```
+
+If capture fails, inspect:
+
+- `*.manifest.json` for final status and error details
+- `*.log.jsonl` for per-step structured logs
+
+If a site keeps shifting during capture:
+
+- wait for a stable selector with `--wait-for selector:...`
+- hide chat widgets, cookie banners, and sticky overlays with `--hide-selector`
+- keep dynamic dev-only overlays out of the page when possible
 
-## Recommended Operational Flow
+## Support and Contact
 
-1. `regression.sample.json` をコピーして自分たちの `regression.sites.json` を作る
-2. 重要な 10〜20 URL を登録する
-3. リリース前に `corepack pnpm regression -- --config ./regression.sites.json` を実行する
-4. `artifacts/regression/summary.json` と各 manifest を確認する
+- General contact: https://co-r-e.com/contact
+- Security issues: see [SECURITY.md](./SECURITY.md)
+- Contribution guide: see [CONTRIBUTING.md](./CONTRIBUTING.md)
 
-## Commands
+## Local Development
 
 ```bash
+corepack pnpm install
+corepack pnpm exec playwright install chromium
 corepack pnpm check
 corepack pnpm test
 corepack pnpm build
+```
+
+Run from the repository:
+
+```bash
+corepack pnpm dev -- capture http://localhost:3000 --out ./artifacts/demo.mp4
+```
+
+Run the regression suite:
+
+```bash
+cp regression.sample.json regression.sites.json
 corepack pnpm regression -- --config ./regression.sites.json
 ```
+
+## Release Flow
+
+Rollberry stays on the `v0.x.x` line for now.
+
+1. Update `package.json` version and `CHANGELOG.md`
+2. Commit the release prep
+3. Create an annotated tag like `git tag -a v0.1.2 -m "Release v0.1.2"`
+4. Push `main` and the tag to GitHub
+5. GitHub Actions publishes to npm via trusted publishing
+
+Trusted publishing setup expected by this repo:
+
+- GitHub repository: `co-r-e/rollberry`
+- Workflow filename: `.github/workflows/publish.yml`
+- Trigger: push tag `v*`
+- In npm package settings, add a trusted publisher that matches the repository
+  and workflow above
+
+## License
+
+[MIT](./LICENSE)

package/SECURITY.md

@@ -0,0 +1,23 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are provided for the latest published `v0.x.x` release and the
+current `main` branch on a best-effort basis.
+
+## Reporting a Vulnerability
+
+Do not open a public GitHub issue for suspected security vulnerabilities.
+
+Please contact us here instead:
+
+- https://co-r-e.com/contact
+
+Include as much detail as possible:
+
+- affected version
+- reproduction steps
+- impact assessment
+- proof of concept, if available
+
+We will review the report privately and respond through the contact channel.

package/package.json

@@ -1,12 +1,34 @@
 {
   "name": "rollberry",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "CLI to capture smooth top-to-bottom scroll videos from web pages, including localhost URLs.",
   "type": "module",
   "packageManager": "pnpm@10.15.0",
+  "author": "CORe Inc.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/co-r-e/rollberry.git"
+  },
+  "homepage": "https://github.com/co-r-e/rollberry#readme",
+  "bugs": {
+    "url": "https://github.com/co-r-e/rollberry/issues"
+  },
+  "keywords": [
+    "cli",
+    "playwright",
+    "scroll",
+    "video",
+    "automation",
+    "localhost"
+  ],
   "files": [
     "dist",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
     "README.md",
+    "SECURITY.md",
     "regression.sample.json"
   ],
   "bin": {