Build & Development.md

Build & Development

This document serves as the reference for all development workflow commands and testing practices. All build operations must use just commands rather than plain go build to ensure proper version injection.

Build Commands

All commands use just task runner:

  • Development workflow: just (runs fmt, lint, staticcheck, test, vuln, reuse)
  • Format code: just fmt (uses gofumpt)
  • Lint: just lint (uses golangci-lint)
  • Static analysis: just staticcheck (uses staticcheck)
  • Test: just test (runs all tests with verbose output)
  • Single test: go test -v ./path/to/package -run TestName
  • Vulnerability check: just vuln (uses govulncheck)
  • License compliance: just reuse (REUSE specification)
  • Build: just build (outputs to ./lunatask-mcp-server, supports GOOS/GOARCH env vars)
  • Run: just run (builds and runs with version injection)
  • Compress binary: just pack (requires upx, run after build)
  • Clean: just clean (removes binary) or just clean-all (removes binary and config)

Version is injected at build time via git describe, so always use just build or just run rather than plain go build.

Version Injection

The version variable in main is set via ldflags during build: -ldflags "-X main.version=...". The justfile extracts version from git describe --long. Don't hardcode version strings; if version is empty, it displays a helpful message about using just build.

Testing Considerations

  • Tests should use go test -v ./... to run all packages
  • Mock the HTTP client in lunatask package tests (set Client.HTTPClient to custom *http.Client)
  • Mock Provider interfaces in tools package tests
  • Timezone-dependent tests should explicitly set timezone in config
  • Natural language date parsing is non-deterministic (relative to "now"), so test with absolute dates or mock time

The README.md contains extensive documentation about:

  • MCP tool descriptions and parameters (authoritative reference for tool behavior)
  • Example LLM system prompts showing real-world usage patterns
  • User-specific workflow rules (area workflows, estimate requirements, status defaults)
  • Contribution workflow using pr.pico.sh (SSH-based patches, no GitHub account needed)

When modifying tools, ensure MCP descriptions in cmd/lunatask-mcp-server.go stay synchronized with actual behavior.