mirror of
https://github.com/garrytan/gstack.git
synced 2026-09-21 04:10:47 +02:00
49 lines
3.2 KiB
Markdown
49 lines
3.2 KiB
Markdown
# 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.
|