Justfile

# GloriousFlywheel - Unified Task Runner
# =====================================
#
# Consolidated task automation for the pooled runner, cache, and dashboard
# substrate. Prefer entering through direnv or nix develop first, then use
# these repo entrypoints instead of ad hoc local-heavy workflows.
#
# Prerequisites:
#   - just (https://github.com/casey/just)
#   - direnv (loads Nix devShell automatically)
#   - Nix with flakes enabled
#
# Quick Start:
#   direnv allow            # Preferred devshell entrypoint
#   just setup              # Seed local config files and backend scaffolds
#   just info               # Show substrate and backend state
#   just                    # List all commands
#   just check              # Run bounded local validation
#   ENV=dev just tofu-init attic
#   ENV=dev just tofu-plan attic
#
# Environment Setup:
#   Create .env from .env.example and choose one backend-init path:
#     - TOFU_BACKEND_CONFIG_FILE=/abs/path/backend.hcl
#     - TOFU_BACKEND_CONFIG_DIR=$PWD/config/backends
#     - TOFU_BACKEND_S3_* environment variables for the active S3-backed stacks
#     - TF_HTTP_* only for legacy or archived HTTP-backend repair paths
#   S3-backed local helper paths:
#     - just tofu-backend-scaffold-s3 <stack>
#     - just tofu-backend-materialize-s3 <stack>
#   Legacy GitLab state init remains available via:
#     just tofu-init-gitlab-legacy <stack>
#   Live backend direction:
#     environment-owned S3-compatible state on `honey`
#   The .envrc automatically loads .env via direnv (dotenv_if_exists)
#
# Environment Selection:
#   ENV=prod just tofu-plan attic    # Target prod cluster
#   ENV=dev just tofu-plan attic     # Target dev cluster (default)

# Default recipe - list available commands
default:
    @just --list --unsorted

# Set up local development environment
setup:
    #!/usr/bin/env bash
    set -euo pipefail

    echo "Setting up local development environment..."
    echo

    # Check for .env file
    if [ ! -f .env ]; then
        echo "Creating .env from .env.example..."
        cp .env.example .env
        echo
        echo "Edit .env and choose your preferred backend-init path."
        echo "Recommended current local path:"
        echo "  1. For the active stacks, prefer TOFU_BACKEND_S3_* or copy"
        echo "     config/backend.s3.example.hcl into config/backends/<stack>-<env>.hcl"
        echo "  2. Use that file directly, or set TOFU_BACKEND_CONFIG_DIR=\$PWD/config/backends"
        echo "  3. Files under config/backends/ are auto-detected by just tofu-init <stack>."
        echo
        echo "Compatibility path:"
        echo "  Export TF_HTTP_ADDRESS / TF_HTTP_LOCK_ADDRESS / TF_HTTP_UNLOCK_ADDRESS"
        echo "  Use this only for legacy stacks or archived HTTP-backend repair work."
        echo
        echo "S3-backed helper path:"
        echo "  just tofu-backend-scaffold-s3 <stack>"
        echo "  or export TOFU_BACKEND_S3_* and run just tofu-backend-materialize-s3 <stack>"
        echo "  These helpers write local backend files for the active S3-backed contract."
        echo
        echo "Legacy compatibility path:"
        echo "  Set TF_HTTP_PASSWORD (and optionally TF_HTTP_USERNAME) and use"
        echo "  just tofu-init-gitlab-legacy <stack>"
        echo
        echo "Live backend direction:"
        echo "  environment-owned S3-compatible state on honey"
        echo
        echo "After editing .env, reload direnv:"
        echo "  direnv allow"
        echo
    else
        echo ".env already exists"
    fi

    LOCAL_BACKEND_COUNT="$(find config/backends -maxdepth 1 -name '*.hcl' 2>/dev/null | wc -l | tr -d ' ')"

    if [ -n "${TOFU_BACKEND_CONFIG_FILE:-}" ]; then
        echo "TOFU_BACKEND_CONFIG_FILE: configured ✓"
    elif [ -n "${TOFU_BACKEND_CONFIG_DIR:-}" ]; then
        echo "TOFU_BACKEND_CONFIG_DIR: configured ✓"
    elif [ "${LOCAL_BACKEND_COUNT:-0}" -gt 0 ]; then
        echo "Local backend files: detected in config/backends ✓"
    elif [ -n "${TOFU_BACKEND_S3_ENDPOINT:-}" ] && [ -n "${TOFU_BACKEND_S3_BUCKET:-}" ]; then
        echo "TOFU_BACKEND_S3_*: configured ✓"
    elif [ -n "${TF_HTTP_ADDRESS:-}" ]; then
        echo "TF_HTTP_ADDRESS: configured ✓"
    elif [ -n "${TF_HTTP_PASSWORD:-}" ]; then
        echo "Legacy TF_HTTP_PASSWORD: configured ✓"
    else
        echo "WARNING: no backend-init path configured yet"
        echo "  Preferred: TOFU_BACKEND_CONFIG_FILE or TOFU_BACKEND_CONFIG_DIR"
        echo "  Active-stack path: TOFU_BACKEND_S3_* environment variables"
        echo "  HTTP path: TF_HTTP_* only for legacy or archived repair work"
        echo "  Local helper: just tofu-backend-scaffold-s3 <stack> or TOFU_BACKEND_S3_* + just tofu-backend-materialize-s3 <stack>"
        echo "  Legacy: TF_HTTP_PASSWORD + just tofu-init-gitlab-legacy <stack>"
        echo "  Live direction: environment-owned S3-compatible state on honey"
    fi

    echo
    echo "Setup complete! Run 'just info' to confirm substrate mode and backend state."

# =============================================================================
# Configuration
# =============================================================================

# Organization config file location
org_config := "config/organization.yaml"

# Environment (set via ENV variable)
env := env_var_or_default("ENV", "dev")

# GitLab compatibility settings (optional, loaded from organization config)
gitlab_url := `yq '.gitlab.url // ""' config/organization.yaml 2>/dev/null || echo ""`
gitlab_project := `yq '.gitlab.project_id // ""' config/organization.yaml 2>/dev/null || echo ""`
gitlab_api := if gitlab_url != "" { gitlab_url + "/api/v4" } else { "" }

# Kubernetes context based on environment (loaded from organization config)
configured_kube_context := `ENV="${ENV:-dev}" && yq ".clusters[] | select(.name == \"$ENV\") | .context // \"\"" config/organization.yaml 2>/dev/null || echo ""`
kube_context_env := env_var_or_default("KUBE_CONTEXT", "")
kube_context := if kube_context_env != "" { kube_context_env } else if configured_kube_context != "" { configured_kube_context } else { "honey" }
kubeconfig_path := `ENV="${ENV:-dev}" && yq ".clusters[] | select(.name == \"$ENV\") | .kubeconfig_path // \"\"" config/organization.yaml 2>/dev/null || echo ""`

# Ingress domain based on environment (loaded from organization config)
ingress_domain := `ENV="${ENV:-dev}" && yq ".clusters[] | select(.name == \"$ENV\") | .domain" config/organization.yaml 2>/dev/null || echo ""`

# Make repo-managed wrappers available to Just recipes even when direnv or
# `nix develop` has not been entered yet. `scripts/tofu` falls back to the
# flake-owned OpenTofu app when host OpenTofu is unavailable.
export PATH := justfile_directory() + "/scripts:" + env_var_or_default("PATH", "")

# SOCKS proxy configuration (optional, loaded from organization config)
socks_host := `yq '.network.proxy_host // ""' config/organization.yaml 2>/dev/null || echo ""`
socks_port := `yq '.network.proxy_port // "1080"' config/organization.yaml 2>/dev/null || echo "1080"`
socks_proxy := if socks_host != "" { "socks5h://localhost:" + socks_port } else { "" }

# =============================================================================
# Network Proxy (Optional)
# =============================================================================

# Start SOCKS proxy (configure ssh host in ~/.ssh/config)
proxy-up:
    @if ssh -O check proxy-host 2>/dev/null; then \
        echo "Proxy already running on localhost:{{socks_port}}"; \
    else \
        echo "Starting SOCKS proxy on localhost:{{socks_port}}..."; \
        ssh -fN proxy-host; \
        echo "Proxy up. Use: HTTPS_PROXY={{socks_proxy}} kubectl ..."; \
    fi

# Stop SOCKS proxy
proxy-down:
    @ssh -O exit proxy-host 2>/dev/null && echo "Proxy stopped" || echo "Proxy not running"

# Check SOCKS proxy status
proxy-status:
    @if ssh -O check proxy-host 2>/dev/null; then \
        echo "Proxy: RUNNING on localhost:{{socks_port}}"; \
        echo "Test:  HTTPS_PROXY={{socks_proxy}} curl -sI https://your-service.example.com"; \
    else \
        echo "Proxy: NOT RUNNING"; \
        echo "Start: just proxy-up"; \
    fi

# Run kubectl through SOCKS proxy (auto-starts proxy if needed)
bk *args:
    #!/usr/bin/env bash
    set -euo pipefail
    if ! ssh -O check proxy-host 2>/dev/null; then
        echo "Starting proxy..." >&2
        ssh -fN proxy-host
    fi
    HTTPS_PROXY={{socks_proxy}} kubectl {{args}}

# Run curl through SOCKS proxy
bcurl *args:
    #!/usr/bin/env bash
    set -euo pipefail
    if ! ssh -O check proxy-host 2>/dev/null; then
        echo "Starting proxy..." >&2
        ssh -fN proxy-host
    fi
    HTTPS_PROXY={{socks_proxy}} curl {{args}}

# =============================================================================
# Development Workflows
# =============================================================================

# Bounded local validation cycle (format + links + public export scrub)
check: fmt-check check-links check-public-docs public-alpha-export-check dogfood-contract-audit dogfood-contract-audit-self-test arc-auth-secret-redaction-contract-check product-reality-review-check rbe-boundary-check rbe-storage-provider-boundary-check rbe-proof-contract-check rbe-target-eligibility-check rbe-platform-contracts-check rbe-worker-toolchain-model-contract-check gf-reapi-cell-chapel-contract-check browser-runtime-authority-contract-check web-rbe-candidate-template-contract-check arc-runner-executor-endpoint-contract-check gf-reapi-cell-manifest-check gf-reapi-cache-frontdoor-contract-check gf-reapi-cell-capacity-policy-check gf-reapi-fairness-dashboard-contract-check gf-runner-ttfch-probe-contract-check gf-reapi-cell-publish-contract-check gf-reapi-cell-digest-resolver-contract-check gf-reapi-cell-proof-contract-check darwin-rbe-proof-dispatch-contract-check darwin-rbe-proof-readiness-contract-check gf-reapi-cell-proof-artifact-contract-check gf-reapi-proof-artifact-download-contract-check gf-reapi-ac-nuke-key-contract-check gf-reapi-ac-attestation-chaos-check bazel-app-image-contract-check nix2container-adapter-node-image-contract-check bazel-devshell-authority-check nix-flake-source-input-authority-contract-check nix-flake-source-mirror-package-contract-check nix-flake-source-authority-package-contract-check bazel-cache-exposure-policy-check bazel-remote-cache-cas-integrity-contract-check pilot-workflow-contract-check workflow-cache-proof-check gf-hit-gate-contract-check bazel-executor-backed-contract-check bazel-benchmark-modes-contract-check consumer-bazel-wrapper-contract-check flywheel-consumer-env-contract-check flywheel-profile-distribution-contract-check flywheel-enrollment-frontdoor-contract-check flywheel-github-oidc-profile-contract-check flywheel-frontdoor-kit-contract-check dev-attach-contract-check kvm-cache-prewarm-contract-check kvm-capacity-policy-contract-check rustfs-openebs-restart-hygiene-contract-check rustfs-lifecycle-secret-contract-check tofu-state-contract-check rustfs-bucket-index-rca-empty-state-keys-contract-check rustfs-state-authority-parser-contract-check attic-nar-integrity-contract-check rustfs-repair-surface-contract-check rustfs-admin-status-contract-check rustfs-heal-semantics-contract-check rustfs-bucket-meta-semantics-contract-check rustfs-trusted-publication-gate-contract-check attic-backend-replacement-package-contract-check rustfs-upgrade-topology-candidate-contract-check rustfs-upgrade-topology-proof-plan-contract-check rustfs-upgrade-topology-plan-guard-contract-check bazel-external-fetch-authority bazel-repository-cache-evidence-contract-check bazel-http-archive-pins-check bazel-external-input-manifest-check bazel-external-input-distdir-check bazel-distdir-coverage-contract-check bazel-distdir-mirror-package-contract-check bazel-distdir-mirror-restore-contract-check bazel-distdir-full-package-proof-contract-check bazel-external-input-authority-contract-check bazel-external-input-authority-package-contract-check bazel-distdir-mirror-github-readiness-contract-check e3-external-input-authority-status-contract-check bazel-distdir-mirror-live-proof-contract-check bazel-vendor-mode-canary-contract-check bazel-external-fetch-authority-self-test bazel-lockfile-contract-check bazel-lockfile-check ha-state-candidate-inventory-contract-check ha-state-authority-truth-contract-check ha-state-candidate-static-gate-contract-check ha-state-selected-candidate-contract-check ha-state-endpoint-package-contract-check ha-state-endpoint-readiness-contract-check ha-state-github-secret-readiness-contract-check ha-state-candidate-proof-contract-check k8s-secret-last-applied-audit-contract-check arc-runner-rehome-manifest-check orgwide-enrollment-scoreboard-contract-check orgwide-enrollment-queue-contract-check arc-diagnostic-self-tests arc-source-cap-targets-check arc-local-apply-source-guard-check kubelet-imagefs-capacity-audit-self-test spoke-onboarding-contract-check consumers-onboarding-contract-check org-tenant-registry-contract-check consumer-registry-writeback-contract-check codeowners-registry-contract-check gf-reapi-cell-lease-gc-reconcile-check
    @echo "All checks passed!"

