Taskfile.yml

version: "3"

vars:
  BINARY: devcontainer
  MODULE: github.com/devcontainers/cli
  # CalVer: YYYYMMDD.<build>. BUILD_NUMBER (e.g. a daily counter or CI run number)
  # defaults to 01 for local builds. Tagged releases use the git tag verbatim.
  VERSION:
    sh: echo "$(git describe --tags --exact-match 2>/dev/null || echo "$(date -u +%Y%m%d).${BUILD_NUMBER:-01}")"
  LDFLAGS: -s -w -X {{.MODULE}}/internal/product.version={{.VERSION}} -X {{.MODULE}}/internal/product.name={{.BINARY}}
  # Minimum hermetic-unit statement coverage the `coverage` gate enforces. Set as a
  # ratchet just below the current level; raise it as coverage grows (never lower).
  COVERAGE_MIN: "52"
  # Package ratchets prevent well-covered parsing packages from masking a
  # regression in the orchestration layers. Keep these just below the measured
  # hermetic baseline and only move them upward.
  COVERAGE_CLI_MIN: "32"
  COVERAGE_DOCKER_MIN: "77"
  COVERAGE_LIFECYCLE_MIN: "73"
  COVERAGE_OCI_MIN: "85"
  # Coverage artifact layout. Every lane writes binary covdata under COVER_DATA/<lane>
  # so `coverage:merge` can union them into the true cross-lane number.
  COVER_DIR: artifacts/coverage
  COVER_DATA: artifacts/coverage/data
  # The image GoReleaser publishes (.goreleaser.yml's dockers), tagged with the version.
  IMAGE: ghcr.io/spin-stack/devcontainer-cli

