Taskfile.yml

# AgentContextOS — cross-platform task runner (https://taskfile.dev)
#
# Works natively on Windows, macOS, and Linux without extra tooling.
# Install: winget install Task.Task  |  brew install go-task  |  https://taskfile.dev/installation
#
# Usage: task <target>     (mirrors every target in the Makefile)

version: "3"

vars:
  PYTHON: "uv run python"
  PYTEST:  "uv run pytest"
  RUFF:    "uv run ruff"
  MYPY:    "uv run mypy"

tasks:
  default:
    desc: List all available tasks
    cmds:
      - task --list
    silent: true

  # ---------------------------------------------------------------------------
  # Setup
  # ---------------------------------------------------------------------------
  bootstrap:
    desc: Install all deps and pre-commit hooks (run once after clone)
    cmds:
      - uv sync --all-packages
      - pnpm install
      - uv run pre-commit install
      - uv run pre-commit install --hook-type commit-msg

  # ---------------------------------------------------------------------------
  # Quality gates
  # ---------------------------------------------------------------------------
  lint:
    desc: Run ruff + mypy on all Python packages
    cmds:
      - "{{.RUFF}} check ."
      - "{{.RUFF}} format --check ."
      - "{{.MYPY}} packages/ apps/gateway/"

  lint:backends:
    desc: mypy --strict on the backends package only
    cmds:
      - "{{.MYPY}} packages/backends/"

  lint:logging:
    desc: "RAG001 — ban logging.getLogger() outside rag_core.logging"
    cmds:
      - "{{.PYTHON}} scripts/check_logging.py"

  # ---------------------------------------------------------------------------
  # Config schema + validation
  # ---------------------------------------------------------------------------
  config-schema:
    desc: Generate rag.yaml JSON Schema → dist/rag.schema.json + dist/rag.schema.yaml
    env:
      PYTHONPATH: "packages/core/src:packages/config/src"
    cmds:
      - "{{.PYTHON}} -m rag_config.gen_schema dist/"

  config-validate:
    desc: Validate the root rag.yaml against the platform schema
    cmds:
      - uv run ragctl config validate rag.yaml

  fmt:
    desc: Auto-fix ruff lint + format in-place
    cmds:
      - "{{.RUFF}} check --fix ."
      - "{{.RUFF}} format ."

  # ---------------------------------------------------------------------------
  # Testing
  # ---------------------------------------------------------------------------
  test:
    desc: Run the full test suite (unit + contract; excludes the perf gate)
    cmds:
      - "{{.PYTEST}} tests/ packages/ -x -q -m 'not perf'"

  test-contract:
    desc: Run SPI conformance suites only
    cmds:
      - "{{.PYTEST}} tests/contract/ -v -m contract"

  test-logs:
    desc: Run logging schema + PII + registry gates
    cmds:
      - "{{.PYTEST}} tests/logs/ -v"

  test-eval:
    desc: Run eval schema + harness skeleton tests
    cmds:
      - "{{.PYTEST}} tests/eval/ -v"

  test-integration:
    desc: "Run integration tests (requires: task dev + task dev-wait)"
    cmds:
      - "{{.PYTEST}} tests/integration/ -v -m integration"

  test-backends:
    desc: "Run backend unit tests (LocalFileStorage — no services required)"
    cmds:
      - "{{.PYTEST}} tests/integration/test_local_storage.py -v"

  perf:
    desc: "Run the gateway latency gate (server-side p99 overhead budget)"
    cmds:
      - "{{.PYTEST}} tests/perf/ -v -m perf"

  load-test:
    desc: "Run the in-process gateway load + profile harness (writes eval/gateway_load_v0/report.*)"
    cmds:
      - "{{.PYTHON}} -m eval.gateway_load_v0.harness"

  chaos-test:
    desc: "Run the chaos-under-load harness — inject backend faults, assert graceful degradation"
    cmds:
      - "{{.PYTHON}} -m eval.gateway_chaos_v0.harness --check"

  chaos-kill:
    desc: "Run the chaos kill-matrix — kill each backend in turn, assert no single failure 5xx-es the gateway"
    cmds:
      - "{{.PYTHON}} -m eval.gateway_chaos_v0.kill_matrix --check"

  redteam:
    desc: "Run the red-team gate — prompt injection / ACL bypass / PII egress / tenant escape probes"
    cmds:
      - "{{.PYTEST}} tests/redteam/ -v -m redteam"

  # ---------------------------------------------------------------------------
  # Schemas
  # env: sets PYTHONPATH cross-platform (Task handles Windows vs Unix syntax)
  # ---------------------------------------------------------------------------
  schemas:
    desc: Generate JSON Schema + Proto artifacts → dist/schemas/
    env:
      PYTHONPATH: "packages/core/src"
    cmds:
      - "{{.PYTHON}} -m rag_core.gen_schemas dist/schemas/"

  lint:schemas:
    desc: "Schema-drift gate — fails if dist/schemas/ is out of sync with rag_core types"
    env:
      PYTHONPATH: "packages/core/src"
    cmds:
      - "{{.PYTHON}} -m rag_core.gen_schemas dist/schemas/"
      - "{{.PYTHON}} scripts/check_schema_drift.py"

  # ---------------------------------------------------------------------------
  # gRPC / proto (Step 3.2)
  # `proto:gen` uses grpcio-tools (pure-Python, cross-platform).
  # `proto:lint` uses buf, which CI installs via bufbuild/buf-setup-action.
  # ---------------------------------------------------------------------------
  proto:gen:
    desc: Regenerate Python gRPC stubs from proto/rag.proto
    cmds:
      - "{{.PYTHON}} scripts/gen_proto_py.py"

  proto:lint:
    desc: "buf lint over proto/ — fails on STANDARD-suite violations"
    cmds:
      - buf lint

  proto:check-drift:
    desc: "Proto-drift gate — fails if committed stubs are out of sync with proto/rag.proto"
    cmds:
      - "{{.PYTHON}} scripts/check_proto_drift.py"

  # ---------------------------------------------------------------------------
  # OpenAPI + SDKs (Step 3.7)
  # `openapi:gen` is pure-Python; `sdk:gen` needs buf + openapi-generator-cli
  # (Java) on the machine — see docs/architecture/sdk-generation.md.
  # ---------------------------------------------------------------------------
  openapi:gen:
    desc: Re-export dist/openapi.{json,yaml} from the live gateway routes
    cmds:
      - "{{.PYTHON}} scripts/export_openapi.py"

  openapi:check-drift:
    desc: "OpenAPI-drift gate — fails if dist/openapi.* is stale vs the gateway"
    cmds:
      - "{{.PYTHON}} scripts/check_openapi_drift.py"

  # ---------------------------------------------------------------------------
  # Documentation site (Step 7.5) — Docusaurus under website/, sourcing docs/
  # ---------------------------------------------------------------------------
  docs:api:
    desc: "Regenerate docs/reference/rest-api.md from dist/openapi.json"
    cmds:
      - "{{.PYTHON}} scripts/gen_api_reference.py"

  docs:dev:
    desc: "Run the documentation site locally (http://localhost:3000)"
    dir: website
    cmds:
      - npm install
      - npm run dev

  docs:build:
    desc: "Build the static documentation site → website/build/"
    dir: website
    cmds:
      - npm install
      - npm run build

  sdk:gen:
    desc: "Generate all SDK artifacts (proto stubs + OpenAPI clients) into sdks/*/"
    cmds:
      - "{{.PYTHON}} scripts/gen_sdks.py"

  sdk:gen-proto:
    desc: "Generate cross-language proto stubs into sdks/*/ (needs buf)"
    cmds:
      - "{{.PYTHON}} scripts/gen_sdks.py --only proto"

  sdk:gen-openapi:
    desc: "Generate Go/Java/.NET OpenAPI clients into sdks/*/ (needs openapi-generator-cli)"
    cmds:
      - "{{.PYTHON}} scripts/gen_sdks.py --only openapi"

  # ---------------------------------------------------------------------------
  # Local dev stack
  # ---------------------------------------------------------------------------
  dev:
    desc: Start core local stack (postgres, redis, qdrant, elasticsearch)
    cmds:
      - docker compose --profile core up -d

  dev-full:
    desc: Start core + full observability stack (+ otel, jaeger, prometheus, grafana, loki)
    cmds:
      - docker compose --profile core --profile observability up -d

  dev-down:
    desc: Stop all local stack services
    cmds:
      - docker compose --profile core --profile observability down

  dev-wait:
    desc: Block until all core services are healthy (timeout 90s)
    cmds:
      - cmd: bash scripts/dev-wait.sh
        platforms: [linux, darwin]
      - cmd: pwsh scripts/dev-wait.ps1
        platforms: [windows]

  dev-seed:
    desc: Run pgvector migration, init Qdrant collections, and load seed data
    cmds:
      - cmd: bash scripts/dev-seed.sh
        platforms: [linux, darwin]
      - cmd: pwsh scripts/dev-seed.ps1
        platforms: [windows]

  dev-reset:
    desc: Tear down volumes, restart services, wait for health, and re-seed
    cmds:
      - docker compose --profile core down -v
      - docker compose --profile core up -d
      - task: dev-wait
      - task: dev-seed

  docker:
    desc: Build all Docker images
    cmds:
      - docker compose build

  # ---------------------------------------------------------------------------
  # Security
  # ---------------------------------------------------------------------------
  audit:
    desc: Run pip-audit for dependency CVEs
    cmds:
      - uv run pip-audit

  # ---------------------------------------------------------------------------
  # IaC — Terraform + Helm
  # ---------------------------------------------------------------------------
  infra:init:
    desc: terraform init for the dev environment
    dir: infra/terraform/environments/dev
    cmds:
      - terraform init

  infra:validate:
    desc: terraform validate for dev + prod environments
    cmds:
      - terraform -chdir=infra/terraform/environments/dev validate
      - terraform -chdir=infra/terraform/environments/prod validate

  infra:plan:
    desc: terraform plan for the dev environment (requires live cluster)
    dir: infra/terraform/environments/dev
    cmds:
      - terraform plan

  helm:lint:
    desc: Lint the rag-platform Helm chart
    cmds:
      - helm lint infra/helm/rag-platform/

  helm:template:
    desc: Render Helm templates to stdout (dry run)
    cmds:
      - helm template rag-platform infra/helm/rag-platform/

  # ---------------------------------------------------------------------------
  # Air-gapped install bundle (Step 6.9)
  # ---------------------------------------------------------------------------
  airgap:build:
    desc: "Build the signed offline install bundle → dist/airgap.tar.gz (needs docker + helm + cosign)"
    cmds:
      - uv run ragctl airgap build --sign

  airgap:build-dry:
    desc: "Build a dry-run bundle (no docker/helm/cosign) — preview packaging + verify logic"
    cmds:
      - uv run ragctl airgap build --dry-run

  airgap:verify:
    desc: "Verify an air-gapped bundle's content hash + signature (BUNDLE=dist/airgap.tar.gz)"
    vars:
      BUNDLE: '{{.BUNDLE | default "dist/airgap.tar.gz"}}'
    cmds:
      - uv run ragctl airgap verify {{.BUNDLE}}

  # ---------------------------------------------------------------------------
  # Cleanup — platform-specific commands via platforms: key
  # ---------------------------------------------------------------------------
  clean:
    desc: Remove build artefacts, caches, and __pycache__
    cmds:
      # macOS / Linux
      - cmd: find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null; true
        platforms: [linux, darwin]
      - cmd: find . -type d -name .mypy_cache -exec rm -rf {} + 2>/dev/null; true
        platforms: [linux, darwin]
      - cmd: find . -type d -name .ruff_cache -exec rm -rf {} + 2>/dev/null; true
        platforms: [linux, darwin]
      - cmd: rm -rf dist/ .pytest_cache/ htmlcov/ .coverage
        platforms: [linux, darwin]
      # Windows (cmd.exe via Task's shell)
      - cmd: for /d /r . %d in (__pycache__)  do @if exist "%d" rd /s /q "%d"
        platforms: [windows]
      - cmd: for /d /r . %d in (.mypy_cache)  do @if exist "%d" rd /s /q "%d"
        platforms: [windows]
      - cmd: for /d /r . %d in (.ruff_cache)  do @if exist "%d" rd /s /q "%d"
        platforms: [windows]
      - cmd: if exist dist         rd /s /q dist
        platforms: [windows]
      - cmd: if exist .pytest_cache rd /s /q .pytest_cache
        platforms: [windows]
      - cmd: if exist htmlcov       rd /s /q htmlcov
        platforms: [windows]
      - cmd: if exist .coverage     del /f .coverage
        platforms: [windows]