Add Aqua registry verification

.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

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.

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

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"
+    }
+  ]
+}

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")

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