SnapRef

SnapRef ist ein abhängigkeitsarmer, lokaler Browser-Automatisierungskern für Agenten: isolierte Sitzungen, interaktive Snapshots mit revisionsgebundenen ausführbaren Referenzen, typisierte Aktuierung/Assertion, Skripte, richtliniengesteuertes MCP, Telemetrie-Belege und plattformübergreifende Lebenszyklus-Gates.

Das Tag v0.2.0-rc.1 ist die veröffentlichte unsignierte Vorabversion. Es enthält self-test. Es enthält nicht 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

Wedge-Belege befinden sich in diesem 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 prüft verzögerte Hydration, offene Shadow Roots und Same-Origin- Iframes und klickt dann alle drei an. demo mcp-policy startet kein Chrome. demo ref-integrity benötigt eine verwaltete Laufzeit.

GitHub Actions go und lokales make verify bestehen mit -short, sodass sie auch nach make init kein Chrome starten. Der Ubuntu-self-test-Job installiert Chrome for Testing und führt snapref self-test sowie snapref demo ref-integrity aus. demo mcp-policy wird durch go test abgedeckt.

In einem Quell-Checkout führt make init dieselben zwei Laufzeitinstallationen aus.

Status: veröffentlichte unsignierte Vorabversion v0.2.0-rc.1 unter https://github.com/nstranquist/snapref. Wedge-demo-Belege befinden sich in diesem Checkout, nicht in diesem Tag. Windows-Support wird erst beworben, wenn ein physisches Windows+Chrome-Gate besteht.

Pakete

• browser: Sitzungen, CDP, Snapshots/Referenzen, Aktionsfähigkeit, Beweise, Fähigkeiten;

• contract: typisierte Operations-/Berechtigungs-/Ergebnis-Registry;

• script: YAML/JSON/Starlark-Workflow-Engine für wiederholbare Abläufe;

• mcp: richtliniengesteuerter MCP-stdio-Server;

• cmd/snapref: eigenständige CLI, Live-Selbsttest und Checkout-Demo-Belege.

Die eigenständigen skill- und job-posting-Befehle geben nur generische typisierte Extraktion aus. Hostspezifische Produktübergaben liegen außerhalb dieses Moduls.

Related MCP server: Ghostlight

Beweise

Diese beiden Belege sind der öffentliche Wedge. Sie sind kein example.com-YAML.

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

Siehe examples/mcp-policy/ und examples/ref-integrity/. Sprechen Sie über SnapRef als den Kernel unter dem Host-Adapter, nicht als eine zweite Browser-Automatisierungsmarke.

Goldener Pfad

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 ist die Standardeinstellung. auto verwendet nur verifizierte verwaltete Laufzeiten (oder eine explizite SNAPREF_CHROME-externe Überschreibung); es sucht oder startet niemals die persönliche Browserinstallation des Bedieners. Headful- und Unpacked-Extension-Arbeit führt zu Chrome for Testing. Gewöhnliche Headless-Arbeit verwendet Headless Shell nur, nachdem ein lokaler Akzeptanz-Benchmark mit exakter Version besteht; andernfalls verwendet es verwaltetes Chrome for Testing. Die Laufzeitinstallation ist explizit und ist der einzige Browserbefehl, der Downloads durchführt.

Benannte CLI-Sitzungen haben eine absturzsichere 10-minütige Leerlauf-Lease; jede Browseroperation erneuert sie. Verwenden Sie --idle-timeout (oder SNAPREF_BROWSER_IDLE_TIMEOUT) für einen längeren begrenzten Workflow und --keep-alive nur, wenn Persistenz beabsichtigt ist. Der Ablauf der Leerlaufzeit behält das benannte Profil für Cookie-/Zustandswiederverwendung; snapref gc zeigt eine Vorschau veralteter toter Sitzungen und Profile, und snapref gc --apply gibt sie frei. Machen Sie einen Snapshot, bevor Sie handeln. Verwenden Sie die neueste Referenz. MCP-Antrieb, Host-Lesen, Host-Schreiben und Ursprungs- Gewährungen sind separate SNAPREF_MCP_*-Autoritäten.

Screenshots sind standardmäßig ganzseitig. YAML/JSON-Playbooks können screenshot_mode: full-page für Archivbeweise oder screenshot_mode: viewport für exakte Falz-/Fokusbeweise deklarieren; ein einzelner Schritt kann den Plan überschreiben. Die Ganzseitenaufnahme misst das gerenderte Dokument, löst jedoch kein anwendungsspezifisches Lazy Loading oder Scroll-Reveals aus. Jeder Skript-Beleg zeichnet den effektiven Modus und die gemessene PNG-Breite/-Höhe auf.

Verifizieren

make verify
make verify-release

make verify führt Tests, den Race-Detektor, vet, native Kompilierung, Windows- Kreuzkompilierung und Release-Vertragsprüfungen aus.

make verify-release erstellt die Release-Artefakte außerdem zweimal. Es erfordert, dass jedes Artefakt über beide Builds byteidentisch ist.

Der Artefakt-Builder verwendet nur den lokalen Modul-Cache. Er deaktiviert Abhängigkeits-Downloads, Workspace-Überschreibungen, Benutzer-Go-Einstellungen und automatische Toolchain-Downloads.

Der Live-snapref self-test verifiziert die Bereitschaft hydrierter Snapshots. Er verifiziert auch die Referenz-Aktuierung über offene Shadow Roots und Same-Origin-Frames hinweg. Dieser Befehl ist ein Maschinen-Beleg (--json). GitHub Actions führt ihn auf Ubuntu nach snapref runtime install --runtime chrome-for-testing aus. Lokales make verify übergibt -short und startet kein Chrome. Nach make init sind Live-Belege snapref self-test, snapref demo ref-integrity und make test-live.

