Taskfile.yml

# https://taskfile.dev
version: "3"
vars:
  BINARY_NAME: specgraph
  MAIN_PKG: ./cmd/specgraph
tasks:
  default:
    desc: Show available tasks
    cmds:
      - task --list
  # Development
  dev:
    desc: Build and run specgraph server in development mode
    deps: [build]
    cmds:
      - ./{{.BINARY_NAME}} serve
  dev:stop:
    desc: Stop the SpecGraph server (launchd service + Docker containers)
    cmds:
      - |
        # Stop launchd service if installed
        launchctl bootout gui/$(id -u)/com.specgraph.server 2>/dev/null || true
        # Stop Docker containers from specgraph serve/up
        docker compose -f "${XDG_DATA_HOME:-$HOME/.local/share}/specgraph/docker-compose.yaml" down 2>/dev/null || true
  dev:reset:
    desc: Stop server, drop data volumes, remove stale compose file, rebuild
    cmds:
      - task: dev:stop
      - docker compose -f "${XDG_DATA_HOME:-$HOME/.local/share}/specgraph/docker-compose.yaml" down -v 2>/dev/null || true
      - rm -f "${XDG_DATA_HOME:-$HOME/.local/share}/specgraph/docker-compose.yaml"
      - task: clean
      - task: build
  # Code Generation
  generate:
    desc: Generate all code (protobuf)
    deps: [proto]
  proto:
    desc: Generate Go code from protobuf definitions
    sources:
      - proto/**/*.proto
      - buf.yaml
      - buf.gen.yaml
    generates:
      - gen/**/*.go
    cmds:
      - buf generate
  proto:check:
    desc: Verify generated proto code is up to date (side-effect-free)
    cmds:
      - |
        tmpdir=$(mktemp -d)
        trap 'rm -rf "$tmpdir"' EXIT
        buf generate -o "$tmpdir"
        diff -rq gen/ "$tmpdir/gen" > /dev/null 2>&1
  # Building
  web:dev:
    desc: Start SvelteKit dev server (proxies API to :8080)
    dir: web
    cmds:
      - pnpm dev
  web:build:
    desc: Build SvelteKit for production (output to web/build/)
    dir: web
    sources:
      - web/src/**/*
      - web/svelte.config.js
      - web/vite.config.ts
      - web/package.json
    generates:
      - web/build/**/*
    cmds:
      - pnpm install
      - pnpm build
  build:
    desc: Build the specgraph binary
    deps: [generate, 'web:build']
    cmds:
      - go build -o {{.BINARY_NAME}} {{.MAIN_PKG}}
  build:all:
    desc: Build for all platforms
    deps: [generate, 'web:build']
    cmds:
      - task: build:linux
      - task: build:darwin
  build:linux:
    desc: Build for Linux
    deps: [generate, 'web:build']
    cmds:
      - GOOS=linux GOARCH=amd64 go build -o dist/{{.BINARY_NAME}}-linux-amd64 {{.MAIN_PKG}}
      - GOOS=linux GOARCH=arm64 go build -o dist/{{.BINARY_NAME}}-linux-arm64 {{.MAIN_PKG}}
  build:darwin:
    desc: Build for macOS
    deps: [generate, 'web:build']
    cmds:
      - GOOS=darwin GOARCH=amd64 go build -o dist/{{.BINARY_NAME}}-darwin-amd64 {{.MAIN_PKG}}
      - GOOS=darwin GOARCH=arm64 go build -o dist/{{.BINARY_NAME}}-darwin-arm64 {{.MAIN_PKG}}
  # Testing
  test:
    desc: Run all tests
    deps: [generate]
    cmds:
      - go test -race -v ./...
  test:coverage:
    desc: Run tests with coverage
    deps: [generate]
    cmds:
      - go test -race -coverprofile=coverage.out -covermode=atomic ./...
      - go tool cover -html=coverage.out -o coverage.html
  test:short:
    desc: Run short tests only
    deps: [generate]
    cmds:
      - go test -short -v ./...
  test:integration:
    desc: Run integration tests (requires Docker for Memgraph)
    deps: [generate]
    cmds:
      - go test -tags integration -race -v -p 1 ./...
  test:e2e:
    desc: Run all E2E tests (requires Docker)
    cmds:
      - task: test:e2e:api
      - task: test:e2e:cli
      - task: test:e2e:docker
      - task: test:e2e:ui
  test:e2e:ui:
    desc: Run Playwright UI E2E tests (all in Docker, no host ports needed)
    cmds:
      - |
        compose="$(realpath e2e/ui/docker-compose.e2e.yaml)"
        docker compose -f "$compose" up --build --abort-on-container-exit --exit-code-from playwright
        rc=$?
        docker compose -f "$compose" down -v
        exit $rc
  test:e2e:ui:clean:
    desc: Clean up UI E2E Docker resources
    cmds:
      - docker compose -f e2e/ui/docker-compose.e2e.yaml down -v --rmi local
  test:e2e:api:
    desc: Run API E2E tests (requires Docker for Memgraph)
    deps: [generate]
    cmds:
      - go test -tags e2e -v -timeout 5m ./e2e/api/...
  test:e2e:cli:
    desc: Run CLI E2E tests (requires Docker)
    deps: [build]
    cmds:
      - go test -tags e2e_cli -v -count=1 -timeout 300s ./e2e/cli/
  test:e2e:agent:
    desc: Run Agent E2E tests (requires Docker + ANTHROPIC_API_KEY)
    deps: [build]
    cmds:
      - go test -tags e2e_agent -v -count=1 -timeout 600s ./e2e/agent/
  test:e2e:docker:
    desc: Run Docker mode E2E tests (requires Docker)
    deps: [build]
    cmds:
      - go test -tags e2e -v -timeout 5m ./e2e/docker/...
  # Linting
  lint:
    desc: Run all linters
    cmds:
      - task: lint:go
      - task: lint:markdown
      - task: lint:yaml
      - task: lint:constitution-callers
  lint:go:
    desc: Lint Go code
    deps: [generate, 'web:build']
    cmds:
      - golangci-lint run
  lint:markdown:
    desc: Lint Markdown files
    cmds:
      - rumdl check .
  lint:yaml:
    desc: Lint YAML files
    cmds:
      - yamlfmt -lint .
  lint:constitution-callers:
    desc: Guard against reintroducing the deprecated Store.GetConstitution method (spgr-8ar piece D)
    cmds:
      - |
        # Fails the build if anyone reintroduces the storage-layer
        # GetConstitution method that piece D removed. Detects the
        # method declaration's unique signature on a *Store or any
        # ConstitutionBackend implementer:
        #   func (<recv>) GetConstitution(<ctx>) (*storage.Constitution|*Constitution, error)
        #
        # If the method declaration reappears, callers can compile
        # against it again and the silent-layer-dropping bug
        # piece A fixed is back. By blocking the declaration, we
        # transitively block the calls.
        #
        # The RPC handler's GetConstitution on *ConstitutionHandler
        # takes a connect.Request, so it doesn't match this regex. The
        # composer's GetConstitution returns *authoring.ConstitutionSummary,
        # so it doesn't match either. Only the deprecated storage form
        # is caught.
        if rg -nP 'func\s*\([^)]+\)\s*GetConstitution\s*\(\s*ctx[^)]*\)\s*\(\s*\*(?:storage\.)?Constitution\s*,\s*error\s*\)' --type go . 2>/dev/null; then
          echo "ERROR: Store.GetConstitution was removed in spgr-8ar piece D." >&2
          echo "Use GetMergedConstitution (merged + provenance) or GetConstitutionLayer (single layer)." >&2
          exit 1
        fi
  # License headers
  license:check:
    desc: Check SPDX license headers
    cmds:
      - |
        set -euo pipefail
        DIRS="cmd internal proto e2e"
        EXISTING_DIRS=""
        for dir in $DIRS; do
          [[ -d "$dir" ]] && EXISTING_DIRS="$EXISTING_DIRS $dir"
        done
        command -v addlicense >/dev/null 2>&1 || go install github.com/google/addlicense@latest
        addlicense -check -f LICENSE_HEADER -ignore '**/*.pb.go' -ignore 'vendor/**' -ignore 'e2e/ui/**' $EXISTING_DIRS
  license:add:
    desc: Add missing SPDX license headers
    cmds:
      - |
        set -euo pipefail
        DIRS="cmd internal proto e2e"
        EXISTING_DIRS=""
        for dir in $DIRS; do
          [[ -d "$dir" ]] && EXISTING_DIRS="$EXISTING_DIRS $dir"
        done
        command -v addlicense >/dev/null 2>&1 || go install github.com/google/addlicense@latest
        addlicense -f LICENSE_HEADER -ignore '**/*.pb.go' -ignore 'vendor/**' -ignore 'e2e/ui/**' $EXISTING_DIRS
  # Formatting
  fmt:
    desc: Format all files
    cmds:
      - task: fmt:go
      - task: fmt:yaml
      - task: fmt:markdown
      - task: fmt:dprint
  fmt:go:
    desc: Format Go code
    cmds:
      - gofumpt -w .
  fmt:yaml:
    desc: Format YAML files
    cmds:
      - yamlfmt .
  fmt:markdown:
    desc: Format Markdown files
    cmds:
      - rumdl fmt .
  fmt:dprint:
    desc: Format with dprint
    cmds:
      - dprint fmt
  fmt:check:
    desc: Check formatting without modifying
    cmds:
      - dprint check
  # Dependencies
  deps:
    desc: Download and tidy dependencies
    cmds:
      - go mod download
      - go mod tidy
  deps:upgrade:
    desc: Upgrade all dependencies
    cmds:
      - go get -u ./...
      - go mod tidy
  # Documentation
  docs:setup:
    desc: Set up documentation development environment
    dir: site
    cmds:
      - uv sync
  docs:build:
    desc: Build documentation site
    dir: site
    cmds:
      - uv run zensical build
  docs:serve:
    desc: Start documentation dev server
    dir: site
    cmds:
      - uv run zensical serve
  docs:cli:
    desc: Generate CLI reference documentation
    deps: [build]
    cmds:
      - ./{{.BINARY_NAME}} docs cli site/docs/cli-reference.md
  docs:cli:check:
    desc: Verify CLI reference is up to date
    deps: [build]
    vars:
      CLI_REF_TMP:
        sh: mktemp
    cmds:
      - ./{{.BINARY_NAME}} docs cli {{.CLI_REF_TMP}}
      - diff -u site/docs/cli-reference.md {{.CLI_REF_TMP}}
  # Git hooks
  hooks:install:
    desc: Install git hooks
    cmds:
      - lefthook install
      - bd hooks install --chain
  hooks:uninstall:
    desc: Uninstall git hooks
    cmds:
      - bd hooks uninstall
      - lefthook uninstall
  # Tools
  tools:
    desc: Install development tools
    cmds:
      - brew install golangci-lint gofumpt lefthook actionlint goreleaser dprint cocogitto rumdl yamlfmt buf
      - brew install steveyegge/beads/bd
      - echo "Tools installed. Run 'task hooks:install' to set up git hooks."
  # Skills (agentskills.io-shaped SKILL.md packages under skills/)
  skills:validate:
    desc: Validate skills/ packages against the agentskills.io minimal contract
    cmds:
      - go run ./internal/skillvalidate/cmd ./skills
  # Quality gates
  check:
    desc: Fast local quality gate (no Docker required)
    deps: [generate]
    cmds:
      - task: fmt:check
      - task: license:check
      - task: lint
      - task: skills:validate
      - task: build
      - go test -short -race ./...
  pr-prep:
    desc: Full pre-push quality gate (requires Docker)
    cmds:
      - task: clean
      - task: check
      - task: test:integration
      - task: test:e2e
  # Cleanup
  clean:
    desc: Clean build artifacts
    cmds:
      - rm -rf dist/
      - rm -f {{.BINARY_NAME}}
      - rm -f coverage.out coverage.html
      - rm -rf gen/
      - rm -rf web/node_modules web/build web/.svelte-kit
      - rm -rf e2e/ui/node_modules e2e/ui/test-results
  # Release
  release:check:
    desc: Validate goreleaser config
    cmds:
      - goreleaser check
  release:snapshot:
    desc: Build snapshot locally (no publish, local arch only)
    cmds:
      - goreleaser build --snapshot --clean --single-target