Taskfile.yml

version: "3"

# Akua dev tasks. Run `task --list` to see available tasks.
#
# Invariant: every render runs in a wasmtime WASI sandbox. No shell-out.
# See CLAUDE.md + docs/security-model.md.

vars:
  HELM_ENGINE_WASM: crates/helm-engine-wasm/assets/helm-engine.wasm
  KUSTOMIZE_ENGINE_WASM: crates/kustomize-engine-wasm/assets/kustomize-engine.wasm
  # Produced by `task build:render-worker`. Embedded in the CLI at
  # build time via akuapkg-cli's build.rs — AOT-compiled to a .cwasm
  # matching the runtime wasmtime Config hash so per-render
  # Module::deserialize is a memcpy, not a Cranelift pass.
  RENDER_WORKER_WASM: target/wasm32-wasip1/release/akua-render-worker.wasm
  SDK_TYPES_DIR: packages/sdk/src/types

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

  # ---- Build / test / check ------------------------------------------------

  build:
    desc: Build the Rust workspace (no wasm engines — sandbox-only features)
    cmds:
      - cargo build --workspace

  test:
    desc: Run all Rust tests
    deps:
      - sandbox-artifacts
    cmds:
      - cargo test --workspace

  check:
    desc: cargo check + clippy
    deps:
      - sandbox-artifacts
    cmds:
      - cargo check --workspace
      - cargo clippy --workspace --all-targets -- -D warnings

  hooks:install:
    desc: Wire `.githooks/` as this repo's hooks dir (sets `core.hooksPath`)
    cmds:
      - git config core.hooksPath .githooks
      - echo "git hooks → .githooks (run \`git config --unset core.hooksPath\` to disable)"

  hooks:check-pre-push:
    desc: Check that pre-push stays a lightweight non-mutating default gate
    cmds:
      - bash scripts/check-pre-push-hook.sh

  fmt:
    desc: Format Rust code
    cmds:
      - cargo fmt --all

  fmt:check:
    desc: Check Rust formatting (no writes)
    cmds:
      - cargo fmt --all -- --check

  lint:
    desc: Run cargo clippy with warnings as errors
    deps:
      - sandbox-artifacts
    cmds:
      - cargo clippy --workspace --all-targets -- -D warnings

  # Rendering verbs (and clippy --all-targets, which compiles them) need
  # the embedded wasmtime sandbox artifacts on disk: akuapkg-cli's build.rs
  # precompiles them into the binary, and emits E_SANDBOX_UNAVAILABLE
  # when any is missing. Both lint + test depend on this.
  #
  # `deps:` runs children in parallel — the three builds are independent
  # toolchains (Rust→wasip1 + Go→wasip1 × 2) so concurrency is a
  # straightforward win.
  sandbox-artifacts:
    desc: Build every embedded wasm needed by akuapkg-cli's build.rs
    deps:
      - build:render-worker
      - build:helm-engine-wasm
      - build:kustomize-engine-wasm

  ci:
    desc: Run the full CI pipeline locally
    # fmt:check has no build deps; fan it out alongside the heavy tasks
    # so it finishes during the first few seconds of cargo compilation.
    # lint and test share sandbox-artifacts (built once, parallel
    # internal fan-out) and share cargo's target/ cache — the second
    # is mostly incremental.
    deps:
      - fmt:check
    cmds:
      - task: release:check-workflows
      - task: hooks:check-pre-push
      - task: lint
      - task: test

  site:gen:
    desc: Regenerate every site/* page from its source-of-truth (codes.rs / cli.md / docs/* / examples/*) and verify no internal links 404
    cmds:
      - bun scripts/gen-landing.ts
      - bun scripts/gen-start-page.ts
      - bun scripts/gen-error-pages.ts
      - bun scripts/gen-cli-pages.ts
      - bun scripts/gen-concept-pages.ts
      - bun scripts/gen-example-pages.ts
      - bun scripts/check-site-links.ts

  site:check-links:
    desc: Walk site/**/*.html and fail if any internal href/src points to a missing file or anchor
    cmds:
      - bun scripts/check-site-links.ts

  site:errors:gen:
    desc: Regenerate site/errors/*.html from cli_contract::codes
    cmds:
      - bun scripts/gen-error-pages.ts

  release:validate:
    desc: Pre-tag smoke — render every green example and diff against committed goldens
    deps:
      - build:engines
      - build:render-worker
    cmds:
      # Each green example commits its rendered/ output. The integration
      # tests already byte-diff every render against the golden, so this
      # task is the canonical pre-tag confidence check: if it's green,
      # render output is byte-identical to what shipped on main.
      # `--include-ignored` runs `examples_kcl_ecosystem`, which is
      # `#[ignore]`-gated by default (live ghcr.io pull + wasmtime
      # epoch budget make it flaky in `cargo test --workspace`).
      # Pre-tag we WANT it to run.
      - cargo test -p akuapkg-cli --features cosign-verify,dev-watch
          --test examples_helm_hello
          --test examples_hello_webapp
          --test examples_pkg_compose
          --test examples_kustomize_hello
          --test examples_kcl_ecosystem
          --test examples_install_as_package
          --test examples_subpackage_helm
          --test examples_export
          --test examples_helm_repo_dep
          -- --include-ignored

  release:check-workflows:
    desc: Check release workflow step ordering invariants
    cmds:
      - bash scripts/check-release-workflows.sh

  # ---- Release builds ------------------------------------------------------

  release:local:
    desc: Build the release binary locally
    cmds:
      - cargo build --release -p akuapkg-cli
      - ls -lh target/release/akuapkg

  release:target:
    desc: Build Akuapkg for a specific Rust target (used by the release workflow)
    vars:
      TARGET: '{{.TARGET | default "x86_64-unknown-linux-gnu"}}'
      CARGO: '{{.CARGO | default "cargo"}}'
    cmds:
      - '{{.CARGO}} build --release -p akuapkg-cli --target {{.TARGET}}'
      - ls -lh target/{{.TARGET}}/release/akuapkg

  # ---- Embedded engines (wasip1; built by Go toolchain, hosted by wasmtime)
  # Each engine is a Go program compiled to `wasm32-wasip1` and embedded in
  # akua-core. Never shell-out — see CLAUDE.md invariant.

  build:helm-engine-wasm:
    desc: Build the embedded Helm v4 template engine (Go → wasip1, forked; ~20 MB wasm)
    dir: crates/helm-engine-wasm
    status:
      - test -f assets/helm-engine.wasm
    cmds:
      - ./fork/apply.sh                          # clones helm@v4.1.4, applies client-go strip patch
      # go.sum is gitignored; re-sync in case apply.sh fast-pathed on an
      # already-patched fork tree and skipped its own `go mod tidy`.
      - cd go-src && go mod tidy
      # -buildmode=c-shared is load-bearing: `go:wasmexport` functions only
      # reach the host linker's symbol table under that buildmode on wasip1.
      - cd go-src && GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -ldflags='-s -w' -o ../assets/helm-engine.wasm .
      - ls -lh assets/helm-engine.wasm

  build:helm-engine-wasm:stock:
    desc: Build without the client-go strip patch (~75 MB wasm) — for cross-checking patch behaviour
    dir: crates/helm-engine-wasm
    cmds:
      - cd go-src && go mod edit -dropreplace helm.sh/helm/v4 && go mod tidy
      - cd go-src && GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -ldflags='-s -w' -o ../assets/helm-engine.wasm .
      - ls -lh assets/helm-engine.wasm

  build:kustomize-engine-wasm:
    desc: Build the embedded kustomize engine (Go → wasip1, stock kustomize; ~26 MB wasm)
    dir: crates/kustomize-engine-wasm
    status:
      - test -f assets/kustomize-engine.wasm
    cmds:
      # go.sum is gitignored (regenerated per build); populate it before
      # `go build` — otherwise fresh checkouts fail with "missing go.sum
      # entry for ...". `go mod tidy` is a no-op when already in sync.
      - cd go-src && go mod tidy
      - cd go-src && GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -ldflags='-s -w' -o ../assets/kustomize-engine.wasm .
      - ls -lh assets/kustomize-engine.wasm

  build:engines:
    desc: Build every embedded engine
    deps:
      - build:helm-engine-wasm
      - build:kustomize-engine-wasm

  # ---- Render worker (Rust → wasip1; the Phase 4 sandbox) ------------------

  build:render-worker:
    desc: Build akua-render-worker for wasm32-wasip1 (embedded in akuapkg-cli)
    # akua-core is linked into the worker, so akua-core edits change
    # the produced wasm. Without it in `sources:`, task's caching
    # reports "up to date" while akuapkg-cli's build.rs flags the worker
    # as stale — the contributor goes in circles.
    sources:
      - crates/akua-render-worker/**/*.rs
      - crates/akua-render-worker/Cargo.toml
      - crates/akua-core/src/**/*.rs
      - crates/akua-core/Cargo.toml
    generates:
      - "{{.RENDER_WORKER_WASM}}"
    cmds:
      # `strip` + `debug` overrides preserve the wasm `name` section so
      # wasmtime trap backtraces resolve to function names instead of
      # `wasm function NNNN`. Workspace `[profile.release]` strips
      # everything by default — this scopes the override to the worker
      # only without polluting other release builds.
      - >-
        cargo build --release -p akua-render-worker --target wasm32-wasip1
        --config 'profile.release.strip="none"'
        --config 'profile.release.debug="line-tables-only"'
      - ls -lh {{.RENDER_WORKER_WASM}}
      # Record the content hash of the sources the .wasm was just built
      # from. akuapkg-cli's build.rs reads this on next consumer build —
      # mismatch means host/worker drift (a release-quality bug).
      # Authoritative over mtime; not perturbed by `git checkout`.
      - >-
        cargo run --quiet -p source-hash --
        "{{.TASKFILE_DIR}}"
        "{{.RENDER_WORKER_WASM}}.sources.sha256"
        crates/akua-render-worker/src
        crates/akua-render-worker/Cargo.toml
        crates/akua-core/src
        crates/akua-core/Cargo.toml

  sdk:gen:
    desc: Regenerate packages/sdk/src/types/*.ts and src/schemas/akua.json from Rust serde types
    cmds:
      # ts-rs's `#[ts(export)]` emits one file per type when the
      # auto-generated `export_bindings_*` test runs. We pin the
      # output dir via `TS_RS_EXPORT_DIR` since the macro leaves
      # `export_to` empty. Run the lib tests for every crate that
      # declares a `contract_type!` — akua-core owns the shared
      # primitives, akuapkg-cli owns per-verb response shapes.
      - |
        TS_RS_EXPORT_DIR="$(pwd)/{{.SDK_TYPES_DIR}}" \
          cargo test -p akua-core --features ts-export --lib export_bindings
      - |
        TS_RS_EXPORT_DIR="$(pwd)/{{.SDK_TYPES_DIR}}" \
          cargo test -p akuapkg-cli --features schema-export,ts-export --lib export_bindings
      # schemars bundle — single `akua.json` with every type in
      # `$defs`. Triggered by the dedicated emission test.
      - cargo test -p akuapkg-cli --features schema-export,ts-export --test export_sdk_bundle

  sdk:check:
    desc: Fail if generated SDK artifacts drift from the Rust source
    cmds:
      - task: sdk:gen
      - git diff --exit-code -- packages/sdk/src/types packages/sdk/src/schemas

  sdk:install:
    desc: Install @akua-dev/sdk deps (bun)
    dir: packages/sdk
    cmds:
      - bun install --frozen-lockfile

  sdk:build:
    desc: Build @akua-dev/sdk for npm — delegates to packages/sdk's own `build` script
    # `package.json`'s "build" script (also `prepublishOnly`) is the single
    # source of truth for the bundler entrypoints + flags. It used to be a
    # second, independently-maintained copy of this command that only
    # bundled `src/mod.ts` — `src/execute.ts` silently fell out of the
    # entrypoint list, so `dist/execute.js` was never produced even though
    # `tsc --emitDeclarationOnly` still emitted `dist/execute.d.ts` for
    # every source file. `exports["./execute"]` pointed at a `.js` that
    # didn't exist, and nothing checked that until a real install broke
    # (shipped as the dead v0.9.3 npm release). Delegating here instead of
    # duplicating the command keeps CI (`task sdk:build`) and local/
    # `prepublishOnly` builds byte-identical by construction.
    deps: [sdk:install]
    dir: packages/sdk
    cmds:
      - bun run build

  sdk:test:
    desc: Run @akua-dev/sdk TS unit tests (bun + Node — engine-bridge tests gate on Node WASI)
    # `build:engines` was redundant — `native:build` already triggers
    # both engines via `native-engines:stage`. Listing it twice meant
    # `build:helm-engine-wasm` was reachable via two dep paths and got
    # invoked concurrently in CI, racing on the helm-fork tree. The
    # remaining deps converge on a single helm-engine-wasm invocation.
    # Keep sdk:install in cmds, not deps: Bun installs share workspace
    # state, so running it in parallel with native:install can race.
    deps: [native:build, build:render-worker]
    dir: packages/sdk
    cmds:
      - task: sdk:install
      - bun test

  sdk:e2e:
    desc: End-to-end — build akua, then run every SDK test with AKUA_E2E=1 (unlocks the gated e2e cases)
    deps: [sdk:install]
    cmds:
      - cargo build -p akuapkg-cli
      - cd packages/sdk && AKUA_E2E=1 bun test

  sdk:bench:
    desc: Render-throughput baseline for @akua-dev/sdk (cold + p50/p95/p99 warm). `task sdk:bench -- --check` enforces budgets.
    deps: [sdk:install]
    cmds:
      - cd packages/sdk && bun run bench/render-source.bench.ts {{.CLI_ARGS}}

  sdk:publish:check:
    desc: Dry-run `npm publish` — catches package manifest issues before tag push
    deps: [sdk:build]
    dir: packages/sdk
    cmds:
      # `npm pack --dry-run` reports the tarball contents + size without
      # writing or publishing. Catches missing files, wrong main/types
      # paths, accidental dist/ omission. On its own it only reports what
      # IS in the tarball — it doesn't know execute.js was ever supposed
      # to be there, which is exactly how v0.9.3 shipped a tarball that
      # "packed successfully" without dist/execute.js. The verify step
      # below cross-checks the packed file list against package.json's
      # exports map, so a missing entrypoint fails here instead of on a
      # customer's `npm install`. Writes outside dist/ — dist/ is fully
      # included by package.json's `files` array, so a leftover file
      # dropped in there would ship inside the real published tarball.
      - |
        pack_json="$(mktemp)"
        npm pack --dry-run --json > "$pack_json"
        bun run scripts/verify-package-exports.ts --tarball "$pack_json"
        rm -f "$pack_json"

  native:install:
    desc: Install @akua-dev/native deps (bun)
    dir: crates/akua-napi
    cmds:
      - bun install --frozen-lockfile

  native-engines:stage:
    desc: Copy helm + kustomize engine wasm into crates/akua-native-engines-npm/ so `bun install` resolves the package locally during dev.
    deps:
      - build:helm-engine-wasm
      - build:kustomize-engine-wasm
    cmds:
      - cp crates/helm-engine-wasm/assets/helm-engine.wasm crates/akua-native-engines-npm/helm-engine.wasm
      - cp crates/kustomize-engine-wasm/assets/kustomize-engine.wasm crates/akua-native-engines-npm/kustomize-engine.wasm

  native:build:
    desc: Build the napi addon for the host platform (release)
    deps: [native:install, native-engines:stage, build:render-worker]
    dir: crates/akua-napi
    cmds:
      - bunx napi build --platform --release

  native:publish:check:
    desc: Dry-run `npm pack` for the meta + per-platform native packages + engines.
    deps: [native:build]
    cmds:
      # Stage the per-platform npm/<target>/ directories the way the
      # release workflow does, then pack each + the meta + engines.
      - cd crates/akua-napi && bunx napi create-npm-dirs
      - cd crates/akua-napi && (bunx napi artifacts || true)  # no-op when only host artifact exists
      - |
        set -eu
        cd crates/akua-napi
        for dir in npm/*/; do
          echo "--- packing ${dir} ---"
          (cd "$dir" && npm pack --dry-run)
        done
        echo "--- packing meta @akua-dev/native ---"
        npm pack --dry-run
      - |
        echo "--- packing @akua-dev/native-engines ---"
        cd crates/akua-native-engines-npm
        npm pack --dry-run

  npm:bootstrap:
    desc: One-time local publish of 9 stub packages at 0.0.0-bootstrap.0 to claim names on npmjs.com. Run `npm login` first; afterwards configure trusted publishers per package and let CI handle real releases.
    vars:
      BOOTSTRAP_VERSION: 0.0.0-bootstrap.0
    cmds:
      # Sanity guards. Bootstrap mutates package.json files in-place
      # then restores them via the trap below; abort if the worktree
      # is dirty so a failure can't silently lose user changes.
      - |
        if ! npm whoami >/dev/null 2>&1; then
          echo "ERROR: not logged in to npm. Run \`npm login\` first." >&2
          exit 1
        fi
        if ! git diff --quiet HEAD -- crates/akua-napi/package.json packages/sdk/package.json; then
          echo "ERROR: crates/akua-napi/package.json or packages/sdk/package.json has uncommitted changes." >&2
          echo "Commit or stash before running npm:bootstrap (it rewrites these files temporarily)." >&2
          exit 1
        fi
        echo "Publishing as: $(npm whoami)"
        echo "Bootstrap version: {{.BOOTSTRAP_VERSION}}"
        echo "Press Ctrl-C in 5s to abort..."
        sleep 5
      # Patch versions to the bootstrap tag, generate per-platform npm
      # dirs, publish all 9 packages, then restore the originals via
      # `git checkout` regardless of whether publish succeeded.
      - |
        set -eu
        trap 'git checkout -- crates/akua-napi/package.json packages/sdk/package.json crates/akua-native-engines-npm/package.json 2>/dev/null || true' EXIT

        v={{.BOOTSTRAP_VERSION}}
        jq --arg v "$v" '.version = $v' \
          crates/akua-napi/package.json > crates/akua-napi/package.json.tmp
        mv crates/akua-napi/package.json.tmp crates/akua-napi/package.json
        jq --arg v "$v" \
          '.version = $v | .dependencies["@akua-dev/native"] = $v' \
          packages/sdk/package.json > packages/sdk/package.json.tmp
        mv packages/sdk/package.json.tmp packages/sdk/package.json
        jq --arg v "$v" '.version = $v' \
          crates/akua-native-engines-npm/package.json \
          > crates/akua-native-engines-npm/package.json.tmp
        mv crates/akua-native-engines-npm/package.json.tmp \
          crates/akua-native-engines-npm/package.json

        (cd crates/akua-napi && bunx napi create-npm-dirs)

        # Per-platform stubs first (no .node binary needed; we're just
        # claiming the name).
        for dir in crates/akua-napi/npm/*/; do
          echo "--- publishing ${dir} ---"
          (cd "$dir" && npm publish --access public --tag bootstrap)
        done

        # Engines stub — declared as a dep by the meta package, so
        # claim the name before publishing the meta.
        echo "--- publishing @akua-dev/native-engines ---"
        (cd crates/akua-native-engines-npm && npm publish --access public --tag bootstrap)

        # Meta package — declares optionalDependencies on the per-
        # platform stubs we just published + a hard dep on engines.
        echo "--- publishing meta @akua-dev/native ---"
        (cd crates/akua-napi && npm publish --access public --tag bootstrap)

        # SDK — depends on the meta. Build dist/ first so the tarball
        # has the same shape as a real release (lets us validate the
        # full publish manifest end-to-end).
        echo "--- building + publishing @akua-dev/sdk ---"
        task sdk:build
        (cd packages/sdk && npm publish --access public --tag bootstrap)

        echo
        echo "Bootstrap complete. Next:"
        echo "  1. https://www.npmjs.com/settings/akua-dev/packages — verify all 10 packages appear"
        echo "  2. For each package: Settings → Trusted Publishers → add GitHub Actions"
        echo "     org=akua-dev  repo=akua  workflow=release-publish.yml  environment=none"
        echo "  3. See docs/releasing.md before running a release."

  release:dry-run:
    desc: Run the full pre-release pipeline locally (gen + check + build + pack)
    cmds:
      # Mirrors the GitHub Actions release workflows — every step here
      # is what CI does, minus the actual `npm publish` (which needs
      # GitHub OIDC and can only run from Actions).
      - task: sdk:gen
      - task: sdk:check
      - task: native:publish:check
      - task: sdk:publish:check

  # ---- Sandbox test harness (Phase 4+) -------------------------------------

  test:sandbox:
    desc: Run the wasmtime-hosted render worker against the examples
    deps:
      - build:engines
    cmds:
      - echo "TODO (Phase 4 of docs/roadmap.md) — not yet implemented"
      - exit 1

  # ---- Coverage (Rust + SDK) ----------------------------------------------
  # The goal is coverage-driven bug discovery: every uncovered branch is a
  # latent test gap, which empirically correlates with bugs that ship.
  # `task coverage` prints workspace-wide line/branch numbers; the gap report
  # lists files under threshold so you know where to add tests next.

  coverage:rust:
    desc: Rust coverage — runs full workspace test suite under cargo-llvm-cov + nextest
    deps:
      - sandbox-artifacts                # tests need engines + render-worker .wasm on disk
    cmds:
      # cargo-llvm-cov compiles the workspace with profile-instrumented
      # codegen and merges per-test profiles into a single report.
      # cargo-nextest replaces libtest as the runner — process-per-test
      # isolation + default parallelism, ~2-3× faster on our 622-test
      # suite. `cargo llvm-cov nextest` is a first-class integration.
      # Auto-install both if missing; pinned versions keep CI reproducible.
      - command -v cargo-llvm-cov >/dev/null 2>&1 || cargo install cargo-llvm-cov --locked --version 0.6.16
      - command -v cargo-nextest >/dev/null 2>&1 || cargo install cargo-nextest --locked --version 0.9.86
      - cargo llvm-cov clean --workspace
      # Default features cover the cli + core + napi paths. Example
      # golden tests live behind cosign-verify + dev-watch in akuapkg-cli;
      # run them in a second instrumented pass so their lines count.
      # Test failures don't abort report generation — coverage of a
      # partially-failing run is still informative, and the report
      # itself surfaces what wasn't exercised. Run `cargo nextest run
      # --workspace` separately to fail-the-build on real test breakage.
      - cmd: cargo llvm-cov nextest --no-report --workspace --no-fail-fast
        ignore_error: true
      - cmd: cargo llvm-cov nextest --no-report -p akuapkg-cli --features cosign-verify,dev-watch --no-fail-fast
        ignore_error: true
      # Doc tests aren't covered by nextest; bring them in via libtest.
      # Small impact (~32 fence blocks across the workspace) but counted.
      - cmd: cargo llvm-cov --no-report --workspace --doctests
        ignore_error: true
      - cargo llvm-cov report --html --output-dir target/llvm-cov/html
      - cargo llvm-cov report --json --output-path target/llvm-cov/coverage.json
      - cargo llvm-cov report --summary-only

  coverage:rust:open:
    desc: Open the Rust coverage HTML report in the default browser
    cmds:
      - open target/llvm-cov/html/index.html

  coverage:sdk:
    desc: SDK coverage — bun test --coverage with text + lcov reporters
    dir: packages/sdk
    deps:
      - sdk:install
      - native:build                     # napi addon must exist; tests load it
      - build:render-worker              # render-worker .wasm needed by render tests
    cmds:
      - mkdir -p coverage
      - bun test --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir=coverage

  coverage:sdk:open:
    desc: Open the SDK coverage HTML report (renders lcov → html via genhtml)
    dir: packages/sdk
    cmds:
      - |
        if ! command -v genhtml >/dev/null 2>&1; then
          echo "Install lcov first (brew install lcov, or apt install lcov)" >&2
          exit 1
        fi
        genhtml coverage/lcov.info --output-directory coverage/html --quiet
        open coverage/html/index.html

  coverage:
    desc: Run both Rust + SDK coverage; total runtime ~5–10 min cold
    deps:
      - coverage:rust
      - coverage:sdk
    cmds:
      - |
        echo
        echo '=== Coverage summary ==='
        echo 'Rust HTML report:  target/llvm-cov/html/index.html'
        echo 'Rust JSON summary: target/llvm-cov/coverage.json'
        echo 'SDK lcov:          packages/sdk/coverage/lcov.info'
        echo 'Run `task coverage:gaps` to list files below threshold.'

  coverage:gaps:
    desc: 'List files below {{.THRESHOLD | default "60"}}% line coverage as bug-discovery candidates. Override with THRESHOLD=80.'
    vars:
      THRESHOLD: '{{.THRESHOLD | default "60"}}'
    cmds:
      - |
        if [ ! -f target/llvm-cov/coverage.json ]; then
          echo "No coverage data. Run \`task coverage:rust\` first." >&2
          exit 1
        fi
        echo "=== Rust files under {{.THRESHOLD}}% line coverage ==="
        cargo llvm-cov report --json | jq -r --argjson t {{.THRESHOLD}} '
          .data[0].files[]
          | select(.summary.lines.percent < $t)
          | "\(.summary.lines.percent | (. * 10 | floor) / 10)\t\(.filename | sub(".*/akua/"; ""))"
        ' | sort -n | column -t -s $'\t' || echo "(none)"
      - |
        if [ ! -f packages/sdk/coverage/lcov.info ]; then
          echo
          echo "No SDK coverage data. Run \`task coverage:sdk\` first to include SDK files." >&2
        else
          echo
          echo "=== SDK files under {{.THRESHOLD}}% line coverage ==="
          # parse lcov: SF:<file>; LF:<lines found>; LH:<lines hit>
          awk -v t={{.THRESHOLD}} '
            /^SF:/ { f=substr($0,4); lf=0; lh=0 }
            /^LF:/ { lf=substr($0,4) }
            /^LH:/ { lh=substr($0,4) }
            /^end_of_record$/ {
              if (lf > 0) {
                p = lh*100/lf
                if (p < t) printf "%.1f\t%s\n", p, f
              }
            }
          ' packages/sdk/coverage/lcov.info | sort -n | column -t -s $'\t' || echo "(none)"
        fi

  coverage:clean:
    desc: Wipe all coverage artifacts
    cmds:
      - rm -rf target/llvm-cov packages/sdk/coverage

  # ---- Quality gates (security audit, feature combinatorics, dead deps) ---

  audit:
    desc: Scan Cargo.lock against the RustSec advisory DB (cargo-audit)
    cmds:
      - command -v cargo-audit >/dev/null 2>&1 || cargo install cargo-audit --locked --version 0.21.2
      - cargo audit

  hack:
    desc: 'Test every feature combination across the workspace (cargo-hack). 18 feature flags = many combos; this catches feature-gated bugs before they ship.'
    cmds:
      - command -v cargo-hack >/dev/null 2>&1 || cargo install cargo-hack --locked --version 0.6.40
      # check is faster than test; we just want to catch compile-time
      # feature breakage. Run test-feature-combinations less often.
      - cargo hack check --feature-powerset --workspace --no-dev-deps

  hack:test:
    desc: 'Run tests across every feature combination (slower than `hack`; for pre-release).'
    deps:
      - sandbox-artifacts
    cmds:
      - command -v cargo-hack >/dev/null 2>&1 || cargo install cargo-hack --locked --version 0.6.40
      - cargo hack test --feature-powerset --workspace --no-fail-fast

  deps:unused:
    desc: Find unused workspace dependencies (cargo-machete)
    cmds:
      - command -v cargo-machete >/dev/null 2>&1 || cargo install cargo-machete --locked --version 0.7.1
      - cargo machete

  miri:
    desc: 'Run miri on the unsafe-heavy crate (engine-host-wasm has 15 unsafe blocks; Module::deserialize is the load-bearing one). Slow — keep out of default CI.'
    cmds:
      - rustup +nightly component add miri
      - cargo +nightly miri test -p engine-host-wasm

  build:timings:
    desc: 'Generate cargo build --timings HTML to diagnose slow compile bottlenecks (kcl-lang transitives are the usual suspect).'
    cmds:
      - cargo build --workspace --timings
      - 'echo "Open: target/cargo-timings/cargo-timing.html"'

  # ---- Clean ---------------------------------------------------------------

  clean:
    desc: Remove Rust target/
    cmds:
      - cargo clean

  clean:engines:
    desc: Remove embedded engine artifacts
    cmds:
      - rm -f {{.HELM_ENGINE_WASM}} {{.KUSTOMIZE_ENGINE_WASM}}