1 Commits

Author SHA1 Message Date
clawbot
a6a744b45f build: unify the gate so root make check covers the backend (closes #16)
All checks were successful
check / check (push) Successful in 42s
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/frontend-check` is the frontend half of the gate, exposed as
  the `check-frontend` 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
  `check-backend` target is the mirror of it.
- `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.

READMEs at the root and in `backend/` document every script, and
`TODO.md` records the change.
2026-08-09 05:52:55 +00:00
14 changed files with 41 additions and 330 deletions

View File

@@ -5,14 +5,14 @@ COPY package.json yarn.lock ./
RUN yarn install --frozen-lockfile
RUN apk add --no-cache git make
COPY . .
# make frontend-check runs script/frontend-check (test + lint +
# make check-frontend runs script/frontend-check (test + lint +
# fmt-check for the frontend); its test step is the production yarn
# build, so this both produces dist/ and gates the image on
# lint/fmt-check/test regressions, not merely a broken build. It is the
# frontend half of `make check` rather than all of it because this stage
# is a node image with no Go toolchain; the backend half is gated by
# Dockerfile.backend, and script/cibuild builds both images.
RUN make frontend-check
RUN make check-frontend
# nginx:stable-alpine as of 2026-02-22
FROM nginx@sha256:15e96e59aa3b0aada3a121296e3bce117721f42d88f5f64217ef4b18f458c6ab

View File

@@ -1,5 +1,5 @@
.PHONY: bootstrap setup dev test lint fmt fmt-check check frontend-check \
backend-check docker hooks
.PHONY: bootstrap setup dev test lint fmt fmt-check check check-frontend \
check-backend docker hooks
# Standard targets are thin shims; the implementations live in script/
# per the scripts-to-rule-them-all pattern (see the Entrypoints section
@@ -32,11 +32,10 @@ check:
# Half-repo gates. Used by the two Dockerfiles, whose build stages only
# have the toolchain for their own half; prefer `make check` otherwise.
# Each is named after the script it shims, like every other target here.
frontend-check:
check-frontend:
@script/frontend-check
backend-check:
check-backend:
@backend/script/check
docker:

View File

@@ -35,13 +35,8 @@ The repo holds two projects: the frontend at the repo root and the Go backend in
root scripts cover both, so `make check` at the root fails if either half is
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
already new enough) and golangci-lint at the version `Dockerfile.backend`
pins. Everything not installed by the system package manager comes from a
hash-verified release archive and is symlinked onto `PATH`, so `make check`
works in a plain shell afterwards
- `script/bootstrap` — install all dependencies (pinned node via nvm if needed,
yarn via corepack, `yarn install --frozen-lockfile`)
- `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)
@@ -58,10 +53,8 @@ broken. We provide:
- `script/frontend-lint` — run prettier in check mode
- `script/frontend-fmt` — format everything prettier understands (writes)
- `script/frontend-fmt-check` — check prettier formatting (read-only)
- `script/frontend-check` — the frontend half of `script/check`, shimmed by
`make frontend-check` and used by `Dockerfile`, whose build stage is a node
image with no Go toolchain. Its mirror `make backend-check` shims to
`backend/script/check`
- `script/frontend-check` — the frontend half of `script/check`, used by
`Dockerfile`, whose build stage is a node image with no Go toolchain
- `script/docker` — build both images, tagged via `script/projectname`:
`netwatch` from `Dockerfile` and `netwatch-server` from `Dockerfile.backend`
- `script/cibuild` — CI entrypoint: builds both images; the only build step in

View File

@@ -25,10 +25,8 @@ files, so merging it also closes most compliance gaps.
- 2026-08-09: unified the gate: the root `make check` now covers the Go backend
as well as the frontend, the backend moved onto scripts-to-rule-them-all
(`backend/script/*` with `backend/Makefile` as thin shims), the duplicate
pre-commit hook installer in `backend/Makefile` was removed, `script/cibuild`
now builds both images as the workflow's only build step, and
`script/bootstrap` provisions the backend toolchain (pinned, hash-verified Go
and golangci-lint) so a fresh clone can pass the widened gate
pre-commit hook installer in `backend/Makefile` was removed, and
`script/cibuild` now builds both images as the workflow's only build step
- 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

View File

@@ -4,24 +4,15 @@ SPA and persists them as zstd-compressed JSONL files on disk.
## Getting Started
From this directory (`backend/`):
```bash
# Build and run locally
make run
# Run the backend's tests, lint, and format check
# Run tests, lint, and format check
make check
```
From the repo root, one directory up — `Dockerfile.backend` lives there and its
build context is the repo root, so there is no `docker` target here:
```bash
# Build both images, including netwatch-server
# Docker (from the repo root; the image's build context is the repo root)
make docker
# Run the backend image
docker run -p 8080:8080 netwatch-server
```

View File

@@ -4,13 +4,12 @@
# gate covers the backend.
set -eu
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
main() {
cd "$ROOT"
"$ROOT/script/test"
"$ROOT/script/lint"
"$ROOT/script/fmt-check"
"$SCRIPT_DIR/test"
"$SCRIPT_DIR/lint"
"$SCRIPT_DIR/fmt-check"
}
main "$@"

View File

@@ -13,16 +13,6 @@ set -eu
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
# sha256 of the pinned backend/.golangci.yml.
#
# PROVISIONAL. The hash below is the file currently on main, which is
# the schema-invalid v1-keyed config described above: it is pinned only
# so this branch and main stay green, NOT because it is canonical.
#
# The canonical org-wide .golangci.yml is
# 021cc83f4e6fc7c31b95b34b846723dfcf20b66b7baeea1dc40406e643346bcb,
# and PR #31 replaces backend/.golangci.yml with it. When #31 lands,
# GOLANGCI_CONFIG_SHA256 must be updated to that hash in the same
# commit. Until then, do not treat the pinned file as the standard.
GOLANGCI_CONFIG_SHA256="33ba2bf7fe4a44779d09b0fb31d6daf03685f8dc9d2bc417f963d7aabb0d17dc"
# sha256 <file>: print the file's sha256, coreutils or Darwin/busybox.

View File

@@ -2,11 +2,12 @@
# script/run: build and run netwatch-server locally.
set -eu
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
main() {
"$SCRIPT_DIR/build"
cd "$ROOT"
"$ROOT/script/build"
exec ./netwatch-server "$@"
}

View File

@@ -5,20 +5,7 @@
# 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
# already new enough, and golangci-lint is 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
# run go and golangci-lint cannot pass the repo-wide gate or the
# pre-commit hook that script/setup installs.
#
# Anything installed outside the system package manager is symlinked
# into a directory that is on PATH, so a later `make check` in a plain
# shell finds it. nvm only puts node on PATH for shells that source
# nvm.sh, which neither make nor the git hook does.
# release archive, never curl | sh).
set -eu
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
@@ -30,37 +17,9 @@ NVM_VERSION="0.40.3"
NVM_SHA256="5f4d6aaa04a177dc93c985e31dbc411ab6b8c6e1e21d8015dbc1372625fcd1d0"
YARN_VERSION="1.22.22"
# Go 1.25.7 (2026-08-09). This is the toolchain inside the pinned
# golang:1.25-alpine builder of Dockerfile.backend, so a local build
# uses the same compiler CI does. GO_MIN_VERSION is the floor from
# backend/go.mod; an already-installed go at or above it is used as is.
GO_VERSION="1.25.7"
GO_MIN_VERSION="1.25.5"
# golangci-lint 2.7.2 (2026-08-09). MUST stay equal to the golangci-lint
# pinned in Dockerfile.backend (currently commit
# 9f61b0f53f80672872fced07b6874397c3ed197b, which is tag v2.7.2), so a
# local `make lint` and CI's in-image `make check` report the same
# findings.
#
# Reconciliation note: PR #31 moves Dockerfile.backend to golangci-lint
# v2.12.2, commit c0d3ddc9cf3faa61a4e378e879ece580256d76e5. When that
# lands, GOLANGCI_LINT_VERSION and every hash in golangci_lint_sha256()
# below must be updated to the v2.12.2 release archives in the same
# commit, or local and CI will disagree.
GOLANGCI_LINT_VERSION="2.7.2"
# Where hash-verified archives are unpacked. Version-scoped, so bumping
# a pin installs alongside the old copy instead of half-overwriting it.
# Filled in by main() from script/projectname.
GO_DIR=""
GOLANGCI_LINT_DIR=""
PKGMGR=""
SUDO=""
APT_UPDATED=""
BIN_DIR=""
NODE_BIN=""
detect_pkgmgr() {
[ -n "$PKGMGR" ] && return 0
@@ -120,85 +79,6 @@ verify_sha256() {
fi
}
# fetch_verified <url> <expected-hash> <dest>: download a release
# archive and check it against a hash hardcoded in this script before
# anything is unpacked or run. Never pipe a remote script to a shell.
fetch_verified() {
if missing curl; then pkg_install curl curl curl curl; fi
curl -fsSL -o "$3" "$1"
verify_sha256 "$3" "$2"
}
# platform: <os>-<arch> as used in the Go and golangci-lint release
# archive filenames.
platform() {
plat_os="$(uname -s)"
plat_arch="$(uname -m)"
case "$plat_os" in
Linux) plat_os="linux" ;;
Darwin) plat_os="darwin" ;;
*)
echo "bootstrap: unsupported OS $plat_os" >&2
exit 1
;;
esac
case "$plat_arch" in
x86_64 | amd64) plat_arch="amd64" ;;
aarch64 | arm64) plat_arch="arm64" ;;
*)
echo "bootstrap: unsupported architecture $plat_arch" >&2
exit 1
;;
esac
echo "$plat_os-$plat_arch"
}
# ver_ge <have> <want>: succeed if dotted version <have> is at least
# <want>, comparing up to three numeric components.
ver_ge() {
awk -v have="$1" -v want="$2" '
BEGIN {
n = split(have, h, ".")
m = split(want, w, ".")
for (i = 1; i <= 3; i++) {
hv = (i <= n) ? h[i] + 0 : 0
wv = (i <= m) ? w[i] + 0 : 0
if (hv > wv) exit 0
if (hv < wv) exit 1
}
exit 0
}'
}
# ensure_bin_dir: pick the directory provisioned tools are linked into.
# /usr/local/bin when writable (root, or a Homebrew prefix), otherwise
# ~/.local/bin, which is prepended to PATH for the rest of this run and
# reported so the user can add it permanently.
ensure_bin_dir() {
[ -n "$BIN_DIR" ] && return 0
if [ -d /usr/local/bin ] && [ -w /usr/local/bin ]; then
BIN_DIR="/usr/local/bin"
else
BIN_DIR="$HOME/.local/bin"
mkdir -p "$BIN_DIR"
fi
case ":$PATH:" in
*":$BIN_DIR:"*) ;;
*)
PATH="$BIN_DIR:$PATH"
export PATH
echo "bootstrap: add $BIN_DIR to your PATH" >&2
;;
esac
}
# link_bin <target> <name>: idempotently expose one provisioned binary
# on PATH.
link_bin() {
ensure_bin_dir
ln -sfn "$1" "$BIN_DIR/$2"
}
# nvm is a bash script; run a command in a bash with nvm loaded
nvm_sh() {
bash -c ". \"\$HOME/.nvm/nvm.sh\" && $*"
@@ -211,9 +91,9 @@ ensure_nvm() {
if missing curl; then pkg_install curl curl curl curl; fi
if missing git; then pkg_install git git git git; fi
tmp="$(mktemp -d)"
fetch_verified \
"https://github.com/nvm-sh/nvm/archive/refs/tags/v${NVM_VERSION}.tar.gz" \
"$NVM_SHA256" "$tmp/nvm.tar.gz"
curl -fsSL -o "$tmp/nvm.tar.gz" \
"https://github.com/nvm-sh/nvm/archive/refs/tags/v${NVM_VERSION}.tar.gz"
verify_sha256 "$tmp/nvm.tar.gz" "$NVM_SHA256"
mkdir -p "$HOME/.nvm"
tar -xzf "$tmp/nvm.tar.gz" -C "$HOME/.nvm" --strip-components=1
rm -rf "$tmp"
@@ -223,10 +103,6 @@ ensure_node() {
if ! missing node; then return 0; fi
ensure_nvm
nvm_sh "nvm install $NODE_VERSION"
NODE_BIN="$HOME/.nvm/versions/node/v$NODE_VERSION/bin"
for nb in node npm npx corepack; do
if [ -e "$NODE_BIN/$nb" ]; then link_bin "$NODE_BIN/$nb" "$nb"; fi
done
}
ensure_yarn() {
@@ -240,9 +116,6 @@ ensure_yarn() {
else
npm install -g "yarn@$YARN_VERSION"
fi
if [ -n "$NODE_BIN" ] && [ -e "$NODE_BIN/yarn" ]; then
link_bin "$NODE_BIN/yarn" yarn
fi
}
install_js_deps() {
@@ -254,136 +127,9 @@ install_js_deps() {
fi
}
# go_sha256 <platform>: sha256 of
# https://go.dev/dl/go1.25.7.<platform>.tar.gz, from the signed release
# index at https://go.dev/dl/?mode=json (2026-08-09).
go_sha256() {
case "$1" in
linux-amd64)
echo "12e6d6a191091ae27dc31f6efc630e3a3b8ba409baf3573d955b196fdf086005"
;;
linux-arm64)
echo "ba611a53534135a81067240eff9508cd7e256c560edd5d8c2fef54f083c07129"
;;
darwin-amd64)
echo "bf5050a2152f4053837b886e8d9640c829dbacbc3370f913351eb0904cb706f5"
;;
darwin-arm64)
echo "ff18369ffad05c57d5bed888b660b31385f3c913670a83ef557cdfd98ea9ae1b"
;;
*)
echo "bootstrap: no pinned Go archive hash for $1" >&2
exit 1
;;
esac
}
# go_ok: an already-installed go is acceptable if it is at least
# GO_MIN_VERSION, mirroring how node is used when already present.
go_ok() {
if missing go; then return 1; fi
have="$(go version 2>/dev/null | awk '{print $3}')"
have="${have#go}"
[ -n "$have" ] || return 1
ver_ge "$have" "$GO_MIN_VERSION"
}
ensure_go() {
if go_ok; then return 0; fi
if [ ! -x "$GO_DIR/bin/go" ]; then
plat="$(platform)"
tmp="$(mktemp -d)"
fetch_verified \
"https://go.dev/dl/go${GO_VERSION}.${plat}.tar.gz" \
"$(go_sha256 "$plat")" "$tmp/go.tar.gz"
rm -rf "$GO_DIR.partial"
mkdir -p "$GO_DIR.partial"
tar -xzf "$tmp/go.tar.gz" -C "$GO_DIR.partial" --strip-components=1
rm -rf "$GO_DIR"
mv "$GO_DIR.partial" "$GO_DIR"
rm -rf "$tmp"
fi
link_bin "$GO_DIR/bin/go" go
link_bin "$GO_DIR/bin/gofmt" gofmt
}
# golangci_lint_sha256 <platform>: sha256 of the golangci-lint 2.7.2
# release archive for that platform, from
# https://github.com/golangci/golangci-lint/releases/download/v2.7.2/golangci-lint-2.7.2-checksums.txt
# (2026-08-09).
golangci_lint_sha256() {
case "$1" in
linux-amd64)
echo "ce46a1f1d890e7b667259f70bb236297f5cf8791a9b6b98b41b283d93b5b6e88"
;;
linux-arm64)
echo "7028e810837722683dab679fb121336cfa303fecff39dfe248e3e36bc18d941b"
;;
darwin-amd64)
echo "6966554840a02229a14c52641bc38c2c7a14d396f4c59ba0c7c8bb0675ca25c9"
;;
darwin-arm64)
echo "6ce86a00e22b3709f7b994838659c322fdc9eae09e263db50439ad4f6ec5785c"
;;
*)
echo "bootstrap: no pinned golangci-lint archive hash for $1" >&2
exit 1
;;
esac
}
# golangci_lint_ok: unlike go, this must be the exact pinned version.
# A different version reports a different set of findings, so local
# results would stop matching what Dockerfile.backend gates on.
golangci_lint_ok() {
if missing golangci-lint; then return 1; fi
have="$(golangci-lint version 2>&1 | awk '
{
for (i = 1; i < NF; i++) {
if ($i == "version") {
v = $(i + 1)
sub(/^v/, "", v)
print v
exit
}
}
}')"
[ "$have" = "$GOLANGCI_LINT_VERSION" ]
}
ensure_golangci_lint() {
if golangci_lint_ok; then return 0; fi
if [ ! -x "$GOLANGCI_LINT_DIR/golangci-lint" ]; then
plat="$(platform)"
base="golangci-lint-${GOLANGCI_LINT_VERSION}-${plat}"
tmp="$(mktemp -d)"
fetch_verified \
"https://github.com/golangci/golangci-lint/releases/download/v${GOLANGCI_LINT_VERSION}/${base}.tar.gz" \
"$(golangci_lint_sha256 "$plat")" "$tmp/golangci-lint.tar.gz"
mkdir -p "$tmp/x"
tar -xzf "$tmp/golangci-lint.tar.gz" -C "$tmp/x" --strip-components=1
rm -rf "$GOLANGCI_LINT_DIR.partial"
mkdir -p "$GOLANGCI_LINT_DIR.partial"
cp "$tmp/x/golangci-lint" "$GOLANGCI_LINT_DIR.partial/golangci-lint"
chmod +x "$GOLANGCI_LINT_DIR.partial/golangci-lint"
rm -rf "$GOLANGCI_LINT_DIR"
mv "$GOLANGCI_LINT_DIR.partial" "$GOLANGCI_LINT_DIR"
rm -rf "$tmp"
fi
link_bin "$GOLANGCI_LINT_DIR/golangci-lint" golangci-lint
if ! golangci_lint_ok; then
echo "bootstrap: a different golangci-lint precedes $BIN_DIR on your" >&2
echo " PATH; local lint findings may not match what CI gates on" >&2
fi
}
main() {
cd "$ROOT"
toolchain="$HOME/.local/share/$("$ROOT/script/projectname")/toolchain"
GO_DIR="$toolchain/go-$GO_VERSION"
GOLANGCI_LINT_DIR="$toolchain/golangci-lint-$GOLANGCI_LINT_VERSION"
if missing make; then pkg_install gnumake make make make; fi
if missing git; then pkg_install git git git git; fi
@@ -391,9 +137,6 @@ main() {
ensure_yarn
install_js_deps
ensure_go
ensure_golangci_lint
echo "bootstrap complete"
}

View File

@@ -4,13 +4,12 @@
# scripts-to-rule-them-all. Must not modify any files.
set -eu
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
main() {
cd "$ROOT"
"$ROOT/script/test"
"$ROOT/script/lint"
"$ROOT/script/fmt-check"
"$SCRIPT_DIR/test"
"$SCRIPT_DIR/lint"
"$SCRIPT_DIR/fmt-check"
}
main "$@"

View File

@@ -4,11 +4,12 @@
# as <name>-server. Both build from the repo root as their context.
set -eu
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
main() {
cd "$ROOT"
name="$("$ROOT/script/projectname")"
name="$("$SCRIPT_DIR/projectname")"
timeout 300 docker build -t "$name" -f Dockerfile .
timeout 300 docker build -t "$name-server" -f Dockerfile.backend .
}

View File

@@ -6,13 +6,12 @@
# the whole repo. Must not modify any files.
set -eu
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
main() {
cd "$ROOT"
"$ROOT/script/frontend-test"
"$ROOT/script/frontend-lint"
"$ROOT/script/frontend-fmt-check"
"$SCRIPT_DIR/frontend-test"
"$SCRIPT_DIR/frontend-lint"
"$SCRIPT_DIR/frontend-fmt-check"
}
main "$@"

View File

@@ -3,11 +3,10 @@
# checks fail. Our own extension to scripts-to-rule-them-all.
set -eu
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
main() {
cd "$ROOT"
"$ROOT/script/check"
"$SCRIPT_DIR/check"
}
main "$@"

View File

@@ -3,12 +3,11 @@
# installs dependencies and the git pre-commit hook.
set -eu
ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
main() {
cd "$ROOT"
"$ROOT/script/bootstrap"
"$ROOT/script/install-precommit"
"$SCRIPT_DIR/bootstrap"
"$SCRIPT_DIR/install-precommit"
}
main "$@"