# Validate markdown cross-references resolve to real files
check-links:
    @node scripts/check-links.js --mode markdown

# Validate the future public docs package manifest and scrub rules
check-public-docs:
    @node scripts/generate-public-docs-reference.js check
    @node scripts/public-docs-export.js check

# Validate source-repo dogfood contract drift stays classified
dogfood-contract-audit:
    @node scripts/dogfood-contract-audit.js

# Prove the dogfood audit catches hosted scalar, block-list, matrix, and exception drift
dogfood-contract-audit-self-test:
    @bash ./tests/dogfood_contract_audit.sh

# Validate ARC auth secret dry-run output never prints credential material
arc-auth-secret-redaction-contract-check:
    @bash ./tests/arc_auth_secret_redaction_contract.sh

# Validate the BCR/RBE/RustFS product reality review stays grounded
product-reality-review-check:
    @python3 ./scripts/validate-product-reality-review.py

# Validate the repo still proves Bazel remote cache, not remote execution
rbe-boundary-check:
    @python3 ./scripts/validate-rbe-boundary.py

# Validate CAS/distdir storage provider docs do not select Civo or a default provider
rbe-storage-provider-boundary-check:
    @python3 ./scripts/validate-rbe-storage-provider-boundary.py

# Validate the explicit, non-default RBE proof wrapper contract
rbe-proof-contract-check:
    @bash ./tests/rbe_proof_wrapper_contract.sh

# Validate target-class eligibility before expanding RBE claims
rbe-target-eligibility-check:
    @bash ./tests/rbe_target_eligibility_contract.sh

# Validate Linux and Darwin RBE platform identities and boundaries
rbe-platform-contracts-check:
    @bash ./tests/rbe_platform_contracts.sh

# Validate the spoke registry against the spoke-* module contract (W4.5)
spoke-onboarding-contract-check:
    @bash ./tests/spoke_onboarding_contract.sh

# Validate the RBE/image consumer registry-of-record (config/consumer-registry.json)
consumers-onboarding-contract-check:
    @bash ./tests/consumer_onboarding_contract.sh

# Validate the schema-only org tenant registry for future org-grained tenancy (TIN-2364)
org-tenant-registry-contract-check:
    @bash ./tests/org_tenant_registry_contract.sh

# Validate the consumer-registry write-back latch contract (TIN-2212): offline
# fixture battery with a stubbed gh (happy path, idempotency, stale-run and
# absent-entry refusals, cache-hits-only mode, red run).
consumer-registry-writeback-contract-check:
    @bash ./tests/consumer_registry_writeback_contract.sh

# Assert .github/CODEOWNERS exists and owner-gates both credential-granting
# registries (D6, TIN-2212) — keeps the "CODEOWNERS-gated registry entry"
# claim in the enrollment governance docs machine-true.
codeowners-registry-contract-check:
    @bash ./tests/codeowners_registry_contract.sh

# Register / re-validate an RBE/image consumer: edit config/consumer-registry.json
# to add your entry, then run this. Static, GF-core-only; live reality is
# confirmed by `just flywheel-enroll-verify` in the implementation overlay.
flywheel-enroll-register:
    @python3 ./scripts/validate-consumer-registry.py --self-test
    @python3 ./scripts/validate-consumer-registry.py
    @echo "Registered consumers:"
    @python3 -c "import json; [print('  -', c['github_repository'], '->', c['runner_class'], '/', c['image_repository']) for c in json.load(open('config/consumer-registry.json'))['consumers']]"

# Register / re-validate a schema-only org tenant. This does not grant runtime
# exchange/cell authority; it only records explicit future org tenancy.
flywheel-org-tenant-register:
    @python3 ./scripts/validate-org-tenant-registry.py --self-test
    @python3 ./scripts/validate-org-tenant-registry.py
    @echo "Registered org tenants:"
    @python3 -c "import json; [print('  -', t['tenant_id'], '->', t['github_owner'], '/', t['migration_stage'], '/', 'runtime=' + str(t['runtime_grants_enabled']).lower()) for t in json.load(open('config/org-tenant-registry.json'))['tenants']]"

# Latch observed enrollment reality from a finished run (green conclusion +
# parsed Bazel remote counts) onto the matching registry entry (TIN-2212).
# Auto-detects the run's repo across config/consumer-registry.json and
# config/spoke-registry.json (D1: spokes latch on their spoke entry). Never
# creates or edits intent fields — the entry must already exist. Idempotent
# per run id; refuses runs older than the recorded latch.
flywheel-enroll-writeback run_url:
    @python3 ./scripts/consumer-registry-writeback.py --run-url "{{run_url}}"
    @python3 ./scripts/validate-consumer-registry.py
    @python3 ./scripts/validate-spoke-registry.py

# Latch a fresh-repo enrollment proof onto the DISPATCHED consumer's registry
# entry (TIN-2126). The proof runs in this repo's Actions but proves the
# consumer named by its run title ('Fresh enroll <owner/repo>@<ref>'); the
# latch records the host under proof_repository. Same contract as
# flywheel-enroll-writeback otherwise.
flywheel-enroll-writeback-consumer run_url entry_repo:
    @python3 ./scripts/consumer-registry-writeback.py --run-url "{{run_url}}" --entry-repo "{{entry_repo}}"
    @python3 ./scripts/validate-consumer-registry.py
    @python3 ./scripts/validate-spoke-registry.py

# Validate the current RBE worker image and toolchain model boundary
rbe-worker-toolchain-model-contract-check:
    @bash ./tests/rbe_worker_toolchain_model_contract.sh

# Validate the pinned Chapel candidate closure in the shared Linux worker image
gf-reapi-cell-chapel-contract-check:
    @bash ./tests/gf_reapi_cell_chapel_contract.sh

# Validate the browser runtime authority contract for web RBE proofs
browser-runtime-authority-contract-check:
    @bash ./tests/browser_runtime_authority_contract.sh

# Validate the public web RBE candidate template and guide
web-rbe-candidate-template-contract-check:
    @bash ./tests/web_rbe_candidate_template_contract.sh

# Validate opt-in ARC runner executor endpoint wiring
arc-runner-executor-endpoint-contract-check:
    @bash ./tests/arc_runner_executor_endpoint_contract.sh

# Validate the explicit gf-rbe REAPI proof manifest boundary
gf-reapi-cell-manifest-check:
    @bash ./tests/gf_reapi_cell_manifest_contract.sh

# Validate the token-enforced, routable gf-reapi-cell cache front-door gate
gf-reapi-cache-frontdoor-contract-check:
    @bash ./tests/gf_reapi_cache_frontdoor_contract.sh

# Validate gf-reapi-cell proof-window residency and runner-capacity boundary
gf-reapi-cell-capacity-policy-check:
    @bash ./tests/gf_reapi_cell_capacity_policy_contract.sh

# Validate the first gf-reapi-cell tenant fairness operator dashboard contract
gf-reapi-fairness-dashboard-contract-check:
    @bash ./tests/gf_reapi_fairness_dashboard_contract.sh

# Validate the first runner-side TTFCH probe and dashboard contract
gf-runner-ttfch-probe-contract-check:
    @bash ./tests/gf_runner_ttfch_probe_contract.sh

# Validate the app image still uses the current rules_img package-load contract.
bazel-app-image-contract-check:
    @bash ./tests/bazel_app_image_contract.sh

# Validate the reusable nix2container adapter-node image builder for nix-only spokes.
nix2container-adapter-node-image-contract-check:
    @bash ./tests/nix2container_adapter_node_image_contract.sh

# Validate gf-reapi-cell image publication and manifest rendering boundary
gf-reapi-cell-publish-contract-check:
    @bash ./tests/gf_reapi_cell_publish_contract.sh

# Validate gf-reapi-cell GHCR digest resolution for proof dispatch inputs
gf-reapi-cell-digest-resolver-contract-check:
    @bash ./tests/gf_reapi_cell_digest_resolver_contract.sh

# Validate the explicit gf-reapi-cell live proof harness boundary
gf-reapi-cell-proof-contract-check:
    @bash ./tests/gf_reapi_cell_proof_contract.sh

# Validate the Darwin-specific proof dispatch/readiness wrapper
darwin-rbe-proof-dispatch-contract-check:
    @bash ./tests/darwin_rbe_proof_dispatch_contract.sh

# Validate the Darwin proof readiness preflight
darwin-rbe-proof-readiness-contract-check:
    @bash ./tests/darwin_rbe_proof_readiness_contract.sh

# Check Darwin proof inputs and render the dry-run dispatch command
darwin-rbe-proof-readiness *args:
    @bash ./scripts/check-darwin-rbe-proof-readiness.sh {{args}}

# Validate client-lease vs GC-TTL reconciliation (W1.3)
gf-reapi-cell-lease-gc-reconcile-check:
    @bash ./tests/gf_reapi_cell_lease_gc_reconcile_contract.sh

# Prove the gf-reapi-cell S3 backend against a real MinIO server (SigV4 + full
# CAS round-trip). Opt-in / not in `check`: spins a throwaway MinIO via nix.
gf-reapi-cell-s3-minio-proof:
    cd services/gf-reapi-cell && \
      GF_REAPI_MINIO_BIN="$(nix build --no-link --print-out-paths nixpkgs#minio)/bin/minio" \
      go test -tags minio_integration ./internal/cell/ -run MinIO -count=1 -v

# Resolve the immutable published gf-reapi-cell image digest from GitHub Packages
gf-reapi-cell-resolve-digest *args:
    @bash ./scripts/resolve-gf-reapi-cell-digest.sh {{args}}

# Validate downloaded gf-reapi-cell proof artifact evidence
gf-reapi-cell-proof-artifact-contract-check:
    @bash ./tests/gf_reapi_cell_proof_artifact_contract.sh

# Validate hosted proof artifact download + verification handoff
gf-reapi-proof-artifact-download-contract-check:
    @bash ./tests/gf_reapi_proof_artifact_download_contract.sh

# Download and verify a hosted GF REAPI Cell Proof artifact
gf-reapi-proof-artifact-download *args:
    @bash ./scripts/download-gf-reapi-proof-artifact.sh {{args}}

# Validate surgical gf-reapi-cell action-cache invalidation and rollback
gf-reapi-ac-nuke-key-contract-check:
    @bash ./tests/gf_reapi_ac_nuke_key_contract.sh

# Validate the W2.5 gf-reapi-cell AC writer-attestation chaos gate
gf-reapi-ac-attestation-chaos-check:
    @bash ./tests/gf_reapi_cell_ac_attestation_chaos.sh

# Test the minimal GF-owned REAPI proof cell
gf-reapi-cell-test:
    @cd services/gf-reapi-cell && go test ./...

# Mint a short-lived gf-reapi-cell JWT/profile from GitHub OIDC without
# printing bearer tokens.
gf-reapi-token-exchange *args:
    @nix run .#gf-reapi-token-exchange -- {{args}}

# Run the explicit RBE proof wrapper. Requires operator-provided proof env.
bazel-rbe-proof *args:
    @bash ./scripts/bazel-rbe-proof.sh {{args}}

# Run or render the explicit gf-reapi-cell proof harness
gf-reapi-cell-proof *args:
    @bash ./scripts/run-gf-reapi-cell-proof.sh {{args}}

# Dispatch or render the hosted GF REAPI Cell Proof workflow
gf-reapi-cell-proof-dispatch *args:
    @bash ./scripts/dispatch-gf-reapi-cell-proof.sh {{args}}

# Dry-run or execute a surgical gf-reapi-cell action-cache nuke-key drill
gf-reapi-ac-nuke-key *args:
    @python3 ./scripts/gf-reapi-ac-nuke-key.py {{args}}

# Validate devshell Bazel resolves through Bazelisk and .bazelversion.
bazel-devshell-authority-check:
    @python3 ./scripts/validate-bazel-devshell-authority.py

# Validate the developer-machine and package-cache exposure policy boundary.
bazel-cache-exposure-policy-check:
    @bash ./tests/bazel_cache_exposure_policy.sh

# Audit bazel-remote CAS decoded payload digest integrity.
bazel-remote-cache-cas-integrity-audit *args:
    @python3 ./scripts/bazel-remote-cache-cas-integrity-audit.py {{args}}

# Validate the bazel-remote CAS integrity audit contract.
bazel-remote-cache-cas-integrity-contract-check:
    @bash ./tests/bazel_remote_cache_cas_integrity_contract.sh

# Validate public pilot workflow examples stay cache-backed and write-gated.
pilot-workflow-contract-check:
    @bash ./tests/pilot_workflow_template_contract.sh

# Validate the opt-in executor-backed Bazel wrapper contract.
bazel-executor-backed-contract-check:
    @bash ./tests/bazel_executor_backed_contract.sh

