build: unify the gate so root make check covers the backend (closes #16)

Root `make check` only ever ran the frontend, so the "main is always
green" policy was satisfied vacuously: the Go backend could be entirely
broken and the root gate stayed green.

- The backend moves onto scripts-to-rule-them-all. Its test, lint, fmt,
  fmt-check, build, run and clean implementations now live in
  `backend/script/`, and `backend/Makefile` is thin shims. The backend
  is its own project (own module, README, LICENSE, linter config,
  Dockerfile stage), and `Dockerfile.backend` only copies `backend/`
  into its builder, so its scripts have to live under `backend/`.
- The root `script/test`, `script/lint`, `script/fmt` and
  `script/fmt-check` now run the frontend step and then the matching
  `backend/script/*` step, so `script/check` — and therefore the
  pre-commit hook — gates both halves. The frontend-only steps moved
  into `script/frontend-*` so nothing is duplicated.
- `script/bootstrap` now provisions the backend's toolchain as well,
  because widening the gate without widening bootstrap left the
  documented fresh-clone path (`make setup`) installing a pre-commit
  hook that rejected every commit with `golangci-lint: not found`.
  golangci-lint is installed at exactly `2.7.2`, the version
  `Dockerfile.backend` pins, so local findings match CI. Go is reused
  only when the installed version falls inside a window — at least
  `backend/go.mod`'s floor, and no newer in major.minor than the Go the
  pinned linter was built with — otherwise `go1.25.7` is installed. The
  upper bound is load-bearing: golangci-lint links `go/types` from its
  own build toolchain, so the pinned `2.7.2` (built with `go1.25.4`)
  panics with "file requires newer Go version go1.26" against a host Go
  1.26, which would leave `make setup` exiting 0 and every commit
  rejected. Both tools come from a specific release archive whose sha256
  is hardcoded here and verified before anything is unpacked — never an
  install script piped to a shell — and both are symlinked onto `PATH`,
  since nvm-style activation does not reach `make` or the git hook.
- `script/bootstrap` links only into `~/.local/bin` and never into a
  system-wide prefix. `/usr/local/bin` is shared with other users and
  with a package manager — on an Intel Mac it is the Homebrew prefix —
  and pointing an entry there at one user's `$HOME` breaks it for
  everyone else. It also refuses, non-zero, to replace anything it did
  not create: only a symlink already pointing into its own toolchain
  directory is overwritten, so a pre-existing binary is reported rather
  than deleted. `corepack enable` is given `--install-directory` so its
  four shims (`yarn`, `yarnpkg`, `pnpm`, `pnpx`) land inside that same
  toolchain directory instead of beside the corepack binary, and only
  `yarn` is linked onto `PATH`.
- `script/bootstrap` exits non-zero when it cannot guarantee the pinned
  toolchain is the one the gate will run. Reporting success while
  knowing a different linter or a newer Go precedes `~/.local/bin` is
  the same defect this commit exists to remove, so the final step
  re-resolves `go`, `gofmt`, `golangci-lint`, `node` and `yarn` against
  the caller's own `PATH` and fails with what it found and how to fix
  it. The three tools that carry a version constraint are re-checked
  with the same predicates their installs use, not for bare presence:
  `gofmt` is a gate tool — `backend/script/fmt-check` runs it — and its
  output is not guaranteed identical across Go releases, so a `gofmt`
  built by a different Go than the one that compiles the code counts as
  missing. `go` and `gofmt` are relinked on every run in which the
  pinned toolchain is the one in use, rather than only on the run that
  unpacked the archive, so a deleted link is repaired instead of
  falling through to whatever `gofmt` the host happens to have. The
  failure text separates a tool that resolves to the wrong build
  (something shadows `~/.local/bin`) from one that does not resolve at
  all (nothing is shadowing it, it was never installed), and always
  names a real directory rather than interpolating an unset one.
- `script/frontend-check` is the frontend half of the gate, exposed as
  the `frontend-check` target, for the frontend Dockerfile: its build
  stage is a node image with no Go toolchain. The backend half is gated
  by `Dockerfile.backend`, and `script/cibuild` builds both images, so
  the two Dockerfiles together still gate the whole repo. The
  `backend-check` target is the mirror of it. Both targets are named
  after the script they shim, like every other target.
- `script/cibuild` builds both images through one `build_image` helper,
  and the Gitea workflow's only build step is `script/cibuild`; the raw
  `docker build -f Dockerfile.backend .` is gone from the workflow.
  `script/docker` likewise builds and tags both images.
- `backend/Makefile`'s `hooks` target is removed. It wrote the same
  `.git/hooks/pre-commit` as `script/install-precommit`, so the two
  clobbered each other and the developer silently ended up gating on
  only one half of the repo. `script/install-precommit` is now the only
  installer, and the hook it writes runs the repo-wide `script/check`.
- `backend/Makefile`'s `docker` target is removed too: the backend image
  builds from the repo root with a root-level Dockerfile, so it belongs
  to the root `script/docker` and `script/cibuild` rather than to a
  backend script that would have to reach outside `backend/`.
- `backend/script/lint` verifies that `.golangci.yml` still matches its
  pinned sha256 before running the linter. Offline hash comparison, no
  network. The pin is marked provisional in the file: it is the config
  currently on `main`, and the comment names PR #31 and the canonical
  hash that must replace it when #31 lands.
- Every script locates the repo root with the mandated
  `$(cd "$(dirname "$0")/.." && pwd -P)` idiom, `cd`s there, and calls
  siblings as `"$ROOT/script/<name>"`; the `SCRIPT_DIR` variant is gone.

READMEs at the root and in `backend/` document every script, the
backend's Getting Started separates commands run from `backend/` from
those run at the repo root, and `TODO.md` records the change.

README.md

@@ -37,11 +37,13 @@ broken. We provide:
 
 - `script/bootstrap` — install all dependencies, assuming nothing is present:
   pinned node via nvm if needed, yarn via corepack,
-  `yarn install --frozen-lockfile`, and the backend's toolchain — Go (reused if
+  `yarn install --frozen-lockfile`, and the backend's toolchain — Go (an
-  already new enough) and golangci-lint at the version `Dockerfile.backend`
+  already-installed Go is reused only when its version falls inside the window
-  pins. Everything not installed by the system package manager comes from a
+  the pinned golangci-lint can analyse; a newer Go is ignored, not preferred)
-  hash-verified release archive and is symlinked onto `PATH`, so `make check`
+  and golangci-lint at the version `Dockerfile.backend` pins. Everything not
-  works in a plain shell afterwards
+  installed by the system package manager comes from a hash-verified release
+  archive and is symlinked into `~/.local/bin`, so `make check` works in a plain
+  shell afterwards
 - `script/setup` — make a fresh clone ready for development: bootstrap plus the
   git pre-commit hook
 - `script/projectname` — print the project name (used for the Docker image tags)

