feat: componentize GStack 2 runtime and release integrity

2026-09-20 20:00:45 +02:00 · 2026-07-20 14:16:23 -07:00
parent b0ea2296d1
commit f14445bb00
270 changed files with 9681 additions and 51572 deletions
@@ -0,0 +1,48 @@
+# ADR 0001: public infrastructure tools
+
+- Status: accepted for the GStack 2 candidate
+- Date: 2026-07-20
+- Scope: installation, first-use UX, browser binaries, release integrity, and
+  updater ownership
+
+## Decision
+
+Use public tools only where they have a narrow, replaceable responsibility:
+
+| Responsibility | Decision | Boundary |
+|---|---|---|
+| Skill discovery, host placement, project/global scope, selection, update, and removal | [Vercel Agent Skills CLI](https://github.com/vercel-labs/skills), pinned to 1.5.19 in verification | Canonical and exclusive skill lifecycle. GStack never silently enrolls a host. |
+| Interactive terminal prompts | [Clack](https://github.com/bombshell-dev/clack), if adopted after the current zero-dependency prompt surface needs richer TTY UX | Presentation only; consent state, policy, transactions, and non-TTY flags stay in GStack. No dependency is added merely for styling. |
+| Local browser binaries | [Playwright](https://playwright.dev/docs/browsers) | Existing local Chromium manager only. No cloud-browser provider. |
+| Cross-platform launchers | [Bun compile](https://bun.sh/docs/bundler/executables) | Build-time native launcher production; the runtime remains host-neutral. |
+| Release signing and verification metadata | [Sigstore Cosign](https://docs.sigstore.dev/cosign/signing/signing_with_blobs/) in release CI | CI signs immutable archives keylessly. Every client verifies byte count and SHA-256; Cosign verification is additional when already installed, never a mandatory end-user install. |
+| Release attestations | [GitHub artifact attestations](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations/use-artifact-attestations) | Provenance for release artifacts, with actions pinned to immutable commits and `id-token: write` limited to the signing job. |
+
+GStack owns the product-specific remainder: the signed runtime manifest,
+capability consent, atomic install journal, rollback, doctor output, and the
+first-use prompt that appears only when a chosen skill needs an unavailable
+capability.
+
+## Rejected as mandatory dependencies
+
+- `oclif`: a second CLI framework would not solve skill placement, consent, or
+  transactional updates and would expand the runtime dependency surface.
+- `eget`: convenient binary download UX, but it does not encode GStack's fixed
+  artifact host, manifest, capability, rollback, or privacy policies.
+- `mise` and `aqua`: useful optional environment/package managers, but requiring
+  either would add a package manager in front of the standard Agent Skills
+  installer.
+- hosted browsers, device farms, alternate iOS drivers, ComfyUI, model weights,
+  and GPU runtimes: outside the accepted architecture.
+
+## Consequences
+
+The standard installer can evolve independently without GStack maintaining six
+host adapters. The optional runtime has one auditable release format and no
+automatic setup. Public-tool telemetry and network behavior must be disclosed
+at the point of use; upstream Agent Skills telemetry can be disabled with
+`DISABLE_TELEMETRY=1` or `DO_NOT_TRACK=1`.
+
+The repository keeps tests for the pinned installer behavior and release
+contract. A future tool swap must preserve those contracts instead of leaking
+the tool's own nouns into the six-skill public surface.