# Validate mode-separated Bazel benchmark evidence generation.
bazel-benchmark-modes-contract-check:
    @bash ./tests/bazel_benchmark_modes_contract.sh

# Validate the copied consumer Bazel wrapper's cache/fetch/input wiring.
consumer-bazel-wrapper-contract-check:
    @bash ./tests/consumer_bazel_wrapper_contract.sh

# Validate the consumer Bazel environment profile materializer.
flywheel-consumer-env-contract-check:
    @bash ./tests/flywheel_consumer_env_contract.sh

# Validate the fleet-managed non-secret profile distribution contract.
flywheel-profile-distribution-contract-check:
    @bash ./tests/flywheel_profile_distribution_contract.sh

# Validate the enroll/doctor/verify front-door classification contract.
flywheel-enrollment-frontdoor-contract-check:
    @bash ./tests/flywheel_enrollment_frontdoor_contract.sh

# Validate the hosted GitHub OIDC token-exchange profile helper.
flywheel-github-oidc-profile-contract-check:
    @bash ./tests/flywheel_github_oidc_profile_contract.sh

# Validate the distributable consumer front-door kit.
flywheel-frontdoor-kit-contract-check:
    @bash ./tests/flywheel_frontdoor_kit_contract.sh

# Explain the current GloriousFlywheel enrollment/profile state.
flywheel-doctor *args:
    @bash ./scripts/flywheel-doctor.sh {{args}}

# Fail unless the current shell is attached or explicitly in local-proof mode.
flywheel-verify *args:
    @bash ./scripts/flywheel-verify.sh {{args}}

# Materialize a fallback .env.flywheel.local profile for a consumer repo.
flywheel-enroll profile *args:
    @bash ./scripts/flywheel-enroll.sh "{{profile}}" {{args}}

# Exchange GitHub Actions OIDC for a short-lived gf-reapi-cell profile.
flywheel-github-oidc-profile *args:
    @bash ./scripts/flywheel-github-oidc-profile.sh {{args}}

# Materialize a non-secret GloriousFlywheel consumer Bazel environment profile.
flywheel-consumer-env profile *args:
    @bash ./scripts/flywheel-consumer-env.sh "{{profile}}" {{args}}

# Validate .agents/skills/<name>/SKILL.md contracts (frontmatter, 1536-char
# description cap, body length) and the .claude/skills symlink mirror.
skills-validate:
    @python3 ./scripts/validate-skills.py
    @for link in .claude/skills/*; do \
        name="$(basename "$link")"; \
        if [ ! -L "$link" ] || [ ! -f "$link/SKILL.md" ]; then \
            echo "FAIL $name: .claude/skills/$name must be a symlink resolving to .agents/skills/$name" >&2; exit 1; \
        fi; \
        if [ ! -d ".agents/skills/$name" ]; then \
            echo "FAIL $name: symlink exists but .agents/skills/$name does not" >&2; exit 1; \
        fi; \
    done
    @for skill in .agents/skills/*/; do \
        name="$(basename "$skill")"; \
        if [ ! -L ".claude/skills/$name" ]; then \
            echo "FAIL $name: missing .claude/skills/$name symlink" >&2; exit 1; \
        fi; \
    done
    @echo "skills symlink mirror OK"

# List the published agent skills.
skills-list:
    @ls -1 .agents/skills/

# Validate the developer cache attachment helper does not false-positive.
dev-attach-contract-check:
    @bash ./tests/dev_attach_contract.sh

# Validate the trusted KVM cache prewarm boundary.
kvm-cache-prewarm-contract-check:
    @bash ./tests/kvm_cache_prewarm_contract.sh

# Validate the KVM runner capacity policy boundary.
kvm-capacity-policy-contract-check:
    @bash ./tests/kvm_capacity_policy_contract.sh

# Validate RustFS/OpenEBS restart hygiene stays bounded.
rustfs-openebs-restart-hygiene-contract-check:
    @bash ./tests/rustfs_openebs_restart_hygiene.sh

# Validate RustFS lifecycle jobs keep credentials out of rendered pod args.
rustfs-lifecycle-secret-contract-check:
    @bash ./tests/rustfs_lifecycle_secret_contract.sh

# Validate live honey state keys stay explicit and fail closed elsewhere.
tofu-state-contract-check:
    @bash ./tests/tofu_state_contract.sh

# Validate bucket-only RustFS RCA mode handles no required state keys.
rustfs-bucket-index-rca-empty-state-keys-contract-check:
    @bash ./tests/rustfs_bucket_index_rca_empty_state_keys.sh

# Validate RustFS S3 list-buckets parsing only accepts real Bucket/Name entries.
rustfs-state-authority-parser-contract-check:
    @bash ./tests/rustfs_state_authority_check_parser.sh

# Validate Attic NAR integrity failure reporting.
attic-nar-integrity-contract-check:
    @bash ./tests/attic_nar_integrity_contract.sh

# Validate RustFS repair-surface inventory stays read-only and truth-preserving.
rustfs-repair-surface-contract-check:
    @bash ./tests/rustfs_repair_surface_contract.sh

# Validate RustFS admin status probing stays read-only and truth-preserving.
rustfs-admin-status-contract-check:
    @bash ./tests/rustfs_admin_status_contract.sh

# Validate RustFS heal semantics audit stays source-only and truth-preserving.
rustfs-heal-semantics-contract-check:
    @bash ./tests/rustfs_heal_semantics_contract.sh

# Validate RustFS bucket-metadata admin audit stays source-only and truth-preserving.
rustfs-bucket-meta-semantics-contract-check:
    @bash ./tests/rustfs_bucket_meta_semantics_contract.sh

# Validate the TIN-1147 trusted Attic publication backend gate.
rustfs-trusted-publication-gate-contract-check:
    @bash ./tests/rustfs_trusted_publication_gate_contract.sh

# Validate the static TIN-1147 trusted Attic publication backend gate.
rustfs-trusted-publication-gate-check *args:
    @python3 ./scripts/validate-rustfs-trusted-publication-gate.py {{args}}

# Validate a non-secret TIN-1147 Attic backend replacement package.
attic-backend-replacement-package-gate *args:
    @python3 ./scripts/attic-backend-replacement-package-gate.py {{args}}

# Write an intentionally non-live TIN-1147 Attic backend replacement package template.
attic-backend-replacement-package-template output="attic-backend-replacement-package.json":
    @python3 ./scripts/attic-backend-replacement-package-gate.py --write-template {{output}}

# Offline guard test for the TIN-1147 Attic backend replacement package gate.
attic-backend-replacement-package-self-test:
    @python3 ./scripts/attic-backend-replacement-package-gate.py --self-test

# Validate TIN-1147 Attic backend replacement package gate wiring.
attic-backend-replacement-package-contract-check:
    @bash ./tests/attic_backend_replacement_package.sh

# Validate the RustFS upgrade-topology candidate packet.
rustfs-upgrade-topology-candidate-contract-check:
    @bash ./tests/rustfs_upgrade_topology_candidate_contract.sh

# Validate the static RustFS upgrade-topology candidate packet.
rustfs-upgrade-topology-candidate-check *args:
    @python3 ./scripts/validate-rustfs-upgrade-topology-candidate.py {{args}}

# Validate the RustFS upgrade-topology proof-plan contract.
rustfs-upgrade-topology-proof-plan-contract-check:
    @bash ./tests/rustfs_upgrade_topology_proof_plan_contract.sh

# Validate the static RustFS upgrade-topology proof plan.
rustfs-upgrade-topology-proof-plan-check *args:
    @python3 ./scripts/validate-rustfs-upgrade-topology-proof-plan.py {{args}}

# Validate the RustFS upgrade-topology saved-plan guard wiring.
rustfs-upgrade-topology-plan-guard-contract-check:
    @bash ./tests/rustfs_upgrade_topology_plan_guard_contract.sh

# Guard a saved tofu show -json plan for the RustFS upgrade-topology attempt.
rustfs-upgrade-topology-plan-guard plan_json="":
    #!/usr/bin/env bash
    set -euo pipefail
    if [ -n "{{plan_json}}" ]; then
        python3 ./scripts/rustfs-upgrade-topology-plan-guard.py "{{plan_json}}"
    else
        python3 ./scripts/rustfs-upgrade-topology-plan-guard.py
    fi

# Report Bazel external repository/archive fetch authority separately from the
# remote action cache contract.
bazel-external-fetch-authority *args:
    @bash ./scripts/external-fetch-authority.sh {{args}}

# Summarize run-local Bazel repository-cache population evidence.
bazel-repository-cache-evidence *args:
    @python3 ./scripts/bazel-repository-cache-evidence.py {{args}}

# Render the Bazel external input lockfile manifest.
bazel-external-input-manifest *args:
    @python3 ./scripts/external-input-manifest.py {{args}}

# Render locked Nix flake source archive inputs.
nix-flake-source-input-manifest *args:
    @python3 ./scripts/flake-source-input-manifest.py {{args}}

# Validate the Nix flake source input authority contract.
nix-flake-source-input-authority *args:
    @python3 ./scripts/validate-nix-flake-source-authority.py {{args}}

# Package already-materialized Nix flake source archives into the provider-neutral mirror layout.
nix-flake-source-mirror-package *args:
    @python3 ./scripts/nix-flake-source-mirror-package.py package {{args}}

# Verify a provider-neutral Nix flake source mirror package root.
nix-flake-source-mirror-verify *args:
    @python3 ./scripts/nix-flake-source-mirror-package.py verify {{args}}

# Restore a Nix flake source archive root from a provider-neutral mirror package root.
nix-flake-source-mirror-restore *args:
    @python3 ./scripts/nix-flake-source-mirror-package.py restore {{args}}

# Validate a non-secret Nix flake source authority package.
nix-flake-source-authority-package-gate *args:
    @python3 ./scripts/nix-flake-source-authority-package-gate.py {{args}}

# Write an intentionally non-live Nix flake source authority package template.
nix-flake-source-authority-package-template output="nix-flake-source-authority-package.json":
    @python3 ./scripts/nix-flake-source-authority-package-gate.py --write-template {{output}}

# Offline guard test for the Nix flake source authority package gate.
nix-flake-source-authority-package-self-test:
    @python3 ./scripts/nix-flake-source-authority-package-gate.py --self-test

# Materialize a verified Bazel distdir from the candidate input manifest.
bazel-external-input-distdir *args:
    @python3 ./scripts/materialize-bazel-distdir.py {{args}}

# Validate the Bazel distdir source-proof coverage contract.
bazel-distdir-coverage *args:
    @python3 ./scripts/validate-bazel-distdir-coverage.py {{args}}

# Package a verified local distdir into the provider-neutral durable-mirror layout.
bazel-distdir-mirror-package *args:
    @python3 ./scripts/bazel-distdir-mirror-package.py package {{args}}

# Verify a provider-neutral durable-mirror package root.
bazel-distdir-mirror-verify *args:
    @python3 ./scripts/bazel-distdir-mirror-package.py verify {{args}}

# Restore a Bazel distdir from a provider-neutral durable-mirror package root.
bazel-distdir-mirror-restore *args:
    @python3 ./scripts/bazel-distdir-mirror-package.py restore {{args}}

# Validate the durable Bazel external input authority contract.
bazel-external-input-authority *args:
    @python3 ./scripts/validate-bazel-external-input-authority.py {{args}}

# Validate a non-secret Bazel external-input authority package.
bazel-external-input-authority-package-gate *args:
    @python3 ./scripts/bazel-external-input-authority-package-gate.py {{args}}

# Write an intentionally non-live Bazel external-input authority package template.
bazel-external-input-authority-package-template output="bazel-external-input-authority-package.json":
    @python3 ./scripts/bazel-external-input-authority-package-gate.py --write-template {{output}}

# Offline guard test for the Bazel external-input authority package gate.
bazel-external-input-authority-package-self-test:
    @python3 ./scripts/bazel-external-input-authority-package-gate.py --self-test

# Validate the Bazel external input lockfile manifest guard.
bazel-external-input-manifest-check:
    @bash ./tests/bazel_external_input_manifest.sh

# Validate the Bazel external input distdir materializer guard.
bazel-external-input-distdir-check:
    @bash ./tests/bazel_external_input_distdir.sh

# Validate the Bazel distdir source-proof coverage contract.
bazel-distdir-coverage-contract-check:
    @bash ./tests/bazel_distdir_coverage_contract.sh

# Validate the provider-neutral Bazel distdir mirror package primitive.
bazel-distdir-mirror-package-contract-check:
    @bash ./tests/bazel_distdir_mirror_package_contract.sh

# Validate restored Bazel --distdir proof from a provider-neutral mirror package.
bazel-distdir-mirror-restore-contract-check:
    @bash ./tests/bazel_distdir_mirror_restore_contract.sh

# Run the TIN-1468 full-candidate distdir package/restore proof. This is
# intentionally not part of `just check`; use the contract check there so local
# validation stays bounded.
bazel-distdir-full-package-proof:
    @bash ./scripts/bazel-distdir-full-package-proof.sh

# Validate TIN-1468 full-candidate distdir package proof workflow and docs wiring.
bazel-distdir-full-package-proof-contract-check:
    @bash ./tests/bazel_distdir_full_package_proof_contract.sh

# Validate the durable Bazel external input authority contract.
bazel-external-input-authority-contract-check:
    @bash ./tests/bazel_external_input_authority_contract.sh