TODO.md

@@ -33,7 +33,9 @@ files, so merging it also closes most compliance gaps.
   golangci-lint cannot analyse packages built by a newer Go; it links only into
   `~/.local/bin`, never a system-wide prefix, and refuses to replace anything it
   did not create; and it exits non-zero rather than reporting success when the
-  tools on the caller's `PATH` are not the pinned ones
+  tools on the caller's `PATH` are not the pinned ones — `gofmt` included, held
+  to the same version agreement as `go` and relinked on every run so a deleted
+  link cannot leave another Go's `gofmt` gating the repo
 - 2026-07-07 Adopted scripts-to-rule-them-all: `script/` entrypoints, Makefile
   shims, README Entrypoints section
 - 2026-02-27: backend with buffered zstd-compressed report storage; CI workflow

script/bootstrap

@@ -5,10 +5,11 @@
 # or apk (detected in that order); assumes nothing is present. Node is
 # used directly if installed; otherwise it is installed at a pinned
 # version via nvm (installing nvm itself first, from a hash-verified
-# release archive, never curl | sh). Go is used directly if it is
+# release archive, never curl | sh). Go is used directly only if its
-# already new enough, and golangci-lint is installed at the exact pinned
+# version falls inside the pinned window described at GO_MAX_MINOR below
-# version; both come from hash-verified official release archives, never
+# -- a newer Go is ignored, not preferred -- and golangci-lint is
-# an install script.
+# installed at the exact pinned version; both come from hash-verified
+# official release archives, never an install script.
 #
 # The backend's toolchain is bootstrapped here because script/check runs
 # backend/script/test and backend/script/lint, so a machine that cannot
@@ -22,10 +23,13 @@
 #
 # Three rules govern what this script is allowed to touch:
 #
-#   1. It never writes outside $HOME. A per-repo bootstrap has no
+#   1. Everything it installs itself lands under $HOME, using $TMPDIR
-#      business writing to /usr/local/bin, a Homebrew prefix, or any
+#      only for scratch downloads it then deletes. The one exception is
-#      other system-wide location shared with other users and with a
+#      the system package manager, which it shells out to for base
-#      package manager.
+#      tooling (see pkg_install) and which owns those paths already. A
+#      per-repo bootstrap has no business writing to /usr/local/bin, a
+#      Homebrew prefix, or any other system-wide location behind that
+#      package manager's back.
 #   2. It never replaces something it did not create. Only a symlink
 #      that already points into one of its own managed directories is
 #      overwritten; anything else is left alone and bootstrap exits
@@ -381,8 +385,32 @@ go_ok() {
     ver_ge "$GO_MAX_MINOR" "$(echo "$have" | cut -d. -f1,2)"
 }
 
