SnapRef

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

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

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

Estado: 0.2.0-rc.1 en https://github.com/nstranquist/snapref. El soporte para Windows no se anuncia hasta que una compuerta física de Windows+Chrome pase.

Paquetes

• browser: sesiones, CDP, instantáneas/refs, capacidad de acción, 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 y autocomprobación en vivo.

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

Related MCP server: ChromePlayMCP

Ruta dorada

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 valor predeterminado. auto solo usa runtimes administrados verificados (o una anulación externa explícita SNAPREF_CHROME); nunca busca ni lanza la instalación personal del navegador del operador. El trabajo con headful y extensiones desempaquetadas 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 administrado. La instalación del runtime es explícita y es el único comando de navegador que descarga.

Las sesiones CLI con nombre tienen un arrendamiento de inactividad de 10 minutos a prueba de fallos; cada operación de navegador lo renueva. Use --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 reutilizar cookies/estado; snapref gc previsualiza sesiones y perfiles muertos obsoletos, y snapref gc --apply los recupera. Tome una instantánea antes de actuar. Use la ref más reciente. Los permisos de MCP de conducción, lectura de host, escritura de host y orígenes son autoridades separadas SNAPREF_MCP_*.

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 perezosa específica de la aplicación ni los desplazamientos reveladores. 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 idéntico byte a byte en ambas construcciones.

El constructor de artefactos usa solo la caché de módulos local. Desactiva descargas de dependencias, anulaciones de espacio de trabajo, configuraciones de usuario de Go y descargas automáticas de toolchain.

La autocomprobación en vivo snapref self-test 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 de mismo origen.

make release-dist construye de forma reproducible archivos CGO-free para macOS arm64, Linux amd64 y Windows amd64 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. Solo cambia 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 de sistema de archivos, el árbol fuente, ancestros del árbol fuente, salidas de enlaces simbólicos y artefactos administrados 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 elimine ese directorio hasta que restaure o copie los artefactos retenidos.

Use 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 resumen de cada ruta de 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 en la deriva de permisos. Una discrepancia de resumen 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 vinculados a revisiones, capacidad de acción, grabaciones y runtimes administrados.

• 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. Los permisos de conducción, lectura de host, escritura de host y orígenes son autoridades separadas.

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

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

Consulte 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úe sobre la ref más reciente vinculada a revisión. eval es una vía de escape, no la ruta de descubrimiento. Los permisos de conducción, lectura de host, escritura de host y orígenes 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 fotos fijas no.

Solución de problemas

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

• Sesión ausente 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: tome una nueva snapshot y use la ref sr-… más reciente.

• Actuación MCP rechazada: establezca SNAPREF_MCP_ALLOW_DRIVE=1 (o --allow-drive) y una lista de permitidos de orígenes si restringe hosts.

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

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

Apache-2.0. Consulte SECURITY.md, docs/VERSIONING.md, NOTICE, THIRD_PARTY_NOTICES.md y los textos de third_party/licenses/ incluidos antes de redistribuir.