# Validate the Nix flake source input authority contract.
nix-flake-source-input-authority-contract-check:
    @bash ./tests/nix_flake_source_input_authority.sh

# Validate the Nix flake source mirror package/restore primitive.
nix-flake-source-mirror-package-contract-check:
    @bash ./tests/nix_flake_source_mirror_package_contract.sh

# Validate the Nix flake source authority package gate wiring.
nix-flake-source-authority-package-contract-check:
    @bash ./tests/nix_flake_source_authority_package.sh

# Validate the Bazel external-input authority package gate wiring.
bazel-external-input-authority-package-contract-check:
    @bash ./tests/bazel_external_input_authority_package.sh

# Prove a validated mirror package through the selected live S3-compatible
# external-input authority. This is intentionally not part of `just check`; use
# the contract check there so local validation stays bounded.
bazel-distdir-mirror-live-proof *args:
    @python3 ./scripts/bazel-distdir-mirror-live-proof.py {{args}}

# Check the non-secret package and scoped env readiness before spending the
# full package/proof runtime. This writes redacted evidence and fails closed
# unless all required live-proof env names are present and match the package.
bazel-distdir-mirror-live-readiness *args:
    @python3 ./scripts/bazel-distdir-mirror-live-readiness.py {{args}}

# Check visible GitHub variable/secret names for TIN-1468 live-proof injection.
bazel-distdir-mirror-github-readiness *args:
    @python3 ./scripts/bazel-distdir-mirror-github-readiness.py {{args}}

# Render the read-only E3 external-input authority close-gate status.
e3-external-input-authority-status *args:
    @python3 ./scripts/e3-external-input-authority-status.py {{args}}

# Validate E3 external-input authority status wiring and offline fixtures.
e3-external-input-authority-status-contract-check:
    @bash ./tests/e3_external_input_authority_status.sh

# Validate TIN-1468 live mirror proof wiring and static safety boundaries.
bazel-distdir-mirror-live-proof-contract-check:
    @bash ./tests/bazel_distdir_mirror_live_proof_contract.sh

# Validate TIN-1468 GitHub variable/secret-name readiness classification.
bazel-distdir-mirror-github-readiness-contract-check:
    @bash ./tests/bazel_distdir_mirror_github_readiness.sh

# Run the W3.4 Bazel vendor-mode canary. This is intentionally not part of
# `just check`; use the contract check there so local validation stays bounded.
bazel-vendor-mode-canary:
    @bash ./scripts/gf-bazel-vendor-mode-canary.sh

# Validate W3.4 vendor-mode canary workflow, script, and docs wiring.
bazel-vendor-mode-canary-contract-check:
    @bash ./tests/bazel_vendor_mode_canary_contract.sh

# Run offline fixture tests for Bazel external fetch authority and wrapper args.
bazel-external-fetch-authority-self-test:
    @bash ./tests/bazel_external_fetch_authority.sh

# Validate W3.3 repository-cache evidence generation.
bazel-repository-cache-evidence-contract-check:
    @bash ./tests/bazel_repository_cache_evidence.sh

# Validate direct Bazel http_archive/http_file calls declare non-empty sha256.
bazel-http-archive-pins-check:
    @bash ./tests/bazel_http_archive_pins_contract.sh
    @python3 ./scripts/validate-bazel-http-archive-pins.py

# Validate MODULE.bazel.lock is present, tracked, well-formed, and current.
bazel-lockfile-check:
    @bash ./scripts/validate-bazel-lockfile.sh

# Validate MODULE.bazel.lock checker stale-vs-unavailable behavior.
bazel-lockfile-contract-check:
    @bash ./tests/bazel_lockfile_check_contract.sh

# Report whether the private repo can safely become public as-is
public-alpha-visibility-report:
    @node scripts/public-alpha-visibility-gate.js report

# Fail until direct repository visibility blockers are resolved
public-alpha-visibility-strict:
    @node scripts/public-alpha-visibility-gate.js strict

# Regenerate structured public-docs references
public-docs-generate:
    @node scripts/generate-public-docs-reference.js write

# Materialize the scrubbed future public docs package
public-docs-export out=".public-docs-export":
    @node scripts/public-docs-export.js write --out {{out}}

# Validate the scrubbed public-alpha mirror seed
public-alpha-export-check:
    @node scripts/public-docs-export.js check --manifest config/public-alpha-export.json

# Materialize the scrubbed public-alpha mirror seed with fresh-history instructions
public-alpha-export out=".public-alpha-export":
    @node scripts/public-docs-export.js write --manifest config/public-alpha-export.json --out {{out}}

# Full validation including Nix flake checks and tofu validation.
check-full: check nix-check tofu-validate-all
    @echo "Full validation complete!"

# Full development cycle: check + build
dev: check nix-build
    @echo "Development build complete!"

# Show current environment configuration
info:
    #!/usr/bin/env bash
    set -euo pipefail
    ACTIVE_KUBE_CONTEXT="${KUBE_CONTEXT:-{{kube_context}}}"
    ACTIVE_GITLAB_API="{{gitlab_api}}"
    ACTIVE_GITLAB_PROJECT="{{gitlab_project}}"
    ACTIVE_BAZEL_MODE="${GF_BAZEL_SUBSTRATE_MODE:-compatibility-local-only}"
    LOCAL_BACKEND_COUNT="$(find config/backends -maxdepth 1 -name '*.hcl' 2>/dev/null | wc -l | tr -d ' ')"
    echo "Environment Configuration"
    echo "========================="
    echo "ENV:             {{env}}"
    echo "Kube Context:    ${ACTIVE_KUBE_CONTEXT:-unset}"
    echo "Ingress:         {{ingress_domain}}"
    echo "GitLab API:      ${ACTIVE_GITLAB_API:-unset}"
    echo "Project ID:      ${ACTIVE_GITLAB_PROJECT:-unset}"
    echo
    echo "Backend Initialization"
    echo "======================"
    if [ -n "${TOFU_BACKEND_CONFIG_FILE:-}" ]; then
        echo "Config file:      ${TOFU_BACKEND_CONFIG_FILE}"
    elif [ -n "${TOFU_BACKEND_CONFIG_DIR:-}" ]; then
        echo "Config dir:       ${TOFU_BACKEND_CONFIG_DIR}"
    elif [ "${LOCAL_BACKEND_COUNT:-0}" -gt 0 ]; then
        echo "Auto local files: ${LOCAL_BACKEND_COUNT} file(s) under config/backends"
    elif [ -n "${TOFU_BACKEND_S3_ENDPOINT:-}" ] && [ -n "${TOFU_BACKEND_S3_BUCKET:-}" ]; then
        echo "S3 env path:      ${TOFU_BACKEND_S3_ENDPOINT} (${TOFU_BACKEND_S3_BUCKET})"
    elif [ -n "${TF_HTTP_ADDRESS:-}" ]; then
        echo "TF_HTTP_ADDRESS:  ${TF_HTTP_ADDRESS} (legacy compatibility path)"
    elif [ -n "${TF_HTTP_PASSWORD:-}" ]; then
        echo "Legacy GitLab:    TF_HTTP_PASSWORD configured"
    else
        echo "Backend:          not configured"
    fi
    echo "Active stacks:    backend \"s3\" on environment-owned honey state"
    echo
    echo "Bazel Substrate"
    echo "==============="
    echo "Mode:            ${ACTIVE_BAZEL_MODE}"
    if [ -n "${BAZEL_REMOTE_CACHE:-}" ]; then
        echo "Remote cache:    ${BAZEL_REMOTE_CACHE}"
    else
        echo "Remote cache:    unset"
        echo "Contract note:   just bazel-build-cached requires a real shared cache endpoint"
    fi
    if [ -n "${BAZEL_REMOTE_EXECUTOR:-}" ]; then
        echo "Remote executor: ${BAZEL_REMOTE_EXECUTOR}"
    else
        echo "Remote executor: unset"
    fi
    echo "Contract check:  just cache-contract"
    echo
    echo "Local Files"
    echo "==========="
    if [ -f .env ]; then
        echo ".env file:       exists ✓"
    else
        echo ".env file:       missing (run 'just setup')"
    fi
    if [ -f config/organization.yaml ]; then
        echo "organization.yaml: exists ✓"
    else
        echo "organization.yaml: missing (copy config/organization.example.yaml)"
    fi

# Classify cache attachment without contacting services or running Bazel
cache-contract:
    @scripts/cache-attachment-contract.sh

# Require a real Bazel remote-cache endpoint for cache-backed dogfood
cache-contract-strict:
    @scripts/cache-attachment-contract.sh --strict

# Require local Nix to trust the configured Attic cache
cache-contract-nix-strict:
    @scripts/cache-attachment-contract.sh --strict-nix

# Prove developer-machine shared-cache attachment with a bounded Bazel target.
# Defaults to read-only cache use; pass upload=true for trusted cache writes.
developer-cache-attachment-proof target="//:deployment_bundle" upload="false":
    @GF_DEVELOPER_CACHE_PROOF_UPLOAD="{{upload}}" bash ./scripts/developer-cache-attachment-proof.sh "{{target}}"

gf-hit-gate-contract-check:
    @bash ./tests/gf_hit_gate_contract.sh

# Alpha self-service developer cache attachment helper.
# Shows current state, prints actionable next steps if incomplete, optionally
# runs a bounded proof. Operator help still expected for endpoint provisioning.
# Pass --proof to exercise the cache against //:deployment_bundle when attached.
dev-attach *args:
    @bash ./scripts/dev-attach.sh {{args}}

# =============================================================================
# Nix Commands
# =============================================================================

# Build Nix flake against the shared cache-backed substrate (local execution
# still occurs on cache miss)
nix-build:
    nix build

# Build OCI container image
nix-build-container:
    nix build .#container

# Build all Nix outputs against the same shared cache-backed substrate
nix-build-all:
    nix build .#attic-client
    nix build .#attic-server
    nix build .#container
    nix build .#attic-gc-image

# Run full Nix flake checks. This may build heavyweight Attic/container closures.
nix-check:
    nix flake check

# Update flake inputs
nix-update:
    nix flake update

# Show flake outputs
nix-show:
    nix flake show

# Fallback devshell entrypoint when not using direnv
nix-shell:
    nix develop

# Format Nix files
nix-fmt:
    nix fmt

# =============================================================================
# OpenTofu Commands (Stack-Level)
# =============================================================================

