Taskfile.yml

# Copyright (c) 2019-2026 Truestamp, Inc.
# SPDX-License-Identifier: MIT
#
# https://taskfile.dev

version: "3"

vars:
  BINARY: truestamp
  MODULE: github.com/truestamp/truestamp-cli

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

  # =============================================================================
  # Build
  # =============================================================================

  build:
    desc: Build the CLI binary for the current platform
    vars:
      VERSION:
        # Derive from the nearest git tag. `--dirty` flags uncommitted
        # changes, `--always` falls back to a short SHA if no tag exists.
        # Leading `v` is stripped so local builds match GoReleaser's
        # {{.Version}} format.
        sh: git describe --tags --always --dirty 2>/dev/null | sed 's/^v//' | tr -d '[:space:]' || echo dev
      GIT_COMMIT:
        sh: git rev-parse --short HEAD 2>/dev/null || echo unknown
      BUILD_DATE:
        sh: date -u +%Y-%m-%dT%H:%M:%SZ
      BUILD_YEAR:
        sh: date -u +%Y
      LDFLAGS: -s -w -X {{.MODULE}}/internal/version.Version={{.VERSION}} -X {{.MODULE}}/internal/version.GitCommit={{.GIT_COMMIT}} -X {{.MODULE}}/internal/version.BuildDate={{.BUILD_DATE}} -X {{.MODULE}}/internal/version.BuildYear={{.BUILD_YEAR}}
    cmds:
      - mkdir -p build
      - go build -ldflags "{{.LDFLAGS}}" -o build/{{.BINARY}} ./cmd/truestamp
    sources:
      - "**/*.go"
      # go:embed pulls non-Go files into the binary at compile time
      # (e.g. internal/config/defaults/config.toml). Track them here
      # so editing one invalidates the cache and forces a rebuild.
      - "internal/config/defaults/*.toml"
      - go.mod
      - go.sum
    generates:
      - "build/{{.BINARY}}"

  build-all:
    desc: Cross-compile for all supported platforms
    deps:
      - build
    vars:
      VERSION:
        sh: git describe --tags --always --dirty 2>/dev/null | sed 's/^v//' | tr -d '[:space:]' || echo dev
      GIT_COMMIT:
        sh: git rev-parse --short HEAD 2>/dev/null || echo unknown
      BUILD_DATE:
        sh: date -u +%Y-%m-%dT%H:%M:%SZ
      BUILD_YEAR:
        sh: date -u +%Y
      LDFLAGS: -s -w -X {{.MODULE}}/internal/version.Version={{.VERSION}} -X {{.MODULE}}/internal/version.GitCommit={{.GIT_COMMIT}} -X {{.MODULE}}/internal/version.BuildDate={{.BUILD_DATE}} -X {{.MODULE}}/internal/version.BuildYear={{.BUILD_YEAR}}
    cmds:
      - mkdir -p build
      - GOOS=darwin GOARCH=arm64 go build -ldflags "{{.LDFLAGS}}" -o build/{{.BINARY}}-{{.VERSION}}-darwin-arm64 ./cmd/truestamp
      - GOOS=darwin GOARCH=amd64 go build -ldflags "{{.LDFLAGS}}" -o build/{{.BINARY}}-{{.VERSION}}-darwin-amd64 ./cmd/truestamp
      - GOOS=linux GOARCH=amd64 go build -ldflags "{{.LDFLAGS}}" -o build/{{.BINARY}}-{{.VERSION}}-linux-amd64 ./cmd/truestamp
      - GOOS=linux GOARCH=arm64 go build -ldflags "{{.LDFLAGS}}" -o build/{{.BINARY}}-{{.VERSION}}-linux-arm64 ./cmd/truestamp
      - GOOS=windows GOARCH=amd64 go build -ldflags "{{.LDFLAGS}}" -o build/{{.BINARY}}-{{.VERSION}}-windows-amd64.exe ./cmd/truestamp
      - GOOS=windows GOARCH=arm64 go build -ldflags "{{.LDFLAGS}}" -o build/{{.BINARY}}-{{.VERSION}}-windows-arm64.exe ./cmd/truestamp
      - echo "Built v{{.VERSION}} binaries in build/"

  # =============================================================================
  # Run
  # =============================================================================

  run:
    desc: "Run verify without building (usage: task run -- proof.json [--skip-external] [--skip-signatures] [--json])"
    cmds:
      - go run ./cmd/truestamp verify {{.CLI_ARGS}}

  upgrade-test-local:
    desc: "Build with a fake older version and exercise 'upgrade --check' against live GitHub releases"
    cmds:
      - |
        OLD_VERSION=0.0.1
        LDFLAGS="-X {{.MODULE}}/internal/version.Version=${OLD_VERSION}"
        mkdir -p build
        go build -ldflags "$LDFLAGS" -o build/truestamp-upgrade-test ./cmd/truestamp
        ./build/truestamp-upgrade-test upgrade --check || EXIT=$?
        echo "upgrade --check exit code: ${EXIT:-0}"
        if [ "${EXIT:-0}" != "1" ] && [ "${EXIT:-0}" != "0" ] && [ "${EXIT:-0}" != "3" ]; then
          echo "unexpected exit code"
          exit 1
        fi

  # =============================================================================
  # Docs preview (mirrors get.truestamp.com)
  # =============================================================================

  docs-serve:
    desc: "Serve docs/ locally with caddy (mirrors get.truestamp.com). Browse http://localhost:8080, test `curl http://localhost:8080/install.sh | sh` against the staged installer."
    cmds:
      - mise exec -- caddy file-server --listen :8080 --root docs

  # =============================================================================
  # Test & Quality
  # =============================================================================

  test:
    desc: Run all Go tests
    cmds:
      - go test ./...

  test-verbose:
    desc: Run all Go tests with verbose output
    cmds:
      - go test -v ./...

  test-chaos:
    desc: Run wschannel chaos tests under -race (no live server needed)
    cmds:
      - go test -tags=chaos -count=1 -race -timeout=120s ./internal/wschannel/...

  fuzz-codec:
    desc: Fuzz wschannel JSON codec and redactor (30s per target)
    cmds:
      - go test -run=^$ -fuzz=FuzzFrameUnmarshal -fuzztime=30s ./internal/wschannel/
      - go test -run=^$ -fuzz=FuzzParseReply -fuzztime=30s ./internal/wschannel/
      - go test -run=^$ -fuzz=FuzzRedactSecrets -fuzztime=30s ./internal/wschannel/

  test-coverage:
    desc: Run tests with coverage summary
    cmds:
      - go test -cover ./...

  test-coverage-report:
    desc: Generate HTML coverage report and open in browser
    cmds:
      - go test -coverprofile=coverage.out ./...
      - go tool cover -html=coverage.out -o coverage.html
      - open coverage.html
      - echo "Coverage report written to coverage.html"

  test-coverage-full:
    desc: "Accurate coverage including CLI integration tests' subprocess runs (Go 1.20+ instrumented binaries)"
    cmds:
      # Clean start. Two covdata sub-dirs: `bin` for the subprocess
      # binary's runtime data, `test` for go test's per-test-binary data.
      - rm -rf coverage && mkdir -p coverage/bin coverage/test coverage/merged
      # TRUESTAMP_COVERDIR is read by verify_test.go's TestMain to
      # (a) build the subprocess binary with -cover and (b) point its
      # GOCOVERDIR at coverage/bin. We don't use GOCOVERDIR directly
      # here because `go test -cover` overwrites GOCOVERDIR in the test
      # process's environment with its own temp dir.
      - TRUESTAMP_COVERDIR=$PWD/coverage/bin go test -cover -coverpkg=./... ./... -args -test.gocoverdir=$PWD/coverage/test >/dev/null
      # Merge the two covdata directories into a single textfmt profile.
      - go tool covdata merge -i=coverage/bin,coverage/test -o coverage/merged
      - go tool covdata textfmt -i=coverage/merged -o coverage.out
      - echo "--- per-function coverage (tail) ---"
      - go tool cover -func=coverage.out | tail -20
      - echo "--- per-package coverage ---"
      - |
        go tool cover -func=coverage.out | awk '
          /^total:/ { next }
          {
            split($1, a, ":")
            pkg = a[1]
            sub(/\/[^\/]+$/, "", pkg)
            pct = $NF
            gsub("%", "", pct)
            sum[pkg] += pct
            n[pkg]++
          }
          END {
            for (p in sum) printf "%-60s %6.2f%%\n", p, sum[p]/n[p]
          }
        ' | sort
      - echo "--- total ---"
      - 'go tool cover -func=coverage.out | grep ^total:'
      - go tool cover -html=coverage.out -o coverage.html
      - echo "HTML report written to coverage.html"

  vet:
    desc: Run go vet static analysis
    cmds:
      - go vet ./...

  lint:
    desc: "All quality checks: vet + fmt-check + staticcheck + gosec. staticcheck and gosec are pinned in .tool-versions and installed by `mise install`."
    deps: [vet, fmt-check]
    cmds:
      - staticcheck ./...
      # gosec exclusions, justified:
      #   G104: unhandled lipgloss.Println / fmt.Fprintf to stdout — errors there
      #         are not actionable in a CLI.
      #   G115: wire-format integer conversions where source values are bounded
      #         by protocol constants (proof version byte, epoch-root counts).
      #   G304: reading user-specified file paths IS the point of a CLI.
      #   G301/G302/G306: 0644/0755 are the correct Unix defaults for config
      #         files and user-installed binaries.
      #   G401/G501/G505: MD5 and SHA-1 are supported as legacy hash_type
      #         values (mirrors the Truestamp backend registry); runtime
      #         emits a stderr warning when either is used.
      #   G204: subprocess invocations (xattr, cosign) use hard-coded binary
      #         names resolved via PATH LookPath — no user-controlled command.
      #   G704: URL-from-variable used only for known upstream services
      #         (Horizon, Blockstream, keyring); not user-controlled.
      - gosec -quiet -exclude-dir=testdata -exclude=G104,G115,G301,G302,G306,G304,G401,G501,G505,G204,G704 ./...

  vuln-check:
    desc: "Scan go.mod deps for known vulnerabilities. govulncheck is pinned in .tool-versions and installed by `mise install`."
    cmds:
      - govulncheck ./...

  test-race:
    desc: "Run all tests under the race detector (~2-20x slower; catches concurrent unsynchronized memory access)"
    cmds:
      - go test -race ./...

  bench:
    desc: "Run all benchmarks (BenchmarkXxx) with -benchmem for alloc accounting"
    cmds:
      - go test -run=^$ -bench=. -benchmem ./...

  bench-compare:
    desc: "Capture a baseline benchmark profile. Usage: task bench-compare -- baseline.txt (then later: go test -bench=. ... > new.txt && benchstat baseline.txt new.txt)"
    cmds:
      - |
        out="${1:-{{.CLI_ARGS | default "bench.out"}}}"
        go test -run=^$ -bench=. -benchmem -count=5 ./... | tee "$out"
        echo "Baseline written to $out. Compare later with: benchstat $out new.out"

  fuzz:
    desc: "Smoke-run every FuzzXxx with its seed corpus (no mutation, ~seconds)"
    cmds:
      - go test -run=^Fuzz ./...

  fuzz-deep:
    desc: "Actively fuzz every FuzzXxx for DURATION (default 15s) each. Use for manual hardening; very chatty. Failing targets are retried once to absorb the Go fuzz engine's known shutdown-boundary flake where an in-flight input reports 'context deadline exceeded' when fuzztime expires. A real bug writes a reproducer under the owning package's testdata/fuzz/FuzzXxx/ directory and reproduces on replay instantly. IMPORTANT: any files written under */testdata/fuzz/* must be committed — they are the permanent corpus that `task test` replays as regression tests. Run `find . -path '*/testdata/fuzz/*' -type f` after this task to list new reproducers, and `git add` (or `jj file track`) them before you commit."
    vars:
      DURATION: '{{.DURATION | default "15s"}}'
    cmds:
      - |
        set -e
        failed=0
        for pkg in $(go list ./...); do
          tests=$(go test -list='^Fuzz' "$pkg" 2>/dev/null | grep '^Fuzz' || true)
          for t in $tests; do
            echo "==> $pkg :: $t ({{.DURATION}})"
            if ! go test -run=^$ -fuzz="^${t}$" -fuzztime={{.DURATION}} "$pkg"; then
              echo "==> $pkg :: $t — first attempt failed; retrying once to rule out fuzz-engine shutdown flake"
              if ! go test -run=^$ -fuzz="^${t}$" -fuzztime={{.DURATION}} "$pkg"; then
                failed=$((failed+1))
              fi
            fi
          done
        done
        if [ $failed -gt 0 ]; then
          echo "FAILED: $failed fuzz target(s) discovered issues; see testdata/fuzz/ for reproducers"
          exit 1
        fi

  fuzz-list:
    desc: "List every FuzzXxx target across the repo"
    cmds:
      - |
        for pkg in $(go list ./...); do
          tests=$(go test -list='^Fuzz' "$pkg" 2>/dev/null | grep '^Fuzz' || true)
          if [ -n "$tests" ]; then
            echo "$pkg"
            echo "$tests" | sed 's/^/  /'
          fi
        done

  fmt:
    desc: Format all Go source files
    cmds:
      - gofmt -w .

  fmt-check:
    desc: Check formatting without modifying files
    cmds:
      - test -z "$(gofmt -l .)" || (echo "Files need formatting:" && gofmt -l . && exit 1)

  precommit:
    desc: "Fast pre-commit checks (fmt + lint + test + build). Target <10s on a hot cache. Note: 'task test' already replays every FuzzXxx seed corpus as part of the regular test suite, so no separate fuzz step is needed here."
    cmds:
      - task: fmt
      - task: lint
      - task: test
      - task: build

  precommit-full:
    desc: "Strict pre-release bundle: precommit + race detector + active mutation fuzzing + vuln scan + all-platform build. Takes ~3-5 min."
    cmds:
      - task: fmt
      - task: lint
      - task: test-race
      - task: fuzz
      - task: vuln-check
      - task: build-all

  # =============================================================================
  # Release (GoReleaser)
  # =============================================================================

  release-check:
    desc: Validate .goreleaser.yaml syntax and configuration
    cmds:
      - mise exec -- goreleaser check

  release-snapshot:
    desc: "Local snapshot release into dist/ — skips cosign signing (keyless requires the CI OIDC token) and GitHub publishing, so this runs fully offline and is safe for pre-release inspection."
    cmds:
      - mise exec -- goreleaser release --snapshot --clean --skip=sign,publish
      - 'echo "✅ Snapshot artifacts in dist/"'

  # =============================================================================
  # Dependencies
  # =============================================================================

  deps:
    desc: Download and tidy module dependencies
    cmds:
      - go mod tidy
      - go mod download

  deps-update:
    desc: Update all dependencies to latest versions
    cmds:
      - go get -u ./...
      - go mod tidy

  # =============================================================================
  # Cleanup
  # =============================================================================

  clean:
    desc: Remove build directory and artifacts
    cmds:
      - rm -rf build/
      - echo "Cleaned build artifacts"