SnapRef

SnapRef는 에이전트를 위한 의존성이 적고 로컬 우선(local-first) 브라우저 자동화 코어입니다: 격리된 세션, 개정(revision)에 바인딩된 실행 가능한 참조(ref)가 포함된 대화형 스냅샷, 타입이 있는 실행/검증(actuation/assertion), 스크립트, 정책 기반 MCP, 텔레메트리 영수증(receipt), 플랫폼 간 수명주기 게이트를 제공합니다.

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는 동일한 두 런타임 설치를 실행합니다.

상태: 0.2.0-rc.1 at https://github.com/nstranquist/snapref. Windows 지원은 실제 Windows+Chrome 게이트를 통과하기 전까지는 공지되지 않습니다.

패키지

• browser: 세션, CDP, 스냅샷/참조, 동작 가능성(actionability), 증거, 스킬;

• 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 외부 재정의를 사용). 운영자의 개인 브라우저 설치를 검색하거나 실행하지 않습니다. 헤드풀(headful) 및 압축 해제된 확장 프로그램 작업은 Chrome for Testing으로 라우팅됩니다. 일반적인 헤드리스 작업은 정확한 버전의 로컬 수용 벤치마크가 통과한 후에만 Headless Shell을 사용하며, 그렇지 않으면 관리형 Chrome for Testing을 사용합니다. 런타임 설치만 명시적이며 다운로드를 수행하는 유일한 브라우저 명령입니다.

명명된 CLI 세션은 크래시에 안전한 10분 유휴 임대(idle lease)를 갖습니다. 모든 브라우저 작업이 이를 갱신합니다. 더 긴 제한 시간 워크플로에는 --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는 수화된(hydrated) 스냅샷 준비 상태를 확인합니다. 또한 열린 shadow root와 동일 출처 프레임에서 참조 실행을 확인합니다.

make release-dist는 법적/보안 파일과 SHA256SUMS 매니페스트가 포함된 CGO가 없는 macOS arm64, Linux amd64, Windows amd64 아카이브를 재현 가능하게 빌드합니다. 이를 게시하지는 않습니다.

릴리스 명령은 모든 파일을 형제 스테이징 디렉터리에 빌드합니다. 기존 출력 디렉터리에서 명명된 아카이브와 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은 발견(discovery) 기본값입니다. 가장 새로운 개정 바인딩 참조로 작업하세요. eval은 탈출구(escape hatch)이지 발견 경로가 아닙니다. 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/ 텍스트를 참조하세요.