+# gofmt_ok: gofmt is a gate tool -- backend/script/fmt-check runs it --
+# and its output is not guaranteed byte-identical across Go releases, so
+# a gofmt from a different release than the go that compiles the code is
+# treated exactly like a missing one, the same way a mismatched
+# golangci-lint is. `go version <file>` prints the toolchain a Go binary
+# was built with, so this compares the gofmt that resolves on PATH
+# against the go that resolves on PATH, without depending on where
+# either one lives. Anything it cannot read -- no go to ask, gofmt
+# absent, not a Go binary -- fails closed.
+gofmt_ok() {
+    if missing go; then return 1; fi
+    if missing gofmt; then return 1; fi
+    go_have="$(go version 2>/dev/null | awk '{print $3}')"
+    [ -n "$go_have" ] || return 1
+    fmt_have="$(go version "$(command -v gofmt)" 2>/dev/null | awk '{print $NF}')"
+    [ "$fmt_have" = "$go_have" ]
+}
+
+# ensure_go: reuse the host toolchain only when the go on PATH is inside
+# the window AND a gofmt from that same release is on PATH with it. Both
+# link_bin calls sit outside that early return, so whenever the pinned
+# toolchain is the one in use they run on every bootstrap, not only on
+# the run that unpacked the archive: a deleted or never-created gofmt
+# link is restored rather than silently left to some other Go's gofmt.
 ensure_go() {
-    if go_ok; then return 0; fi
+    if go_ok && gofmt_ok; then return 0; fi
     if [ ! -x "$GO_DIR/bin/go" ]; then
         plat="$(platform)"
         tmp="$(mktemp -d)"
@@ -474,7 +502,22 @@ ensure_golangci_lint() {
 # warning buried in a long bootstrap log is not enough. So the checks
 # re-run against the PATH the caller will have (theirs, plus $BIN_DIR at
 # the front if bootstrap had to ask for it), and a failure is fatal.
+#
+# Every gate tool that has a version constraint is checked with the same
+# predicate its install used -- go_ok, gofmt_ok, golangci_lint_ok -- not
+# with a bare presence test, because a wrong-version gate tool produces
+# different results from the one CI runs, which is the failure this
+# function exists to prevent. node and yarn have no pinned version to
+# disagree about, so presence is the whole constraint for them.
 verify_toolchain() {
+    # BIN_DIR is only set once something needed linking, but the remedy
+    # text must name a real directory in every reachable state, so fall
+    # back to the one ensure_bin_dir would have chosen.
+    bin_dir="${BIN_DIR:-$HOME/.local/bin}"
+
+    # Model the PATH the caller will actually have: their own, plus
+    # $BIN_DIR at the front only if bootstrap linked something there and
+    # therefore told them to add it.
     verify_path="$ORIG_PATH"
     if [ -n "$BIN_DIR" ]; then
         case ":$ORIG_PATH:" in
@@ -488,8 +531,9 @@ verify_toolchain() {
     export PATH
     bad=""
     go_ok || bad="$bad go"
+    gofmt_ok || bad="$bad gofmt"
     golangci_lint_ok || bad="$bad golangci-lint"
-    for t in gofmt node yarn; do
+    for t in node yarn; do
         if missing "$t"; then bad="$bad $t"; fi
     done
     PATH="$saved_path"
@@ -497,20 +541,43 @@ verify_toolchain() {
 
     [ -z "$bad" ] && return 0
 
+    # Two different faults land here and they need different remedies: a
+    # tool that resolves but is the wrong build is being shadowed, and
+    # telling the user to fix PATH is right; a tool that does not resolve
+    # at all is not being shadowed by anything, and saying so would send
+    # them hunting for a conflict that does not exist.
     echo "bootstrap: the toolchain on your PATH cannot run the gate." >&2
+    wrong=""
+    absent=""
     for t in $bad; do
         where="$(
             export PATH="$verify_path"
-            command -v "$t" || echo "not found"
+            command -v "$t" 2>/dev/null || true
         )"
-        echo "  $t: $where" >&2
+        if [ -n "$where" ]; then
+            echo "  $t: $where (wrong version)" >&2
+            wrong="$wrong $t"
+        else
+            echo "  $t: not found" >&2
+            absent="$absent $t"
+        fi
     done
-    echo "  Expected these to come from $BIN_DIR. Something earlier on" >&2
+    echo "  The pinned toolchain is linked into $bin_dir." >&2
-    echo "  your PATH is shadowing them, or PATH does not reach it." >&2
+    if [ -n "$wrong" ]; then
-    echo "  Put $BIN_DIR first in PATH, or remove the conflicting tool," >&2
+        echo "  The tools shown with a path resolve to a build this" >&2
-    echo "  then re-run bootstrap. Failing rather than leaving you a" >&2
+        echo "  script did not provision: something earlier on your PATH" >&2
-    echo "  bootstrap that reports success and a \`make check\` that does" >&2
+        echo "  shadows $bin_dir. Put $bin_dir first in" >&2
-    echo "  not run." >&2
+        echo "  PATH, or remove the conflicting tool, then re-run." >&2
+    fi
+    if [ -n "$absent" ]; then
+        echo "  The tools shown as not found are on no directory of your" >&2
+        echo "  PATH at all, so nothing is shadowing them. Add $bin_dir" >&2
+        echo "  to PATH and re-run; if they are still not found after" >&2
+        echo "  that, bootstrap failed to install them and that is a bug" >&2
+        echo "  in this script, not in your environment." >&2
+    fi
+    echo "  Failing rather than leaving you a bootstrap that reports" >&2
+    echo "  success and a \`make check\` that does not run." >&2
     exit 1
 }