mcpx testing: every formatter and linter in the CI matrix, pinned by the flake (and run the plugin's bun test) #1996

Relocated from dezren39/darwin-nix#141 on 2026-10-28 (placement audit): mcpx's single source lives in developing-today/code (pkgs/mcpx); re-home tracked at #309. Original body below; issue references inside it are historical (dezren39/nix numbering).

Parent: #95

Summary

Put every formatter (check mode) and every linter (at warning severity or stricter, not the minimal preset) for mcpx into the test matrix, with tool versions pinned by the flake so nix fmt / the dev shell locally gives the same answer as CI. Also run the one TypeScript test file CI has never run (plugin/opencode/mcpx/daemon.test.ts). The repo already has most of the plumbing -- treefmt.nix, a flake formatter, checks.formatting, checks.tidy -- but none of it covers Go, TypeScript or shell, and none of it runs in CI.

Original notes

• testing
  • make a comprehensive github action ci.yaml workflow (or test.yaml) that is as fast as possible,
    • all formatters and linters in test matrix, formatters in check mode, linters set to warning or more than minimal.

Current state

Existing plumbing (repo root, main d0b7e01):

• treefmt.nix: programs.nixfmt and programs.rustfmt enabled; # programs.shellcheck.enable = true; # failures. projectRootFile = "flake.nix", so it formats the whole repo.
• flake.nix:422-429: formatter = the treefmt wrapper (nix fmt); checks.formatting = treefmt's check derivation over inputs.self; checks.tidy = flake-tidy all --check.
• justfile fmt: nixfmt *.nix pkgs/*.nix then nix run .#flake-tidy -- all || true -- the glob does not reach pkgs/mcpx/package.nix, and the || true swallows tidy failures. tidy-check: nix run .#flake-tidy -- all --check. So just fmt and nix fmt disagree about package.nix, and a CI check-mode formatter would fail on a file the documented local command cannot fix. Repair (from Phase 2: keep_prior revives earlier grants for a re-added member #169, see the comment below): just fmt calls nix fmt, which also picks up every program later added to treefmt.nix without a second edit.
• pkgs/mcpx/docs/release-runbook.md:158-168 "Checks" lists gofmt -l ., go vet ./..., go test ./... -count=1, scripts/stress.sh, scripts/bench.sh, nix build .#mcpx, and "README.md must stay a symlink to docs/story.md" (test -L README.md). None of these except go test and nix build run in CI.
• go test already runs a subset of vet (atomic, bool, buildtags, directive, errorsas, ifaceassert, nilfunc, printf, stringintconv, tests; go help test). Full go vet adds copylocks, loopclosure, lostcancel, unusedresult and others.
• No .golangci.yml, no deno.json, no .shellcheckrc, no .editorconfig in pkgs/mcpx.
• plugin/opencode/mcpx/daemon.test.ts: 21 tests at 05c78b2 (Phase 5: tag event bodies must travel with the event #182 added two) over the plugin's daemon discovery ladder, written for bun test (import ... from "bun:test", Bun.serve({unix}); the header says bun test plugin/opencode/mcpx/daemon.test.ts). Still never run by CI: .github/workflows/ has no bun test or deno test step. Plugin direction: build(deps): bump actions/checkout from 3 to 4 #47 (opencode v2), Update Rust crate anyhow to 1.0.75 #48 (harness-free core).

Baseline, run read-only on d0b7e01 with the tools installed on a dev machine (not the flake's pinned versions):

So turning any of this on needs one clean-up commit first (or a baseline), and a style decision for TypeScript.

The tool set

golangci-lint configuration, "warning or more than minimal": v2 with linters.default: standard (errcheck, govet, ineffassign, staticcheck, unused) plus a curated set that fits this codebase -- e.g. errorlint, bodyclose, noctx, misspell, unconvert, usestdlibvars, gocritic (diagnostic tags), revive (a few rules). From #169: staticcheck with checks: ["all"] rather than its default subset, and copyloopvar (Go 1.22 made the rt := rt idiom redundant; internal/e2e/runtime_test.go:15,47 still carry it). Not gosec in the blocking set: security is deferred, and on a process-spawning CLI it yields a large low-signal backlog. Not default: all: it enables style linters that contradict each other and would turn the first PR into a rewrite. Commit pkgs/mcpx/.golangci.yml; new linters are added one PR at a time with their fixes.

TypeScript style decision: either adopt deno's defaults and reformat the plugin once, or write a deno.json fmt block that matches the current opencode style. The plugin is loaded by opencode and #47/#48 may move or reshape it -- coordinate there before a mass reformat; lint can start immediately since it is independent of style.

Markdown: deno fmt also formats .md. The book is the docs tree's; exclude docs/** and AGENTS.md until the docs tree decides its own formatting.

Approaches -- how tools are installed and pinned

A -- marketplace actions per tool (least recommended)

golangci/golangci-lint-action, reviewdog/action-shellcheck, raven-actions/actionlint, each with its own version input. Fast to write, and golangci-lint-action caches well. But every tool's version lives in YAML, local runs use whatever is installed (the baseline above already used unpinned local tools), and Renovate bumps them independently of the flake. This is how "passes locally, fails in CI" starts.

B -- Go tools via the tool directive, the rest via actions

Go 1.24+ tool directives in go.mod pin Go tools and go tool golangci-lint run works locally and in CI. But it adds golangci-lint's large dependency graph to pkgs/mcpx/go.mod/go.sum, which changes the Nix vendorHash and Renovate's grouped Go bumps get much bigger (the vendorHash repair exists precisely because those bumps are painful). Pins Go tools only; shell/Nix/TS tools stay unpinned.

C -- the flake pins everything; treefmt for formatters, a dev shell for linters (recommended)

• Formatters: extend treefmt.nix with programs.gofmt, programs.deno (fmt), programs.shfmt, keeping nixfmt; scope the new ones to pkgs/mcpx/** with per-program includes so the rest of the repo is not reformatted by this issue. treefmt-nix ships modules for gofmt, gofumpt, goimports, golangci-lint, deno, prettier, biome, shfmt, shellcheck, actionlint, nixfmt, statix, deadnix (seen in a local copy of the input; confirm against the pinned rev). CI runs nix fmt -- --ci (or builds checks.x86_64-linux.formatting) -- check mode, non-zero on any diff, prints the diff. Locally nix fmt gives byte-identical results because it is the same derivation.
• Linters: the devShells.mcpx that Update Rust crate rand to v0.9.3 [SECURITY] #134 proposes (go, gopls, deno, bun, node, git, python3, golangci-lint), extended with shellcheck, actionlint, statix, deadnix -- one shell, pinned by flake.lock; CI runs nix develop .#mcpx -c <linter>; locally the same command. Do not run golangci-lint through treefmt: its treefmt module runs golangci-lint run --fix per file, which needs module downloads (not available in the checks sandbox) and rewrites code.
• Costs: the Nix install (~8 s) plus substitution per lint job; competitive only with a store cache (Update Rust crate tokio to v1.38.2 [SECURITY] #135 decision 7). One flake.lock bump updates every tool at once -- that is the point, and also a risk (a formatter upgrade reformats; ⚡ Bolt: Optimize search match counting performance #142 handles that).

Recommended because it is the only option where local == CI by construction, it reuses what the repo already has, and it keeps Go tool dependencies out of mcpx's go.mod.

Matrix layout

Three lint legs, each small, plus a plugin test leg:

If queue pressure shows up (#140), fmt and lint-other merge first. Run plugin under Deno and Node too only if #48 makes the core runtime-neutral (today the test imports bun:test and Bun.serve, so it is Bun-only). scripts/stress.sh and scripts/bench.sh stay manual (they use real servers from .mcpx.json); #97 decides whether a stress leg exists.

Implementation order (small PRs)

1. .golangci.yml with default: standard, go vet, gofmt check, shellcheck/actionlint -- fix what they find (small: gofmt is clean, shellcheck has 3).
2. plugin leg: bun test (no reformat needed).
3. deno lint (13 fixes) and deno check.
4. TS/shell/Nix formatting once the style is agreed: one reformat commit per language, then the check turns on. Add the reformat commits to .git-blame-ignore-revs.
5. Curated extra golangci linters, one per PR.

Alternative sequencing (from #169), for any linter whose backlog is too big for one fix-up PR: land it continue-on-error: true with ::warning:: annotations, fix the backlog in a dedicated PR, then flip it to blocking. Formatters block from day one either way -- a formatter has no judgement calls. Whichever path, the end state must be "clean and enforced", never another # ... # failures line like treefmt.nix:6.

Open questions

1. TypeScript style: deno defaults vs matching opencode's (no semicolons, width 120)? Depends on build(deps): bump actions/checkout from 3 to 4 #47/Update Rust crate anyhow to 1.0.75 #48 plans for the plugin.
2. shfmt flags for scripts/*.sh (indent width) -- match the existing files.
3. Scope: mcpx only, or turn the whole-repo checks.formatting into a CI job too (build(deps): bump build/buck/preludes/buck2-prelude from d956689 to 3cfc766 #49's territory)?
4. Is nix flake check usable as a CI step for mcpx, or does it evaluate/build too much of the repo (opencode patches, darwin-only packages)? Prefer building the single checks.x86_64-linux.formatting attribute.
5. deno check of the plugin needs opencode's plugin types -- available offline, or does it need Update Rust crate anyhow to 1.0.75 #48 first?
6. Does checks.formatting pass on main today? Nothing runs it; the baseline above already found pkgs/mcpx/package.nix unformatted by a system nixfmt. If it is red, step one is the backlog, and its size is unknown (from Phase 2: keep_prior revives earlier grants for a re-added member #169).

Ease · Impact · Related

Ease M (mostly clean-up and one style decision) · Impact med · Depends on / related: #95, #135 (legs, Nix cache, tool-version decision), #142 (auto-applies the same formatters), #140 (merge legs under queue pressure), #134 (the shared mcpx dev shell), #47, #48 (plugin shape and its tests), #49 (repo-wide format/tidy checks), #99 (which of these agents run locally: formatters yes, full lint maybe), #35 (version drift), #129 (its settings-effect guard needs this issue's plugin leg to cover plugin-scoped settings, which only the plugin's TypeScript reads).

Security/auth deferred; see tracker.

Acceptance criteria

• Every formatter/linter named in the body's CI matrix runs in CI pinned by the flake, the plugin's bun test runs, and the workflow is green.
• The work described in the Summary/Scope above is delivered via a branch + PR (no direct push to main); verification runs in GitHub Actions CI, not on the sandbox.
• Evidence (CI links, timings, or probe output as applicable) is recorded on this issue before it is closed.