snapref demo mcp-policy ist der Antriebs-/Ursprungs-Gewährungs-Beleg. snapref demo ref-integrity ist der veraltete Referenz-Beleg: Snapshot, klicken Sie sr-…, Snapshot erneut, alte Referenz schlägt geschlossen fehl.

make release-dist erstellt reproduzierbar CGO-freie macOS-arm64-, Linux-amd64- und Windows-amd64-Archive mit Rechts-/Sicherheitsdateien und einem SHA256SUMS-Manifest. Es veröffentlicht sie nicht.

Der Release-Befehl erstellt alle Dateien in einem Geschwister-Staging-Verzeichnis. Er ändert nur die benannten Archive und SHA256SUMS in einem vorhandenen Ausgabeverzeichnis.

Nicht zusammenhängende Ausgabedateien bleiben unverändert. Der Befehl lehnt Dateisystemwurzeln, den Quellbaum, Vorfahren des Quellbaums, symbolische Link-Ausgaben und nicht reguläre verwaltete Artefakte ab.

Wenn die Wiederherstellung nach einem Veröffentlichungsfehler fehlschlägt, druckt der Befehl das Wiederherstellungs-Staging-Verzeichnis und behält es. Löschen Sie dieses Verzeichnis erst, wenn Sie die aufbewahrten Artefakte wiederhergestellt oder kopiert haben.

Verwenden Sie ein bedienerkontrolliertes Ausgabeverzeichnis. Die Release-Transaktion schützt nicht vor einem nicht vertrauenswürdigen Prozess, der das Verzeichnis gleichzeitig ändert.

EXTRACTION.json pinnt einen Digest jedes gemeinsamen Quellpfads, kanonischen regulären Dateimodus und Dateibyte. Windows-Checkout-Berechtigungen werden auf den erforderlichen 0644-Modus des Repositorys normalisiert; andere Plattformen schlagen bei Berechtigungsabweichung fehl. Eine Digest-Abweichung bedeutet, dass der ausgecheckte Baum vom überprüften Quell-Lock abgewichen ist und vor einem Release neu synchronisiert werden muss.

Die versionierten öffentlichen Artefaktverträge befinden sich in schemas/telemetry-v2.schema.json und schemas/script-run-v2.schema.json. Jedes Release-Archiv enthält beide Schemas und docs/VERSIONING.md.

Architektur

SnapRef ist eine lokale Engine, keine gehostete Browser-Flotte.

• browser besitzt isolierte Chromium-Sitzungen, CDP, Snapshots, revisionsgebundene Referenzen, Aktionsfähigkeit, Aufzeichnungen und verwaltete Laufzeiten.

• contract ist die typisierte Operations- und Berechtigungs-Registry.

• script führt YAML/JSON/Starlark-Pläne gegen eine offene Sitzung aus.

• mcp ist ein richtliniengesteuerter stdio-Server. Antrieb, Host-Lesen, Host-Schreiben und Ursprungs-Gewährungen sind separate Autoritäten.

• cmd/snapref ist die eigenständige CLI. Host-Adapter leben außerhalb dieses Moduls.

• processtree ist eine gebündelte MIT-Kopie, die nur für begrenzte Subprozess- Abbrüche in Release- und Benchmark-Tools verwendet wird.

Siehe docs/ARCHITECTURE.md.

Verwendung

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 ist die Entdeckungs-Standardeinstellung. Handeln Sie auf der neuesten revisionsgebundenen Referenz. eval ist eine Notluke, nicht der Entdeckungspfad. MCP-Antrieb, Host-Lesen, Host-Schreiben und Ursprungs-Gewährungen sind separate explizite Autoritäten.

Konfiguration

Die Laufzeitinstallation ist der einzige Befehl, der herunterlädt. Aufzeichnungspakete, die Video oder GIF kodieren, erfordern ffmpeg im PATH; Standbild-Pakete nicht.

Fehlerbehebung

• no Chromium-class browser found: führen Sie snapref runtime install --runtime chrome-for-testing --channel stable aus.

• Sitzung nach Leerlauf fehlt: benannte Sitzungen laufen nach 10 Minuten ab; das Profil bleibt bis close --purge-profile oder gc --apply erhalten.

• Veraltete ausführbare Referenz: machen Sie einen neuen snapshot und verwenden Sie die neueste sr-…-Referenz.

• MCP-Aktuierung verweigert: setzen Sie SNAPREF_MCP_ALLOW_DRIVE=1 (oder --allow-drive) und eine Ursprungs-Allowlist, wenn Sie Hosts einschränken.

• already recording nach einem Absturz: Der nächste In-Process-Start gibt verwaisten In-Process-Zustand frei. Ein getrennter Start, der fehlschlug, bevor eine PID gestempelt wurde, muss entfernt werden: löschen Sie $SNAPREF_HOME/recordings/<name> (Standard ~/.snapref/browser/recordings/<name>). Wenn eine getrennte PID noch lebt, stoppen Sie zuerst diesen Prozess.

• Video-Enkodierung schlägt fehl: installieren Sie ffmpeg; Standbild-Pakete benötigen es nicht. Die CLI gibt bei Fehlern ein begrenztes ffmpeg-stderr aus.

Apache-2.0. Siehe SECURITY.md, docs/VERSIONING.md, NOTICE, THIRD_PARTY_NOTICES.md und die gebündelten third_party/licenses/-Texte vor der Weiterverteilung.