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을 확인한 다음 세 가지를 모두 클릭합니다. 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는 동일한 두 런타임 설치를 실행합니다.

상태: 게시된 서명되지 않은 사전 릴리스 v0.2.0-rc.1 at 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

증명

이 두 영수증은 공개 웨지입니다. example.com YAML이 아닙니다.

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

examples/mcp-policy/ 및 examples/ref-integrity/를 참조하세요. SnapRef를 호스트 어댑터 아래의 커널로 이야기하세요. 두 번째 브라우저 자동화 브랜드로 말하지 마세요.

골든 패스

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를 사용하세요. 유휴 만료는 쿠키/상태 재사용을 위해 명명된 프로필을 유지합니다. 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는 릴리스 아티팩트를 두 번 빌드합니다. 모든 아티팩트가 두 빌드에서 바이트 단위로 동일해야 합니다.

아티팩트 빌더는 로컬 모듈 캐시만 사용합니다. 종속성 다운로드, 워크스페이스 재정의, 사용자 Go 설정 및 자동 도구 체인 다운로드를 비활성화합니다.

라이브 snapref self-test는 하이드레이션된 스냅샷 준비 상태를 확인합니다. 또한 열린 섀도우 루트와 동일 출처 프레임에서 참조 조작을 확인합니다. 이 명령은 기계 영수증(--json)입니다. GitHub Actions는 Ubuntu에서 snapref runtime install --runtime chrome-for-testing 후에 실행합니다. 로컬 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/ 텍스트를 참조하세요.