diff --git a/.agents/skills/archie-build-and-env/SKILL.md b/.agents/skills/archie-build-and-env/SKILL.md index 3ccb07b2c..aa39f71d8 100644 --- a/.agents/skills/archie-build-and-env/SKILL.md +++ b/.agents/skills/archie-build-and-env/SKILL.md @@ -35,7 +35,7 @@ task --list ```bash go version go env GOTOOLCHAIN GOVERSION GOOS GOARCH CGO_ENABLED GOTMPDIR GOCACHE GOMODCACHE -task --version; gofumpt -version; golangci-lint version +task --version; golangci-lint version; gofumpt -version node --version; npm --version # UI only; docs need no Node toolchain docker --version; docker compose version git --version; gpg --version @@ -45,32 +45,23 @@ Classify a missing command as an environment prerequisite. Bootstrap (verified 2026-09-19): Go ≥ 1.27.0, Task ≥ 3.x, gofumpt v0.11.0, golangci-lint 2.13.2, Node 24.x for the `ui/` frontend. -`gofumpt` and `golangci-lint` are one pair, not two independent tools. -`task fmt` formats with the standalone gofumpt; `task lint` re-checks that -formatting with the gofumpt golangci-lint vendors, and `task check` runs -`fmt` then `lint` without diffing the tree, so `lint` is the only hard -failure for formatting. Install the pair from `Dockerfile` -(`GOLANGCI_LINT_VERSION` 2.13.2 -> gofumpt `GOFUMPT_VERSION` 0.11.0) rather -than `@latest` for either: on a construct the two versions disagree on, -`task fmt` cannot converge `task lint`, and the gate is unsatisfiable. +`task fmt` runs `go fix` and then `golangci-lint fmt`; `task lint` uses the +same binary and `.golangci.yml`, so its gofumpt, goimports, and gci rules have +one owner and the writer converges the checker. Standalone `gofumpt` remains +only for generated protobuf contracts in `tools/proto.sh`. -A rule only one side applies fails the same way, so `task fmt` also passes -`-extra` to match the formatter's `extra-rules`. Both mismatches are -reachable in ordinary code: gofumpt <= v0.9.2 keeps the redundant parens in -`any((Trees)(nil))` that >= v0.10.0 removes, and without `-extra` -`func f(a int, b int)` stays put while `task lint` demands `func f(a, b int)`. -Formatting that only `task lint` can produce is still a real gap -- `gci`'s -`custom-order` places archie-core imports last, where gofumpt sorts them -alphabetically -- so run `golangci-lint fmt` when `task fmt` leaves a -formatting failure standing. +The three Yaegi secret-engine examples carry `//go:build ignore`. goimports +cannot type-check them and deletes a genuinely used `internal/secret` import, +so `.golangci.yml` excludes those exact files from the formatter set. Their +runtime loading remains covered by `internal/secret/engines_test.go`. | Surface | Repository declaration | Installed snapshot | Interpretation | |---|---|---|---| | Runtime Go | `go 1.27.0` in `go.mod` | Go 1.27.0, linux/amd64 | Requires at least declared Go level. | | Tools Go | `go 1.27.0` in `tools/go.mod` | Same Go 1.27.0 binary | Toolchain must satisfy both modules. | | Task | Taskfile schema `version: "3"` | Task 3.48.0 | Installed version is environment fact. | -| gofumpt | `task fmt`; pinned in `Dockerfile` (`GOFUMPT_VERSION`) | v0.11.0 | Must equal the gofumpt golangci-lint vendors. | -| golangci-lint | v2 config in `.golangci.yml`; pinned in `Dockerfile` | 2.13.2 | Vendors gofumpt v0.11.0; `golangci-lint run` enables the formatters. | +| gofumpt | Generated protobuf formatting; pinned in `Dockerfile` | v0.11.0 | Not the ordinary source formatter. | +| golangci-lint | v2 config in `.golangci.yml`; pinned in `Dockerfile` | 2.13.2 | Owns ordinary formatting and lint checks. | | Node | `ui/` frontend build | 26.9.0 / npm 11.19.1 | No `engines`/`packageManager` field. Docs need no Node. | | Containers | Compose commands in `Taskfile.yml` | Podman-backed, unusable in this sandbox | Verify CLI, Compose plugin, daemon/socket separately. | @@ -123,19 +114,20 @@ golangci-lint run ./... | Task | Exact effect | |---|---| -| `task fmt` | `gofumpt -extra -w .`, then `go fix ./...` — both may rewrite source. | +| `task fmt` | `go fix ./...`, then `golangci-lint fmt` — both may rewrite source. | | `task vet` | `go vet ./...` in the runtime module. | | `task lint` | `golangci-lint run ./...`. | | `task build` | Builds both commands into `bin/`. | | `task test` | `go test ./... -count=1` in the runtime module. | -| `task check` | `fmt` + `go fix ./...` again + `proto:lint` + `proto:check` + `docs:check` + `vet` + `lint` + `build` + `test` + `test:tools` + `test:ui`. | +| `task check` | `fmt` + `proto:lint` + `proto:check` + `docs:check` + `vet` + `lint` + `build` + `test` + `test:tools` + `test:ui`. | | `task clean` | Recursively removes `bin/`; destructive. | | `task docker-build` | `docker compose build agent` only. | `task check` is the definitive gate but omits race tests, `task vuln`, and `task docker-build`. Its docs step, `docs:check`, verifies committed generated data and never renders anything: there is still no documentation build. -Run only in authorized writable worktree. For read-only preview: `gofumpt -l .`. +Run only in an authorized writable worktree. For a read-only ordinary-source +preview, use `golangci-lint fmt --diff`. ## Verify the tools module separately diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 04a0194b1..698bfc5e9 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -64,12 +64,10 @@ jobs: with: node-version: "22" - # Pinned, not @latest: this gate rewrites formatting with the standalone - # gofumpt, and the agent image that gates PRs re-checks it with the - # gofumpt bundled in its golangci-lint. Those two versions must agree - # (see Dockerfile), or a PR passes here and fails there unfixably. - - name: Install gofumpt - run: go install mvdan.cc/gofumpt@v0.11.0 + - name: Install quality tools + run: | + go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.13.2 + go install mvdan.cc/gofumpt@v0.11.0 - name: Install protobuf tools run: bash tools/proto.sh install @@ -85,11 +83,13 @@ jobs: - name: Quality gate run: | - gofumpt -w . go fix ./... + golangci-lint fmt + git diff --exit-code bash tools/proto.sh lint bash tools/proto.sh check go vet ./... + golangci-lint run ./... go build ./... go test ./... -count=1 diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml new file mode 100644 index 000000000..d0e8bd891 --- /dev/null +++ b/.github/workflows/quality.yml @@ -0,0 +1,51 @@ +name: Quality + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +concurrency: + group: quality-${{ github.ref }} + cancel-in-progress: true + +jobs: + check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - uses: actions/setup-go@v5 + with: + go-version-file: go.mod + + - uses: actions/setup-node@v4 + with: + node-version: "24" + cache: npm + cache-dependency-path: ui/package-lock.json + + - name: Install quality tools + run: | + go install github.com/go-task/task/v3/cmd/task@v3.48.0 + go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.13.2 + go install mvdan.cc/gofumpt@v0.11.0 + bash tools/proto.sh install + sudo apt-get update + sudo apt-get install -y --no-install-recommends ripgrep + + - name: Ensure contract baseline ref + run: | + if ! git show-ref --verify --quiet refs/heads/main; then + git branch main origin/main + fi + + - name: Run definitive gate + run: | + task check + git diff --exit-code diff --git a/.golangci.yml b/.golangci.yml index 6342a5c16..140aebf37 100644 --- a/.golangci.yml +++ b/.golangci.yml @@ -120,7 +120,8 @@ formatters: - gci settings: gofumpt: - extra-rules: true + extra: + group-params: true gci: # Matches the grouping already used across this repo. sections: @@ -130,6 +131,11 @@ formatters: custom-order: true exclusions: generated: strict + # These are Yaegi programs shipped as examples. goimports cannot type-check + # files excluded by //go:build ignore and deletes their genuinely used + # internal/secret import, leaving the interpreter unable to load them. + paths: + - ^examples/secret-engines/(age|sops|vault)\.go$ issues: # 0 = report everything. The defaults (50 per linter, 3 per message) diff --git a/CLAUDE.md b/CLAUDE.md index 80bf6c7d0..9a3c76f8e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -85,20 +85,19 @@ automatically and note it in the handoff. Commands are defined in `Taskfile.yml` (requires Go 1.27.0, [Task](https://taskfile.dev), `gofumpt`, `golangci-lint`, and Node/npm). -Install `gofumpt` and `golangci-lint` as the pinned pair from `Dockerfile`, -never `@latest` for either: `task fmt` formats with the standalone gofumpt -while `task lint` re-checks it with the gofumpt golangci-lint vendors, so a -version mismatch makes `task check` unsatisfiable. +Install the versions pinned in `Dockerfile`, never `@latest`. `golangci-lint` +is the single writer for ordinary Go formatting; standalone `gofumpt` formats +generated protobuf contracts only. ```bash task build # build archied and archie-agent binaries into bin/ task test # go test ./... -count=1 task test:ui # dashboard node tests (DOM-building primitives) task ui # build dashboard into ui/dist (LAW asset) -task fmt # gofumpt -w . && go fix ./... +task fmt # go fix ./... && golangci-lint fmt task vet # go vet ./... task lint # golangci-lint run ./... -task check # fmt + go fix + proto:lint + proto:check + docs:check + vet + lint + build + test + test:tools + test:ui (The Definitive Gate) +task check # fmt + proto:lint + proto:check + docs:check + vet + lint + build + test + test:tools + test:ui (The Definitive Gate) task dev # archied live-reload + Vite HMR together on :5173 ``` @@ -265,8 +264,8 @@ structures found in legacy packages. tests. 3. **Quality Gate:** Run `task check`. 4. **Formatting is LAW:** Adopt all formatting and simplification changes from - `task fmt` (`gofumpt` + `go fix`) verbatim. Never revert or fight canonical - linter/formatter diffs. + `task fmt` (`go fix` + the configured golangci-lint formatters) verbatim. + Never revert or fight canonical linter/formatter diffs. 5. **No standing adversarial-review pass (for contributors):** Do not spawn a separate fresh-context reviewer pass on every change as a matter of course. Red-green TDD plus `task check` is the gate; a manual adversarial pass is diff --git a/Dockerfile b/Dockerfile index 996da915b..4b0cb9bcc 100644 --- a/Dockerfile +++ b/Dockerfile @@ -62,12 +62,8 @@ ENV PATH="/usr/local/go/bin:/go/bin:${PATH}" # module and build cache into the image. delve is omitted because it ships no # prebuilt binary; `go install ...@latest` at runtime if an agent needs it. # -# `task fmt` formats with this gofumpt and `task lint` then re-checks -# formatting with the gofumpt golangci-lint vendors. Any construct the two -# versions disagree on makes the gate unsatisfiable -- `task fmt` cannot -# converge a check run by a different formatter. So GOFUMPT_VERSION must equal -# the mvdan.cc/gofumpt version in golangci-lint v${GOLANGCI_LINT_VERSION}'s -# go.mod (2.13.2 -> v0.11.0). Bump the two together, never separately. +# golangci-lint owns ordinary source formatting and lint checks. Standalone +# gofumpt is retained for generated protobuf contracts in tools/proto.sh. ARG GOLANGCI_LINT_VERSION=2.13.2 ARG GOFUMPT_VERSION=0.11.0 ARG BUF_VERSION=1.72.0 diff --git a/Taskfile.yml b/Taskfile.yml index cf8d33bdb..dce4ca076 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -10,14 +10,13 @@ tasks: - task --list fmt: - desc: Format and fix Go source (gofumpt, go fix) + desc: Fix and format Go source with the gate's configured formatters cmds: - # -extra must match the gofumpt formatter's extra-rules in - # .golangci.yml. Without it `task fmt` cannot produce what `task lint` - # demands -- e.g. func f(a int, b int) -> func f(a, b int) -- so a - # contributor has no command that satisfies the gate. - - gofumpt -extra -w . - go fix ./... + # This must use the same engine and configuration as task lint. Running + # standalone gofumpt cannot reproduce goimports or gci's custom import + # grouping, so it can leave a tree that the gate rejects. + - golangci-lint fmt proto:install: desc: Install the pinned Buf and protobuf Go generators @@ -355,10 +354,9 @@ tasks: - go -C tools test -mod=readonly ./... -count=1 check: - desc: "Full quality gate: fmt, go fix, proto, docs, vet, lint, build, test, tools tests, ui tests and bundle" + desc: "Full quality gate: fmt, proto, docs, vet, lint, build, test, tools tests, ui tests and bundle" cmds: - task: fmt - - go fix ./... - task: proto:lint - task: proto:check - task: docs:check diff --git a/deploy_workflow_test.go b/deploy_workflow_test.go index db92c3f8e..f48f8597c 100644 --- a/deploy_workflow_test.go +++ b/deploy_workflow_test.go @@ -40,3 +40,43 @@ func TestDeployWorkflowOnlyPublishesRuntimeImageForRuntimeTag(t *testing.T) { t.Fatal("archied build step is unexpectedly conditional") } } + +func TestDeployWorkflowUsesConfiguredFormatters(t *testing.T) { + source := readDeploymentFile(t, ".github/workflows/deploy.yml") + for _, required := range []string{ + "github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.13.2", + "golangci-lint fmt", + "git diff --exit-code", + "golangci-lint run ./...", + } { + if !strings.Contains(source, required) { + t.Errorf("deploy workflow is missing formatter gate %q", required) + } + } + if strings.Contains(source, "gofumpt -w .") { + t.Error("deploy workflow bypasses the configured formatter set") + } +} + +func TestPullRequestsRunTheDefinitiveGateWithoutPublishAccess(t *testing.T) { + source := readDeploymentFile(t, ".github/workflows/quality.yml") + for _, required := range []string{ + "pull_request:", + "contents: read", + "task check", + "git diff --exit-code", + } { + if !strings.Contains(source, required) { + t.Errorf("quality workflow is missing %q", required) + } + } + for _, forbidden := range []string{ + "packages: write", + "docker/login-action", + "docker/build-push-action", + } { + if strings.Contains(source, forbidden) { + t.Errorf("quality workflow has publishing capability %q", forbidden) + } + } +} diff --git a/deployment_contract_test.go b/deployment_contract_test.go index 716267cef..adafe994c 100644 --- a/deployment_contract_test.go +++ b/deployment_contract_test.go @@ -67,6 +67,35 @@ func TestWorkerImageIsNotDocumentedAsAStandaloneExecutor(t *testing.T) { } } +func TestFormattingUsesOneConfiguredWriter(t *testing.T) { + taskfile := readDeploymentFile(t, "Taskfile.yml") + fmtStart := strings.Index(taskfile, " fmt:\n") + fmtEnd := strings.Index(taskfile, " proto:install:\n") + if fmtStart < 0 || fmtEnd < fmtStart { + t.Fatal("Taskfile has no bounded fmt task") + } + fmtTask := taskfile[fmtStart:fmtEnd] + + fix := strings.Index(fmtTask, "- go fix ./...") + format := strings.Index(fmtTask, "- golangci-lint fmt") + if fix < 0 || format < 0 || fix > format { + t.Error("fmt task must run go fix before the configured golangci-lint formatters") + } + if strings.Contains(fmtTask, "gofumpt -") { + t.Error("fmt task bypasses the configured formatter set with standalone gofumpt") + } + if got := strings.Count(taskfile, "- go fix ./..."); got != 1 { + t.Errorf("Taskfile runs go fix %d times, want exactly once through task fmt", got) + } +} + +func TestFormattersExcludeInterpretedSecretEngines(t *testing.T) { + config := readDeploymentFile(t, ".golangci.yml") + if !strings.Contains(config, `^examples/secret-engines/(age|sops|vault)\.go$`) { + t.Fatal("formatter config does not protect the interpreted secret engines") + } +} + func TestSupportedProfilesUseOneExecutionTopology(t *testing.T) { profiles := []string{ "deployments/single-forge-github.toml",