SnapRef

SnapRef es un núcleo de automatización de navegador local primero y con pocas dependencias para agentes: sesiones aisladas, instantáneas interactivas con referencias ejecutables vinculadas a revisión, actuación/aserción tipada, scripts, MCP con políticas, recibos de telemetría y puertas de ciclo de vida multiplataforma.

La etiqueta v0.2.0-rc.1 es la prepublicación sin firmar publicada. Incluye self-test. No incluye 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

Los recibos de cuña están en este checkout:

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 comprueba la hidratación diferida, los shadow roots abiertos y los iframes del mismo origen, y luego hace clic en los tres. demo mcp-policy no lanza Chrome. demo ref-integrity necesita un runtime gestionado.

GitHub Actions go y make verify local pasan -short, por lo que no lanzan Chrome incluso después de make init. El trabajo self-test de Ubuntu instala Chrome for Testing y ejecuta snapref self-test además de snapref demo ref-integrity. demo mcp-policy está cubierto por go test.

En un checkout de código fuente, make init ejecuta las mismas dos instalaciones de runtime.

Estado: prepublicación sin firmar publicada v0.2.0-rc.1 en https://github.com/nstranquist/snapref. Los recibos de demo de cuña están en este checkout, no en esa etiqueta. El soporte de Windows no se anuncia hasta que una puerta física de Windows+Chrome pase.

Paquetes

• browser: sesiones, CDP, instantáneas/refs, accionabilidad, evidencia, habilidades;

• contract: registro tipado de operaciones/permisos/resultados;

• script: motor de flujos de trabajo repetibles YAML/JSON/Starlark;

• mcp: servidor MCP stdio con políticas;

• cmd/snapref: CLI independiente, autocomprobación en vivo y recibos de demo del checkout.

Los comandos independientes skill y job-posting emiten solo extracción tipada genérica. Las transferencias de productos específicos del host están fuera de este módulo.

Related MCP server: ChromePlayMCP

Pruebas

Estos dos recibos son la cuña pública. No son YAML de example.com.

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

Ver examples/mcp-policy/ y examples/ref-integrity/. Habla de SnapRef como el núcleo bajo el adaptador del host, no como una segunda marca de automatización de navegador.

Camino dorado

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

Headless es el predeterminado. auto usa solo runtimes gestionados verificados (o un override externo explícito SNAPREF_CHROME); nunca busca ni lanza la instalación personal del navegador del operador. El trabajo headful y de extensión desempaquetada se enruta a Chrome for Testing. El trabajo headless ordinario usa Headless Shell solo después de que pase un benchmark de aceptación local de versión exacta; de lo contrario, usa Chrome for Testing gestionado. La instalación del runtime es explícita y es el único comando de navegador que descarga.

Las sesiones CLI con nombre tienen una concesión de inactividad de 10 minutos a prueba de bloqueos; cada operación del navegador la renueva. Usa --idle-timeout (o SNAPREF_BROWSER_IDLE_TIMEOUT) para un flujo de trabajo acotado más largo y --keep-alive solo cuando la persistencia sea intencional. La expiración por inactividad conserva el perfil con nombre para reutilización de cookies/estado; snapref gc previsualiza sesiones y perfiles muertos obsoletos, y snapref gc --apply los reclama. Haz una instantánea antes de actuar. Usa la ref más reciente. La conducción MCP, la lectura del host, la escritura del host y los permisos de origen son autoridades SNAPREF_MCP_* separadas.

Las capturas de pantalla son de página completa por defecto. Los playbooks YAML/JSON pueden declarar screenshot_mode: full-page para evidencia de archivo o screenshot_mode: viewport para evidencia exacta de pliegue/enfoque; un paso individual puede anular el plan. La captura de página completa mide el documento renderizado pero no activa la carga diferida específica de la aplicación ni las revelaciones por desplazamiento. Cada recibo de script registra el modo efectivo y el ancho/alto PNG medido.

Verificar

make verify
make verify-release

make verify ejecuta pruebas, el detector de carreras, vet, compilación nativa, compilación cruzada de Windows y comprobaciones de contrato de lanzamiento.

make verify-release también construye los artefactos de lanzamiento dos veces. Requiere que cada artefacto sea byte-idéntico en ambas construcciones.

El constructor de artefactos usa solo la caché de módulos local. Desactiva las descargas de dependencias, los overrides del workspace, la configuración de Go del usuario y las descargas automáticas de toolchain.

