SnapRef

SnapRef は、依存関係が少なく、ローカルファーストのブラウザ自動化コアです。エージェント向けに、分離されたセッション、リビジョンに紐づく実行可能な参照を持つインタラクティブなスナップショット、型付きの操作・検証、スクリプト、ポリシーで制御される MCP、テレメトリの受領証、クロスプラットフォームのライフサイクルゲートを提供します。

go install github.com/nstranquist/snapref/cmd/snapref@v0.2.0-rc.1
snapref runtime install --runtime chrome-for-testing --channel stable
snapref runtime install --runtime headless-shell --channel stable
snapref self-test

ソースチェックアウトでは、make init が同じ2つのランタイムインストールを実行します。

ステータス: https://github.com/nstranquist/snapref にて 0.2.0-rc.1。Windows サポートは、物理的な Windows+Chrome ゲートが合格するまで宣伝されません。

パッケージ

• browser: セッション、CDP、スナップショット/参照、操作可能性、証跡、スキル。

• contract: 型付きの操作/権限/結果レジストリ。

• script: YAML/JSON/Starlark による反復可能なワークフローエンジン。

• mcp: ポリシーで制御される MCP stdio サーバー。

• cmd/snapref: スタンドアロン CLI とライブ自己テスト。

スタンドアロンの skill および job-posting コマンドは、汎用の型付き抽出のみを出力します。ホスト固有の成果物の引き渡しは、このモジュールの範囲外です。

Related MCP server: ChromePlayMCP

ゴールデンパス

snapref runtime install --runtime chrome-for-testing --channel stable
snapref runtime install --runtime headless-shell --channel stable
snapref runtime verify --all
snapref open demo
snapref exec demo navigate http://localhost:3000
snapref exec demo snapshot --wait-for-selector '[data-test="app-ready"]' --settle 1s
snapref exec demo click 'sr-…:e1'
snapref close demo --purge-profile

ヘッドレスがデフォルトです。auto は検証済みの管理ランタイム（または明示的な SNAPREF_CHROME 外部オーバーライド）のみを使用し、オペレーターの個人用ブラウザインストールを検索または起動することはありません。ヘッドフルおよび未パック拡張機能の作業は Chrome for Testing にルーティングされます。通常のヘッドレス作業では、正確なバージョンのローカル受け入れベンチマークが合格した場合にのみ Headless Shell を使用し、それ以外は管理された Chrome for Testing を使用します。ランタイムのインストールは明示的であり、ダウンロードを実行する唯一のブラウザコマンドです。

名前付き CLI セッションには、クラッシュセーフな10分間のアイドルリースがあります。すべてのブラウザ操作がそれを更新します。より長い有界ワークフローには --idle-timeout（または SNAPREF_BROWSER_IDLE_TIMEOUT）を使用し、--keep-alive は永続化が意図的な場合にのみ使用してください。アイドル期限切れは、Cookie/状態の再利用のために名前付きプロファイルを保持します。snapref gc は古いデッドセッションとプロファイルをプレビューし、snapref gc --apply でそれらを回収します。操作の前にスナップショットを取得してください。最新の参照を使用してください。MCP ドライブ、ホスト読み取り、ホスト書き込み、オリジン許可は、それぞれ独立した SNAPREF_MCP_* 権限です。

スクリーンショットはデフォルトで全ページです。YAML/JSON プレイブックは、アーカイブ証跡用に screenshot_mode: full-page を、正確な折り目/フォーカス証跡用に screenshot_mode: viewport を宣言できます。個々のステップでプランを上書きできます。全ページキャプチャはレンダリングされたドキュメントを測定しますが、アプリケーション固有の遅延読み込みやスクロール表示をトリガーしません。各スクリプトの受領証には、有効なモードと測定された PNG の幅/高さが記録されます。

検証

make verify
make verify-release

make verify は、テスト、レース検出器、vet、ネイティブコンパイル、Windows クロスコンパイル、リリース契約チェックを実行します。

make verify-release はリリース成果物を2回ビルドします。すべての成果物が両ビルド間でバイト単位で同一であることが必要です。

成果物ビルダーはローカルモジュールキャッシュのみを使用します。依存関係のダウンロード、ワークスペースのオーバーライド、ユーザーの Go 設定、自動ツールチェーンのダウンロードを無効にします。

ライブの snapref self-test は、ハイドレートされたスナップショットの準備状態を検証します。また、開いているシャドウルートと同一オリジンフレーム間での参照操作を検証します。

