SnapRef

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

タグ v0.2.0-rc.1 は公開された未署名のプレリリースです。self-test を含みます。demo は含みません。

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

ウェッジのレシートはこのチェックアウトにあります:

go run ./cmd/snapref demo mcp-policy
go run ./cmd/snapref runtime install --runtime chrome-for-testing --channel stable
go run ./cmd/snapref demo ref-integrity

self-test は、遅延ハイドレーション、オープンなシャドウルート、同一オリジンの iframe をチェックし、3 つすべてをクリックします。demo mcp-policy は Chrome を起動しません。demo ref-integrity は管理されたランタイムを必要とします。

GitHub Actions の go とローカルの make verify は -short を渡すため、make init 後でも Chrome を起動しません。Ubuntu の self-test ジョブは Chrome for Testing をインストールし、snapref self-test と snapref demo ref-integrity を実行します。demo mcp-policy は go test でカバーされています。

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

ステータス: 公開された未署名のプレリリース v0.2.0-rc.1 は https://github.com/nstranquist/snapref にあります。ウェッジ demo のレシートはこのチェックアウトにあり、そのタグにはありません。Windows サポートは、物理的な Windows+Chrome ゲートが合格するまで宣伝されません。

パッケージ

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

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

• script: YAML/JSON/Starlark の反復可能なワークフローエンジン;

• mcp: ポリシーでゲートされた MCP stdio サーバー;

• cmd/snapref: スタンドアロン CLI、ライブセルフテスト、チェックアウトデモのレシート。

スタンドアロンの skill および job-posting コマンドは、汎用の型付き抽出のみを出力します。ホスト固有の製品ハンドオフはこのモジュールの外部にあります。

Related MCP server: ChromePlayMCP

証明

これら 2 つのレシートは公開ウェッジです。example.com の YAML ではありません。

go run ./cmd/snapref demo mcp-policy
go run ./cmd/snapref demo ref-integrity

examples/mcp-policy/ と examples/ref-integrity/ を参照してください。SnapRef をホストアダプタの下のカーネルとして話し、2 番目のブラウザ自動化ブランドとしては話さないでください。

ゴールデンパス

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 は、ハイドレートされたスナップショットの準備状態を検証します。また、オープンなシャドウルートと同一オリジンのフレームにわたる参照操作を検証します。そのコマンドはマシンレシート（--json）です。GitHub Actions は、snapref runtime install --runtime chrome-for-testing の後に Ubuntu でそれを実行します。ローカルの make verify は -short を渡し、Chrome を起動しません。make init 後、ライブレシートは snapref self-test、snapref demo ref-integrity、および make test-live です。

snapref demo mcp-policy はドライブ/オリジン許可のレシートです。snapref demo ref-integrity は古い参照のレシートです: スナップショット、sr-… をクリック、再度スナップショット、古い参照はフェイルクローズします。

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/ テキストを参照してください。