# Initialize a tofu stack using its active backend family
tofu-init stack:
    #!/usr/bin/env bash
    set -euo pipefail
    REPO_ROOT="$(cd "{{justfile_directory()}}" && pwd)"
    cd tofu/stacks/{{stack}}

    echo "=== Initializing {{stack}} ({{env}}) ==="

    STATE_NAME="$(bash "${REPO_ROOT}/scripts/tofu-state-contract.sh" state-name "{{stack}}" "{{env}}")"
    BACKEND_FAMILY="$(sed -n 's/.*backend "\([^"]*\)".*/\1/p' backend.tf | head -n1)"
    if [ -z "${BACKEND_FAMILY}" ]; then
        echo "ERROR: could not determine backend family from tofu/stacks/{{stack}}/backend.tf"
        exit 1
    fi

    ACTIVE_BACKEND_FILE="${TOFU_BACKEND_CONFIG_FILE:-}"
    if [ -z "${ACTIVE_BACKEND_FILE}" ] && [ -n "${TOFU_BACKEND_CONFIG_DIR:-}" ]; then
        ACTIVE_BACKEND_FILE="${TOFU_BACKEND_CONFIG_DIR%/}/${STATE_NAME}.hcl"
    fi
    AUTO_BACKEND_FILE="{{justfile_directory()}}/config/backends/${STATE_NAME}.hcl"

    if [ -n "${ACTIVE_BACKEND_FILE}" ]; then
        if [ ! -f "${ACTIVE_BACKEND_FILE}" ]; then
            echo "ERROR: backend config file not found: ${ACTIVE_BACKEND_FILE}"
            exit 1
        fi
        echo "Using backend config file: ${ACTIVE_BACKEND_FILE}"
        echo "Backend family: ${BACKEND_FAMILY}"
        tofu init -reconfigure -backend-config="${ACTIVE_BACKEND_FILE}"
        exit 0
    fi

    if [ "${BACKEND_FAMILY}" = "http" ] && [ -n "${TF_HTTP_ADDRESS:-}" ]; then
        echo "Using backend configuration from TF_HTTP_* environment variables"
        echo "Backend family: http"
        tofu init -reconfigure
        exit 0
    fi

    if [ "${BACKEND_FAMILY}" = "s3" ] \
        && [ -n "${TOFU_BACKEND_S3_ENDPOINT:-}" ] \
        && [ -n "${TOFU_BACKEND_S3_BUCKET:-}" ] \
        && { [ -n "${TOFU_BACKEND_S3_ACCESS_KEY:-}" ] || [ -n "${AWS_ACCESS_KEY_ID:-}" ]; } \
        && { [ -n "${TOFU_BACKEND_S3_SECRET_KEY:-}" ] || [ -n "${AWS_SECRET_ACCESS_KEY:-}" ]; }; then
        TMP_BACKEND_FILE="$(mktemp "${TMPDIR:-/tmp}/tofu-backend-{{stack}}-{{env}}.XXXXXX.hcl")"
        trap 'rm -f "${TMP_BACKEND_FILE}"' EXIT
        TOFU_BACKEND_OUTPUT_FILE="${TMP_BACKEND_FILE}" \
            bash "${REPO_ROOT}/scripts/materialize-s3-backend-config.sh" "{{stack}}" "{{env}}" >/dev/null
        echo "Using backend configuration from TOFU_BACKEND_S3_* environment variables"
        echo "Backend family: s3"
        tofu init -reconfigure -backend-config="${TMP_BACKEND_FILE}"
        exit 0
    fi

    if [ -f "${AUTO_BACKEND_FILE}" ]; then
        echo "Using backend config file: ${AUTO_BACKEND_FILE}"
        echo "Backend family: ${BACKEND_FAMILY}"
        tofu init -reconfigure -backend-config="${AUTO_BACKEND_FILE}"
        exit 0
    fi

    if [ "${BACKEND_FAMILY}" = "http" ] \
        && [ -n "{{gitlab_api}}" ] && [ -n "{{gitlab_project}}" ] && [ -n "${TF_HTTP_PASSWORD:-}" ]; then
        echo "WARNING: falling back to legacy GitLab HTTP backend initialization"
        echo "Prefer TOFU_BACKEND_CONFIG_FILE, TOFU_BACKEND_CONFIG_DIR, or TF_HTTP_* for new work"
        tofu init -reconfigure \
            -backend-config="address={{gitlab_api}}/projects/{{gitlab_project}}/terraform/state/${STATE_NAME}" \
            -backend-config="lock_address={{gitlab_api}}/projects/{{gitlab_project}}/terraform/state/${STATE_NAME}/lock" \
            -backend-config="unlock_address={{gitlab_api}}/projects/{{gitlab_project}}/terraform/state/${STATE_NAME}/lock" \
            -backend-config="lock_method=POST" \
            -backend-config="unlock_method=DELETE" \
            -backend-config="username=${TF_HTTP_USERNAME:-gitlab-ci-token}" \
            -backend-config="password=${TF_HTTP_PASSWORD:-}"
        exit 0
    fi

    echo "ERROR: no backend-init configuration found for ${STATE_NAME}"
    echo
    echo "Preferred paths:"
    echo "  TOFU_BACKEND_CONFIG_FILE=/abs/path/${STATE_NAME}.hcl just tofu-init {{stack}}"
    echo "  TOFU_BACKEND_CONFIG_DIR=\$PWD/config/backends just tofu-init {{stack}}"
    echo "  config/backends/${STATE_NAME}.hcl (auto-detected local default)"
    echo
    if [ "${BACKEND_FAMILY}" = "http" ]; then
        echo "Active backend family: http"
        echo "  export TF_HTTP_ADDRESS=... TF_HTTP_LOCK_ADDRESS=... TF_HTTP_UNLOCK_ADDRESS=..."
        if [ -n "{{gitlab_api}}" ] && [ -n "{{gitlab_project}}" ]; then
            echo
            echo "Legacy compatibility path:"
            echo "  TF_HTTP_PASSWORD=... just tofu-init-gitlab-legacy {{stack}}"
        fi
    elif [ "${BACKEND_FAMILY}" = "s3" ]; then
        echo "Active backend family: s3"
        echo "  export TOFU_BACKEND_S3_ENDPOINT=... TOFU_BACKEND_S3_BUCKET=..."
        echo "  export TOFU_BACKEND_S3_ACCESS_KEY=... TOFU_BACKEND_S3_SECRET_KEY=..."
        echo "  optional: export TOFU_BACKEND_S3_KEY=... when no canonical key is locked"
    else
        echo
        echo "No family-specific init fallback is defined for ${BACKEND_FAMILY}."
    fi
    exit 1

# Run local preflight checks before tofu init/plan
tofu-preflight stack:
    bash ./scripts/tofu-preflight.sh {{stack}} {{env}} {{org_config}}

# Print the current state-name and S3 key contract for one stack
tofu-state-contract stack:
    bash ./scripts/tofu-state-contract.sh describe {{stack}} {{env}}

# Summarize backend/init state across all active stacks
tofu-backend-audit:
    bash ./scripts/tofu-backend-audit.sh {{env}} {{org_config}}

# Prove the live honey RustFS-backed S3 state authority candidate
tofu-state-authority-proof:
    bash ./scripts/tofu-state-authority-proof.sh {{kube_context}}

# Deep-check the live RustFS-backed S3 state authority and optional stack state key
tofu-state-authority-deep-check stack="":
    #!/usr/bin/env bash
    set -euo pipefail
    ARGS=(--context "{{kube_context}}")
    if [ -n "{{stack}}" ]; then
        STATE_KEY="$(bash ./scripts/tofu-state-contract.sh s3-key "{{stack}}" "{{env}}")"
        ARGS+=(--state-key "${STATE_KEY}")
    fi
    if [ "${#ARGS[@]}" -gt 2 ]; then
        ARGS+=(--read-state-objects)
    fi
    python3 ./scripts/rustfs-state-authority-check.py "${ARGS[@]}"

# Capture a RustFS bucket-index RCA snapshot without restarting RustFS
rustfs-bucket-index-rca *args:
    bash ./scripts/rustfs-bucket-index-rca.sh {{args}}

# Capture the live RustFS repair/admin surface without mutating the backend
rustfs-repair-surface-inventory *args:
    bash ./scripts/rustfs-repair-surface-inventory.sh {{args}}

# Probe RustFS signed admin background-heal status without mutating the backend
rustfs-admin-status-probe *args:
    python3 ./scripts/rustfs-admin-status-probe.py {{args}}

# Audit tagged RustFS source heal semantics without mutating a live backend
rustfs-heal-semantics-audit *args:
    bash ./scripts/rustfs-heal-semantics-audit.sh {{args}}

# Audit tagged RustFS source bucket-metadata admin semantics without live calls
rustfs-bucket-meta-semantics-audit *args:
    bash ./scripts/rustfs-bucket-meta-semantics-audit.sh {{args}}

# Check current OpenTofu state backend against the HA authority gate
tofu-state-ha-readiness *args:
    bash ./scripts/tofu-state-ha-readiness.sh {{args}}

# Prove a scratch/disposable S3-compatible candidate before protected state migration
ha-state-candidate-proof *args:
    python3 ./scripts/ha-state-candidate-proof.py {{args}}

# Validate the static contract for an HA OpenTofu state authority candidate
ha-state-candidate-static-gate *args:
    python3 ./scripts/ha-state-candidate-static-gate.py {{args}}

# Validate the selected non-secret HA OpenTofu state candidate contract
ha-state-selected-candidate-static-gate:
    python3 ./scripts/ha-state-candidate-static-gate.py --contract ./docs/contracts/ha-opentofu-state-managed-s3-candidate.json

# Validate a non-secret HA OpenTofu state endpoint package before proof
ha-state-endpoint-package-gate *args:
    python3 ./scripts/ha-state-endpoint-package-gate.py {{args}}

# Check endpoint package and scoped proof credential readiness before live proof
ha-state-endpoint-readiness *args:
    python3 ./scripts/ha-state-endpoint-readiness.py {{args}}

# Check visible GitHub secret names for scoped HA state proof authority
ha-state-github-secret-readiness *args:
    python3 ./scripts/ha-state-github-secret-readiness.py {{args}}

# Write an intentionally non-live HA OpenTofu state endpoint package template
ha-state-endpoint-package-template output="ha-state-endpoint-package.json":
    python3 ./scripts/ha-state-endpoint-package-gate.py --write-template {{output}}

# Check the selected HA OpenTofu state candidate contract and docs wiring
ha-state-selected-candidate-contract-check:
    @bash ./tests/ha_state_selected_candidate_contract.sh

# Inventory live HA OpenTofu state authority candidate surfaces
ha-state-candidate-inventory *args:
    python3 ./scripts/ha-state-candidate-inventory.py --context {{kube_context}} {{args}}

# Offline guard test for the HA state candidate proof harness
ha-state-candidate-proof-self-test:
    python3 ./scripts/ha-state-candidate-proof.py --self-test

# Offline guard test for the HA state candidate static gate
ha-state-candidate-static-gate-self-test:
    python3 ./scripts/ha-state-candidate-static-gate.py --self-test

# Offline guard test for the HA state candidate inventory classifier
ha-state-candidate-inventory-self-test:
    python3 ./scripts/ha-state-candidate-inventory.py --self-test

# Offline guard test for the HA state endpoint package gate
ha-state-endpoint-package-self-test:
    python3 ./scripts/ha-state-endpoint-package-gate.py --self-test

# Offline guard test for the HA state endpoint readiness gate
ha-state-endpoint-readiness-self-test:
    python3 ./scripts/ha-state-endpoint-readiness.py --self-test

# Offline guard test for the HA state GitHub secret readiness gate
ha-state-github-secret-readiness-self-test:
    python3 ./scripts/ha-state-github-secret-readiness.py --self-test

# Check the HA state candidate inventory keeps known non-candidates rejected
ha-state-candidate-inventory-contract-check:
    @bash ./tests/ha_state_candidate_inventory.sh

# Check current docs keep HA state authority truth aligned with live evidence
ha-state-authority-truth-contract-check:
    @bash ./tests/ha_state_authority_truth.sh

# Check the HA state candidate static gate keeps rejected surfaces rejected
ha-state-candidate-static-gate-contract-check:
    @bash ./tests/ha_state_candidate_static_gate.sh

# Check the HA state endpoint package gate keeps unsafe packages rejected
ha-state-endpoint-package-contract-check:
    @bash ./tests/ha_state_endpoint_package.sh

# Check the HA state endpoint readiness gate keeps missing package/credential states red
ha-state-endpoint-readiness-contract-check:
    @bash ./tests/ha_state_endpoint_readiness.sh

# Check the HA state GitHub secret readiness gate rejects substitute authorities
ha-state-github-secret-readiness-contract-check:
    @bash ./tests/ha_state_github_secret_readiness.sh

# Check the HA state candidate proof harness keeps its migration guardrails
ha-state-candidate-proof-contract-check:
    @bash ./tests/ha_state_candidate_proof.sh

# Audit live Kubernetes Secrets for last-applied annotations that embed data
k8s-secret-last-applied-audit *args:
    python3 ./scripts/k8s-secret-last-applied-audit.py {{args}}

# Render redaction-safe cleanup commands for Secret last-applied annotations
k8s-secret-last-applied-cleanup-plan *args:
    python3 ./scripts/k8s-secret-last-applied-audit.py --cleanup-plan {{args}}

# Check the Kubernetes Secret annotation leak audit stays redaction-safe
k8s-secret-last-applied-audit-contract-check:
    @bash ./tests/k8s_secret_last_applied_audit.sh

# Inspect live ARC runtime shape and flag listener-cap, runner-count, session, heavy-lane, and cache drift
arc-runtime-audit *args:
    bash ./scripts/arc-runtime-audit.sh {{kube_context}} arc-runners arc-systems {{args}}

# Settle-aware post-apply prove gate for ARC listener caps (transient recreation vs persistent drift)
arc-prove-listener-caps *args:
    bash ./scripts/arc-prove-listener-caps.sh --context {{kube_context}} --runner-namespace arc-runners --system-namespace arc-systems {{args}}

# Reap idle leaked (zombie) EphemeralRunner CRs that would stall a quiesce drain; requires --scale-set
arc-reap-zombies *args:
    bash ./scripts/reap-idle-leaked-ephemeral-runners.sh --context {{kube_context}} --namespace arc-runners --system-namespace arc-systems {{args}}

# Reap stale-generation zombie EphemeralRunners deadlocking an eventual-strategy listener rollover (TIN-2055); requires --scale-set, try --dry-run first
arc-reap-zombies-stale *args:
    bash ./scripts/reap-idle-leaked-ephemeral-runners.sh --context {{kube_context}} --namespace arc-runners --system-namespace arc-systems --stale-generation {{args}}

# Classify Kubernetes API/CNI, kubelet eviction, and node-pressure evidence for ARC disconnects
arc-network-continuity-audit *args:
    python3 ./scripts/arc-network-continuity-audit.py --context {{kube_context}} --runner-namespace arc-runners --system-namespace arc-systems {{args}}

# Correlate queued GitHub Actions jobs with ARC scale-set activity
arc-listener-queue-drift *args:
    python3 ./scripts/arc-listener-queue-drift.py --context {{kube_context}} --runner-namespace arc-runners --system-namespace arc-systems {{args}}

# Fail if any AutoscalingRunnerSet is hand-applied drift (managed-by != Helm /
# carries a last-applied-configuration) instead of being owned by its
# gha-runner-scale-set Helm release via `just arc-apply`.
arc-no-manual-drift-audit *args:
    python3 ./scripts/arc-no-manual-drift-audit.py --context {{kube_context}} --namespace arc-runners {{args}}

# Inspect shared ARC workflow labels across owner overlay scale sets
arc-shared-label-capacity-audit *args:
    python3 ./scripts/arc-shared-label-capacity-audit.py --context {{kube_context}} --namespace arc-runners {{args}}

# Inspect ARC burst capacity across node pod slots, pod consumers, active runner jobs, shared labels, quota, and fast-local scratch PVCs
arc-burst-capacity-audit *args:
    python3 ./scripts/arc-burst-capacity-audit.py --context {{kube_context}} --namespace arc-runners {{args}}

# Run offline fixture tests for ARC burst capacity diagnostics
arc-burst-capacity-audit-self-test:
    bash ./tests/arc_burst_capacity_audit.sh

# Run offline fixture tests for ARC network, runtime, queue, capacity, and ownership diagnostics
arc-diagnostic-self-tests:
    bash ./tests/arc_network_continuity_audit.sh
    bash ./tests/arc_runtime_audit.sh
    bash ./tests/arc_listener_queue_drift.sh
    bash ./tests/arc_shared_label_capacity_audit.sh
    bash ./tests/arc_burst_capacity_audit.sh
    bash ./tests/arc_no_manual_drift_audit.sh
    bash ./tests/arc_runner_residue_audit.sh

# Validate source-derived ARC cap targets used by managed apply restore
arc-source-cap-targets-check:
    bash ./tests/arc_source_cap_targets.sh

# Check the local arc-runners apply source guard.
arc-local-apply-source-guard-check:
    bash ./scripts/arc-local-apply-source-guard.sh --self-test

# Inspect kubelet root/imagefs capacity separately from durable storage
kubelet-imagefs-capacity-audit *args:
    python3 ./scripts/kubelet-imagefs-capacity-audit.py --context {{kube_context}} {{args}}

# Run offline fixture tests for kubelet root/imagefs warning and critical boundaries
kubelet-imagefs-capacity-audit-self-test:
    bash ./tests/kubelet_imagefs_capacity_audit.sh

# Verify live Attic cache public-read and key authority without printing secrets
attic-cache-authority-check:
    #!/usr/bin/env bash
    set -euo pipefail
    expected="$(python3 ./scripts/attic-public-key-from-tfvars.py tofu/stacks/arc-runners/honey.tfvars)"
    if [ -z "${expected}" ]; then
        echo "ERROR: committed runner tfvars do not declare a consistent attic_public_key"
        exit 1
    fi
    ATTIC_EXPECTED_PUBLIC_KEY="${expected}" bash ./scripts/attic-cache-authority-check.sh {{kube_context}} nix-cache main

# Verify that a live Attic narinfo entry has a NAR body that streams cleanly
attic-nar-integrity-check *args:
    bash ./scripts/attic-nar-integrity-check.sh {{args}}

# Publish trusted KVM VM-test closure warmth into Attic from an operator context.
kvm-cache-prewarm profile="kvm-vm-test" *args="":
    bash ./scripts/cache-warm.sh --profile {{profile}} {{args}}

# Render or apply the trusted in-cluster KVM prewarm publisher Job.
kvm-cache-prewarm-job *args:
    bash ./scripts/kvm-cache-prewarm-job.sh {{args}}

# Verify the ARC controller GHCR pull secret matches the runner namespace copy
arc-ghcr-pull-secret-check:
    bash ./scripts/reconcile-arc-ghcr-pull-secret.sh --context {{kube_context}} --runner-namespace arc-runners --controller-namespace arc-systems --secret-name ghcr-pull

# Sync the ARC controller GHCR pull secret from the runner namespace copy
arc-ghcr-pull-secret-sync:
    bash ./scripts/reconcile-arc-ghcr-pull-secret.sh --context {{kube_context}} --runner-namespace arc-runners --controller-namespace arc-systems --secret-name ghcr-pull --apply

# Inspect honey runner host workdirs for stale checkout blockers
honey-runner-workdir-audit *hosts:
    bash ./scripts/honey-runner-workdir-audit.sh {{hosts}}

# Remediate one honey runner host repo workdir (dry-run by default)
honey-runner-workdir-remediate host repo *args:
    bash ./scripts/honey-runner-workdir-remediate.sh {{host}} {{repo}} {{args}}

# Reconcile honey runner host workdirs across the selected hosts
honey-runner-workdir-reconcile *args:
    bash ./scripts/honey-runner-workdir-reconcile.sh {{args}}

# Inspect or control bounded lifecycle state for one honey runner host root
honey-runner-host-lifecycle host *args:
    bash ./scripts/honey-runner-host-lifecycle.sh {{host}} {{args}}

# Start from a failed GitHub Actions run and triage honey checkout blockers
honey-runner-checkout-triage *args:
    python3 ./scripts/honey-runner-checkout-triage.py {{args}}

# Generate the live orgwide runner enrollment scoreboard
orgwide-enrollment-scoreboard *args:
    python3 ./scripts/orgwide-enrollment-scoreboard.py {{args}}

# Generate the live orgwide enrollment promotion queue
orgwide-enrollment-queue *args:
    python3 ./scripts/orgwide-enrollment-queue.py {{args}}

# Validate committed ARC runner sets stay capability-class shaped
arc-runner-taxonomy-guard *args="tofu/stacks/arc-runners/honey.tfvars":
    python3 ./scripts/validate-arc-runner-taxonomy.py {{args}}

# Classify live ARC residue against implementation-overlay ownership
arc-runner-residue-audit *args:
    python3 ./scripts/arc-runner-residue-audit.py {{args}}

# Validate the non-mutating ARC residue rehome manifest
arc-runner-rehome-manifest-check:
    python3 ./scripts/arc-runner-residue-rehome-plan.py --check

# Render the non-mutating ARC residue rehome plan
arc-runner-residue-rehome-plan *args:
    python3 ./scripts/arc-runner-residue-rehome-plan.py {{args}}

# Check pulled ARC runner state files against the residue rehome manifest
arc-runner-residue-state-check core_state overlay_state *args:
    python3 ./scripts/arc-runner-residue-state-check.py --core-state "{{core_state}}" --overlay-state "{{overlay_state}}" {{args}}

# Read-only enrollment preflight for an implementation overlay checkout
implementation-overlay-preflight overlay_root tfvars repo *args:
    python3 ./scripts/implementation-overlay-preflight.py --overlay-root "{{overlay_root}}" --tfvars "{{tfvars}}" --repo "{{repo}}" {{args}}

# Create or rotate an implementation overlay ARC GitHub App secret pair
implementation-overlay-arc-secret overlay_root *args:
    bash ./scripts/implementation-overlay-arc-secret.sh --overlay-root "{{overlay_root}}" {{args}}

# Generate the live tranche-1 Bazel dogfood proof status
bazel-dogfood-tranche-status *args:
    python3 ./scripts/tranche-proof-status.py {{args}}

# Runner workspace cleanup (dry-run by default)
runner-cleanup *ARGS:
    ./scripts/runner-workspace-cleanup.sh {{ ARGS }}

# Create a local backend config scaffold for a stack/environment
tofu-backend-scaffold stack:
    bash ./scripts/scaffold-backend-config.sh {{stack}} {{env}}

# Create a local S3-compatible backend config scaffold for a stack/environment
tofu-backend-scaffold-s3 stack:
    bash ./scripts/scaffold-backend-config.sh {{stack}} {{env}} s3

# Materialize a local backend file from legacy GitLab HTTP state settings
tofu-backend-materialize-gitlab-legacy stack:
    bash ./scripts/materialize-gitlab-backend-config.sh {{stack}} {{env}} {{org_config}}

# Materialize a local backend file from the current TF_HTTP_* environment
tofu-backend-materialize-http stack:
    bash ./scripts/materialize-http-backend-config.sh {{stack}} {{env}}

# Materialize a local backend file from the current S3-compatible backend environment
tofu-backend-materialize-s3 stack:
    bash ./scripts/materialize-s3-backend-config.sh {{stack}} {{env}}

# Initialize a stack with the legacy GitLab HTTP backend contract
tofu-init-gitlab-legacy stack:
    #!/usr/bin/env bash
    set -euo pipefail
    cd tofu/stacks/{{stack}}

    echo "=== Initializing {{stack}} with legacy GitLab backend ({{env}}) ==="

    case "{{stack}}" in
        attic)
            STATE_NAME="attic-{{env}}"
            ;;
        gitlab-runners)
            STATE_NAME="gitlab-runners-{{env}}"
            ;;
        *)
            STATE_NAME="{{stack}}-{{env}}"
            ;;
    esac

    if [ -z "{{gitlab_api}}" ] || [ -z "{{gitlab_project}}" ]; then
        echo "ERROR: config/organization.yaml does not define gitlab.url and gitlab.project_id"
        exit 1
    fi

    if [ -z "${TF_HTTP_PASSWORD:-}" ]; then
        echo "ERROR: TF_HTTP_PASSWORD is required for the legacy GitLab backend path"
        exit 1
    fi

    tofu init -reconfigure \
        -backend-config="address={{gitlab_api}}/projects/{{gitlab_project}}/terraform/state/${STATE_NAME}" \
        -backend-config="lock_address={{gitlab_api}}/projects/{{gitlab_project}}/terraform/state/${STATE_NAME}/lock" \
        -backend-config="unlock_address={{gitlab_api}}/projects/{{gitlab_project}}/terraform/state/${STATE_NAME}/lock" \
        -backend-config="lock_method=POST" \
        -backend-config="unlock_method=DELETE" \
        -backend-config="username=${TF_HTTP_USERNAME:-gitlab-ci-token}" \
        -backend-config="password=${TF_HTTP_PASSWORD:-}"