make release-dist は、CGO フリーの macOS arm64、Linux amd64、Windows amd64 アーカイブを、法的/セキュリティファイルと SHA256SUMS マニフェストとともに再現可能にビルドします。公開はしません。

リリースコマンドは、兄弟ステージングディレクトリ内のすべてのファイルをビルドします。既存の出力ディレクトリ内の名前付きアーカイブと SHA256SUMS のみを変更します。

無関係な出力ファイルは変更されません。コマンドは、ファイルシステムルート、ソースツリー、ソースツリーの祖先、シンボリックリンク出力、および非通常の管理成果物を拒否します。

公開エラー後の復元が失敗した場合、コマンドはリカバリステージングディレクトリを出力して保持します。保持された成果物を復元またはコピーするまで、そのディレクトリを削除しないでください。

オペレーター制御の出力ディレクトリを使用してください。リリーストランザクションは、ディレクトリを同時に変更する信頼できないプロセスから保護しません。

EXTRACTION.json は、共有ソースパス、正規の通常ファイルモード、ファイルバイトのダイジェストを固定します。Windows チェックアウトの権限は、リポジトリの必須 0644 モードに正規化されます。他のプラットフォームでは権限のずれで失敗します。ダイジェストの不一致は、チェックアウトされたツリーがレビュー済みソースロックからずれたことを意味し、リリース前に再同期する必要があります。

バージョン付きの公開成果物契約は、schemas/telemetry-v2.schema.json と schemas/script-run-v2.schema.json にあります。各リリースアーカイブには、両方のスキーマと docs/VERSIONING.md が含まれます。

アーキテクチャ

SnapRef はローカルエンジンであり、ホスト型ブラウザフリートではありません。

• browser は、分離された Chromium セッション、CDP、スナップショット、リビジョンに紐づく参照、操作可能性、録画、管理ランタイムを所有します。

• contract は、型付きの操作および権限レジストリです。

• script は、開いているセッションに対して YAML/JSON/Starlark プランを実行します。

• mcp は、ポリシーで制御される stdio サーバーです。ドライブ、ホスト読み取り、ホスト書き込み、オリジン許可は独立した権限です。

• cmd/snapref はスタンドアロン CLI です。ホストアダプターはこのモジュールの外部にあります。

• processtree は、リリースおよびベンチマークツールでの有界サブプロセスキャンセルにのみ使用される、ベンダー提供の MIT コピーです。

docs/ARCHITECTURE.md を参照してください。

使用法

snapref open demo
snapref exec demo navigate https://example.com
snapref exec demo snapshot --wait-for-selector body --settle 1s
snapref exec demo click 'sr-…:e1'
snapref close demo --purge-profile
snapref mcp

snapshot がディスカバリのデフォルトです。最新のリビジョンに紐づく参照に対して操作してください。eval はエスケープハッチであり、ディスカバリパスではありません。MCP ドライブ、ホスト読み取り、ホスト書き込み、オリジン許可は、それぞれ独立した明示的な権限です。

設定

ランタイムのインストールは、ダウンロードを実行する唯一のコマンドです。ビデオまたは GIF をエンコードする録画パックには PATH 上の ffmpeg が必要です。静止画パックには不要です。

トラブルシューティング

• no Chromium-class browser found: snapref runtime install --runtime chrome-for-testing --channel stable を実行してください。

• アイドル後にセッションが消えた: 名前付きセッションは10分で期限切れになります。プロファイルは close --purge-profile または gc --apply まで残ります。

• 古い実行可能参照: 新しい snapshot を取得し、最新の sr-… 参照を使用してください。

• MCP 操作が拒否された: SNAPREF_MCP_ALLOW_DRIVE=1（または --allow-drive）を設定し、ホストを制限する場合はオリジン許可リストを設定してください。

• クラッシュ後の already recording: 次のインプロセス起動で放棄されたインプロセス状態が回収されます。PID がスタンプされる前に失敗したデタッチ起動は、$SNAPREF_HOME/recordings/<name>（デフォルト ~/.snapref/browser/recordings/<name>）を削除して除去する必要があります。デタッチされた PID がまだ生きている場合は、先にそのプロセスを停止してください。

• ビデオエンコードに失敗: ffmpeg をインストールしてください。静止画パックには不要です。CLI は失敗時に制限付きの ffmpeg stderr を出力します。

Apache-2.0。再配布前に SECURITY.md、docs/VERSIONING.md、NOTICE、THIRD_PARTY_NOTICES.md、および同梱の third_party/licenses/ テキストを参照してください。