Taskfile.yaml

version: "3"

vars:
  CLUSTER_NAME: kamerplanter

tasks:
  # ── Development Environment ─────────────────────────────────

  setup:
    desc: Create Kind cluster and install prerequisites
    cmds:
      - ./scripts/dev-setup.sh

  teardown:
    desc: Tear down Kind cluster
    cmds:
      - ./scripts/dev-teardown.sh

  dev:
    desc: Start full Skaffold dev loop (file sync stays automatic, rebuild/redeploy on Enter)
    cmds:
      - skaffold dev --auto-build=false --auto-deploy=false --auto-sync=true

  dev:backend:
    desc: Start Skaffold dev loop (backend only, file sync automatic, rebuild/redeploy on Enter)
    cmds:
      - skaffold dev -p backend-only --auto-build=false --auto-deploy=false --auto-sync=true

  dev:core:
    desc: Start Skaffold dev loop for the KP Core module only (backend, frontend, celery, arangodb, timescaledb) — excludes the KI/AI (ki) module. File sync stays automatic; rebuild/redeploy on Enter.
    cmds:
      - skaffold dev -m kp --auto-build=false --auto-deploy=false --auto-sync=true

  dev:ki:
    desc: Start Skaffold dev loop for the KI/AI module (knowledge-service, embedding-service, reranker, pgvector) — RAG stack without image recognition. File sync stays automatic; rebuild/redeploy on Enter.
    cmds:
      - skaffold dev -m ki --auto-build=false --auto-deploy=false --auto-sync=true

  dev:recognition:
    desc: Start Skaffold dev loop for image recognition (inference-service) plus the ki module that provides the shared pgvector store. Optional feature (REQ-029-A). File sync stays automatic; rebuild/redeploy on Enter.
    cmds:
      - skaffold dev -m ki -m recognition --auto-build=false --auto-deploy=false --auto-sync=true

  dev:recognition:only:
    desc: Start only the recognition inference-service (no RAG stack). Requires the kamerplanter-ki pgvector DB to be running already (e.g. from 'task dev:ki'). File sync stays automatic; rebuild/redeploy on Enter.
    cmds:
      - skaffold dev -m recognition --auto-build=false --auto-deploy=false --auto-sync=true

  dev:all:
    desc: Start Skaffold dev loop for all modules (KP Core + KI/AI + recognition). File sync stays automatic; rebuild/redeploy on Enter.
    cmds:
      - skaffold dev -m kp -m ki -m recognition --auto-build=false --auto-deploy=false --auto-sync=true

  # ── Image Recognition (REQ-029-A) ───────────────────────────

  recognition:acquire:
    desc: Trigger reference-image acquisition for ALL species — populates the DINOv2 pgvector index and the species thumbnails/gallery. Requires the recognition + ki + backend stack running.
    cmds:
      - kubectl exec deploy/kamerplanter-celery-worker -n default -- celery -A app.tasks call app.tasks.reference_image_tasks.acquire_all_reference_images_task

  recognition:coverage:
    desc: Print the reference-image coverage report (how many species are recognizable). Port-forward the backend first (task dev:core) or run inside the cluster.
    cmds:
      - 'curl -s http://localhost:8000/api/v1/admin/reference-images/coverage -H "Authorization: Bearer ${ADMIN_TOKEN}"'

  # ── System Tuning ───────────────────────────────────────────

  fix:inotify:
    desc: Increase inotify limits (fixes 'too many open files' in Skaffold)
    cmds:
      - sudo sysctl fs.inotify.max_user_watches=524288
      - sudo sysctl fs.inotify.max_user_instances=512
      - echo -e "fs.inotify.max_user_watches=524288\nfs.inotify.max_user_instances=512" | sudo tee /etc/sysctl.d/90-inotify.conf
    status:
      - test $(cat /proc/sys/fs/inotify/max_user_watches) -ge 524288
      - test $(cat /proc/sys/fs/inotify/max_user_instances) -ge 512

  # ── Backend ─────────────────────────────────────────────────

  lint:backend:
    desc: Run ruff linter on backend code
    dir: src/backend
    cmds:
      - ruff check .

  test:backend:
    desc: Run backend pytest suite
    dir: src/backend
    cmds:
      - python -m pytest tests/ {{.CLI_ARGS}}

  deps:compile:
    desc: |
      Recompile the backend dependency locks (requirements.txt +
      requirements-dev.txt) from src/backend/pyproject.toml — the single source of
      truth (NFR-009 §6.1). Run this after editing [project].dependencies or the
      dev extra, then commit the regenerated locks. Uses the exact same flags AND
      the exact same pinned pip-tools version (7.5.3) as the CI lock-staleness
      gate, so a fresh run leaves no diff. Requires that pinned pip-tools on a
      Python 3.14 interpreter: `pip install 'pip-tools==7.5.3'`.
    dir: src/backend
    cmds:
      - pip-compile --generate-hashes --output-file=requirements.txt --strip-extras pyproject.toml
      - pip-compile --generate-hashes --extra=dev --output-file=requirements-dev.txt --strip-extras pyproject.toml

  # ── Shared libs ─────────────────────────────────────────────

  vectordb:sync:
    desc: Sync the shared kp_vectordb infra (connection/schema/config) into both services
    cmds:
      - python src/libs/kp_vectordb/sync.py

  vectordb:check:
    desc: Verify the kp_vectordb service copies are in sync (CI guard, non-zero exit on drift)
    cmds:
      - python src/libs/kp_vectordb/sync.py --check

  test:kp-vectordb:
    desc: Run the shared kp_vectordb package test suite
    dir: src/libs/kp_vectordb
    cmds:
      - python -m pytest {{.CLI_ARGS}}

  # ── Frontend ────────────────────────────────────────────────

  lint:frontend:
    desc: Run ESLint on frontend code
    dir: src/frontend
    cmds:
      - npx eslint src/

  typecheck:
    desc: Run TypeScript type check (no emit)
    dir: src/frontend
    cmds:
      - npx tsc --noEmit

  test:frontend:
    desc: Run frontend vitest suite
    dir: src/frontend
    cmds:
      - npx vitest run {{.CLI_ARGS}}

  # ── E2E Tests ───────────────────────────────────────────────

  test:e2e:
    desc: Run Selenium E2E tests
    cmds:
      - ./scripts/run-e2e.sh {{.CLI_ARGS}}

  test:e2e:smoke:
    desc: Run Selenium E2E smoke tests (core functionality, ~2min)
    cmds:
      - ./scripts/run-e2e.sh --smoke {{.CLI_ARGS}}

  # ── Documentation ───────────────────────────────────────────

  docs:catalog:
    desc: Regenerate the Claude skill & agent catalog pages (docs/<locale>/skills/, agents/, tags.md)
    cmds:
      - python scripts/docs/gen_catalog.py

  docs:fact-tables:
    desc: Regenerate the fact-table snippets (docs/_generated/) from backend code & seed data
    cmds:
      - python scripts/docs/gen_fact_tables.py

  docs:venv:
    desc: |
      Create the isolated MkDocs venv (.venv-docs) and install docs/requirements.txt.
      Idempotent. The system Pythons cannot run MkDocs here (PEP-668 / mixed
      user-site packages), so docs:serve/build run from this venv. Override the
      base interpreter with DOCS_PYTHON=<path> if `python3` is not usable.
    vars:
      DOCS_PYTHON: '{{.DOCS_PYTHON | default "python3"}}'
    cmds:
      - '{{.DOCS_PYTHON}} -m venv .venv-docs'
      - .venv-docs/bin/pip install -q --upgrade pip
      - .venv-docs/bin/pip install -q -r docs/requirements.txt
    status:
      - test -x .venv-docs/bin/mkdocs

  docs:serve:
    desc: |
      Serve MkDocs documentation locally (regenerates the Claude catalog and
      fact tables first). Runs on port DOCS_PORT (default 8001; 8000 is taken by
      the backend port-forward). Override with: task docs:serve DOCS_PORT=8123
    deps: [docs:catalog, docs:fact-tables, docs:venv]
    vars:
      DOCS_PORT: '{{.DOCS_PORT | default "8001"}}'
    cmds:
      - .venv-docs/bin/mkdocs serve --dev-addr 127.0.0.1:{{.DOCS_PORT}}

  docs:build:
    desc: Build MkDocs documentation (regenerates the Claude catalog & fact tables first)
    deps: [docs:catalog, docs:fact-tables, docs:venv]
    cmds:
      - .venv-docs/bin/mkdocs build

  # ── MCP Tooling (Claude Code) ───────────────────────────────
  # See docs/de/development/mcp-tools.md and spec/dev-tooling/MCP-SERVERS.md

  mcp:status:
    desc: Show status of all MCP-related prerequisites (Chrome debug port, kubectl, Playwright cache)
    silent: true
    cmds:
      - |
        echo "── node / npx (required by all MCP servers) ──"
        if command -v npx >/dev/null 2>&1; then
          echo "  ✓ npx: $(npx --version) (node: $(node --version))"
        else
          echo "  ✗ npx not found — install Node.js (asdf install nodejs 25.9.0 or apt install nodejs npm)"
        fi
        echo "── chrome-devtools-mcp ──"
        if curl -sf --max-time 1 http://localhost:9222/json/version >/dev/null 2>&1; then
          BROWSER=$(curl -s http://localhost:9222/json/version | python3 -c "import sys,json;print(json.load(sys.stdin).get('Browser','?'))")
          echo "  ✓ Chrome listening on :9222 ($BROWSER)"
        else
          echo "  ✗ Chrome not running on :9222 — run 'task mcp:chrome'"
        fi
        echo "── kubernetes-mcp-server ──"
        if ctx=$(kubectl config current-context 2>/dev/null); then
          echo "  ✓ kubectl context: $ctx"
          if kubectl get ns default >/dev/null 2>&1; then
            echo "  ✓ cluster reachable"
          else
            echo "  ⚠ cluster context set but unreachable"
          fi
        else
          echo "  ✗ no kubectl context — run 'task setup'"
        fi
        echo "── playwright ──"
        if [ -d "$HOME/.cache/ms-playwright" ] && ls "$HOME/.cache/ms-playwright"/chromium-* >/dev/null 2>&1; then
          echo "  ✓ Chromium binary cached"
        else
          echo "  ⚠ Chromium not cached — downloads on first use (~200MB) or run 'task mcp:setup'"
        fi
        echo "── context7 ──"
        if curl -sf --max-time 2 https://context7.com >/dev/null 2>&1; then
          echo "  ✓ context7.com reachable"
        else
          echo "  ⚠ context7.com unreachable — check internet connection"
        fi

  mcp:chrome:
    desc: Start Chrome with remote debugging port :9222 in isolated profile (for chrome-devtools-mcp)
    silent: true
    vars:
      MCP_CHROME_URL: '{{.MCP_CHROME_URL | default "http://localhost:5173"}}'
      MCP_CHROME_PROFILE: '{{.MCP_CHROME_PROFILE | default "/tmp/chrome-debug"}}'
    cmds:
      - |
        if curl -sf --max-time 1 http://localhost:9222/json/version >/dev/null 2>&1; then
          echo "✓ Chrome already listening on :9222"
          exit 0
        fi
        if command -v google-chrome >/dev/null; then BROWSER=google-chrome
        elif command -v chromium >/dev/null; then BROWSER=chromium
        elif command -v chromium-browser >/dev/null; then BROWSER=chromium-browser
        elif [ -x "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" ]; then
          BROWSER="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
        else
          echo "✗ No Chrome/Chromium found in PATH" >&2
          echo "  Install Chrome or set BROWSER manually" >&2
          exit 1
        fi
        mkdir -p "{{.MCP_CHROME_PROFILE}}"
        nohup "$BROWSER" \
          --remote-debugging-port=9222 \
          --user-data-dir="{{.MCP_CHROME_PROFILE}}" \
          --no-first-run \
          --no-default-browser-check \
          "{{.MCP_CHROME_URL}}" \
          >"{{.MCP_CHROME_PROFILE}}/chrome.log" 2>&1 &
        CHROME_PID=$!
        echo "Started Chrome (pid $CHROME_PID), waiting for :9222 …"
        for i in 1 2 3 4 5 6 7 8 9 10; do
          if curl -sf --max-time 1 http://localhost:9222/json/version >/dev/null 2>&1; then
            echo "✓ Chrome ready at http://localhost:9222"
            echo "  → opened {{.MCP_CHROME_URL}}"
            echo "  → profile: {{.MCP_CHROME_PROFILE}}"
            echo "  → stop with: task mcp:chrome:stop"
            exit 0
          fi
          sleep 1
        done
        echo "✗ Chrome did not become reachable within 10s" >&2
        echo "  Check log: {{.MCP_CHROME_PROFILE}}/chrome.log" >&2
        exit 1

  mcp:chrome:stop:
    desc: Stop the debug Chrome instance running on :9222
    silent: true
    cmds:
      - |
        if ! curl -sf --max-time 1 http://localhost:9222/json/version >/dev/null 2>&1; then
          echo "Chrome not running on :9222"
          exit 0
        fi
        pkill -f "remote-debugging-port=9222" 2>/dev/null || true
        sleep 1
        if curl -sf --max-time 1 http://localhost:9222/json/version >/dev/null 2>&1; then
          echo "⚠ Chrome still responding — try 'pkill -9 -f remote-debugging-port=9222'" >&2
          exit 1
        fi
        echo "✓ Stopped debug Chrome"

  mcp:setup:
    desc: One-time MCP setup — pre-fetch Playwright Chromium and warm npx caches
    silent: true
    cmds:
      - |
        if ! command -v npx >/dev/null 2>&1; then
          echo "✗ npx not found in PATH" >&2
          echo >&2
          echo "  All MCP servers (chrome-devtools, playwright, context7, kubernetes)" >&2
          echo "  are launched via 'npx' and require Node.js." >&2
          echo >&2
          echo "  Install via asdf (matches ~/.tool-versions):" >&2
          echo "    asdf plugin add nodejs" >&2
          echo "    asdf install nodejs 25.9.0" >&2
          echo >&2
          echo "  Or system package:" >&2
          echo "    sudo apt install nodejs npm" >&2
          exit 1
        fi
        echo "── Pre-fetching Playwright Chromium (~200MB) ──"
        npx -y playwright install chromium
        echo
        echo "── Warming npx caches for MCP servers ──"
        echo "  · chrome-devtools-mcp"
        npx -y chrome-devtools-mcp@latest --help >/dev/null 2>&1 || true
        echo "  · @playwright/mcp"
        npx -y @playwright/mcp@latest --help >/dev/null 2>&1 || true
        echo "  · @upstash/context7-mcp"
        npx -y @upstash/context7-mcp@latest --help >/dev/null 2>&1 || true
        echo "  · kubernetes-mcp-server"
        npx -y kubernetes-mcp-server@latest --help >/dev/null 2>&1 || true
        echo
        task mcp:status

  mcp:e2e:debug:
    desc: Start docker-compose.e2e.yml frontend with published port :8080 for live MCP debugging
    cmds:
      - |
        echo "Frontend will be available at http://localhost:8080"
        echo "Selenium tests in the same network are unaffected."
        echo "Stop with Ctrl+C — no changes are written to docker-compose.e2e.yml."
        echo
        docker compose -f docker-compose.e2e.yml \
          run --rm --service-ports --publish 8080:80 frontend

  # ── Claude Code (portfolio plugin adoption) ─────────────────
  # kamerplanter consumes the nolte-shared + nolte-engineering portfolio plugins
  # from a local checkout of claude-shared via --plugin-dir (mirrors
  # claude-shared's own `task plugin:reload`). See CLAUDE.md §"Claude Code
  # plugin adoption". Only domain-specialised assets (plant/HA/agrobiology/RAG)
  # stay in .claude/; generic delivery capabilities come from the plugins.

  claude:
    desc: |
      Start Claude Code with the nolte-shared + nolte-engineering portfolio
      plugins loaded from the local claude-shared checkout. Override the checkout
      location with NOLTE_CLAUDE_SHARED (default ~/repos/github/claude-shared).
      Forwards extra args, e.g.: task claude -- --resume
    silent: true
    cmds:
      - |
        CLAUDE_SHARED="${NOLTE_CLAUDE_SHARED:-$HOME/repos/github/claude-shared}"
        if [ ! -d "$CLAUDE_SHARED/plugins/nolte-engineering" ]; then
          echo "✗ claude-shared checkout not found at: $CLAUDE_SHARED" >&2
          echo "  Clone nolte/claude-shared there, or set NOLTE_CLAUDE_SHARED to its path." >&2
          exit 1
        fi
        exec claude \
          --plugin-dir "$CLAUDE_SHARED" \
          --plugin-dir "$CLAUDE_SHARED/plugins/nolte-engineering" \
          {{.CLI_ARGS}}

  # ── Crash recovery & parallel working copies (merged from Taskfile.yml) ──

  resume:
    desc: |
      List resumable Claude Code sessions for THIS working copy (newest first,
      with their opening prompt) and print the exact `claude --resume` command.
      Use after a notebook crash, terminal close, or session expiry to get back
      to an interrupted run — covers all top-level work in this directory.
      Subagent and Workflow runs are NOT --resume-able; see CLAUDE.md
      §"Crash recovery".
    cmds:
      - python3 scripts/resume_sessions.py
    silent: true

  worktree:root:
    desc: |
      Print the resolved worktree root for this machine. Reads
      NOLTE_WORKTREE_ROOT (the per-machine, freely chosen path) and falls back
      to ~/repos/.worktrees.
    cmds:
      - 'echo "${NOLTE_WORKTREE_ROOT:-$HOME/repos/.worktrees}"'
    silent: true

  worktree:add:
    desc: |
      Create a parallel working copy under the configurable worktree root,
      always in the same predictable place:
      ${NOLTE_WORKTREE_ROOT:-~/repos/.worktrees}/<repo>/<slug>/, branched off
      origin/develop. This is the supported alternative to harness worktrees
      nested under .claude/worktrees/ (which the guard-nested-worktree hook
      rejects, because sessions run from there are not --resume-able).

      Usage: task worktree:add -- <branch> [slug]
        task worktree:add -- feat/parser-fix
        task worktree:add -- chore/ci-tidy ci
    cmds:
      - ./scripts/worktree_add.sh {{.CLI_ARGS}}