# Plan a tofu stack
tofu-plan stack:
    #!/usr/bin/env bash
    set -euo pipefail
    cd tofu/stacks/{{stack}}

    mapfile -t TFVARS_LIST < <(cd "{{justfile_directory()}}" && bash ./scripts/tofu-var-files.sh "{{stack}}" "{{env}}")
    ACTIVE_KUBE_CONTEXT="${KUBE_CONTEXT:-{{kube_context}}}"
    ACTIVE_KUBECONFIG_PATH="${KUBECONFIG_PATH_OVERRIDE:-{{kubeconfig_path}}}"

    if [[ -n "${ACTIVE_KUBECONFIG_PATH}" && "${ACTIVE_KUBECONFIG_PATH}" == "~/"* ]]; then
        ACTIVE_KUBECONFIG_PATH="${HOME}/${ACTIVE_KUBECONFIG_PATH#\~/}"
    fi

    echo "=== Planning {{stack}} ({{env}}) ==="
    echo "Using tfvars:"
    for tfvars in "${TFVARS_LIST[@]}"; do
        echo "  - ${tfvars}"
    done

    if [ -z "${ACTIVE_KUBE_CONTEXT}" ]; then
        echo "ERROR: no cluster context found for ENV={{env}}"
        echo "Set KUBE_CONTEXT or update config/organization.yaml"
        exit 1
    fi

    PLAN_ARGS=(
        -var="cluster_context=${ACTIVE_KUBE_CONTEXT}"
    )

    if [ -n "${ACTIVE_KUBECONFIG_PATH}" ]; then
        PLAN_ARGS+=(-var="k8s_config_path=${ACTIVE_KUBECONFIG_PATH}")
    fi

    if [ -n "${GHCR_TOKEN:-}" ]; then
        if [ -z "${GHCR_USERNAME:-}" ]; then
            echo "ERROR: GHCR_USERNAME is required when GHCR_TOKEN is set"
            exit 1
        fi
        PLAN_ARGS+=(-var="ghcr_token=${GHCR_TOKEN}")
        PLAN_ARGS+=(-var="ghcr_username=${GHCR_USERNAME}")
    fi

    for tfvars in "${TFVARS_LIST[@]}"; do
        PLAN_ARGS+=(-var-file="${tfvars}")
    done

    tofu plan "${PLAN_ARGS[@]}" -out=tfplan

    echo ""
    echo "Plan saved to: tofu/stacks/{{stack}}/tfplan"
    echo "Run 'just tofu-plan-guard {{stack}}', then 'just tofu-apply {{stack}}' to apply"

# Guard a saved tofu plan before apply
tofu-plan-guard stack plan="tfplan":
    #!/usr/bin/env bash
    set -euo pipefail
    cd tofu/stacks/{{stack}}

    if [ ! -f "{{plan}}" ]; then
        echo "ERROR: No plan file found at tofu/stacks/{{stack}}/{{plan}}. Run 'just tofu-plan {{stack}}' first."
        exit 1
    fi

    tofu show -json "{{plan}}" | python3 ../../../scripts/validate-tofu-plan-guard.py --stack "{{stack}}"

# Apply a tofu stack (uses saved plan)
tofu-apply stack:
    #!/usr/bin/env bash
    set -euo pipefail
    cd tofu/stacks/{{stack}}

    if [ ! -f tfplan ]; then
        echo "ERROR: No plan file found. Run 'just tofu-plan {{stack}}' first."
        exit 1
    fi

    bash "{{justfile_directory()}}/scripts/arc-local-apply-source-guard.sh" "{{stack}}"

    if [ "${GF_TOFU_STATE_AUTHORITY_GUARD_ALLOW:-}" = "1" ]; then
        echo "WARNING: GF_TOFU_STATE_AUTHORITY_GUARD_ALLOW=1 set; skipping RustFS state authority guard"
    else
        echo "=== Checking RustFS state authority for {{stack}} ({{env}}) ==="
        STATE_KEY="$(bash "{{justfile_directory()}}/scripts/tofu-state-contract.sh" s3-key "{{stack}}" "{{env}}")"
        python3 "{{justfile_directory()}}/scripts/rustfs-state-authority-check.py" \
            --context "${KUBE_CONTEXT:-{{kube_context}}}" \
            --state-key "${STATE_KEY}" \
            --read-state-objects
    fi

    if [ "${GF_TOFU_PLAN_GUARD_ALLOW:-}" = "1" ]; then
        echo "WARNING: GF_TOFU_PLAN_GUARD_ALLOW=1 set; skipping OpenTofu plan guard"
    else
        echo "=== Guarding {{stack}} plan ==="
        tofu show -json tfplan | python3 ../../../scripts/validate-tofu-plan-guard.py --stack "{{stack}}"
    fi

    echo "=== Applying {{stack}} ({{env}}) ==="
    tofu apply tfplan

