mirror of
https://github.com/garrytan/gstack.git
synced 2026-09-21 04:10:47 +02:00
feat: componentize GStack 2 runtime and release integrity
This commit is contained in:
Sinabina
@@ -0,0 +1,118 @@
|
||||
# Release integrity
|
||||
|
||||
GStack has two explicit version identities during the 2.0 migration:
|
||||
|
||||
- `VERSION` and `package.json.version` are the repository/package release
|
||||
counter. They remain byte-equal and retain the existing four-slot format so
|
||||
the 1.x compatibility ship queue does not silently fail open.
|
||||
- `package.json.gstack.runtimeVersion`, `runtime/index.js`,
|
||||
`runtime/install.js`, and every standards-installed bootstrap declare the
|
||||
managed-runtime protocol release `2.0.0`. The official artifact tag and
|
||||
manifest use that value.
|
||||
|
||||
They are intentionally different namespaces. CI fails if either identity
|
||||
drifts inside its own namespace.
|
||||
|
||||
## Runtime release
|
||||
|
||||
The `Release runtime artifacts` workflow builds the complete managed bundle on
|
||||
six native targets:
|
||||
|
||||
```text
|
||||
darwin-arm64 darwin-x64
|
||||
linux-arm64 linux-x64 (glibc)
|
||||
windows-arm64 windows-x64
|
||||
```
|
||||
|
||||
Each archive has one `gstack/` root and no symlinks. CI records an exact byte
|
||||
count and SHA-256, signs the archive keylessly with Cosign, emits a Sigstore
|
||||
bundle, and also creates a GitHub build-provenance attestation. The release
|
||||
manifest contains only official GitHub Release URLs and the fixed workflow
|
||||
certificate identity.
|
||||
|
||||
Browser-capable archives include the Playwright-managed Chromium directory at
|
||||
`.gstack-runtime-browsers`. The builder runs `playwright install chromium`
|
||||
only—never `--with-deps` or `sudo`—copies physical files into the immutable
|
||||
slot, and launch-smokes that exact Chromium on every native release runner.
|
||||
The stable capability launcher sets `PLAYWRIGHT_BROWSERS_PATH` to the active
|
||||
slot; it does not rely on an operator's global Playwright cache.
|
||||
|
||||
Each official artifact also owns its Bun executable. Release CI pins Bun
|
||||
1.3.14, copies that physical executable into
|
||||
`.gstack-runtime-tools/bun[.exe]`, records its relative path and probed version
|
||||
in `.gstack-bundle.json`, and exposes it through the stable `$GSTACK_HOME/bin/bun`
|
||||
launcher. The tagged Bun license inventory and source/relink notice are
|
||||
vendored under `runtime/licenses/` and their expected hashes are release-gated.
|
||||
|
||||
The native release smoke removes the `setup-bun` directory from `PATH`, supplies
|
||||
only an explicit `GSTACK_NODE`, runs the stable managed-Bun launcher, and opens
|
||||
`about:blank` through the installed browser before cleanup. Compiled browser
|
||||
clients use their adjacent `server-node.mjs` on every platform, so browser,
|
||||
design, and PDF readiness does not depend on a host-global Bun installation.
|
||||
|
||||
The bootstrap always verifies the manifest schema, target, exact byte count,
|
||||
and SHA-256 before extraction. If Cosign is already installed it additionally
|
||||
verifies the Sigstore bundle, certificate identity, and GitHub Actions OIDC
|
||||
issuer. Cosign is not downloaded or required on an end-user machine.
|
||||
|
||||
The official Linux archives are glibc builds. The bootstrap detects a musl
|
||||
host before any network request and returns a typed unsupported-platform error;
|
||||
it does not download a glibc archive that cannot validate on Alpine. Musl is
|
||||
not claimed by the current six-artifact release matrix.
|
||||
|
||||
Runtime tool requirements are capability-scoped. Node is the bootstrap and
|
||||
stable-launcher floor. On Windows, retained shell-based helpers additionally
|
||||
require Git for Windows Bash; doctor reports that check explicitly. Python 3 is
|
||||
only required by specialist flows that label it as a prerequisite. Missing
|
||||
Bash or Python does not change the native browser/design/PDF payload or turn
|
||||
those capabilities into host-global Bun consumers.
|
||||
|
||||
## npm package
|
||||
|
||||
The npm tarball is a small runtime-control/bootstrap package, not a second
|
||||
GStack installer. Its allowlist contains the Node-only runtime control plane,
|
||||
the `gstack` launcher, documentation, license, and version marker. It excludes
|
||||
the six skills and large compiled capability payloads. Skills come from the
|
||||
Agent Skills installer; optional capability payloads come from the verified
|
||||
runtime release only after approval.
|
||||
|
||||
CI packs the tarball, installs it into an isolated directory, invokes
|
||||
`gstack --version`, initializes isolated state through `gstack setup`, and
|
||||
invokes `gstack-runtime-bootstrap --help`. It also enforces conservative packed
|
||||
size and entry-count ceilings.
|
||||
|
||||
## Dependency audit policy
|
||||
|
||||
`puppeteer-core` was unused and removed. Playwright remains the only browser
|
||||
manager. Bun's current audit command does not distinguish production from
|
||||
development dependencies, so CI gates critical advisories across the entire
|
||||
lockfile and reports the complete audit. At the 2026-07-20 checkpoint, the
|
||||
remaining high advisories are under the retained development-only Claude Agent
|
||||
SDK and Hugging Face evaluation stack; neither is copied into the managed
|
||||
runtime. They must be re-audited before changing those test SDKs or promoting
|
||||
the release status.
|
||||
|
||||
## Static-analysis disposition
|
||||
|
||||
- Shell syntax and high-confidence ShellCheck errors are gated on setup and
|
||||
release/build boundaries. Runtime JavaScript is syntax-checked with the
|
||||
supported Node floor. Workflow actions are pinned and actionlint remains its
|
||||
own gate.
|
||||
- Added production/docs lines are scanned by GStack's deterministic redaction
|
||||
engine. Removed lines do not block credential cleanup. Known synthetic-secret
|
||||
fixture/evaluation paths are excluded so the gate stays meaningful; those
|
||||
paths retain dedicated redaction tests.
|
||||
- The repository has no TypeScript compiler dependency or `tsconfig.json`.
|
||||
Calling Bun transpilation a typecheck would be false, while enabling `tsc`
|
||||
across the legacy mixed JS/TS/generated tree is a separate migration. This
|
||||
candidate records typecheck as not yet enforceable rather than a green gate.
|
||||
- There is no repository formatter or general source-linter configuration.
|
||||
Introducing one during release hardening would mechanically rewrite
|
||||
byte-pinned generated and parity corpora. Actionlint, ShellCheck, runtime
|
||||
syntax, existing tests, and generated-freshness checks are enforced now; a
|
||||
formatter/linter migration remains explicit follow-up work.
|
||||
- No `CODEOWNERS` file is invented. Git history identifies contributors but
|
||||
does not prove the current GitHub user/team with review authority in the
|
||||
`time-attack` organization. Repository administrators must name a real team
|
||||
and enable required CODEOWNER review together; until then ownership review
|
||||
is an open governance control, not a fabricated file.
|
||||
Reference in New Issue
Block a user