7fa52772b3
* docs/building.md — how to build jj-commitd and planctl from source, requirements, `go install` recipes, reproducible-build flags (`-trimpath -ldflags="-buildid="` per planctl PRD R7.3), test + benchmark commands, cross-compile, CI matrix link. * docs/planctl.md — full command reference beyond --help: plan-dir discovery cases A-D, all 9 classification codes with severity and meaning, tag-grammar spec (including paren-aware annotations + the tag-unclosed recovery semantics), the five EARS regexes and the bold-prefix exemption, JSON schema, worked examples for pre-commit / CI / multi-plan / JSON consumers. * docs/jj-commitd.md — architecture diagram, socket event protocol (session-start, post-edit, session-end, shutdown, status) with field tables, all env vars (REPO_ROOT, JJ_HOOK_DEBOUNCE_SEC, JJ_HOOK_STALE_MIN, JJ_HOOK_AUTO_SQUASH), baked-in timing constants, socket / log paths, fallback mode, troubleshooting. * README.md — expanded the jj-commitd bullets and linked to each reference from a new "Documentation" section; kept top-level summaries terse.
118 lines
4.1 KiB
Markdown
118 lines
4.1 KiB
Markdown
# Building from source
|
|
|
|
This repo ships two Go binaries under `cmd/`:
|
|
|
|
| Binary | Purpose | Path |
|
|
|--------------|-----------------------------------------------------------------|-------------------------|
|
|
| `jj-commitd` | Debounced commit daemon for Claude Code sessions (optional). | `cmd/jj-commitd/` |
|
|
| `planctl` | Lint tool for spec-driven plan directories. | `cmd/planctl/` |
|
|
|
|
Both are pure-Go, standard-module-layout, and require no system libraries at runtime. `jj-commitd` shells out to the `jj` CLI; `planctl` has no runtime dependencies beyond the Go standard library and the one compiled-in `github.com/yuin/goldmark` module.
|
|
|
|
## Requirements
|
|
|
|
- **Go 1.22 or newer** on `PATH`. The repo's `go.mod` pins a higher toolchain (`go 1.26.1`) for development, but both binaries compile on 1.22 per PRD R7.1 and the CI matrix in `.forgejo/workflows/planctl.yml`.
|
|
- **`jj`** — only needed at *runtime* for `jj-commitd`. Not a build dependency.
|
|
- No other tools needed for a vanilla build.
|
|
|
|
## Installing with `go install` (recommended)
|
|
|
|
Places the binary at `$GOBIN` (falls back to `$GOPATH/bin`, defaulting to `~/go/bin/`). Make sure that directory is on your `PATH`.
|
|
|
|
```bash
|
|
# From anywhere:
|
|
go install forgejo.zerova.net/sid/template-jj/cmd/planctl@latest
|
|
go install forgejo.zerova.net/sid/template-jj/cmd/jj-commitd@latest
|
|
|
|
# Pin a specific tag or commit:
|
|
go install forgejo.zerova.net/sid/template-jj/cmd/planctl@v1.0.0
|
|
go install forgejo.zerova.net/sid/template-jj/cmd/planctl@<commit-sha>
|
|
```
|
|
|
|
Both binaries are tagged in lockstep with the repo.
|
|
|
|
## Building from a checkout
|
|
|
|
```bash
|
|
git clone https://forgejo.zerova.net/sid/template-jj.git
|
|
cd template-jj
|
|
|
|
# Binaries to ./bin/
|
|
go build -o bin/planctl ./cmd/planctl/
|
|
go build -o bin/jj-commitd ./cmd/jj-commitd/
|
|
```
|
|
|
|
`go build` without `-o` emits the binary into the current directory using the package directory name — useful for one-off checks:
|
|
|
|
```bash
|
|
cd cmd/planctl && go build && ./planctl --version
|
|
```
|
|
|
|
## Reproducible builds
|
|
|
|
Per PRD R7.3 for `planctl` — `go build -trimpath -ldflags="-buildid="` produces byte-stable binaries given the same source.
|
|
|
|
```bash
|
|
go build -trimpath -ldflags="-buildid=" -o bin/planctl ./cmd/planctl/
|
|
```
|
|
|
|
`-trimpath` strips the absolute checkout path from the binary; `-buildid=` zeroes the per-build Go toolchain fingerprint. The output is suitable for deterministic distribution and CI caching.
|
|
|
|
## Verifying the build
|
|
|
|
```bash
|
|
./bin/planctl --version
|
|
# planctl 0.1.0-dev
|
|
|
|
./bin/jj-commitd status # over an existing socket — see docs/jj-commitd.md
|
|
```
|
|
|
|
Run the test suite:
|
|
|
|
```bash
|
|
go test ./cmd/planctl/...
|
|
go test ./cmd/jj-commitd/...
|
|
```
|
|
|
|
`planctl` also has a benchmark:
|
|
|
|
```bash
|
|
go test -bench=. -benchtime=3x -run=^$ ./cmd/planctl/
|
|
```
|
|
|
|
Expected output on a 2023-era machine: ~1 ms per `Benchmark_Lint_BigPlan` invocation (the ~90 KB `testdata/perf/big-plan` fixture), well under the PRD success metric M3 ceiling of 100 ms.
|
|
|
|
## CI matrix
|
|
|
|
`planctl` is exercised in `.forgejo/workflows/planctl.yml` across:
|
|
|
|
- `os`: `ubuntu-latest`, `macos-latest`, `windows-latest`
|
|
- `go`: `1.22`, `stable`
|
|
|
|
A dedicated benchmark job runs once per push on `ubuntu-latest` + `stable`. `jj-commitd` has no CI cell yet — it's covered by its own package tests and integration in practice.
|
|
|
|
## Binary sizes
|
|
|
|
On `darwin/arm64` with Go 1.26.1, stripped with `-ldflags="-s -w"`:
|
|
|
|
- `planctl`: ~5 MB (includes goldmark).
|
|
- `jj-commitd`: ~3 MB (stdlib only).
|
|
|
|
Both well under any practical size budget.
|
|
|
|
## Cross-compiling
|
|
|
|
Standard Go cross-compile:
|
|
|
|
```bash
|
|
GOOS=linux GOARCH=amd64 go build -o bin/planctl-linux-amd64 ./cmd/planctl/
|
|
GOOS=windows GOARCH=amd64 go build -o bin/planctl.exe ./cmd/planctl/
|
|
```
|
|
|
|
No cgo dependencies; cross-builds work on any platform with the Go toolchain.
|
|
|
|
## See also
|
|
|
|
- [`docs/planctl.md`](planctl.md) — `planctl` command reference.
|
|
- [`docs/jj-commitd.md`](jj-commitd.md) — `jj-commitd` command reference.
|
|
- [`INTEGRATION.md`](../INTEGRATION.md) — integrating this template into an existing or new project.
|