# Plan and apply in one step
tofu-deploy stack: (tofu-init stack) (tofu-plan stack) (tofu-apply stack)

# Destroy a tofu stack (with confirmation)
tofu-destroy stack:
    #!/usr/bin/env bash
    set -euo pipefail
    cd tofu/stacks/{{stack}}

    mapfile -t TFVARS_LIST < <(cd "{{justfile_directory()}}" && bash ./scripts/tofu-var-files.sh "{{stack}}" "{{env}}")
    ACTIVE_KUBE_CONTEXT="${KUBE_CONTEXT:-{{kube_context}}}"
    ACTIVE_KUBECONFIG_PATH="${KUBECONFIG_PATH_OVERRIDE:-{{kubeconfig_path}}}"

    if [[ -n "${ACTIVE_KUBECONFIG_PATH}" && "${ACTIVE_KUBECONFIG_PATH}" == "~/"* ]]; then
        ACTIVE_KUBECONFIG_PATH="${HOME}/${ACTIVE_KUBECONFIG_PATH#\~/}"
    fi

    echo "WARNING: This will destroy all resources in {{stack}} ({{env}})!"
    read -p "Type 'yes' to confirm: " confirm
    if [ "$confirm" != "yes" ]; then
        echo "Aborted."
        exit 1
    fi

    if [ -z "${ACTIVE_KUBE_CONTEXT}" ]; then
        echo "ERROR: no cluster context found for ENV={{env}}"
        echo "Set KUBE_CONTEXT or update config/organization.yaml"
        exit 1
    fi

    DESTROY_ARGS=(
        -var="cluster_context=${ACTIVE_KUBE_CONTEXT}"
    )

    if [ -n "${ACTIVE_KUBECONFIG_PATH}" ]; then
        DESTROY_ARGS+=(-var="k8s_config_path=${ACTIVE_KUBECONFIG_PATH}")
    fi

    if [ -n "${GHCR_TOKEN:-}" ]; then
        if [ -z "${GHCR_USERNAME:-}" ]; then
            echo "ERROR: GHCR_USERNAME is required when GHCR_TOKEN is set"
            exit 1
        fi
        DESTROY_ARGS+=(-var="ghcr_token=${GHCR_TOKEN}")
        DESTROY_ARGS+=(-var="ghcr_username=${GHCR_USERNAME}")
    fi

    for tfvars in "${TFVARS_LIST[@]}"; do
        DESTROY_ARGS+=(-var-file="${tfvars}")
    done

    tofu destroy "${DESTROY_ARGS[@]}"

# Exercise the shared HPA deployment module with mock-provider plan fixtures.
hpa-deployment-test:
    #!/usr/bin/env bash
    set -euo pipefail
    export PATH="${PWD}/scripts:${PATH}"
    cd tofu/modules/hpa-deployment
    ../../../scripts/tofu fmt -check -recursive
    ../../../scripts/tofu-init-retry.sh -backend=false -input=false -no-color
    ../../../scripts/tofu test -no-color

# Validate all tofu modules and stacks
tofu-validate-all:
    #!/usr/bin/env bash
    set -euo pipefail
    echo "=== Validating OpenTofu configurations ==="

    ERRORS=0

    if ! python3 ./scripts/validate-tofu-tfvars.py; then
        ERRORS=$((ERRORS + 1))
    fi

    if ! python3 ./scripts/validate-tofu-image-pins.py; then
        ERRORS=$((ERRORS + 1))
    fi

    if ! python3 ./scripts/validate-tofu-provider-locks.py; then
        ERRORS=$((ERRORS + 1))
    fi

    if ! python3 ./scripts/validate-tofu-module-docs.py; then
        ERRORS=$((ERRORS + 1))
    fi

    if ! python3 ./scripts/validate-tofu-plan-guard.py --self-test; then
        ERRORS=$((ERRORS + 1))
    fi

    if ! python3 ./scripts/validate-runner-cache-contract.py \
        --arc-tfvars tofu/stacks/arc-runners/honey.tfvars \
        --attic-tfvars tofu/stacks/attic/honey.tfvars; then
        ERRORS=$((ERRORS + 1))
    fi

    if ! bash ./scripts/validate-setup-flywheel-cache-hints.sh; then
        ERRORS=$((ERRORS + 1))
    fi

    if ! bash ./scripts/validate-workflow-cache-proofs.sh; then
        ERRORS=$((ERRORS + 1))
    fi

    if ! python3 ./scripts/validate-rbe-boundary.py; then
        ERRORS=$((ERRORS + 1))
    fi

    if ! python3 ./scripts/attic-public-key-from-tfvars.py --check \
        tofu/stacks/arc-runners/honey.tfvars; then
        ERRORS=$((ERRORS + 1))
    fi

    if ! python3 ./scripts/validate-runner-scale-contract.py \
        --arc-tfvars tofu/stacks/arc-runners/honey.tfvars; then
        ERRORS=$((ERRORS + 1))
    fi

    if ! python3 ./scripts/validate-runner-capacity-model.py \
        --arc-tfvars tofu/stacks/arc-runners/honey.tfvars; then
        ERRORS=$((ERRORS + 1))
    fi

    # Validate modules (syntax only - providers need init)
    # Modules are validated via stacks that use them
    echo "Checking module syntax..."
    for dir in tofu/modules/*/; do
        if [ -f "${dir}main.tf" ]; then
            echo "  Module: $(basename $dir)"
            # Just check HCL syntax, not full validation (needs providers)
            mapfile -t MODULE_TF_FILES < <(find "$dir" -type f -name "*.tf" | sort)
            if [ ${#MODULE_TF_FILES[@]} -gt 0 ] && ! tofu fmt -check "${MODULE_TF_FILES[@]}" >/dev/null 2>&1; then
                echo "    WARNING: Format issues detected"
            fi
        fi
    done

    # Validate stacks that have been initialized
    echo ""
    echo "Checking initialized stacks..."
    for dir in tofu/stacks/*/; do
        if [ -f "${dir}main.tf" ]; then
            stack_name=$(basename "$dir")
            if [ -d "${dir}.terraform" ]; then
                echo "  Stack: ${stack_name} (initialized)"
                if ! (cd "$dir" && tofu validate 2>/dev/null); then
                    echo "    ERROR: Validation failed"
                    ERRORS=$((ERRORS + 1))
                fi
            else
                echo "  Stack: ${stack_name} (not initialized - run 'just tofu-init ${stack_name}')"
            fi
        fi
    done

    echo ""
    if [ $ERRORS -gt 0 ]; then
        echo "Validation completed with $ERRORS error(s)"
        exit 1
    fi
    echo "Validation complete!"

# Format all tofu files
tofu-fmt:
    tofu fmt -recursive tofu/