El snapref self-test en vivo verifica la preparación de instantáneas hidratadas. También verifica la actuación de refs a través de shadow roots abiertos y marcos del mismo origen. Ese comando es un recibo de máquina (--json). GitHub Actions lo ejecuta en Ubuntu después de snapref runtime install --runtime chrome-for-testing. El make verify local pasa -short y no lanza Chrome. Después de make init, los recibos en vivo son snapref self-test, snapref demo ref-integrity y make test-live.

snapref demo mcp-policy es el recibo de conducción/permiso de origen. snapref demo ref-integrity es el recibo de ref obsoleta: instantánea, clic en sr-…, instantánea de nuevo, la ref antigua falla de forma segura.

make release-dist construye de forma reproducible archivos macOS arm64, Linux amd64 y Windows amd64 sin CGO con archivos legales/seguridad y un manifiesto SHA256SUMS. No los publica.

El comando de lanzamiento construye todos los archivos en un directorio de staging hermano. Cambia solo los archivos nombrados y SHA256SUMS en un directorio de salida existente.

Los archivos de salida no relacionados permanecen sin cambios. El comando rechaza raíces del sistema de archivos, el árbol fuente, los ancestros del árbol fuente, las salidas de enlaces simbólicos y los artefactos gestionados no regulares.

Si la restauración falla después de un error de publicación, el comando imprime y conserva el directorio de staging de recuperación. No elimines ese directorio hasta que restaures o copies los artefactos retenidos.

Usa un directorio de salida controlado por el operador. La transacción de lanzamiento no protege contra un proceso no confiable que cambie el directorio concurrentemente.

EXTRACTION.json fija un digest de cada ruta fuente compartida, modo de archivo regular canónico y byte de archivo. Los permisos de checkout de Windows se normalizan al modo 0644 requerido por el repositorio; otras plataformas fallan ante la deriva de permisos. Una discrepancia de digest significa que el árbol verificado se desvió del bloqueo de fuente revisado y debe resincronizarse antes de un lanzamiento.

Los contratos de artefactos públicos versionados viven en schemas/telemetry-v2.schema.json y schemas/script-run-v2.schema.json. Cada archivo de lanzamiento incluye ambos esquemas y docs/VERSIONING.md.

Arquitectura

SnapRef es un motor local, no una flota de navegadores alojados.

• browser posee sesiones de Chromium aisladas, CDP, instantáneas, refs vinculadas a revisión, accionabilidad, grabaciones y runtimes gestionados.

• contract es el registro tipado de operaciones y permisos.

• script ejecuta planes YAML/JSON/Starlark contra una sesión abierta.

• mcp es un servidor stdio con políticas. La conducción, la lectura del host, la escritura del host y los permisos de origen son autoridades separadas.

• cmd/snapref es la CLI independiente. Los adaptadores de host viven fuera de este módulo.

• processtree es una copia MIT vendida usada solo para la cancelación acotada de subprocesos en herramientas de lanzamiento y benchmark.

Ver docs/ARCHITECTURE.md.

Uso

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 es el predeterminado de descubrimiento. Actúa sobre la ref vinculada a revisión más reciente. eval es una vía de escape, no la ruta de descubrimiento. La conducción MCP, la lectura del host, la escritura del host y los permisos de origen son autoridades explícitas separadas.

Configuración

La instalación del runtime es el único comando que descarga. Los paquetes de grabación que codifican video o GIF requieren ffmpeg en PATH; los paquetes de fotogramas fijos no.

Solución de problemas

• no Chromium-class browser found: ejecuta snapref runtime install --runtime chrome-for-testing --channel stable.

• Sesión faltante después de inactividad: las sesiones con nombre expiran después de 10 minutos; el perfil permanece hasta close --purge-profile o gc --apply.

• Ref ejecutable obsoleta: toma una nueva snapshot y usa la ref sr-… más reciente.

• Actuación MCP rechazada: establece SNAPREF_MCP_ALLOW_DRIVE=1 (o --allow-drive) y una lista de permitidos de origen si restringes hosts.

• already recording después de un bloqueo: el siguiente inicio en proceso reclama el estado en proceso abandonado. Un inicio separado que falló antes de que se sellara un PID debe eliminarse: borra $SNAPREF_HOME/recordings/<name> (por defecto ~/.snapref/browser/recordings/<name>). Si un PID separado sigue vivo, detén ese proceso primero.

• La codificación de video falla: instala ffmpeg; los paquetes de fotogramas fijos no lo necesitan. La CLI imprime un stderr de ffmpeg acotado en caso de fallo.

Apache-2.0. Ver SECURITY.md, docs/VERSIONING.md, NOTICE, THIRD_PARTY_NOTICES.md y los textos incluidos en third_party/licenses/ antes de la redistribución.