1<!--
 2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
 3
 4SPDX-License-Identifier: CC0-1.0
 5-->
 6
 7# Build & Development
 8
 9This 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.
10
11## Build Commands
12
13All commands use `just` task runner:
14
15- **Development workflow**: `just` (runs fmt, lint, staticcheck, test, vuln, reuse)
16- **Format code**: `just fmt` (uses gofumpt)
17- **Lint**: `just lint` (uses golangci-lint)
18- **Static analysis**: `just staticcheck` (uses staticcheck)
19- **Test**: `just test` (runs all tests with verbose output)
20- **Single test**: `go test -v ./path/to/package -run TestName`
21- **Vulnerability check**: `just vuln` (uses govulncheck)
22- **License compliance**: `just reuse` (REUSE specification)
23- **Build**: `just build` (outputs to `./lunatask-mcp-server`, supports GOOS/GOARCH env vars)
24- **Run**: `just run` (builds and runs with version injection)
25- **Compress binary**: `just pack` (requires upx, run after build)
26- **Clean**: `just clean` (removes binary) or `just clean-all` (removes binary and config)
27
28Version is injected at build time via git describe, so always use `just build` or `just run` rather than plain `go build`.
29
30## Version Injection
31
32The `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`.
33
34## Testing Considerations
35
36- Tests should use `go test -v ./...` to run all packages
37- Mock the HTTP client in lunatask package tests (set `Client.HTTPClient` to custom `*http.Client`)
38- Mock Provider interfaces in tools package tests
39- Timezone-dependent tests should explicitly set timezone in config
40- Natural language date parsing is non-deterministic (relative to "now"), so test with absolute dates or mock time
41
42## Related Documentation
43
44The README.md contains extensive documentation about:
45- MCP tool descriptions and parameters (authoritative reference for tool behavior)
46- Example LLM system prompts showing real-world usage patterns
47- User-specific workflow rules (area workflows, estimate requirements, status defaults)
48- Contribution workflow using pr.pico.sh (SSH-based patches, no GitHub account needed)
49
50When modifying tools, ensure MCP descriptions in `cmd/lunatask-mcp-server.go` stay synchronized with actual behavior.