Taskfile.yml

version: '3'

silent: true

set: [errexit, nounset, pipefail]

vars:
  GIT_VERSION:
    sh: git describe --tags --always --dirty 2>/dev/null || echo dev
  VERSION: '{{.VERSION | default .GIT_VERSION}}'
  REGISTRY: '{{.REGISTRY | default "ghcr.io"}}'
  REPOSITORY: '{{.REPOSITORY | default "projectcapsule/change-windows"}}'
  IMG: '{{.IMG | default (printf "%s/%s:%s" .REGISTRY .REPOSITORY .VERSION)}}'
  IMAGE_PLATFORM: '{{.IMAGE_PLATFORM | default ""}}'
  PLATFORMS: '{{.PLATFORMS | default "linux/amd64,linux/arm64"}}'
  IMAGE_ARCHIVE: '{{.IMAGE_ARCHIVE | default "dist/controller.tar"}}'
  IMAGE_REF: '{{.IMAGE_REF | default ""}}'
  BUILD_DIR: '{{.BUILD_DIR | default "bin"}}'
  ARTIFACTS: '{{.ARTIFACTS | default "artifacts"}}'
  KIND_CLUSTER: '{{.KIND_CLUSTER | default "scheduled-action-e2e"}}'
  KIND_NODE_IMAGE: '{{.KIND_NODE_IMAGE | default "kindest/node:v1.36.1"}}'
  ENVTEST_K8S_VERSION: '{{.ENVTEST_K8S_VERSION | default "1.36.0"}}'
  ENVTEST_ASSETS_DIR: '{{.ENVTEST_ASSETS_DIR | default "bin/envtest"}}'
  GO_TEST_FLAGS: '{{.GO_TEST_FLAGS | default "-race"}}'
  ENTERPRISE_VERSION: '{{.ENTERPRISE_VERSION | default ""}}'
  ENTERPRISE_REGISTRY: '{{.ENTERPRISE_REGISTRY | default "registry.projectcapsule.dev"}}'
  DRY_RUN: '{{.DRY_RUN | default "false"}}'
  DOCS_BASE_URL: '{{.DOCS_BASE_URL | default "https://change-windows.addons.projectcapsule.dev/"}}'

  LAPTOP_HOST_IP: '{{.LAPTOP_HOST_IP | default ""}}'
  DEV_HOST: '{{.DEV_HOST | default .LAPTOP_HOST_IP | default ""}}'
  DEV_CONTEXT: '{{.DEV_CONTEXT | default ""}}'
  DEV_NAMESPACE: '{{.DEV_NAMESPACE | default "change-windows-system"}}'
  DEV_RELEASE: '{{.DEV_RELEASE | default "change-windows"}}'
  DEV_CERT_DIR: '{{.DEV_CERT_DIR | default "bin/dev/serving-certs"}}'
  DEV_IMAGE_MODE: '{{.DEV_IMAGE_MODE | default "kind"}}'
  DEV_KIND_CLUSTER: '{{.DEV_KIND_CLUSTER | default ""}}'
  DEV_HELM_VALUES: '{{.DEV_HELM_VALUES | default ""}}'
  DEV_TIMEOUT: '{{.DEV_TIMEOUT | default "180"}}'