# Check tofu formatting
tofu-fmt-check:
    #!/usr/bin/env bash
    set -euo pipefail
    batch_size="${TOFU_FMT_CHECK_BATCH_SIZE:-20}"
    files=()
    while IFS= read -r file; do
        files+=("$file")
    done < <(
        git ls-files -- "tofu/**/*.tf" "tofu/**/*.tfvars" "tofu/**/*.tf.json" "tofu/**/*.tfvars.json" |
            while IFS= read -r file; do
                [ -e "$file" ] && printf '%s\n' "$file"
            done
    )
    if [ "${#files[@]}" -eq 0 ]; then
        exit 0
    fi
    for ((i = 0; i < ${#files[@]}; i += batch_size)); do
        tofu fmt -check "${files[@]:i:batch_size}"
    done

# Check stack tfvars files only use declared stack variables
tofu-tfvars-check:
    python3 ./scripts/validate-tofu-tfvars.py

# Check live stack image inputs are immutable and Tofu defaults do not use latest
tofu-image-pin-check:
    python3 ./scripts/validate-tofu-image-pins.py

# Check active stack roots have provider locks committed
tofu-provider-lock-check:
    python3 ./scripts/validate-tofu-provider-locks.py

# Check OpenTofu module reference docs match tofu/modules
tofu-module-docs-check:
    python3 ./scripts/validate-tofu-module-docs.py

# Self-test the OpenTofu saved-plan guard
tofu-plan-guard-check:
    python3 ./scripts/validate-tofu-plan-guard.py --self-test

# Check runner stacks keep shared cache wiring attached
runner-cache-contract-check:
    python3 ./scripts/validate-runner-cache-contract.py \
        --arc-tfvars tofu/stacks/arc-runners/honey.tfvars \
        --attic-tfvars tofu/stacks/attic/honey.tfvars
    bash ./scripts/validate-setup-flywheel-cache-hints.sh
    bash ./scripts/validate-workflow-cache-proofs.sh

# Check setup-flywheel writes portable cache hints for downstream jobs
setup-flywheel-cache-hints-check:
    bash ./scripts/validate-setup-flywheel-cache-hints.sh

# Check workflow proof lanes still assert the cache attachment contracts
workflow-cache-proof-check:
    bash ./scripts/validate-workflow-cache-proofs.sh

# Check committed runner tfvars agree on the public Attic trust key
attic-public-key-contract-check:
    python3 ./scripts/attic-public-key-from-tfvars.py --check \
        tofu/stacks/arc-runners/honey.tfvars

# Check runner stacks keep scale contracts explicit and bounded
runner-scale-contract-check:
    python3 ./scripts/validate-runner-scale-contract.py \
        --arc-tfvars tofu/stacks/arc-runners/honey.tfvars

# Check runner namespace quotas match the committed burst-capacity model
runner-capacity-model-check:
    python3 ./scripts/validate-runner-capacity-model.py \
        --arc-tfvars tofu/stacks/arc-runners/honey.tfvars

# Check orgwide enrollment scoreboard classification stays honest
orgwide-enrollment-scoreboard-contract-check:
    bash ./tests/orgwide_enrollment_scoreboard_contract.sh

# Check orgwide enrollment queue proof policy stays explicit
orgwide-enrollment-queue-contract-check:
    bash ./tests/orgwide_enrollment_queue_contract.sh

# Show tofu state for a stack
tofu-state stack:
    cd tofu/stacks/{{stack}} && tofu state list

# Refresh tofu state for a stack
tofu-refresh stack:
    #!/usr/bin/env bash
    set -euo pipefail
    cd tofu/stacks/{{stack}}
    mapfile -t TFVARS_LIST < <(cd "{{justfile_directory()}}" && bash ./scripts/tofu-var-files.sh "{{stack}}" "{{env}}")
    ACTIVE_KUBE_CONTEXT="${KUBE_CONTEXT:-{{kube_context}}}"
    ACTIVE_KUBECONFIG_PATH="${KUBECONFIG_PATH_OVERRIDE:-{{kubeconfig_path}}}"
    if [[ -n "${ACTIVE_KUBECONFIG_PATH}" && "${ACTIVE_KUBECONFIG_PATH}" == "~/"* ]]; then
        ACTIVE_KUBECONFIG_PATH="${HOME}/${ACTIVE_KUBECONFIG_PATH#\~/}"
    fi
    if [ -z "${ACTIVE_KUBE_CONTEXT}" ]; then
        echo "ERROR: no cluster context found for ENV={{env}}"
        echo "Set KUBE_CONTEXT or update config/organization.yaml"
        exit 1
    fi
    REFRESH_ARGS=(
        -var="cluster_context=${ACTIVE_KUBE_CONTEXT}"
    )
    if [ -n "${ACTIVE_KUBECONFIG_PATH}" ]; then
        REFRESH_ARGS+=(-var="k8s_config_path=${ACTIVE_KUBECONFIG_PATH}")
    fi
    if [ -n "${GHCR_TOKEN:-}" ]; then
        if [ -z "${GHCR_USERNAME:-}" ]; then
            echo "ERROR: GHCR_USERNAME is required when GHCR_TOKEN is set"
            exit 1
        fi
        REFRESH_ARGS+=(-var="ghcr_token=${GHCR_TOKEN}")
        REFRESH_ARGS+=(-var="ghcr_username=${GHCR_USERNAME}")
    fi
    for tfvars in "${TFVARS_LIST[@]}"; do
        REFRESH_ARGS+=(-var-file="${tfvars}")
    done
    tofu refresh "${REFRESH_ARGS[@]}"

# =============================================================================
# Bazel Commands
# =============================================================================

# Run Bazel build (all targets)
bazel-build:
    @echo "GloriousFlywheel does not treat raw local Bazel as the normal contract."
    @echo "Use: just bazel-build-cached, or scripts/bazel-cache-backed.sh build //..., after entering direnv/nix develop and confirming shared cache settings."
    @exit 1

# Run Bazel tests
bazel-test:
    @echo "GloriousFlywheel does not treat raw local Bazel as the normal contract."
    @echo "Use: scripts/bazel-cache-backed.sh test //..., after entering direnv/nix develop and confirming shared cache settings."
    @exit 1

# Run Bazel build with CI config (no remote cache)
bazel-build-ci:
    @echo "GloriousFlywheel does not provide a normal Just wrapper for uncached local Bazel."
    @echo "Use raw bazel --config=ci only for explicit compatibility/debug sessions after entering the dev environment intentionally."
    @exit 1

# Run Bazel build with remote cache
bazel-build-cached:
    bash ./scripts/bazel-cache-backed.sh build //...

# Clean Bazel outputs
bazel-clean:
    @echo "GloriousFlywheel does not expose raw local Bazel cleanup as the normal contract."
    @echo "For explicit debug only: enter direnv/nix develop, confirm cache settings, then run the cleanup command manually."
    @exit 1

# Clean Bazel outputs including cache
bazel-clean-all:
    @echo "GloriousFlywheel does not expose raw local Bazel expunge as the normal contract."
    @echo "For explicit debug only: enter direnv/nix develop, confirm cache settings, then run the expunge command manually."
    @exit 1

# Show Bazel dependency graph
bazel-graph:
    @echo "GloriousFlywheel does not expose raw local Bazel query as the normal contract."
    @echo "For explicit debug only: enter direnv/nix develop, confirm cache settings, then run the graph query manually."
    @exit 1

# =============================================================================
# Kubernetes Commands
# =============================================================================

# List pods in a namespace
k8s-pods namespace="nix-cache":
    kubectl get pods -n {{namespace}} -o wide

# Show pod logs
k8s-logs namespace="nix-cache" selector="app.kubernetes.io/name=attic":
    kubectl logs -n {{namespace}} -l {{selector}} -f --tail=100

# Describe pods in a namespace
k8s-describe namespace="nix-cache":
    kubectl describe pods -n {{namespace}}

# Get events in a namespace (sorted by time)
k8s-events namespace="nix-cache":
    kubectl get events -n {{namespace}} --sort-by='.lastTimestamp'

# Port forward to a service
k8s-forward namespace="nix-cache" service="attic" port="8080":
    kubectl port-forward -n {{namespace}} svc/{{service}} {{port}}:8080

# Get all resources in a namespace
k8s-all namespace="nix-cache":
    @echo "=== Pods ==="
    @kubectl get pods -n {{namespace}} 2>/dev/null || echo "No pods"
    @echo ""
    @echo "=== Deployments ==="
    @kubectl get deployments -n {{namespace}} 2>/dev/null || echo "No deployments"
    @echo ""
    @echo "=== StatefulSets ==="
    @kubectl get statefulsets -n {{namespace}} 2>/dev/null || echo "No statefulsets"
    @echo ""
    @echo "=== Services ==="
    @kubectl get services -n {{namespace}} 2>/dev/null || echo "No services"
    @echo ""
    @echo "=== Ingress ==="
    @kubectl get ingress -n {{namespace}} 2>/dev/null || echo "No ingress"
    @echo ""
    @echo "=== PVCs ==="
    @kubectl get pvc -n {{namespace}} 2>/dev/null || echo "No PVCs"

# Check cluster operators (object storage, CNPG)
k8s-operators:
    @echo "=== RustFS ==="
    @kubectl get pods -n nix-cache -l app.kubernetes.io/name=rustfs 2>/dev/null || echo "RustFS pods not found"
    @echo ""
    @echo "=== CNPG Operator ==="
    @kubectl get pods -n cnpg-system 2>/dev/null || echo "Not installed"

# =============================================================================
# GitLab Runners (Shortcut Commands)
# =============================================================================

# Initialize GitLab runners stack
runners-init: (tofu-init "gitlab-runners")

# Plan GitLab runners deployment
runners-plan: (tofu-plan "gitlab-runners")

# Apply GitLab runners deployment
runners-apply: (tofu-apply "gitlab-runners")

# Full deploy cycle for runners
runners-deploy: (tofu-deploy "gitlab-runners")

# Show runner status for a namespace
runners-status namespace="gitlab-runners":
    @echo "=== Runner Status ({{namespace}}) ==="
    @echo ""
    @echo "=== Pods ==="
    @kubectl get pods -n {{namespace}} -o wide 2>/dev/null || echo "No pods found"
    @echo ""
    @echo "=== HPA ==="
    @kubectl get hpa -n {{namespace}} 2>/dev/null || echo "No HPA found"
    @echo ""
    @echo "=== Helm Releases ==="
    @helm list -n {{namespace}} 2>/dev/null || echo "No helm releases"

# Show runner logs
runners-logs runner namespace="gitlab-runners":
    kubectl logs -n {{namespace}} -l release={{runner}} -f --tail=100

# =============================================================================
# Cache Platform (Shortcut Commands)
# =============================================================================
# The 'attic' stack deploys the complete Nix binary cache platform:
#   - CNPG Operator + PostgreSQL cluster (metadata storage)
#   - RustFS S3-compatible object storage
#   - Attic API server (HPA-enabled Nix binary cache)
#   - Attic GC worker (garbage collection)
#   - DNS records, cache init job, warming CronJob
#   - Bazel remote cache (optional)
#
# The stack directory is named 'attic' for state backend compatibility.
# Use 'just tofu-deploy attic' for the generic recipe.

# Initialize cache platform stack (CNPG, RustFS, Attic, DNS)
cache-init: (tofu-init "attic")

# Plan cache platform deployment
cache-plan: (tofu-plan "attic")

# Apply cache platform deployment
cache-apply: (tofu-apply "attic")

# Full deploy cycle for cache platform (init + plan + apply)
cache-deploy: (tofu-deploy "attic")

# Show cache platform status (pods, operators, storage)
cache-status:
    @echo "=== Cache Platform Status ({{env}}) ==="
    @echo "Namespace: nix-cache"
    @echo ""
    just k8s-all nix-cache
    @echo ""
    just k8s-operators

# Run health check against the cache API endpoint
cache-health endpoint="https://nix-cache.{{ingress_domain}}" namespace="nix-cache":
    ./scripts/health-check.sh -u {{endpoint}} -n {{namespace}} -v

# =============================================================================
# Formatting Commands
# =============================================================================

# Format all files (Nix + Tofu + shell)
fmt: nix-fmt tofu-fmt
    @echo "All files formatted!"

# Check all formatting
fmt-check:
    #!/usr/bin/env bash
    set -euo pipefail
    echo "=== Checking formatting ==="

    # Check Nix formatting
    echo "Checking Nix files..."
    nix fmt -- --ci . 2>/dev/null || { echo "Run 'just nix-fmt' to fix"; exit 1; }

    # Check Tofu formatting
    echo "Checking OpenTofu files..."
    just tofu-fmt-check || { echo "Run 'just tofu-fmt' to fix"; exit 1; }

    echo "All formatting checks passed!"

# =============================================================================
# Security & Linting
# =============================================================================

# Run security scan with Trivy
security-scan:
    @command -v trivy >/dev/null 2>&1 || { echo "Install trivy: brew install trivy"; exit 1; }
    trivy config . --format table

# Run Nix linting (statix + deadnix)
nix-lint:
    @echo "Running statix..."
    statix check .
    @echo "Running deadnix..."
    deadnix .

# =============================================================================
# State Management
# =============================================================================

# Audit known GitLab OpenTofu state paths (legacy compatibility surface)
tofu-state-audit:
    @bash ./scripts/tofu-state-audit.sh {{env}} {{org_config}}

# Legacy alias for state audit
state-list: tofu-state-audit

# Unlock a stuck GitLab-managed state (legacy compatibility surface)
state-unlock name:
    #!/usr/bin/env bash
    set -euo pipefail
    if [ -z "{{gitlab_project}}" ] || [ -z "{{gitlab_api}}" ]; then
        echo "ERROR: gitlab.url and gitlab.project_id must be configured for legacy state unlock"
        exit 1
    fi
    echo "Unlocking state: {{name}}"
    glab opentofu state unlock "{{name}}" 2>/dev/null || \
        curl -X DELETE -H "PRIVATE-TOKEN: ${TF_HTTP_PASSWORD}" \
            "{{gitlab_api}}/projects/{{gitlab_project}}/terraform/state/{{name}}/lock"

# =============================================================================
# Utility Commands
# =============================================================================

# Clean up generated files
clean:
    rm -rf result result-* graph.svg build-graph.svg
    rm -f tofu/stacks/*/tfplan tofu/stacks/*/plan.json tofu/stacks/*/graph.svg
    @echo "Cleaned up generated files"

# Deep clean (includes Bazel + Nix + Terraform)
clean-all: clean bazel-clean
    rm -rf .direnv/
    rm -rf tofu/stacks/*/.terraform/
    @echo "Deep clean complete!"

# Setup git hooks
setup-hooks:
    ./.githooks/setup.sh

# Generate dependency graph for tofu stack
graph stack:
    cd tofu/stacks/{{stack}} && tofu graph | dot -Tsvg > graph.svg
    @echo "Graph saved to tofu/stacks/{{stack}}/graph.svg"

# =============================================================================
# CI Simulation
# =============================================================================

# Run CI checks locally
ci-local: fmt-check nix-check nix-build tofu-validate-all
    @echo ""
    @echo "=== CI checks passed! ==="

# Run CI health check (quick mode, no K8s checks)
ci-health endpoint="https://nix-cache.{{ingress_domain}}":
    ./scripts/health-check.sh -u {{endpoint}} -m 5 -d 10 -M 30

# =============================================================================
# Runner Dashboard App
# =============================================================================

# Install app dependencies
app-install:
    cd app && pnpm install

# Run app dev server
app-dev:
    cd app && pnpm dev

# Build app for production
app-build:
    cd app && pnpm build

# Run app tests
app-test:
    cd app && pnpm test

# Run app type check
app-check:
    cd app && pnpm check

# Run app linter
app-lint:
    cd app && pnpm lint

# Build app via Bazel
app-bazel-build:
    bash ./scripts/bazel-cache-backed.sh build //app:build

# Run app dev server via Bazel
app-bazel-dev:
    @echo "GloriousFlywheel does not treat Bazel local dev-server execution as the normal contract."
    @echo "Use just app-dev for ordinary UI work. Reserve bazel run //app:dev for explicit compatibility/debug sessions after confirming shared cache settings."
    @exit 1

# Build app OCI image via Nix
app-image:
    nix build .#runner-dashboard-image

# Show app status on cluster
app-status:
    @echo "=== Runner Dashboard Status ({{env}}) ==="
    @kubectl get pods -n runner-dashboard -o wide 2>/dev/null || echo "No pods found"
    @echo ""
    @kubectl get ingress -n runner-dashboard 2>/dev/null || echo "No ingress found"

# Initialize runner-dashboard OpenTofu stack
app-init: (tofu-init "runner-dashboard")

# Plan runner-dashboard deployment
app-plan: (tofu-plan "runner-dashboard")

# Apply runner-dashboard deployment
app-apply: (tofu-apply "runner-dashboard")

# Full deploy cycle: build image and tofu apply
app-deploy: app-build app-image (tofu-deploy "runner-dashboard")

# Show runner-dashboard logs
app-logs:
    cd tofu/stacks/runner-dashboard && just env={{env}} logs

# Port-forward runner-dashboard for local testing
app-port-forward:
    cd tofu/stacks/runner-dashboard && just env={{env}} port-forward

# =============================================================================
# Documentation Site
# =============================================================================

# Start docs site dev server
docs-dev:
    cd docs-site && pnpm dev

# Build docs site for production (adapter-static)
docs-build:
    cd docs-site && pnpm build

# Install docs site dependencies
docs-install:
    cd docs-site && pnpm install

# Type-check docs site
docs-check:
    cd docs-site && pnpm check

# =============================================================================
# TeX Research Document
# =============================================================================

# Build research PDF with latexmk
tex:
    #!/usr/bin/env bash
    set -euo pipefail

    TEX_DIR="tex_research/glorious-flywheel"
    TEX_FILE="glorious-flywheel.tex"
    BUILD_DIR="${TEX_DIR}/build"
    DIST_DIR="${TEX_DIR}/dist"

    if ! command -v latexmk &> /dev/null; then
        echo "[tex] latexmk not found. Install via: nix develop"
        exit 0
    fi

    mkdir -p "${BUILD_DIR}" "${DIST_DIR}"

    cd "${TEX_DIR}" && latexmk -pdf -xelatex \
        -interaction=nonstopmode \
        -output-directory=build \
        -shell-escape \
        "${TEX_FILE}" 2>&1 | tail -20 || {
            echo "[tex] Warning: check build/glorious-flywheel.log"
        }

    if [ -f "build/glorious-flywheel.pdf" ]; then
        cp "build/glorious-flywheel.pdf" "dist/"
        echo "[tex] PDF generated: dist/glorious-flywheel.pdf"
    else
        echo "[tex] Warning: PDF not generated"
    fi

# Clean TeX build artifacts
tex-clean:
    rm -rf tex_research/glorious-flywheel/build
    echo "[tex] Build artifacts cleaned"

# Watch and rebuild TeX on changes
tex-watch:
    watchexec -w tex_research/glorious-flywheel -e tex,bib -- just tex

# ============================================================================
# Changelog
# ============================================================================

# Generate CHANGELOG.md from git history
changelog:
    git cliff --output CHANGELOG.md
    echo "[changelog] Generated CHANGELOG.md"

# Preview changelog for next release (dry run)
changelog-preview:
    git cliff --unreleased

# Generate changelog for a specific tag/version
changelog-tag tag:
    git cliff --tag {{tag}} --output CHANGELOG.md
    echo "[changelog] Generated CHANGELOG.md for {{tag}}"