diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 2b84b30..53a56cc 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -36,6 +36,32 @@ jobs: run: | node scripts/validate-distribution-contract.mjs node --test scripts/distribution-contract.test.mjs + - name: Install Aqua for registry validation + uses: aquaproj/aqua-installer@96a9bc20066c5bf5e275b41019cfc165b25f4e2e # v4.0.5 + with: + aqua_version: v2.62.3 + enable_aqua_install: false + - name: Validate Aqua release mappings + env: + AQUA_CONFIG: ${{ github.workspace }}/tests/aqua/aqua.yaml + AQUA_POLICY_CONFIG: ${{ github.workspace }}/tests/aqua/aqua-policy.yaml + run: | + aqua update-checksum + aqua update + git diff --exit-code -- tests/aqua/aqua-checksums.json tests/aqua/aqua.yaml + for environment in darwin/amd64 darwin/arm64 linux/amd64 linux/arm64; do + root="$RUNNER_TEMP/aqua-${environment//\//-}" + AQUA_ROOT_DIR="$root" AQUA_GOOS="${environment%/*}" AQUA_GOARCH="${environment#*/}" aqua install --test + done + native_root="$RUNNER_TEMP/aqua-native" + smoke_directory="$RUNNER_TEMP/aqua-smoke" + mkdir -p "$smoke_directory" + AQUA_ROOT_DIR="$native_root" aqua install + "$native_root/bin/stack" --version + "$native_root/bin/stack" init -o "$smoke_directory/diagram.stack" + "$native_root/bin/stack" check "$smoke_directory/diagram.stack" + "$native_root/bin/stack" render "$smoke_directory/diagram.stack" -o "$smoke_directory/diagram.svg" + test -s "$smoke_directory/diagram.svg" - name: Validate release supply chain run: | node --check scripts/create-supply-chain-smoke-fixture.mjs @@ -115,6 +141,8 @@ jobs: test -s docs/provider-icon-import.md test -s docs/distribution.md test -s docs/supply-chain.md + test -s aqua/README.md + test -s aqua/registry.yaml test -s distribution/distribution-contract.json test -s distribution/distribution-contract.schema.json test -s distribution/release-manifest.schema.json @@ -148,6 +176,9 @@ jobs: test -s scripts/release-workflow.test.mjs test -s scripts/validate-supply-chain-workflow.mjs test -s scripts/supply-chain-workflow.test.mjs + test -s tests/aqua/aqua.yaml + test -s tests/aqua/aqua-checksums.json + test -s tests/aqua/aqua-policy.yaml test -s .github/workflows/release.yaml test -s .github/workflows/supply-chain.yaml test -s templates/catalog.json diff --git a/aqua/README.md b/aqua/README.md new file mode 100644 index 0000000..b77a654 --- /dev/null +++ b/aqua/README.md @@ -0,0 +1,29 @@ +# Aqua registry maintenance + +[`registry.yaml`](./registry.yaml) maps the `stack-sh/cli` package to the canonical Stack CLI GitHub Release archives. It does not rebuild or repack the executable. Aqua downloads the release checksum inventory, requires the selected archive to have a SHA-256 entry, and verifies the keyless Sigstore bundle against the tagged release workflow identity. + +The registry supports only the release contract's tier-1 environments: macOS and glibc-based Linux on arm64 and x86_64. The package name is `stack-sh/cli`, and the installed command remains `stack`. + +## Verify a registry change + +Install the pinned Aqua version used by CI, then test every supported mapping without executing a foreign-architecture binary: + +```sh +aqua update-checksum +aqua update +for environment in darwin/amd64 darwin/arm64 linux/amd64 linux/arm64; do + AQUA_CONFIG=tests/aqua/aqua.yaml \ + AQUA_POLICY_CONFIG=tests/aqua/aqua-policy.yaml \ + AQUA_GOOS="${environment%/*}" \ + AQUA_GOARCH="${environment#*/}" \ + aqua install --test +done +``` + +`aqua update-checksum` must reproduce `tests/aqua/aqua-checksums.json` exactly. The file locks all four release archives to the SHA-256 values obtained from the release checksum asset after Aqua verifies its Sigstore bundle. `aqua update` must leave the pinned fixture unchanged until a newer stable release exists. + +On the native host, repeat without `--test` in an isolated `AQUA_ROOT_DIR`, then run `stack --version`, `stack init`, `stack check`, and `stack render`. + +## Publish an update + +Release archives and checksums remain owned by the immutable GitHub Release. If the artifact naming contract changes, update this registry and all four environment tests in one pull request. After merge, pin the owner registry in user documentation to the resulting full commit SHA. Never use a branch name as a registry `ref`, replace release assets, or point Aqua at repacked bytes. diff --git a/aqua/registry.yaml b/aqua/registry.yaml new file mode 100644 index 0000000..95b62d1 --- /dev/null +++ b/aqua/registry.yaml @@ -0,0 +1,38 @@ +# yaml-language-server: $schema=https://raw.githubusercontent.com/aquaproj/aqua/v2.62.3/json-schema/registry.json + +packages: + - type: github_release + repo_owner: stack-sh + repo_name: cli + description: Native CLI for Stack architecture diagrams + version_constraint: "false" + files: + - name: stack + src: "{{.AssetWithoutExt}}/stack" + version_overrides: + - version_constraint: semver(">= 0.3.0") + asset: stack-{{.Version}}-{{.Arch}}-{{.OS}}.{{.Format}} + format: tar.gz + replacements: + amd64: x86_64 + arm64: aarch64 + darwin: apple-darwin + linux: unknown-linux-gnu + supported_envs: + - darwin/amd64 + - darwin/arm64 + - linux/amd64 + - linux/arm64 + checksum: + type: github_release + asset: stack-{{.Version}}-checksums.txt + algorithm: sha256 + cosign: + opts: + - --certificate-identity-regexp + - "^https://github\\.com/stack-sh/cli/\\.github/workflows/release\\.ya?ml@refs/tags/\\Q{{.Version}}\\E$" + - --certificate-oidc-issuer + - https://token.actions.githubusercontent.com + bundle: + type: github_release + asset: stack-{{.Version}}-checksums.txt.sigstore.json diff --git a/tests/aqua/aqua-checksums.json b/tests/aqua/aqua-checksums.json new file mode 100644 index 0000000..a12e7d7 --- /dev/null +++ b/tests/aqua/aqua-checksums.json @@ -0,0 +1,24 @@ +{ + "checksums": [ + { + "id": "github_release/github.com/stack-sh/cli/v0.3.0/stack-v0.3.0-aarch64-apple-darwin.tar.gz", + "checksum": "10DF35058C9E8438B331B69392F6B9840CBAE3A5278105B0118C3942F62FC356", + "algorithm": "sha256" + }, + { + "id": "github_release/github.com/stack-sh/cli/v0.3.0/stack-v0.3.0-aarch64-unknown-linux-gnu.tar.gz", + "checksum": "2BED2BA5FF4A727646CEDB4EC77AC875E09FC3EDE996A963022D9A97CCDBF7AC", + "algorithm": "sha256" + }, + { + "id": "github_release/github.com/stack-sh/cli/v0.3.0/stack-v0.3.0-x86_64-apple-darwin.tar.gz", + "checksum": "23D8EEA13FF2663E059B7EC91CBC8D6BCA8825380766E87F1718C2DEA217A49F", + "algorithm": "sha256" + }, + { + "id": "github_release/github.com/stack-sh/cli/v0.3.0/stack-v0.3.0-x86_64-unknown-linux-gnu.tar.gz", + "checksum": "6C9AB21D96FC6FB0A12A6FF4F7F56103D8DD8513AC85C8D30AB6E072C5C6A7D9", + "algorithm": "sha256" + } + ] +} diff --git a/tests/aqua/aqua-policy.yaml b/tests/aqua/aqua-policy.yaml new file mode 100644 index 0000000..79b9ab5 --- /dev/null +++ b/tests/aqua/aqua-policy.yaml @@ -0,0 +1,10 @@ +# yaml-language-server: $schema=https://raw.githubusercontent.com/aquaproj/aqua/v2.62.3/json-schema/policy.json + +registries: + - name: stack-sh + type: local + path: ../../aqua/registry.yaml +packages: + - name: stack-sh/cli + registry: stack-sh + version: semver(">= 0.3.0") diff --git a/tests/aqua/aqua.yaml b/tests/aqua/aqua.yaml new file mode 100644 index 0000000..eb64f79 --- /dev/null +++ b/tests/aqua/aqua.yaml @@ -0,0 +1,14 @@ +# yaml-language-server: $schema=https://raw.githubusercontent.com/aquaproj/aqua/v2.62.3/json-schema/aqua-yaml.json + +checksum: + enabled: true + require_checksum: true + supported_envs: + - all +registries: + - name: stack-sh + type: local + path: ../../aqua/registry.yaml +packages: + - name: stack-sh/cli@v0.3.0 + registry: stack-sh