tasks:
  default:
    desc: List available tasks.
    cmds:
      - task --list

  generate:
    desc: Generate DeepCopy methods.
    run: once
    cmds:
      - controller-gen object:headerFile=api/boilerplate.go.txt paths=./...

  manifests:
    desc: Generate CRDs and RBAC directly into the Helm chart.
    run: once
    cmds:
      - controller-gen rbac:roleName=manager-role,fileName=manager-role.yaml crd paths=./... output:crd:dir=charts/change-windows/crds output:rbac:dir=charts/change-windows/files

  fmt:
    desc: Format Go sources and maintained YAML files.
    cmds:
      - golangci-lint fmt
      - yamlfmt .

  vet:
    desc: Run go vet.
    cmds:
      - go vet ./...

  test:
    desc: Run unit and real API-server tests with the race detector.
    env:
      ENVTEST_K8S_VERSION: '{{.ENVTEST_K8S_VERSION}}'
      ENVTEST_ASSETS_DIR: '{{.ENVTEST_ASSETS_DIR}}'
      GO_TEST_FLAGS: '{{.GO_TEST_FLAGS}}'
    cmds:
      - task: generate
      - task: manifests
      - |
        if [ -z "${KUBEBUILDER_ASSETS:-}" ]; then
          KUBEBUILDER_ASSETS="$(setup-envtest use "$ENVTEST_K8S_VERSION" --bin-dir "$ENVTEST_ASSETS_DIR" -p path)"
        fi
        KUBEBUILDER_ASSETS="$(cd "$KUBEBUILDER_ASSETS" && pwd)"
        export KUBEBUILDER_ASSETS
        read -r -a flags <<< "$GO_TEST_FLAGS"
        go test "${flags[@]}" ./... -coverprofile=coverage.out

  test:unit:
    desc: Run unit tests without starting an API server.
    aliases: [test-unit]
    env:
      GO_TEST_FLAGS: '{{.GO_TEST_FLAGS}}'
    cmds:
      - task: generate
      - |
        read -r -a flags <<< "$GO_TEST_FLAGS"
        go test "${flags[@]}" ./... -skip '^TestAPI$'

  docs:generate:
    desc: Generate the API reference from Helm CRDs using crdoc.
    cmds:
      - task: manifests
      - crdoc --resources charts/change-windows/crds --template frontmatter.tmpl --toc docs/api-reference.yaml --output "${REFERENCE_PATH:-docs/content/docs/reference/api.md}"

  docs:install:
    desc: Install locked Doks theme and asset dependencies.
    dir: docs
    run: once
    cmds:
      - npm ci --ignore-scripts --no-audit --no-fund

  docs:build:
    desc: Build the Hugo documentation into dist/docs.
    env:
      DOCS_BASE_URL: '{{.DOCS_BASE_URL}}'
    cmds:
      - task: docs:install
      - task: docs:generate
      - npm --prefix docs run build -- --baseURL "$DOCS_BASE_URL"

  docs:serve:
    desc: Preview documentation at http://localhost:1313 with live reload.
    cmds:
      - task: docs:install
      - task: docs:generate
      - npm --prefix docs run dev -- --baseURL http://localhost:1313/

  docs:check:
    desc: Check API-reference drift and rendered links for root and subpath sites.
    cmds:
      - task: docs:install
      - |
        reference=$(mktemp)
        trap 'rm -f "$reference"' EXIT
        REFERENCE_PATH="$reference" task docs:generate
        diff -u docs/content/docs/reference/api.md "$reference" || {
          echo 'API reference is stale. Run task docs:generate.' >&2
          exit 1
        }
      - |
        scratch=$(mktemp -d)
        trap 'rm -rf "$scratch"' EXIT
        for prefix in '' schedule-actions; do
          site="$scratch/${prefix:-root}"
          npm --prefix docs run build -- --baseURL "https://change-windows.addons.projectcapsule.dev/${prefix:+$prefix/}" --destination "$site/$prefix"
          lychee --offline --include-fragments --index-files index.html --no-progress --root-dir "$site" \
            --remap "^https://change-windows[.]addons[.]projectcapsule[.]dev/(.*) file://$site/\$1" "$site/$prefix/**/*.html"
        done

  docs:test:browser:
    desc: Test the homepage YAML explorer on desktop and mobile Chromium.
    cmds:
      - task: docs:install
      - npm --prefix docs run test:browser

  docs:browser:install:
    desc: Install Chromium and its Linux runtime dependencies for documentation tests.
    cmds:
      - task: docs:install
      - npm --prefix docs exec -- playwright install --with-deps chromium

  headlamp:install:
    desc: Install the plugin's locked npm dependencies.
    dir: headlamp
    cmds:
      - npm ci --include=dev --no-audit --no-fund

  headlamp:check:
    desc: Lint, format-check, type-check, test and build the Headlamp plugin.
    dir: headlamp
    cmds:
      - npm run check

  headlamp:build:
    desc: Build the plugin into headlamp/dist.
    dir: headlamp
    cmds:
      - npm run build

  headlamp:serve:
    desc: Start the Headlamp SDK plugin development watcher.
    dir: headlamp
    cmds:
      - npm start

  headlamp:test:browser:
    desc: Test the built plugin in an existing Headlamp frontend using intercepted API fixtures.
    dir: headlamp
    cmds:
      - npm run build
      - npm run test:browser

  headlamp:package:
    desc: Package the plugin locally without publishing.
    dir: headlamp
    cmds:
      - npm run build
      - npm run package

  headlamp:release-build:
    desc: Check and build the versioned plugin for GoReleaser without changing source package files.
    env:
      HEADLAMP_VERSION: '{{trimPrefix "v" .VERSION}}'
    cmds:
      - task: headlamp:install
      - task: headlamp:check
      - npm --prefix headlamp/dist version "$HEADLAMP_VERSION" --no-git-tag-version --allow-same-version --ignore-scripts

  lint:
    desc: Lint Go sources.
    aliases: [golint]
    cmds:
      - golangci-lint run --timeout=5m

  lint:fix:
    desc: Apply Go lint and formatting fixes.
    aliases: [lint-fix, golint-fix]
    cmds:
      - golangci-lint fmt
      - golangci-lint run --fix --timeout=5m

  lint:config:
    desc: Validate the Go linter configuration.
    aliases: [lint-config]
    cmds:
      - golangci-lint config verify

  lint:yaml:
    desc: Validate YAML syntax and formatting without Python.
    aliases: [lint-yaml]
    cmds:
      - prek run check-yaml --all-files
      - task: lint:yaml:format

  lint:actions:
    desc: Validate GitHub Actions and inline shell scripts.
    aliases: [lint-actions]
    cmds:
      - actionlint -pyflakes=''

  lint:zizmor:
    desc: Security-lint GitHub Actions workflows with zizmor.
    aliases: [lint-zizmor]
    cmds:
      - zizmor .github/workflows/

  lint:zizmor-fix:
    desc: Security-lint GitHub Actions workflows with zizmor.
    aliases: [lint-zizmor-fix]
    cmds:
      - zizmor .github/workflows/ --fix=all

  lint:files:
    desc: Run native prek file hygiene and syntax checks.
    cmds:
      - prek run --group files {{if .CLI_ARGS}}--files {{.CLI_ARGS}}{{else}}--all-files{{end}}

  lint:commits:
    desc: Validate Conventional Commits between COMMIT_BASE and COMMIT_HEAD.
    cmds:
      - |
        : "${COMMIT_HEAD:=HEAD}"
        if [[ -z "${COMMIT_BASE:-}" || "$COMMIT_BASE" =~ ^0+$ ]]; then
          commits=$(git rev-list -1 "$COMMIT_HEAD" --)
        else
          commits=$(git rev-list "$COMMIT_BASE..$COMMIT_HEAD" --)
        fi
        while IFS= read -r commit; do
          [[ -n "$commit" ]] || continue
          git show -s --format=%B "$commit" -- | cog verify --ignore-merge-commits --file -
        done <<< "$commits"

  test:benchmarks:
    desc: Check benchmark fixtures with the race detector.
    cmds:
      - go test -race ./internal/... -run '^$' -bench . -benchtime=1x

  hooks:install:
    desc: Install prek's pre-commit and commit-msg hooks.
    cmds:
      - prek install --force --hook-type pre-commit --hook-type commit-msg

  hooks:check:
    desc: Run all pre-commit hooks on tracked files.
    cmds:
      - prek run --all-files

  verify-generated:
    desc: Reject stale or untracked generated artifacts.
    cmds:
      - task: generate
      - task: manifests
      - git diff --exit-code -- ':(glob)api/**/zz_generated*.go' charts/change-windows/crds charts/change-windows/files
      - |
        if [ -n "$(git ls-files --others --exclude-standard -- ':(glob)api/**/zz_generated*.go' charts/change-windows/crds charts/change-windows/files)" ]; then
          echo 'Untracked generated files found in api/ or Helm chart assets' >&2
          exit 1
        fi

  build:
    desc: Build the controller binary.
    aliases: [all]
    env:
      BUILD_DIR: '{{.BUILD_DIR}}'
    cmds:
      - task: generate
      - task: manifests
      - task: vet
      - mkdir -p "$BUILD_DIR"
      - go build -trimpath -o "$BUILD_DIR/manager" ./cmd

  run:
    desc: Run the controller against the current kubeconfig context.
    cmds:
      - task: generate
      - task: manifests
      - go run ./cmd

  dev:setup:
    desc: Install CRDs and admission webhooks pointing to DEV_HOST on port 9443.
    aliases: [dev-setup]
    env: &dev-env
      DEV_HOST: '{{.DEV_HOST}}'
      DEV_CONTEXT: '{{.DEV_CONTEXT}}'
      DEV_NAMESPACE: '{{.DEV_NAMESPACE}}'
      DEV_RELEASE: '{{.DEV_RELEASE}}'
      DEV_CERT_DIR: '{{.DEV_CERT_DIR}}'
    cmds:
      - task: generate
      - task: manifests
      - |
        bash -euo pipefail <<'BASH'
        umask 077

        : "${DEV_CONTEXT:?DEV_CONTEXT must name the development kubeconfig context}"

        # Validate before generating credentials or changing cluster resources.
        kubectl --context "$DEV_CONTEXT" cluster-info >/dev/null
        mkdir -p "$DEV_CERT_DIR"
        chmod 700 "$DEV_CERT_DIR"
        DEV_CERT_DIR=$(cd "$DEV_CERT_DIR" && pwd)
        cert="$DEV_CERT_DIR/tls.crt"
        key="$DEV_CERT_DIR/tls.key"

        : "${DEV_HOST:?Set DEV_HOST or LAPTOP_HOST_IP to a host reachable from the API server}"
        if [[ "$DEV_HOST" == *:* && "$DEV_HOST" =~ ^[0-9a-fA-F:]+$ ]]; then
          san="IP:$DEV_HOST"
          check=(-checkip "$DEV_HOST")
          url="https://[$DEV_HOST]:9443"
        elif [[ "$DEV_HOST" =~ ^[0-9.]+$ ]]; then
          san="IP:$DEV_HOST"
          check=(-checkip "$DEV_HOST")
          url="https://$DEV_HOST:9443"
        elif [[ "$DEV_HOST" =~ ^[a-zA-Z0-9][a-zA-Z0-9.-]*[a-zA-Z0-9]$ ]]; then
          san="DNS:$DEV_HOST"
          check=(-checkhost "$DEV_HOST")
          url="https://$DEV_HOST:9443"
        else
          echo 'DEV_HOST must be an IP address or DNS name, without a scheme, port, or path.' >&2
          exit 1
        fi
        case "$DEV_HOST" in
          localhost|127.*|::1|0.0.0.0|::) echo 'DEV_HOST must be reachable from the cluster, not a loopback or unspecified address.' >&2; exit 1 ;;
        esac

        # Keep the trust bundle stable across repeat setup; renew expiring or mismatched certs.
        if [[ ! -s "$cert" || ! -s "$key" ]] || \
          ! openssl x509 -in "$cert" -checkend 86400 -noout >/dev/null 2>&1 || \
          ! openssl x509 -in "$cert" "${check[@]}" -noout >/dev/null 2>&1; then
          temp=$(mktemp -d "$DEV_CERT_DIR/new.XXXXXX")
          trap 'rm -rf "$temp"' EXIT
          openssl req -x509 -newkey rsa:3072 -noenc -days 30 \
            -subj '/O=Project Capsule/CN=Change Windows development' \
            -addext "subjectAltName=$san" \
            -addext 'basicConstraints=critical,CA:TRUE' \
            -addext 'keyUsage=critical,digitalSignature,keyEncipherment,keyCertSign' \
            -addext 'extendedKeyUsage=serverAuth' \
            -keyout "$temp/tls.key" -out "$temp/tls.crt" 2>"$temp/openssl.log" || {
              cat "$temp/openssl.log" >&2
              exit 1
            }
          mv "$temp/tls.key" "$key"
          mv "$temp/tls.crt" "$cert"
          rm -rf "$temp"
          trap - EXIT
        fi
        chmod 600 "$key"
        ca_bundle=$(openssl base64 -A -in "$cert")

        # Inline CRDs avoid a hook job and make Helm the sole installer for development.
        # Keep CRDs on uninstall, while removing the fail-closed webhook configuration.
        helm --kube-context "$DEV_CONTEXT" upgrade --install "$DEV_RELEASE" charts/change-windows \
          --namespace "$DEV_NAMESPACE" --create-namespace --skip-crds --wait --timeout 2m \
          --set crds.install=true --set crds.inline=true --set crds.keep=true --set crds.exclusive=true \
          --set webhooks.enabled=true --set webhooks.exclusive=true \
          --set webhooks.certificate.generate.enabled=false \
          --set-string "webhooks.service.url=$url" \
          --set-string "webhooks.service.caBundle=$ca_bundle"
        kubectl --context "$DEV_CONTEXT" wait --for=condition=Established \
          crd/changewindows.addons.projectcapsule.dev --timeout=60s
        printf 'Admission points to %s. Start the host controller with task dev:run using the same DEV_CONTEXT and DEV_NAMESPACE.\n' "$url"
        BASH

  dev:run:
    desc: Run the host controller using the dev:setup certificates and kubeconfig context.
    aliases: [dev-run]
    env: *dev-env
    cmds:
      - |
        bash -euo pipefail <<'BASH'
        umask 077

        : "${DEV_CONTEXT:?DEV_CONTEXT must name the development kubeconfig context}"

        [[ -s "$DEV_CERT_DIR/tls.crt" && -s "$DEV_CERT_DIR/tls.key" ]] || { echo 'Run task dev:setup first to create the serving certificates.' >&2; exit 1; }
        DEV_CERT_DIR=$(cd "$DEV_CERT_DIR" && pwd)
        # Snapshot only the explicitly selected context, without mutating the user's config.
        run_dir=$(mktemp -d "$DEV_CERT_DIR/run.XXXXXX")
        controller_pid=''
        cleanup_run() {
          if [[ -n "$controller_pid" ]]; then
            kill -TERM "$controller_pid" 2>/dev/null || true
            wait "$controller_pid" || true
          fi
          rm -rf "$run_dir"
        }
        trap 'cleanup_run' EXIT
        trap 'exit 130' INT
        trap 'exit 143' TERM
        kubectl --context "$DEV_CONTEXT" config view --minify --flatten --raw > "$run_dir/kubeconfig"
        # go run does not reliably forward termination to its compiled child.
        go build -o "$run_dir/manager" ./cmd
        KUBECONFIG="$run_dir/kubeconfig" "$run_dir/manager" \
          --system-namespace="$DEV_NAMESPACE" \
          --webhook-cert-path="$DEV_CERT_DIR" \
          --metrics-bind-address=0 \
          --health-probe-bind-address=127.0.0.1:8081 &
        controller_pid=$!
        wait "$controller_pid"
        BASH

  dev:deploy:
    desc: Build current source with ko and deploy with Helm to an explicit development context.
    aliases: [dev-deploy]
    env:
      DEV_CONTEXT: '{{.DEV_CONTEXT}}'
      DEV_NAMESPACE: '{{.DEV_NAMESPACE}}'
      DEV_RELEASE: '{{.DEV_RELEASE}}'
      DEV_IMAGE_MODE: '{{.DEV_IMAGE_MODE}}'
      DEV_KIND_CLUSTER: '{{.DEV_KIND_CLUSTER}}'
      DEV_HELM_VALUES: '{{.DEV_HELM_VALUES}}'
      DEV_TIMEOUT: '{{.DEV_TIMEOUT}}'
      IMG: '{{.IMG}}'
      IMAGE_PLATFORM: '{{.IMAGE_PLATFORM}}'
      PLATFORMS: '{{.PLATFORMS}}'
      IMAGE_ARCHIVE: '{{.IMAGE_ARCHIVE}}'
    requires:
      vars:
        - name: DEV_IMAGE_MODE
          enum: [kind, registry]
    cmds:
      - task: generate
      - task: manifests
      - |
        bash -euo pipefail <<'BASH'
        umask 077

        : "${DEV_CONTEXT:?DEV_CONTEXT must name the development kubeconfig context}"
        if [[ "$DEV_IMAGE_MODE" == kind ]]; then
          : "${DEV_KIND_CLUSTER:?DEV_KIND_CLUSTER must name an existing Kind cluster}"
        fi
        [[ "$DEV_TIMEOUT" =~ ^[1-9][0-9]*$ ]] || { echo 'DEV_TIMEOUT must be a positive number of seconds' >&2; exit 1; }
        values=(--reset-values)
        if [[ -n "${DEV_HELM_VALUES:-}" ]]; then
          [[ -f "$DEV_HELM_VALUES" ]] || { echo "Helm values file not found: $DEV_HELM_VALUES" >&2; exit 1; }
          values+=(-f "$DEV_HELM_VALUES")
        fi
        kube=(kubectl --context "$DEV_CONTEXT")
        "${kube[@]}" cluster-info >/dev/null
        "${kube[@]}" get crd certificates.cert-manager.io issuers.cert-manager.io >/dev/null || {
          echo 'Install cert-manager before running dev:deploy.' >&2
          exit 1
        }

        temp=$(mktemp -d)
        trap 'rm -rf "$temp"' EXIT
        pull_policy=IfNotPresent
        if [[ "$DEV_IMAGE_MODE" == kind ]]; then
          # Verify the selected context actually connects to the cluster receiving the image.
          kind get kubeconfig --name "$DEV_KIND_CLUSTER" > "$temp/kubeconfig"
          cluster_path='{.clusters[0].cluster.server}{"\n"}{.clusters[0].cluster.certificate-authority-data}'
          expected=$(kubectl --kubeconfig "$temp/kubeconfig" config view --minify --flatten --raw -o "jsonpath=$cluster_path")
          actual=$("${kube[@]}" config view --minify --flatten --raw -o "jsonpath=$cluster_path")
          [[ -n "$expected" && "$actual" == "$expected" ]] || { echo 'DEV_CONTEXT does not point to DEV_KIND_CLUSTER' >&2; exit 1; }
          arch=$("${kube[@]}" get nodes -o 'jsonpath={range .items[*]}{.status.nodeInfo.architecture}{"\n"}{end}' | sort -u)
          case "$arch" in amd64|arm64) ;; *) echo 'Kind deployment requires a single amd64 or arm64 architecture' >&2; exit 1 ;; esac
          if [[ -n "${IMAGE_PLATFORM:-}" && "$IMAGE_PLATFORM" != "linux/$arch" ]]; then
            echo "IMAGE_PLATFORM must match the Kind nodes: linux/$arch" >&2
            exit 1
          fi
          export IMAGE_PLATFORM="linux/$arch"
          # Repeated deployments of an uncommitted working tree must replace running Pods.
          IMG="$IMG-$(date -u +%Y%m%d%H%M%S)-$(openssl rand -hex 4)"
          export IMG
          task image:build
          kind load image-archive "$IMAGE_ARCHIVE" --name "$DEV_KIND_CLUSTER"
          image="$IMG"
          pull_policy=Never
          # Kind runs inside containers which may not support nested user namespaces.
          values+=(--set manager.hostUsers=true)
        else
          image=$(task image:push)
        fi

        # Inline CRDs avoid a separate hook image and support upgrades from dev:setup.
        # Explicitly replace host webhook settings when switching to in-cluster execution.
        helm --kube-context "$DEV_CONTEXT" upgrade --install "$DEV_RELEASE" charts/change-windows \
          --namespace "$DEV_NAMESPACE" --create-namespace --skip-crds \
          --wait --timeout "${DEV_TIMEOUT}s" "${values[@]}" \
          --set crds.install=true --set crds.inline=true --set crds.keep=true --set crds.exclusive=false \
          --set webhooks.enabled=true --set webhooks.exclusive=false \
          --set-string webhooks.service.url= --set-string webhooks.service.caBundle= \
          --set webhooks.certificate.generate.enabled=true \
          --set-string "manager.image.reference=$image" \
          --set-string "manager.image.pullPolicy=$pull_policy"
        selector="app.kubernetes.io/instance=$DEV_RELEASE"
        "${kube[@]}" -n "$DEV_NAMESPACE" rollout status deployment --selector "$selector" --timeout="${DEV_TIMEOUT}s"
        "${kube[@]}" -n "$DEV_NAMESPACE" wait certificate --selector "$selector" --for=condition=Ready --timeout="${DEV_TIMEOUT}s"
        for index in 0 1; do
          "${kube[@]}" wait validatingwebhookconfiguration --selector "$selector" \
            --for="jsonpath={.webhooks[$index].clientConfig.caBundle}" --timeout="${DEV_TIMEOUT}s"
        done
        # Probe through the API server to check TLS and admission registration, with no persisted object.
        deadline=$((SECONDS + DEV_TIMEOUT))
        until "${kube[@]}" create --dry-run=server -f playground/manifests/dev/readiness.yaml > "$temp/probe.log" 2>&1; do
          if (( SECONDS >= deadline )); then cat "$temp/probe.log" >&2; exit 1; fi
          sleep 1
        done
        printf 'Deployed %s to %s (%s/%s); controller and admission are ready.\n' "$image" "$DEV_CONTEXT" "$DEV_NAMESPACE" "$DEV_RELEASE"
        BASH

  image:build:
    desc: Build a Linux image archive with ko, without a container daemon or registry push.
    aliases: ['image:ko', ko-build-controller, ko-build-all]
    vars: &image-vars
      IMAGE_TAG: '{{.IMG | splitList ":" | last}}'
      IMAGE_REPOSITORY: '{{trimSuffix (printf ":%s" .IMAGE_TAG) .IMG}}'
    env: &image-env
      IMG: '{{.IMG}}'
      IMAGE_TAG: '{{.IMAGE_TAG}}'
      KO_DOCKER_REPO: '{{.IMAGE_REPOSITORY}}'
      CGO_ENABLED: '0'
      IMAGE_PLATFORM: '{{.IMAGE_PLATFORM}}'
      IMAGE_ARCHIVE: '{{.IMAGE_ARCHIVE}}'
      PLATFORMS: '{{.PLATFORMS}}'
    preconditions: &tagged-image
      - sh: '[[ "$IMG" != *@* && "${IMG##*/}" == *:* && "$IMAGE_TAG" =~ ^[a-zA-Z0-9_][a-zA-Z0-9_.-]{0,127}$ && "$KO_DOCKER_REPO" =~ ^[a-z0-9][a-z0-9./:_-]*$ ]]'
        msg: IMG must contain a repository and one valid tag, without a digest.
    cmds:
      - task: generate
      - |
        : "${IMAGE_PLATFORM:=linux/$(go env GOHOSTARCH)}"
        [[ "$IMAGE_PLATFORM" == linux/* && "$IMAGE_PLATFORM" != *,* ]] || { echo 'IMAGE_PLATFORM must select one Linux architecture' >&2; exit 1; }
        mkdir -p "$(dirname "$IMAGE_ARCHIVE")"
        rm -f "$IMAGE_ARCHIVE"
        ko build ./cmd --bare "--tags=$IMAGE_TAG" --push=false "--platform=$IMAGE_PLATFORM" "--tarball=$IMAGE_ARCHIVE" --tag-only

  image:push:
    desc: Publish multi-platform images with ko and print the immutable index reference.
    aliases: [ko-publish-controller]
    vars: *image-vars
    env: *image-env
    preconditions: *tagged-image
    cmds:
      - task generate >&2
      - |
        # ko's stdout is the index; --image-refs also includes child manifests.
        ref=$(ko build ./cmd --bare "--tags=$IMAGE_TAG" --push=true "--platform=$PLATFORMS")
        if [[ ! "$ref" =~ ^[^[:space:]@]+@sha256:[a-f0-9]{64}$ ]] ||
           [[ "${ref%@*}" != "$KO_DOCKER_REPO" && "${ref%@*}" != "$IMG" ]]; then
          echo 'ko did not produce the expected immutable image reference' >&2
          exit 1
        fi
        printf '%s@%s\n' "$KO_DOCKER_REPO" "${ref##*@}"

  image:sign:
    desc: Sign an immutable IMAGE_REF returned by image:push or helm:push.
    env:
      IMAGE_REF: '{{.IMAGE_REF}}'
    cmds:
      - |
        ref=${IMAGE_REF:?Set IMAGE_REF to the immutable reference to sign}
        if [[ ! "$ref" =~ ^[^[:space:]@]+@sha256:[a-f0-9]{64}$ ]]; then
          echo 'IMAGE_REF must be one immutable image reference' >&2
          exit 1
        fi
        cosign sign --yes "$ref"

  registry:login:
    desc: Authenticate ko and Cosign with REGISTRY_USERNAME and REGISTRY_PASSWORD.
    env:
      REGISTRY: '{{.REGISTRY}}'
    cmds:
      - printf '%s' "${REGISTRY_PASSWORD:?REGISTRY_PASSWORD is required}" | ko login "$REGISTRY" --username "${REGISTRY_USERNAME:?REGISTRY_USERNAME is required}" --password-stdin

  helm:login:
    desc: Authenticate Helm with REGISTRY_USERNAME and REGISTRY_PASSWORD.
    env:
      REGISTRY: '{{.REGISTRY}}'
    cmds:
      - printf '%s' "${REGISTRY_PASSWORD:?REGISTRY_PASSWORD is required}" | helm registry login "$REGISTRY" --username "${REGISTRY_USERNAME:?REGISTRY_USERNAME is required}" --password-stdin

  playground:
    desc: Run a disposable Kind playground with Flux-managed Headlamp for up to 30 minutes.
    env:
      PLAYGROUND_CLUSTER: '{{.PLAYGROUND_CLUSTER | default "change-windows-playground"}}'
      PLAYGROUND_MINUTES: '{{.PLAYGROUND_MINUTES | default "30"}}'
      PLAYGROUND_PORT: '{{.PLAYGROUND_PORT | default "18081"}}'
      KIND_NODE_IMAGE: '{{.KIND_NODE_IMAGE}}'
    cmds:
      - |
        bash -euo pipefail <<'BASH'
        umask 077
        [[ "$PLAYGROUND_MINUTES" =~ ^([1-9]|[12][0-9]|30)$ ]] || { echo 'PLAYGROUND_MINUTES must be between 1 and 30' >&2; exit 1; }
        if [[ ! "$PLAYGROUND_PORT" =~ ^[1-9][0-9]{0,4}$ ]] || (( PLAYGROUND_PORT > 65535 )); then
          echo 'Invalid PLAYGROUND_PORT' >&2; exit 1
        fi
        [[ "$PLAYGROUND_CLUSTER" =~ ^[a-z0-9][a-z0-9-]{0,50}[a-z0-9]$ ]] || { echo 'Invalid PLAYGROUND_CLUSTER' >&2; exit 1; }
        clusters=$(kind get clusters)
        if grep -Fxq "$PLAYGROUND_CLUSTER" <<< "$clusters"; then
          echo "Refusing to reuse or delete existing cluster $PLAYGROUND_CLUSTER" >&2
          exit 1
        fi
        # Check the local listener before any expensive builds or cluster creation.
        node -e 'const s = require("node:net").createServer(); s.on("error", e => { console.error(e.message); process.exit(1); }); s.listen(Number(process.argv[1]), "127.0.0.1", () => s.close());' "$PLAYGROUND_PORT"
        temp=$(mktemp -d)
        export KUBECONFIG="$temp/kubeconfig"
        cluster_started=false
        forward_pid=''
        cleanup() {
          result=$?
          trap - EXIT INT TERM
          if [[ -n "$forward_pid" ]]; then
            kill "$forward_pid" 2>/dev/null || true
            wait "$forward_pid" 2>/dev/null || true
          fi
          if [[ "$cluster_started" == true ]]; then
            kind delete cluster --name "$PLAYGROUND_CLUSTER" || result=1
          fi
          rm -rf "$temp"
          exit "$result"
        }
        trap cleanup EXIT
        trap 'exit 130' INT
        trap 'exit 143' TERM

        root="$PWD"
        task headlamp:install headlamp:build
        mkdir -p "$temp/plugins/capsule-change-windows"
        cp headlamp/dist/main.js headlamp/dist/package.json "$temp/plugins/capsule-change-windows/"
        chmod -R a+rX "$temp/plugins"
        cluster_started=true
        (cd "$temp" && kind create cluster --name "$PLAYGROUND_CLUSTER" --image "$KIND_NODE_IMAGE" \
          --config "$root/playground/kind.config.yaml" --kubeconfig "$KUBECONFIG" --wait 120s)
        kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.21.2/cert-manager.yaml
        for deployment in cert-manager cert-manager-webhook cert-manager-cainjector; do
          kubectl -n cert-manager rollout status "deployment/$deployment" --timeout=120s
        done
        export DEV_CONTEXT="kind-$PLAYGROUND_CLUSTER"
        export DEV_NAMESPACE=schedule-action-controller-system
        export DEV_RELEASE=change-windows
        export DEV_IMAGE_MODE=kind
        export DEV_KIND_CLUSTER="$PLAYGROUND_CLUSTER"
        export DEV_HELM_VALUES=playground/installation/change-windows/values.yaml
        export IMG=change-windows:playground
        export IMAGE_ARCHIVE="$temp/controller.tar"
        task dev:deploy
        kubectl apply -k playground/manifests
        kubectl wait changewindow/playground --for=condition=Ready --timeout=120s
        flux install --components=source-controller,helm-controller --watch-all-namespaces=false --timeout=180s
        kubectl apply -k playground/installation/headlamp
        kubectl -n flux-system wait helmrelease/headlamp --for=condition=Ready --timeout=300s
        kubectl -n kube-system rollout status deployment/headlamp --timeout=120s
        kubectl -n kube-system port-forward service/headlamp "$PLAYGROUND_PORT:80" --address=127.0.0.1 > "$temp/forward.log" 2>&1 &
        forward_pid=$!
        url="http://127.0.0.1:$PLAYGROUND_PORT"
        deadline=$((SECONDS + 60))
        until curl --fail --silent --show-error --max-time 5 "$url/plugins/capsule-change-windows/main.js" -o "$temp/main.js"; do
          if ! kill -0 "$forward_pid" 2>/dev/null || (( SECONDS >= deadline )); then cat "$temp/forward.log" >&2; exit 1; fi
          sleep 1
        done
        cmp headlamp/dist/main.js "$temp/main.js"
        printf '\nPlayground ready: %s\nCluster: %s\nExpires in %s minutes. Ctrl+C also deletes it.\n' "$url" "$PLAYGROUND_CLUSTER" "$PLAYGROUND_MINUTES"
        # Start the usable lifetime after all components and the current plugin are ready.
        deadline=$(( $(date +%s) + PLAYGROUND_MINUTES * 60 ))
        while (( $(date +%s) < deadline )); do
          if ! kill -0 "$forward_pid" 2>/dev/null; then cat "$temp/forward.log" >&2; exit 1; fi
          sleep 1 &
          wait $!
        done
        BASH

  e2e:
    desc: Build and deploy through dev:deploy in isolated Kind, then run e2e tests.
    aliases: [test-e2e]
    env:
      KIND_CLUSTER: '{{.KIND_CLUSTER}}'
      KIND_NODE_IMAGE: '{{.KIND_NODE_IMAGE}}'
      IMG: '{{.IMG}}'
      ARTIFACTS: '{{.ARTIFACTS}}'
      IMAGE_ARCHIVE: '{{.IMAGE_ARCHIVE}}'
    cmds:
      - |
        bash -euo pipefail <<'BASH'
        umask 077
        mkdir -p "$ARTIFACTS"
        : > "$ARTIFACTS/e2e.log"
        printf 'image=%s\nnode=%s\ncluster=%s\n' "$IMG" "$KIND_NODE_IMAGE" "$KIND_CLUSTER" > "$ARTIFACTS/run.txt"
        clusters=$(kind get clusters)
        if grep -Fxq "$KIND_CLUSTER" <<< "$clusters"; then
          echo "Refusing to reuse or delete existing cluster $KIND_CLUSTER" >&2
          exit 1
        fi
        # A private kubeconfig prevents changing the developer's current context.
        export KUBECONFIG
        KUBECONFIG=$(mktemp)
        cluster_started=false
        cleanup() {
          result=$?
          trap - EXIT INT TERM
          if [[ "$cluster_started" == true ]]; then
            kind export logs --name "$KIND_CLUSTER" "$ARTIFACTS/cluster" > "$ARTIFACTS/export.log" 2>&1 || true
            kubectl get events -A > "$ARTIFACTS/events.log" 2>&1 || true
            kubectl get changewindows -o yaml > "$ARTIFACTS/changewindows.yaml" 2>&1 || true
            kubectl logs -n schedule-action-controller-system deployment/change-windows > "$ARTIFACTS/controller.log" 2>&1 || true
            kind delete cluster --name "$KIND_CLUSTER" || result=1
          fi
          rm -f "$KUBECONFIG"
          exit "$result"
        }
        trap cleanup EXIT
        trap 'exit 130' INT
        trap 'exit 143' TERM
        cluster_started=true
        kind create cluster --name "$KIND_CLUSTER" --image "$KIND_NODE_IMAGE" --kubeconfig "$KUBECONFIG" --wait 120s
        kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.21.2/cert-manager.yaml
        for deployment in cert-manager cert-manager-webhook cert-manager-cainjector; do
          kubectl -n cert-manager rollout status "deployment/$deployment" --timeout=120s
        done
        export DEV_CONTEXT="kind-$KIND_CLUSTER"
        export DEV_NAMESPACE=schedule-action-controller-system
        export DEV_RELEASE=change-windows
        export DEV_IMAGE_MODE=kind
        export DEV_KIND_CLUSTER="$KIND_CLUSTER"
        export DEV_HELM_VALUES=charts/change-windows/ci/admission-values.yaml
        task dev:deploy
        # A second deployment must also converge without leaving an old image running.
        previous_image=$(kubectl -n "$DEV_NAMESPACE" get deployment change-windows -o jsonpath='{.spec.template.spec.containers[0].image}')
        task dev:deploy
        current_image=$(kubectl -n "$DEV_NAMESPACE" get deployment change-windows -o jsonpath='{.spec.template.spec.containers[0].image}')
        [[ "$current_image" != "$previous_image" ]] || { echo 'Repeated dev deployment did not roll the image' >&2; exit 1; }
        printf 'first-image=%s\nsecond-image=%s\n' "$previous_image" "$current_image" >> "$ARTIFACTS/run.txt"
        # The e2e build tag keeps cluster-dependent tests out of ordinary go test runs.
        go test -tags=e2e ./e2e -v -count=1 -timeout=8m 2>&1 | tee "$ARTIFACTS/e2e.log"
        BASH

  helm:lint:
    desc: Validate Helm packaging.
    aliases: [helm-lint]
    cmds:
      - task: manifests
      - task: helm:schema
      - helm lint charts/change-windows --strict
      - |
        for values in charts/change-windows/ci/*-values.yaml; do
          helm lint charts/change-windows --strict --values "$values"
        done

  helm:docs:
    desc: Generate chart documentation from values and the chart README template.
    cmds:
      - helm-docs --chart-search-root charts/change-windows

  helm:schema:
    desc: Generate the Helm values JSON schema using Helm Docs comments.
    aliases: [helm-schema]
    dir: charts/change-windows
    cmds:
      - helm schema --use-helm-docs

  helm:artifacthub:
    desc: Lint chart metadata with the Artifact Hub CLI container.
    env:
      CHART_DIRECTORY: '{{.ROOT_DIR}}/charts'
    cmds:
      - docker run --rm --volume "${CHART_DIRECTORY}:/charts:ro" --workdir /charts --entrypoint ah artifacthub/ah lint

  helm:verify:
    desc: Check chart rendering and generated documentation/schema drift.
    cmds:
      - task: helm:lint
      - task: helm:docs
      - git diff --exit-code -- charts/change-windows/README.md charts/change-windows/values.schema.json
      - test -z "$(git ls-files --others --exclude-standard charts/change-windows/README.md charts/change-windows/values.schema.json)"

  helm:package:
    desc: Package the chart using VERSION.
    env:
      CHART_VERSION: '{{trimPrefix "v" .VERSION}}'
    cmds:
      - task: manifests
      - task: helm:schema
      - mkdir -p dist/charts
      - helm package charts/change-windows --version "$CHART_VERSION" --app-version "$CHART_VERSION" --destination dist/charts

  helm:push:
    desc: Publish the chart to CHART_REGISTRY and print its immutable reference.
    env:
      CHART_VERSION: '{{trimPrefix "v" .VERSION}}'
      CHART_REGISTRY: '{{.CHART_REGISTRY | default "oci://ghcr.io/projectcapsule/charts"}}'
    cmds:
      - task helm:package >&2
      - |
        if ! output=$(helm push "dist/charts/change-windows-$CHART_VERSION.tgz" "$CHART_REGISTRY" 2>&1); then
          printf '%s\n' "$output" >&2
          exit 1
        fi
        printf '%s\n' "$output" >&2
        digest=$(printf '%s\n' "$output" | sed -n 's/^Digest: \(sha256:[a-f0-9]*\)$/\1/p')
        if [[ ! "$digest" =~ ^sha256:[a-f0-9]{64}$ ]]; then
          echo 'Helm did not return a valid digest' >&2
          exit 1
        fi
        printf '%s/change-windows@%s\n' "${CHART_REGISTRY#oci://}" "$digest"

  release:check:
    desc: Validate GoReleaser configuration.
    cmds:
      - goreleaser check

  release:snapshot:
    desc: Build release archives and SBOMs without publishing or signing.
    cmds:
      - task: release:check
      - goreleaser release --snapshot --clean --skip=publish,sign --timeout 90m

  release:
    desc: Publish a tagged GitHub release (explicit invocation only).
    cmds:
      - task: release:check
      - goreleaser release --clean --timeout 90m

  enterprise:release:
    desc: Publish the enterprise image and chart (use DRY_RUN=true to preview).
    aliases: [enterprise-release]
    vars:
      CHANNEL: '{{.CHANNEL | default "enterprise"}}'
      CHART_PATH: '{{if eq .CHANNEL "prereleases"}}charts/prereleases{{else}}charts{{end}}'
    requires:
      vars:
        - name: CHANNEL
          enum: [enterprise, prereleases]
        - name: DRY_RUN
          enum: ['true', 'false']
    env:
      ENTERPRISE_VERSION: '{{.ENTERPRISE_VERSION}}'
      DRY_RUN: '{{.DRY_RUN}}'
      IMAGE_REPOSITORY: '{{.ENTERPRISE_REGISTRY}}/{{.CHANNEL}}/change-windows'
      CHART_REGISTRY: 'oci://{{.ENTERPRISE_REGISTRY}}/{{.CHART_PATH}}'
    cmds:
      - |
        bash -euo pipefail <<'BASH'
        : "${ENTERPRISE_VERSION:?Set ENTERPRISE_VERSION to the release version}"
        run() {
          if [[ "$DRY_RUN" == true ]]; then printf '%q ' "$@"; printf '\n'; else "$@"; fi
        }
        run env "VERSION=$ENTERPRISE_VERSION" task helm:package
        run env "IMG=$IMAGE_REPOSITORY:$ENTERPRISE_VERSION" task image:push
        run env "VERSION=$ENTERPRISE_VERSION" "CHART_REGISTRY=$CHART_REGISTRY" task helm:push
        printf '\nDeployment (requires cert-manager and a capsule-enterprise image pull secret):\n'
        printf 'helm upgrade --install scheduled-action %q --namespace capsule-system --create-namespace --version %q --set-string manager.image.reference=%q --set %q\n' \
          "$CHART_REGISTRY/change-windows" "$ENTERPRISE_VERSION" "$IMAGE_REPOSITORY:$ENTERPRISE_VERSION" 'serviceAccount.imagePullSecrets[0]=capsule-enterprise'
        BASH

  enterprise:prerelease:
    desc: Publish the prerelease image and chart (use DRY_RUN=true to preview).
    aliases: [enterprise-prerelease]
    cmds:
      - task: enterprise:release
        vars: {CHANNEL: prereleases}

  check:
    desc: Run the checks used by CI (e2e runs separately).
    cmds:
      - task: test
      - task: lint
      - task: lint:config
      - task: lint:files
      - task: lint:yaml
      - task: lint:actions
      - task: lint:zizmor
      - task: helm:lint
      - task: verify-generated
      - task: build
      - task: docs:check

  lint:yaml:format:
    desc: Check maintained YAML formatting.
    cmds:
      - yamlfmt -lint {{if .CLI_ARGS}}{{.CLI_ARGS}}{{else}}.{{end}}

  lint:commit-message:
    desc: Validate a commit-message file supplied after --.
    cmds:
      - cog verify --ignore-merge-commits --file {{.CLI_ARGS}}