Taskfile.yaml

version: 3

env:
  UV_LINK_MODE: copy

tasks:
  default:
    desc: Display available tasks
    cmds:
      - task -l

  restart-api:
    dir: "{{.USER_WORKING_DIR}}"
    cmds:
      - echo "tRestarting API service..."
      - docker compose restart api
    desc: Restart the API service

  generate:
    dotenv: [.env]
    cmds:
      - |
        OPENAPI_TMP="$(mktemp)"
        ENV=test uv run python -c 'import json, os; from dotenv import load_dotenv; load_dotenv(".env"); os.environ["ENV"] = "test"; from qdash.api.main import app; print(json.dumps(app.openapi(), ensure_ascii=False, indent=2))' > "$OPENAPI_TMP"
        mv "$OPENAPI_TMP" docs/oas/openapi.json
      - cd ui && bunx orval@7.14.0 --config ./orval.config.cjs
      - cd clients/typescript && bunx orval@7.14.0 --config ./orval.config.cjs
      - cd ui && bun run fmt
      - cd ui && bun run lint:fix
    desc: Generate the TypeScript clients

  generate-python-schema:
    desc: Generate Python Pydantic schema models from OpenAPI
    vars:
      OPENAPI_INPUT: '{{default "docs/oas/openapi.json" .OPENAPI_INPUT}}'
      PY_SCHEMA_OUTPUT: '{{default "scripts/generated/openapi_models/models.py" .PY_SCHEMA_OUTPUT}}'
    cmds:
      - mkdir -p "$(dirname {{.PY_SCHEMA_OUTPUT}})"
      - |
        uvx --from datamodel-code-generator datamodel-codegen \
          --use-schema-description \
          --target-python-version 3.12 \
          --field-constraints \
          --use-annotated \
          --use-field-description \
          --input {{.OPENAPI_INPUT}} \
          --input-file-type openapi \
          --collapse-root-models \
          --enum-field-as-literal one \
          --set-default-enum-member \
          --use-union-operator \
          --use-subclass-enum \
          --output-model-type pydantic_v2.BaseModel \
          --disable-timestamp \
          --use-standard-collections \
          --strict-nullable \
          --use-default \
          --output {{.PY_SCHEMA_OUTPUT}}
      - uv run ruff format {{.PY_SCHEMA_OUTPUT}}

  knowledge:
    desc: Generate task knowledge JSON from markdown files
    cmds:
      - uv run scripts/generate_task_knowledge.py

  knowledge-pull:
    desc: Pull task-knowledge.json from the knowledge repository (KNOWLEDGE_REPO_URL)
    dotenv: [.env]
    cmds:
      - |
        KNOWLEDGE_DIR="config/task-knowledge"
        if [ -z "$KNOWLEDGE_REPO_URL" ]; then
          echo "KNOWLEDGE_REPO_URL not set, skipping pull"
          exit 0
        fi
        # Build auth URL if credentials available
        AUTH_URL="$KNOWLEDGE_REPO_URL"
        if [ -n "$GITHUB_USER" ] && [ -n "$GITHUB_TOKEN" ]; then
          AUTH_URL=$(echo "$KNOWLEDGE_REPO_URL" | sed "s|https://|https://${GITHUB_USER}:${GITHUB_TOKEN}@|")
        fi
        # Clone or pull
        if [ -d "$KNOWLEDGE_DIR/.git" ]; then
          echo "Pulling latest from $KNOWLEDGE_REPO_URL..."
          git -C "$KNOWLEDGE_DIR" remote set-url origin "$AUTH_URL"
          git -C "$KNOWLEDGE_DIR" fetch origin && git -C "$KNOWLEDGE_DIR" reset --hard origin/main || {
            echo "Pull failed, re-cloning..."
            rm -rf "$KNOWLEDGE_DIR"
            git clone --depth 1 "$AUTH_URL" "$KNOWLEDGE_DIR"
          }
        else
          echo "Cloning $KNOWLEDGE_REPO_URL..."
          rm -rf "$KNOWLEDGE_DIR"
          mkdir -p config
          git clone --depth 1 "$AUTH_URL" "$KNOWLEDGE_DIR"
        fi
        # Verify JSON exists in the cloned repo
        if [ -f "$KNOWLEDGE_DIR/task-knowledge.json" ]; then
          echo "task-knowledge.json ready ($(du -h "$KNOWLEDGE_DIR/task-knowledge.json" | cut -f1))"
        else
          echo "WARNING: task-knowledge.json not found in repo; it will be generated on next PR merge" >&2
        fi

  docs:
    dir: docs
    cmds:
      - bun install
      - bun run docs:dev --host

  docs-gif:
    desc: "Record a docs user-guide GIF from a scenario (usage: task docs-gif -- login). Needs the local stack running (task dev-local)."
    dotenv: [.env]
    cmds:
      - uv run --with playwright python3 docs/demos/record.py --scenario docs/demos/scenarios/{{.CLI_ARGS}}.yaml

  # =============================================================================
  # Lightweight local development (Nix shell + Docker services)
  # =============================================================================

  dev-services:
    desc: Start only the services needed by host-side API/UI development
    cmds:
      - docker compose up -d mongo postgres prefect-server deployment-service user-flow-worker

  dev-local-down:
    desc: Stop host API/UI processes and Docker Compose services started for development
    dotenv: [.env]
    silent: true
    cmds:
      - |
        stop_pidfile() {
          pid_file="$1"
          name="$2"
          expected="$3"
          if [ ! -f "$pid_file" ]; then
            echo "${name} pid file not found"
            return
          fi

          pid="$(cat "$pid_file")"
          command="$(ps -p "$pid" -o command= 2>/dev/null || true)"
          if [ -n "$command" ] && echo "$command" | grep -F "$expected" >/dev/null; then
            echo "Stopping ${name}: ${pid}"
            /bin/kill "$pid" 2>/dev/null || true
          else
            echo "${name} pid file is stale: ${pid}"
          fi
          rm -f "$pid_file"
        }

        stop_command() {
          pattern="$1"
          name="$2"
          pids="$(ps ax -o pid= -o command= | awk -v pattern="$pattern" -v self="$$" 'index($0, pattern) > 0 && $1 != self {print $1}')"
          if [ -n "$pids" ]; then
            echo "Stopping ${name} processes: ${pids}"
            /bin/kill $pids 2>/dev/null || true
          fi
        }

        stop_port() {
          port="$1"
          name="$2"
          pids="$(lsof -ti "tcp:${port}" -sTCP:LISTEN || true)"
          if [ -n "$pids" ]; then
            echo "Stopping ${name} on port ${port}: ${pids}"
            /bin/kill $pids 2>/dev/null || true
          else
            echo "${name} is not listening on port ${port}"
          fi
        }
        stop_pidfile ".tmp/dev-api-local.pid" "API" "uvicorn src.qdash.api.main:app"
        stop_pidfile ".tmp/dev-ui-local.pid" "UI" "bun run dev"
        stop_command "uvicorn src.qdash.api.main:app" "API"
        stop_command "bun run dev" "UI"
        stop_port "${API_PORT:-5715}" "API"
        stop_port "${UI_PORT:-5714}" "UI"
      - docker compose down

  dev-local-setup:
    desc: Install dependencies needed by host-side API/UI development
    cmds:
      - uv sync --locked --all-groups --all-packages
      - mkdir -p "${CONFIG_PATH:-./config/qubex-config}"
      - bun install --cwd ui --frozen-lockfile

  upgrade-uv-lock:
    desc: Upgrade qubex and related qx packages in uv.lock
    cmds:
      - uv sync --all-groups --all-packages --no-cache --upgrade

  dev-api-local:
    desc: Start the API on the host against Docker services
    dotenv: [.env]
    silent: true
    cmds:
      - |
        /bin/sh -c '
        mkdir -p .tmp
        echo "$$" > .tmp/dev-api-local.pid
        MONGO_HOST="${MONGO_HOST:-localhost}" PREFECT_API_URL="http://127.0.0.1:${PREFECT_PORT:-4200}/api" DEPLOYMENT_SERVICE_URL="http://127.0.0.1:${DEPLOYMENT_SERVICE_PORT:-4006}" exec uv run uvicorn src.qdash.api.main:app --reload --host 127.0.0.1 --port "${API_PORT:-5715}"
        '

  dev-ui-local:
    desc: Start the UI on the host against the local API
    dir: ui
    dotenv: [../.env]
    silent: true
    cmds:
      - |
        /bin/sh -c '
        mkdir -p ../.tmp
        echo "$$" > ../.tmp/dev-ui-local.pid
        PORT="${UI_PORT:-5714}" INTERNAL_API_URL="http://127.0.0.1:${API_PORT:-5715}" exec bun run dev
        '

  dev-local:
    desc: Start lightweight local development services, API, and UI
    cmds:
      - task: dev-services
      - task --parallel dev-api-local dev-ui-local

  # =============================================================================
  # Python Tests (all tests run in-memory, no MongoDB required)
  # =============================================================================

  test:
    desc: Run all Python tests
    cmds:
      - uv run pytest tests/ -v

  test-fast:
    desc: Run tests, stop on first failure
    cmds:
      - uv run pytest tests/ -v -x --tb=short

  test-api:
    desc: Run API router tests
    cmds:
      - uv run pytest tests/qdash/api/ -v

  test-client:
    desc: Run Python client tests
    cmds:
      - uv run pytest tests/qdash/client/ -v

  test-client-ts:
    desc: Run TypeScript client checks
    dir: clients/typescript
    cmds:
      - bun run check

  test-workflow:
    desc: Run workflow engine tests
    cmds:
      - uv run pytest tests/qdash/workflow/ -v

  test-repository:
    desc: Run repository tests
    cmds:
      - uv run pytest tests/qdash/workflow/engine/repository/ -v

  test-ui:
    desc: Run UI tests
    dir: ui
    cmds:
      - bun run test:run

  test-coverage:
    desc: Run tests with coverage report
    cmds:
      - uv run pytest tests/ --cov=src/qdash --cov-report=term --cov-report=html

  test-parallel:
    desc: Run tests in parallel (requires pytest-xdist)
    cmds:
      - uv run pytest tests/ -v -n auto

  test-watch:
    desc: Run tests in watch mode (requires pytest-watch)
    cmds:
      - uv run ptw -- -v --tb=short

  build:
    dir: ui
    cmds:
      - bun run build

  drawio-export:
    desc: Export .drawio files to .drawio.png (requires draw.io desktop CLI)
    cmds:
      - |
        n=10
        for f in docs/diagrams/*.drawio; do
          out="${f}.png"
          echo "Exporting $f -> $out"
          xvfb-run -n $n drawio --no-sandbox --export --format png --embed-diagram --scale 2 --output "$out" "$f"
          n=$((n + 1))
        done

  build-docs:
    dir: docs
    cmds:
      - npm run docs:build

  # =============================================================================
  # Linting & Formatting (local development - auto-fix)
  # =============================================================================

  lint:
    desc: Run all linting and formatting (Python + UI)
    cmds:
      - task: lint-python
      - task: lint-ui

  lint-python:
    desc: Run Python linting and formatting (auto-fix)
    cmds:
      - uv run ruff check --fix --quiet .
      - uv run ruff format --quiet .

  lint-ui:
    dir: ui
    desc: Run UI linting and formatting (auto-fix)
    cmds:
      - bun run fmt
      - bun run lint:fix

  # =============================================================================
  # Secret Scanning
  # =============================================================================

  scan-secrets:
    desc: Run full secret scan with Trufflehog (git history + filesystem)
    cmds:
      - trufflehog git file://. --only-verified --fail --exclude-paths=.trufflehog-exclude-paths.txt

  scan-secrets-all:
    desc: Run Trufflehog scan including unverified findings
    cmds:
      - trufflehog git file://. --fail --exclude-paths=.trufflehog-exclude-paths.txt

  scan-leaks:
    desc: Run Betterleaks scan over git history (full repository)
    cmds:
      - |
        if command -v betterleaks >/dev/null 2>&1; then
          betterleaks git . --verbose
        else
          echo "betterleaks not installed; skipping leak scan"
        fi

  scan-leaks-staged:
    desc: Run Betterleaks on staged files only (same as pre-commit)
    cmds:
      - |
        if command -v betterleaks >/dev/null 2>&1; then
          betterleaks git . --pre-commit --staged --verbose
        else
          echo "betterleaks not installed; skipping staged leak scan"
        fi

  # =============================================================================
  # Local Check (run before push)
  # =============================================================================

  check:
    desc: Run all checks locally (lint, typecheck, test, UI, audit)
    cmds:
      - task: lint
      - task: ci-lint
      - task: ci-typecheck
      - task: ci-test
      - task: ci-ui
      - task: scan-leaks

  check-all:
    desc: Run the full local check suite
    cmds:
      - task: check

  # =============================================================================
  # CI Checks (check-only, no auto-fix)
  # =============================================================================

  ci:
    desc: "[CI] Run all Python CI checks"
    cmds:
      - task: ci-lint
      - task: ci-typecheck
      - task: ci-test

  ci-lint:
    desc: Check Python linting (no auto-fix)
    cmds:
      - uv run ruff check .
      - uv run ruff format --check .

  ci-typecheck:
    desc: Run mypy type checking
    cmds:
      - uv run mypy src/qdash/common src/qdash/datamodel src/qdash/dbmodel src/qdash/repository src/qdash/api src/qdash/workflow tests

  ci-test:
    desc: Run all tests with coverage
    cmds:
      - uv run pytest tests/ -v --tb=short --cov=src/qdash --cov-report=xml --cov-report=term

  knip:
    desc: Check for unused exports, dependencies, and files in UI
    dir: ui
    cmds:
      - bun run knip

  knip-fix:
    desc: Auto-fix unused exports and dependencies in UI
    dir: ui
    cmds:
      - bun run knip:fix

  ci-ui:
    desc: Run all UI CI checks
    dir: ui
    cmds:
      - bun run test:run
      - bunx next typegen
      - bunx tsc --noEmit
      - bun run lint
      - bun run fmt:check
      - bun run knip
      - bun audit

  ci-ui-build:
    desc: Build UI for production
    dir: ui
    cmds:
      - bun run build

  tbls-docs:
    cmds:
      - tbls doc -c .tbls.yml -f
    desc: Generate DB Schema Docs

  check-lock-api:
    cmds:
      - uv lock --check
    desc: Check server dependency lock

  check-lock-workflow:
    cmds:
      - uv lock --check
    desc: Check workflow dependency lock

  check-lock-dev:
    cmds:
      - uv lock --check
    desc: Check dev dependency lock

  check-locks:
    cmds:
      - task check-lock-api
      - task check-lock-workflow
      - task check-lock-dev
    desc: Check dependency locks

  build-api:
    cmds:
      - task check-lock-api
      - docker compose build --no-cache api

  build-workflow:
    cmds:
      - task check-lock-workflow
      - docker compose build --no-cache user-flow-worker deployment-service

  deploy-local:
    cmds:
      - task: knowledge-pull
      - docker compose up -d --build
    desc: Deploy the application with Docker Compose in dev mode

  deploy-local-fake:
    env:
      DEFAULT_BACKEND: fake
      ENV: dev-fake
    cmds:
      - task: knowledge-pull
      - docker compose up -d --build
    desc: Deploy the application locally with the fake QUBEX-compatible backend

  deploy-local-fake-down:
    cmds:
      - docker compose down
    desc: Stop the local fake Docker Compose stack

  dev-ui:
    dir: ui
    cmds:
      - bun run dev
    desc: Start the UI development server

  deploy:
    cmds:
      - task: knowledge-pull
      - docker compose --profile tunnel up -d --build
      - sleep 3
      - docker compose restart api
    desc: Deploy the application with Docker Compose