tasks:
  default:
    desc: Build and test the Go CLI
    cmds:
      - task: test:unit
      - task: test:integration
      - task: build

  build:
    desc: Build the static Go CLI
    env:
      CGO_ENABLED: "0"
    cmds:
      - go build -ldflags "{{.LDFLAGS}}" -o {{.BINARY}} ./cmd/devcontainer/
    sources: [cmd/**/*.go, internal/**/*.go, go.mod, go.sum]
    generates: ["{{.BINARY}}"]

  build:coverage:
    desc: Build an instrumented CLI for subprocess/integration coverage
    env:
      CGO_ENABLED: "0"
    cmds:
      - mkdir -p artifacts/coverage/bin artifacts/coverage/data
      - go build -cover -ldflags "{{.LDFLAGS}}" -o artifacts/coverage/bin/{{.BINARY}} ./cmd/devcontainer/

  build:cross:
    desc: Cross-compile release binaries
    env:
      CGO_ENABLED: "0"
    cmds:
      - mkdir -p dist
      # Linux-only scope: only linux/amd64 + linux/arm64 are supported targets.
      - GOOS=linux   GOARCH=amd64 go build -ldflags "{{.LDFLAGS}}" -o dist/{{.BINARY}}-linux-amd64 ./cmd/devcontainer/
      - GOOS=linux   GOARCH=arm64 go build -ldflags "{{.LDFLAGS}}" -o dist/{{.BINARY}}-linux-arm64 ./cmd/devcontainer/
      - ls -lh dist/

  build:smoke:
    desc: Build the CLI and check the binary runs
    deps: [build]
    cmds:
      - ./{{.BINARY}} --version

  test:unit:
    desc: Run hermetic unit tests
    cmds:
      - go test ./cmd/... ./internal/... -skip '^TestClient$|^TestE2E|^TestParityMatrix$|^TestPublishParity$' -count=1 {{.CLI_ARGS}}

  test:integration:
    desc: Run local HTTP integration tests
    cmds:
      - go test ./internal/httpx -run '^TestNewTransport' -count=1 {{.CLI_ARGS}}

  test:race:
    desc: Run hermetic unit tests under the race detector (needs cgo)
    env:
      CGO_ENABLED: "1"
    cmds:
      - go test ./cmd/... ./internal/... -skip '^TestClient$|^TestE2E|^TestParityMatrix$|^TestPublishParity$' -race -count=1 {{.CLI_ARGS}}

  vuln:
    desc: Fail on a vulnerability the code calls and that has a fix, the standard library's included (govulncheck through go-tools' vulngate)
    cmds:
      - go tool vulngate ./...

  coverage:
    desc: Hermetic unit coverage — per-package table + enforce the total/package floors
    cmds:
      # rm -rf first: covdata files accumulate across runs and would inflate the
      # merged number otherwise.
      - rm -rf {{.COVER_DATA}}/unit && mkdir -p {{.COVER_DATA}}/unit
      # -coverprofile keeps coverage.out byte-identical for the gate; the extra
      # -test.gocoverdir also emits binary covdata so `coverage:merge` can union it
      # with the e2e/parity lanes.
      - go test ./cmd/... ./internal/... -skip '^TestClient$|^TestE2E|^TestParityMatrix$|^TestPublishParity$' -coverprofile=coverage.out -count=1 -args -test.gocoverdir={{.ROOT_DIR}}/{{.COVER_DATA}}/unit
      - go run ./cmd/devtool coverage-report coverage.out "unit (hermetic)"
      # Ratchet: total + per-package floors (parsers must not mask lost CLI/OCI coverage).
      - go run ./cmd/devtool coverage-gate coverage.out TOTAL={{.COVERAGE_MIN}} cli={{.COVERAGE_CLI_MIN}} docker={{.COVERAGE_DOCKER_MIN}} lifecycle={{.COVERAGE_LIFECYCLE_MIN}} oci={{.COVERAGE_OCI_MIN}}

  coverage:e2e:
    desc: Coverage of the real in-process E2E paths (requires Docker)
    preconditions:
      - sh: docker info >/dev/null 2>&1
        msg: Docker is required for E2E coverage
    cmds:
      - rm -rf {{.COVER_DATA}}/e2e && mkdir -p {{.COVER_DATA}}/e2e
      # -coverpkg instruments the whole module (these tests invoke NewRootCommand
      # directly); -test.gocoverdir emits binary covdata for the merge.
      - go test ./internal/cli -run '^TestE2E' -count=1 -timeout 5m -coverpkg=./... -args -test.gocoverdir={{.ROOT_DIR}}/{{.COVER_DATA}}/e2e
      - go run ./cmd/devtool coverage-report {{.COVER_DATA}}/e2e "e2e"

  # coverage:_parity-lane runs the instrumented CLI (build:coverage) through a
  # parity lane, collecting covdata into COVER_DATA/<LANE> and printing the table.
  # LANE and RUN (the full `go test ...` invocation) are supplied by the wrappers.
  coverage:_parity-lane:
    internal: true
    deps: [build:coverage, reference:compile]
    cmds:
      - rm -rf {{.COVER_DATA}}/{{.LANE}} && mkdir -p {{.COVER_DATA}}/{{.LANE}}
      - GOCOVERDIR={{.ROOT_DIR}}/{{.COVER_DATA}}/{{.LANE}} CLI_GO={{.ROOT_DIR}}/{{.COVER_DIR}}/bin/{{.BINARY}} {{.RUN}}
      - go run ./cmd/devtool coverage-report {{.COVER_DATA}}/{{.LANE}} "parity:{{.LANE}}"

  coverage:parity-contract:
    desc: Coverage of the instrumented binary through the hermetic contract parity lane
    cmds:
      - task: coverage:_parity-lane
        vars:
          LANE: contract
          RUN: >-
            PARITY_REPORT_FILE={{.ROOT_DIR}}/{{.COVER_DIR}}/parity-contract.json
            PARITY_STRICT=true PARITY_LANE=contract PARITY_SKIP_DOCKER=true PARITY_SKIP_NETWORK=true
            go test ./internal/cli -run '^TestParityMatrix$' -count=1 -timeout 10m -v

  coverage:parity-runtime:
    desc: Coverage of the instrumented binary through the full Docker parity lane
    preconditions:
      - sh: docker info >/dev/null 2>&1
        msg: Docker is required for runtime parity coverage
      - sh: docker info 2>/dev/null | grep -q io.containerd.snapshotter
        msg: The parity runtime lane requires the containerd image store (docker build --platform on local images); enable it with `task ci:prepare-runner`.
      - sh: go run ./cmd/devtool docker-cache-export
        msg: The Docker builder must support cache export (see `devtool ci-prepare-runner`)
    cmds:
      - task: coverage:_parity-lane
        vars:
          LANE: runtime
          RUN: >-
            PARITY_REPORT_FILE={{.ROOT_DIR}}/{{.COVER_DIR}}/parity-runtime.json
            PARITY_STRICT=true PARITY_LANE=all
            go test ./internal/cli -run '^TestParityMatrix$' -count=1 -parallel {{.PARITY_PARALLEL | default "2"}} -timeout 60m -v

  coverage:parity-publish:
    desc: Coverage of real feature/template publication against an ephemeral OCI registry
    preconditions:
      - sh: docker info >/dev/null 2>&1
        msg: Docker is required for publish parity coverage
    cmds:
      - task: coverage:_parity-lane
        vars:
          LANE: publish
          RUN: go test ./internal/cli -run '^TestPublishParity$' -count=1 -timeout 10m -v

  coverage:merge:
    desc: Union every per-lane covdata dir into the true cross-lane coverage report (and the CI job summary)
    cmds:
      - go run ./cmd/devtool coverage-merge {{.COVER_DATA}} {{.COVER_DATA}}/merged "merged (all lanes)" | tee -a "${GITHUB_STEP_SUMMARY:-/dev/null}"

  coverage:summary:
    desc: Add one lane's coverage report (SRC, a coverage.out or covdata dir, titled TITLE) to the CI job summary, or print it
    requires:
      vars: [SRC, TITLE]
    cmds:
      - go run ./cmd/devtool coverage-report {{.SRC}} "{{.TITLE}}" >> "${GITHUB_STEP_SUMMARY:-/dev/stdout}"

  # download-artifact nests each artifact under covdata-<lane>/; coverage:merge wants one dir per
  # lane, the runtime shards still apart.
  coverage:unpack:
    desc: "CI-ONLY: flatten the downloaded covdata-<lane>/ artifacts into the <lane>/ dirs coverage:merge reads"
    dir: "{{.COVER_DATA}}"
    cmds:
      - |
        for d in covdata-*; do [ -d "$d" ] && mv "$d" "${d#covdata-}"; done
        ls -R . || true

  test:e2e:
    desc: Run Go E2E tests with Docker
    deps: [build]
    preconditions:
      - sh: docker info >/dev/null 2>&1
        msg: Docker is required for E2E tests
    cmds:
      - go test ./internal/cli -run TestE2E -count=1 -timeout 5m -v {{.CLI_ARGS}}

  lint:
    desc: Run Go static checks and go-tools' gates - golangci-lint, goroutine lifetimes, tests that cannot fail, AGENTS.md's references, unreachable code, one task per workflow step, pnpm through Socket Firewall
    cmds:
      - go vet ./cmd/... ./internal/...
      - task: lint:go
      - go tool ctxlife
      - go tool testquality -allow .github/testquality-allow.txt ./...
      - go tool refs
      - go tool mutate -stale-exempts
      - task: deadcode
      - go tool taskgate
      - go tool sfw check

  lint:go:
    desc: golangci-lint with .golangci.yml, at the version versions.yaml pins
    cmds:
      # As this user, on this host's module and build caches; GOTOOLCHAIN=local reads the code
      # with the Go the image carries.
      - mkdir -p {{.ROOT_DIR}}/artifacts/golangci-lint
      - >-
        docker run --rm -u "$(id -u):$(id -g)" -v {{.ROOT_DIR}}:/work -w /work
        -v "$(go env GOMODCACHE)":/go/pkg/mod -v "$(go env GOCACHE)":/cache/go-build
        -e GOMODCACHE=/go/pkg/mod -e GOCACHE=/cache/go-build -e GOLANGCI_LINT_CACHE=/work/artifacts/golangci-lint
        -e HOME=/tmp -e GOTOOLCHAIN=local
        $(go tool versions ref golangci-lint) golangci-lint run ./cmd/... ./internal/...

  deadcode:
    desc: Fail on a function the binaries link and never call, or a package none imports, unless .github/deadcode-allow.txt says why
    cmds:
      - go tool deadgate -deadcode "$(go tool -n deadcode)" -roots ./cmd/... -packages ./internal/... -allow .github/deadcode-allow.txt -pending .github/deadcode-pending.txt

  mutate:
    desc: Break what the change against BASE touched and fail on an edit no test refuses (BASE=origin/main; on a pull request, what it merges into)
    cmds:
      # BASE comes from `task mutate BASE=...` or the environment (the workflow's).
      - go tool mutate -base "{{.BASE | default "${BASE:-origin/main}"}}" -max 200

  spec:compliance:
    desc: Verify spec compliance — schema attribute coverage + normative behavior (merge/lifecycle/discovery), excludes Go-only additions
    cmds:
      # All spec contracts are TestSpec* across packages: config attribute
      # coverage + variable/discovery/devcontainerId behavior, imagemeta merge
      # rules, lifecycle execution order.
      - go test ./internal/... -run '^TestSpec' -count=1

  spec:schema-update:
    desc: Refresh the vendored devcontainer.json schema the spec-compliance gate checks against
    cmds:
      - curl -fsSL https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json -o internal/config/testdata/devContainer.base.schema.json
      - 'echo "Schema refreshed. Run ''task spec:compliance'' — any new spec property fails until modeled in internal/config/types.go."'

  testdata:ts-oracle:
    desc: Rewrite every internal/**/testdata/ts-oracle/*.json with the results of the reference TypeScript functions (tools/tsoracle), run in the node image versions.yaml pins (needs Docker)
    deps: [reference:compile]
    cmds:
      - go run ./cmd/devtool ts-oracle "$(go tool versions ref node)"

  testdata:ts-oracle:check:
    desc: Fail when a testdata/ts-oracle golden differs from what the reference TypeScript functions return
    deps: [reference:compile]
    cmds:
      - TS_ORACLE_IMAGE="$(go tool versions ref node)" go test ./internal/devtools -run '^TestTSOracleGoldensMatchTheReference$' -count=1 -v

  reference:
    desc: Install and compile the TypeScript parity oracle
    cmds:
      - task: reference:install
      - task: reference:compile

  reference:commit:
    desc: Record the reference commit the parity reports were made against (artifacts/reference-commit.txt)
    cmds:
      - mkdir -p artifacts
      - git -C reference rev-parse HEAD > artifacts/reference-commit.txt

  parity:contract:
    desc: Run the hermetic CLI contract matrix
    deps: [build, reference:compile]
    cmds:
      # Oracle flag-surface gate: every flag the TS oracle declares per command
      # must be in the inventory (needs reference/ checked out, so it lives here).
      - go test ./internal/cli -run TestOracleFlagCoverage -count=1
      # The ts-oracle goldens must be what the reference's functions return.
      - TS_ORACLE_IMAGE="$(go tool versions ref node)" go test ./internal/devtools -run '^TestTSOracleGoldensMatchTheReference$' -count=1
      - PARITY_REPORT_FILE={{.ROOT_DIR}}/artifacts/parity-contract.json PARITY_STRICT=true PARITY_LANE=contract PARITY_SKIP_DOCKER=true PARITY_SKIP_NETWORK=true go test ./internal/cli -run TestParityMatrix -count=1 -timeout 10m -v {{.CLI_ARGS}}

  parity:semantic:
    desc: Run semantic cases without Docker or network
    deps: [build, reference:compile]
    cmds:
      - PARITY_REPORT_FILE={{.ROOT_DIR}}/artifacts/parity-semantic.json PARITY_STRICT=true PARITY_LANE=semantic PARITY_SKIP_DOCKER=true PARITY_SKIP_NETWORK=true go test ./internal/cli -run TestParityMatrix -count=1 -timeout 10m -v {{.CLI_ARGS}}

  parity:network:
    desc: Run parity cases that require external network access
    deps: [build, reference:compile]
    cmds:
      - PARITY_REPORT_FILE={{.ROOT_DIR}}/artifacts/parity-network.json PARITY_STRICT=true PARITY_LANE=all PARITY_NETWORK_ONLY=true PARITY_SKIP_DOCKER=true go test ./internal/cli -run TestParityMatrix -count=1 -timeout 15m -v {{.CLI_ARGS}}

  parity:differential:
    desc: Compare read-configuration, up and build with the TS oracle over every upstream fixture (reference/src/test/configs); needs Docker and the network
    deps: [build, reference:compile]
    cmds:
      - PARITY_DIFFERENTIAL=1 go test ./internal/cli -run '^TestDifferential' -count=1 -timeout 180m -v {{.CLI_ARGS}}

  parity:runtime:
    desc: Run the runtime parity matrix with Docker (set PARITY_COMMAND=up,build to scope it)
    deps: [build, reference:compile]
    preconditions:
      - sh: docker info >/dev/null 2>&1
        msg: Docker is required for runtime parity
      # Fail fast (~1s) if the containerd image store is off: the runtime lane's
      # update-UID / cache-export builds run `docker build --platform` against
      # locally-built images, which only the containerd store can resolve. Without
      # it the TS oracle fails those builds while Go succeeds → false divergences.
      # The test itself re-checks this (so a direct `go test` is covered too).
      - sh: docker info 2>/dev/null | grep -q io.containerd.snapshotter
        msg: |
          The parity runtime lane requires the containerd image store (docker build
          --platform against locally-built images). Enable it with `task ci:prepare-runner`,
          or add {"features":{"containerd-snapshotter":true}} to /etc/docker/daemon.json.
      # Fail fast (~1s) if the builder can't export build cache — otherwise the
      # runtime cases (build.cache-to-*, build.output-oci-*) fail ~4 min deep with
      # a cryptic buildkit error. The default `docker` driver lacks cache export.
      - sh: go run ./cmd/devtool docker-cache-export
        msg: |
          The Docker builder cannot export build cache (needed by the runtime parity
          matrix: build.cache-to-*, build.output-oci-*). Enable the containerd image
          store (`devtool ci-prepare-runner`) or use a docker-container buildx builder.
    cmds:
      # -parallel default 2 for gate determinism: higher values overload the docker
      # daemon on contended runners and transiently fail compose/heavy cases (they
      # match in isolation). Raise via PARITY_PARALLEL on beefy/idle runners.
      # PARITY_COMMAND (comma-separated, inherited from the environment) scopes the
      # run to the cases affected by a change; unset/"all" runs the full matrix.
      - PARITY_REPORT_FILE={{.ROOT_DIR}}/artifacts/parity-runtime.json PARITY_STRICT=true PARITY_LANE=all go test ./internal/cli -run TestParityMatrix -count=1 -parallel {{.PARITY_PARALLEL | default "2"}} -timeout 60m -v {{.CLI_ARGS}}

  parity:plan:
    desc: "Plan a runtime parity run (run=, commands= to $GITHUB_OUTPUT, or the terminal): on a push or PR the commands DIFF_BASE..DIFF_HEAD can affect, else the full matrix"
    cmds:
      - |
        out="${GITHUB_OUTPUT:-/dev/stdout}"
        case "${GITHUB_EVENT_NAME:-}" in
          push|pull_request)
            go run ./cmd/devtool parity-affected-commands "$DIFF_BASE" "$DIFF_HEAD" >> "$out"
            ;;
          *)
            # The daily run, which daily-changes has already let through.
            echo "run=true" >> "$out"
            echo "commands=all" >> "$out"
            ;;
        esac

  # A skipped lane - publish on a push or PR, or the whole matrix on a quiet day - is a pass.
  parity:gate:
    desc: "CI-ONLY: fail unless the runtime and publish parity jobs (RUNTIME_RESULT, PUBLISH_RESULT) succeeded or were skipped"
    cmds:
      - |
        echo "runtime: $RUNTIME_RESULT, publish: $PUBLISH_RESULT"
        for r in "$RUNTIME_RESULT" "$PUBLISH_RESULT"; do
          case "$r" in
            success|skipped) ;;
            *) echo "runtime/publish parity failed"; exit 1 ;;
          esac
        done

  parity:publish:
    desc: Run the OCI publish parity (features publish/package) — network + registry heavy
    deps: [build, reference:compile]
    preconditions:
      - sh: docker info >/dev/null 2>&1
        msg: Docker is required for publish parity
    cmds:
      - go test ./internal/cli -run TestPublishParity -count=1 -timeout 10m -v

  ci:prepare-runner:
    desc: "CI-ONLY: free disk + enable the containerd image store + bake's fs entitlement off (uses sudo; not for local dev)"
    cmds:
      - go run ./cmd/devtool ci-prepare-runner
      # The TS reference builds a compose service from a Dockerfile it writes under /tmp,
      # outside the build context. Compose builds through bake, and bake on buildx 0.38
      # (GitHub's runner image, 2026-10-24) refuses to read a file outside the context unless
      # the caller passes --allow=fs.read, which the reference never does: every compose case
      # failed with "additional privileges requested" while the Go CLI, which passes the
      # entitlement itself, succeeded. Off for the whole job, so both sides build the same way.
      - echo "BUILDX_BAKE_ENTITLEMENTS_FS=0" >> "${GITHUB_ENV:-/dev/null}"

  ci:daily-changes:
    desc: "Whether the daily lanes run (run= to $GITHUB_OUTPUT, or the terminal): always on a manual dispatch, else only when HEAD changed in the last day"
    cmds:
      - |
        out="${GITHUB_OUTPUT:-/dev/stdout}"
        if [ "${GITHUB_EVENT_NAME:-}" = "workflow_dispatch" ]; then
          echo "manual dispatch → always run" >&2
          echo "run=true" >> "$out"
        else
          go run ./cmd/devtool daily-changed >> "$out"
        fi

  clean:
    desc: Remove generated artifacts and test containers
    cmds:
      - task: docker:clean
      - rm -f {{.BINARY}} coverage.out coverage.html
      - rm -rf artifacts dist src/test/tmp

  release:
    desc: Run GoReleaser; pass --snapshot for a local release
    preconditions:
      - sh: command -v goreleaser >/dev/null
        msg: goreleaser is required
    env:
      DISTROLESS_IMAGE:
        sh: go tool versions ref distroless
    cmds:
      - goreleaser release --clean {{.CLI_ARGS}}

  release:env:
    desc: "CI-ONLY: export what GoReleaser reads from versions.yaml (DISTROLESS_IMAGE) to $GITHUB_ENV"
    cmds:
      - echo "DISTROLESS_IMAGE=$(go tool versions ref distroless)" >> "$GITHUB_ENV"

  # The release workflow's own steps. What only the workflow knows - the dispatch input, the
  # prepare job's outputs, the published digest - comes in the environment.
  release:resolve:
    desc: "Resolve the version, tag and commit to release (to $GITHUB_OUTPUT, or the terminal): a dispatch's VERSION_INPUT or the next CalVer, else the pushed tag"
    cmds:
      # Outside CI there is no tag push, so it answers as a dispatch would: a dry run.
      - go run ./cmd/devtool release-resolve

  release:tag:
    desc: "CI-ONLY: create and push the annotated tag RELEASE_TAG for RELEASE_VERSION, as github-actions[bot]"
    cmds:
      - |
        set -euo pipefail
        git config user.name "github-actions[bot]"
        git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
        git tag -a "$RELEASE_TAG" -m "Release $RELEASE_VERSION"
        git push origin "$RELEASE_TAG"

  release:smoke:
    desc: Check the published image of RELEASE_VERSION reports that version
    cmds:
      - |
        set -euo pipefail
        IMAGE="{{.IMAGE}}:$RELEASE_VERSION"
        GOT="$(docker run --rm "$IMAGE" --version)"
        echo "image reported version: $GOT (expected: $RELEASE_VERSION)"
        test "$GOT" = "$RELEASE_VERSION"

  release:digest:
    desc: "Record the digest of the published image of RELEASE_VERSION (digest= to $GITHUB_OUTPUT, and the job summary)"
    cmds:
      - |
        set -euo pipefail
        IMAGE="{{.IMAGE}}:$RELEASE_VERSION"
        DIGEST="$(docker buildx imagetools inspect "$IMAGE" --format '{{`{{ json .Manifest.Digest }}`}}' | tr -d '\"')"
        echo "digest=${DIGEST}" >>"${GITHUB_OUTPUT:-/dev/stdout}"
        {
          echo "## Published image"
          echo ""
          echo "- \`${IMAGE}\`"
          echo "- digest: \`${DIGEST}\`"
        } >>"${GITHUB_STEP_SUMMARY:-/dev/stdout}"
        docker buildx imagetools inspect "$IMAGE"

  release:latest:
    desc: "CI-ONLY: move the image's mutable :latest tag to RELEASE_DIGEST"
    cmds:
      - |
        set -euo pipefail
        docker buildx imagetools create \
          -t {{.IMAGE}}:latest \
          "{{.IMAGE}}@${RELEASE_DIGEST}"

  # Against the immutable digest, not the mutable tag. cosign/syft rather than buildx's own
  # --provenance/--sbom, which would break docker_manifests.
  release:sign:
    desc: "CI-ONLY: sign the image at RELEASE_DIGEST and attest its SBOM (cosign keyless)"
    cmds:
      - |
        set -euo pipefail
        REF="{{.IMAGE}}@${RELEASE_DIGEST}"
        cosign sign --yes "$REF"
        syft "$REF" -o spdx-json=image.sbom.spdx.json
        cosign attest --yes --predicate image.sbom.spdx.json --type spdxjson "$REF"

  metrics:
    desc: "Perf/distribution metrics (non-gating): Go startup vs Node oracle + artifact sizes -> artifacts/metrics.json"
    deps: [build]
    cmds:
      # Non-gating: never fail the caller. All measurement is best-effort.
      - cmd: go run ./cmd/devtool metrics {{.VERSION}} {{.ROOT_DIR}}/{{.BINARY}} {{.ROOT_DIR}}/reference/dist/spec-node/devContainersSpecCLI.js {{.ROOT_DIR}}/artifacts/metrics.json
        ignore_error: true

  # reference/ is upstream's submodule, pinned by upstream's yarn.lock. pnpm installs it, through
  # the firewall: `pnpm import` reads yarn.lock into a pnpm-lock.yaml at the same versions, and
  # the frozen install holds to it. Neither file pnpm needs can be committed to a submodule, so
  # both are made here, and stay beside node_modules as files the submodule does not track.
  reference:install:
    internal: true
    dir: reference
    status: [test -d node_modules]
    cmds:
      # allowBuilds: the two install scripts yarn ran. esbuild's checks its platform binary, and
      # node-pty, which the oracle loads to exec with a TTY, is compiled; pnpm runs no other.
      # verifyDepsBeforeRun: `pnpm run` would otherwise install what it finds out of date itself,
      # around the firewall.
      - |
        cat > pnpm-workspace.yaml <<'EOF'
        allowBuilds:
          esbuild: true
          node-pty: true
        verifyDepsBeforeRun: error
        EOF
      - go tool sfw pnpm import
      - go tool sfw pnpm install --frozen-lockfile

  reference:compile:
    internal: true
    deps: [reference:install]
    dir: reference
    sources: [src/**/*.ts, package.json, yarn.lock]
    generates: [dist/spec-node/devContainersSpecCLI.js]
    cmds:
      - pnpm run compile

  docker:clean:
    internal: true
    cmds:
      - docker ps -q --filter "label=devcontainer.local_folder" | xargs -r docker rm -f 2>/dev/null || true
      - docker ps -aq --filter "label=com.docker.compose.project" | xargs -r docker rm -f 2>/dev/null || true
    silent: true