From e2b7f156179fb2f3ac544f8a05bf62ca1d10c14b Mon Sep 17 00:00:00 2001 From: sneak Date: Tue, 7 Jul 2026 01:56:43 +0200 Subject: [PATCH 1/2] Adopt scripts-to-rule-them-all: script/ entrypoints, Makefile shims --- .gitea/workflows/check.yml | 2 +- Makefile | 35 ++++++---- README.md | 25 +++++++ TODO.md | 2 + script/bootstrap | 138 +++++++++++++++++++++++++++++++++++++ script/check | 15 ++++ script/cibuild | 15 ++++ script/docker | 15 ++++ script/fmt | 14 ++++ script/fmt-check | 18 +++++ script/install-precommit | 16 +++++ script/lint | 23 +++++++ script/precommit | 21 ++++++ script/projectname | 12 ++++ script/setup | 14 ++++ script/test | 23 +++++++ 16 files changed, 372 insertions(+), 16 deletions(-) create mode 100755 script/bootstrap create mode 100755 script/check create mode 100755 script/cibuild create mode 100755 script/docker create mode 100755 script/fmt create mode 100755 script/fmt-check create mode 100755 script/install-precommit create mode 100755 script/lint create mode 100755 script/precommit create mode 100755 script/projectname create mode 100755 script/setup create mode 100755 script/test diff --git a/.gitea/workflows/check.yml b/.gitea/workflows/check.yml index aca7a51..ee73864 100644 --- a/.gitea/workflows/check.yml +++ b/.gitea/workflows/check.yml @@ -6,4 +6,4 @@ jobs: steps: # actions/checkout v4.2.2, 2026-02-22 - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 - - run: docker build . + - run: script/cibuild diff --git a/Makefile b/Makefile index 63dff60..2fbafdc 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: check lint test fmt fmt-check build clean docker docker-test devserver devserver-stop hooks +.PHONY: bootstrap setup check lint test fmt fmt-check build clean docker docker-versioned docker-test devserver devserver-stop hooks VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev") LDFLAGS := -X main.Version=$(VERSION) @@ -15,27 +15,30 @@ else endif # Default target: run all checks -check: fmt-check lint test +check: + @script/check + +bootstrap: + @script/bootstrap + +setup: + @script/setup # Check formatting without modifying files fmt-check: - @echo "Checking formatting..." - @test -z "$$(gofmt -l . | grep -v '^vendor/')" || (echo "Files need formatting:"; gofmt -l . | grep -v '^vendor/'; exit 1) + @script/fmt-check # Format code fmt: - @echo "Formatting code..." - gofmt -w $$(find . -name '*.go' -not -path './vendor/*') + @script/fmt # Run linter lint: - @echo "Running linter..." - $(NIX_RUN_PREFIX)golangci-lint run$(NIX_RUN_SUFFIX) + @script/lint # Run tests (30-second timeout) test: - @echo "Running tests..." - $(NIX_RUN_PREFIX)CGO_ENABLED=1 go test -timeout 30s -v ./...$(NIX_RUN_SUFFIX) + @script/test # Build the binary build: @@ -47,8 +50,12 @@ clean: rm -rf bin/ rm -rf ./data -# Build Docker image +# Build Docker image (tagged via script/projectname) docker: + @script/docker + +# Build Docker image tagged pixad:$(VERSION) and pixad:latest +docker-versioned: docker build --build-arg VERSION=$(VERSION) -t pixad:$(VERSION) -t pixad:latest . # Run tests in Docker (needed for CGO/libvips) @@ -57,7 +64,7 @@ docker-test: docker run --rm pixad-builder sh -c "CGO_ENABLED=1 GOTOOLCHAIN=auto go test -v ./..." # Run local dev server in Docker -devserver: docker devserver-stop +devserver: docker-versioned devserver-stop docker run -d --name pixad-dev -p 8080:8080 \ -v $(CURDIR)/config.dev.yml:/etc/pixa/config.yml:ro \ pixad:latest @@ -70,6 +77,4 @@ devserver-stop: # Install pre-commit hook hooks: - @printf '#!/bin/sh\nset -e\n' > .git/hooks/pre-commit - @printf 'make check\n' >> .git/hooks/pre-commit - @chmod +x .git/hooks/pre-commit + @script/install-precommit diff --git a/README.md b/README.md index 632a467..2286084 100644 --- a/README.md +++ b/README.md @@ -128,6 +128,31 @@ See `config.example.yml` for all options with defaults. - **Metrics**: Prometheus - **Logging**: stdlib slog +## Entrypoints + +This repository adheres to the +[Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all) +standard: normalized scripts in `script/` are the entrypoints for the +development workflow, and the Makefile targets are thin shims that call +them. We provide: + +- `script/bootstrap` — install all dependencies (idempotent) +- `script/setup` — make a fresh clone ready for development + (bootstrap, then install-precommit) +- `script/projectname` — output the project name ("pixa") +- `script/test` — run the test suite +- `script/lint` — run golangci-lint +- `script/fmt` — format all code (writes) +- `script/fmt-check` — check formatting (read-only) +- `script/check` — run test, lint, and fmt-check +- `script/docker` — build the Docker image tagged via `script/projectname` +- `script/cibuild` — CI entrypoint: `docker build .` (the Dockerfile + runs the checks, so a green build implies a green repo) +- `script/precommit` — pre-commit checks (`go mod tidy` guard, then + `script/check`) +- `script/install-precommit` — install the git pre-commit hook that + runs `script/precommit` + ## TODO See [TODO.md](TODO.md) for the full prioritized task list. diff --git a/TODO.md b/TODO.md index 3a31058..9ee4d18 100644 --- a/TODO.md +++ b/TODO.md @@ -26,6 +26,8 @@ individually. # Completed Steps +- 2026-07-07 Adopted scripts-to-rule-them-all: `script/` entrypoints, + Makefile shims, README Entrypoints section - 2026-04-07 extract magic byte detection into internal/magic (#42) - 2026-03-25 extract allowlist package from internal/imgcache (#41) - 2026-03-25 move schema_migrations table creation into 000.sql (#36) diff --git a/script/bootstrap b/script/bootstrap new file mode 100755 index 0000000..e100955 --- /dev/null +++ b/script/bootstrap @@ -0,0 +1,138 @@ +#!/bin/sh +# script/bootstrap: install all dependencies needed to build and develop +# this repo. Idempotent: every install is guarded by a check so already +# installed tools are skipped. Base tooling comes from nix, apt, brew, +# or apk (detected in that order); assumes NOTHING is present (not git, +# make, or go). golangci-lint is packaged in nix, brew, and apk; on apt +# it is installed from a hash-verified GitHub release archive (never +# curl | sh). CGO image libraries (pkg-config, vips, libheif) are +# installed for the govips bindings. +set -eu + +ROOT="$(cd "$(dirname "$0")/.." && pwd -P)" + +# Pinned versions, 2026-07-07. Never "latest"; exact versions only. +GOLANGCI_LINT_VERSION="2.10.1" +# sha256 of golangci-lint-2.10.1-linux-.tar.gz release archives +GOLANGCI_LINT_SHA256_AMD64="dfa775874cf0561b404a02a8f4481fc69b28091da95aa697259820d429b09c99" +GOLANGCI_LINT_SHA256_ARM64="6652b42ae02915eb2f9cb2a2e0cac99514c8eded8388d88ae3e06e1a52c00de8" + +PKGMGR="" +SUDO="" + +detect_pkgmgr() { + [ -n "$PKGMGR" ] && return 0 + if command -v nix-env >/dev/null 2>&1; then + PKGMGR="nix" + elif command -v apt-get >/dev/null 2>&1; then + PKGMGR="apt" + elif command -v brew >/dev/null 2>&1; then + PKGMGR="brew" + elif command -v apk >/dev/null 2>&1; then + PKGMGR="apk" + else + echo "bootstrap: no supported package manager (nix, apt, brew, apk)" >&2 + exit 1 + fi + if [ "$PKGMGR" = "apt" ]; then + export DEBIAN_FRONTEND=noninteractive + if [ "$(id -u)" != "0" ]; then + SUDO="sudo" + fi + fi +} + +# pkg_install +pkg_install() { + detect_pkgmgr + case "$PKGMGR" in + nix) nix-env -iA "nixpkgs.$1" ;; + apt) $SUDO env DEBIAN_FRONTEND=noninteractive apt-get install -y "$2" ;; + brew) brew install "$3" ;; + apk) apk add --no-cache "$4" ;; + esac +} + +missing() { + ! command -v "$1" >/dev/null 2>&1 +} + +# verify_sha256 +verify_sha256() { + if command -v sha256sum >/dev/null 2>&1; then + actual="$(sha256sum "$1" | cut -d' ' -f1)" + else + actual="$(shasum -a 256 "$1" | cut -d' ' -f1)" + fi + if [ "$actual" != "$2" ]; then + echo "bootstrap: sha256 mismatch for $1" >&2 + echo " expected: $2" >&2 + echo " actual: $actual" >&2 + exit 1 + fi +} + +# apt has no golangci-lint package: install a pinned release archive +# from GitHub, verified by hardcoded sha256 (never curl | sh). +install_golangci_lint_release() { + case "$(uname -m)" in + x86_64) goarch="amd64"; sha="$GOLANGCI_LINT_SHA256_AMD64" ;; + aarch64|arm64) goarch="arm64"; sha="$GOLANGCI_LINT_SHA256_ARM64" ;; + *) + echo "bootstrap: unsupported architecture $(uname -m)" >&2 + exit 1 + ;; + esac + if missing curl; then pkg_install curl curl curl curl; fi + name="golangci-lint-${GOLANGCI_LINT_VERSION}-linux-${goarch}" + tmp="$(mktemp -d)" + curl -fsSL -o "$tmp/$name.tar.gz" \ + "https://github.com/golangci/golangci-lint/releases/download/v${GOLANGCI_LINT_VERSION}/${name}.tar.gz" + verify_sha256 "$tmp/$name.tar.gz" "$sha" + tar -xzf "$tmp/$name.tar.gz" -C "$tmp" + $SUDO install -m 0755 "$tmp/$name/golangci-lint" /usr/local/bin/golangci-lint + rm -rf "$tmp" +} + +ensure_golangci_lint() { + if ! missing golangci-lint; then return 0; fi + detect_pkgmgr + case "$PKGMGR" in + apt) install_golangci_lint_release ;; + *) pkg_install golangci-lint golangci-lint golangci-lint golangci-lint ;; + esac +} + +# CGO dependencies for govips (image processing) +ensure_cgo_deps() { + if missing pkg-config; then + pkg_install pkg-config pkg-config pkg-config pkgconfig + fi + if ! pkg-config --exists vips; then + pkg_install vips libvips-dev vips vips-dev + fi + if ! pkg-config --exists libheif; then + pkg_install libheif libheif-dev libheif libheif-dev + fi +} + +main() { + cd "$ROOT" + + # Base tooling + if missing git; then pkg_install git git git git; fi + if missing make; then pkg_install gnumake make make make; fi + + # Go toolchain and linter + if missing go; then pkg_install go golang go go; fi + ensure_golangci_lint + + # CGO image libraries + ensure_cgo_deps + + go mod download + + echo "bootstrap complete" +} + +main "$@" diff --git a/script/check b/script/check new file mode 100755 index 0000000..cc046f7 --- /dev/null +++ b/script/check @@ -0,0 +1,15 @@ +#!/bin/sh +# script/check: run all checks (test, lint, fmt-check). Our own +# extension to scripts-to-rule-them-all. Must not modify any files. +# Generic: usually needs no adaptation. +set -eu + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)" + +main() { + "$SCRIPT_DIR/test" + "$SCRIPT_DIR/lint" + "$SCRIPT_DIR/fmt-check" +} + +main "$@" diff --git a/script/cibuild b/script/cibuild new file mode 100755 index 0000000..e20e047 --- /dev/null +++ b/script/cibuild @@ -0,0 +1,15 @@ +#!/bin/sh +# script/cibuild: run the CI build. The Dockerfile runs the checks +# (make fmt-check, lint, test), so a successful build implies a green +# repo. Generic: needs no adaptation. The Gitea workflow runs this on +# push. +set -eu + +ROOT="$(cd "$(dirname "$0")/.." && pwd -P)" + +main() { + cd "$ROOT" + docker build . +} + +main "$@" diff --git a/script/docker b/script/docker new file mode 100755 index 0000000..2884e41 --- /dev/null +++ b/script/docker @@ -0,0 +1,15 @@ +#!/bin/sh +# script/docker: build the Docker image tagged with the project name. +# Identical in all repos; the tag comes from script/projectname. +# Generic: needs no adaptation. +set -eu + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)" +ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)" + +main() { + cd "$ROOT" + docker build -t "$("$SCRIPT_DIR/projectname")" . +} + +main "$@" diff --git a/script/fmt b/script/fmt new file mode 100755 index 0000000..976c3a2 --- /dev/null +++ b/script/fmt @@ -0,0 +1,14 @@ +#!/bin/sh +# script/fmt: format all files (writes). +set -eu + +ROOT="$(cd "$(dirname "$0")/.." && pwd -P)" + +main() { + cd "$ROOT" + echo "Formatting code..." + # shellcheck disable=SC2046 # word splitting of file list is wanted + gofmt -w $(find . -name '*.go' -not -path './vendor/*') +} + +main "$@" diff --git a/script/fmt-check b/script/fmt-check new file mode 100755 index 0000000..848fdc6 --- /dev/null +++ b/script/fmt-check @@ -0,0 +1,18 @@ +#!/bin/sh +# script/fmt-check: check formatting (read-only). Same scope as +# script/fmt, but fails instead of writing. +set -eu + +ROOT="$(cd "$(dirname "$0")/.." && pwd -P)" + +main() { + cd "$ROOT" + echo "Checking formatting..." + if [ -n "$(gofmt -l . | grep -v '^vendor/')" ]; then + echo "Files need formatting:" + gofmt -l . | grep -v '^vendor/' + exit 1 + fi +} + +main "$@" diff --git a/script/install-precommit b/script/install-precommit new file mode 100755 index 0000000..49da044 --- /dev/null +++ b/script/install-precommit @@ -0,0 +1,16 @@ +#!/bin/sh +# script/install-precommit: install the git pre-commit hook that runs +# script/precommit. Our own extension to scripts-to-rule-them-all. +# Generic: needs no adaptation. +set -eu + +ROOT="$(cd "$(dirname "$0")/.." && pwd -P)" + +main() { + cd "$ROOT" + printf '#!/bin/sh\nset -e\nscript/precommit\n' > .git/hooks/pre-commit + chmod +x .git/hooks/pre-commit + echo "pre-commit hook installed: runs script/precommit" +} + +main "$@" diff --git a/script/lint b/script/lint new file mode 100755 index 0000000..02c75c1 --- /dev/null +++ b/script/lint @@ -0,0 +1,23 @@ +#!/bin/sh +# script/lint: run the linter. CGO dependencies (pkg-config, vips, +# libheif) come from nix-shell when not already available (e.g. inside +# a Docker build or an existing nix-shell). +set -eu + +ROOT="$(cd "$(dirname "$0")/.." && pwd -P)" + +run_with_cgo_deps() { + if command -v pkg-config >/dev/null 2>&1; then + sh -c "$1" + else + nix-shell -p pkg-config vips libheif golangci-lint git --run "$1" + fi +} + +main() { + cd "$ROOT" + echo "Running linter..." + run_with_cgo_deps "golangci-lint run" +} + +main "$@" diff --git a/script/precommit b/script/precommit new file mode 100755 index 0000000..c59fbe7 --- /dev/null +++ b/script/precommit @@ -0,0 +1,21 @@ +#!/bin/sh +# script/precommit: run by the git pre-commit hook; fails the commit if +# checks fail. Our own extension to scripts-to-rule-them-all. Go repo +# extras: go mod tidy must not change go.mod/go.sum. +set -eu + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)" +ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)" + +main() { + cd "$ROOT" + go mod tidy + git diff --exit-code -- go.mod go.sum || { + echo "precommit: go mod tidy changed go.mod/go.sum;" \ + "stage the changes and retry" >&2 + exit 1 + } + "$SCRIPT_DIR/check" +} + +main "$@" diff --git a/script/projectname b/script/projectname new file mode 100755 index 0000000..f57aed5 --- /dev/null +++ b/script/projectname @@ -0,0 +1,12 @@ +#!/bin/sh +# script/projectname: output the name of this project. Our own +# extension to scripts-to-rule-them-all. Other scripts that need the +# name (e.g. script/docker) call this, so they can stay identical +# across all repos. +set -eu + +main() { + echo "pixa" +} + +main "$@" diff --git a/script/setup b/script/setup new file mode 100755 index 0000000..53327ba --- /dev/null +++ b/script/setup @@ -0,0 +1,14 @@ +#!/bin/sh +# script/setup: set up the repo for development after a fresh clone: +# installs dependencies (script/bootstrap) and the git pre-commit hook. +# Add any repo-specific initialization (db init, .env template) here. +set -eu + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)" + +main() { + "$SCRIPT_DIR/bootstrap" + "$SCRIPT_DIR/install-precommit" +} + +main "$@" diff --git a/script/test b/script/test new file mode 100755 index 0000000..d869902 --- /dev/null +++ b/script/test @@ -0,0 +1,23 @@ +#!/bin/sh +# script/test: run the test suite. CGO dependencies (pkg-config, vips, +# libheif) come from nix-shell when not already available (e.g. inside +# a Docker build or an existing nix-shell). +set -eu + +ROOT="$(cd "$(dirname "$0")/.." && pwd -P)" + +run_with_cgo_deps() { + if command -v pkg-config >/dev/null 2>&1; then + sh -c "$1" + else + nix-shell -p pkg-config vips libheif golangci-lint git --run "$1" + fi +} + +main() { + cd "$ROOT" + echo "Running tests..." + run_with_cgo_deps "CGO_ENABLED=1 go test -timeout 30s -v ./..." +} + +main "$@" -- 2.49.1 From 8f36838b13631bbf2f9a8b01d806f5308113d038 Mon Sep 17 00:00:00 2001 From: sneak Date: Tue, 7 Jul 2026 01:57:04 +0200 Subject: [PATCH 2/2] Refresh vendored REPO_POLICIES.md from prompts@origin/main --- REPO_POLICIES.md | 252 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 239 insertions(+), 13 deletions(-) diff --git a/REPO_POLICIES.md b/REPO_POLICIES.md index 5f8e062..bc2f161 100644 --- a/REPO_POLICIES.md +++ b/REPO_POLICIES.md @@ -1,6 +1,6 @@ --- title: Repository Policies -last_modified: 2026-02-22 +last_modified: 2026-07-06 --- This document covers repository structure, tooling, and workflow standards. Code @@ -34,10 +34,46 @@ style conventions are in separate documents: every file before committing. There are zero exceptions to this rule. - Every repo with software must have a root `Makefile` with these targets: - `make test`, `make lint`, `make fmt` (writes), `make fmt-check` (read-only), - `make check` (prereqs: `test`, `lint`, `fmt-check`), `make docker`, and - `make hooks` (installs pre-commit hook). A model Makefile is at - `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`. + `make bootstrap`, `make setup`, `make test`, `make lint`, `make fmt` (writes), + `make fmt-check` (read-only), `make check` (runs `test`, `lint`, `fmt-check`), + `make docker`, and `make hooks` (installs pre-commit hook). A model Makefile + is at `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`. + +- Repos follow the + [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all) + pattern: the implementation of each Makefile target lives in an executable + script in `script/` (`script/bootstrap`, `script/setup`, `script/test`, + `script/lint`, `script/fmt`, `script/fmt-check`, `script/check`, + `script/docker`), and the Makefile targets are thin shims that call them. The + scripts must be POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they run in + minimal containers (e.g. alpine images have no bash); locate the repo root + with `$(cd "$(dirname "$0")/.." && pwd -P)` and `cd` there before acting. From + the standard's canonical set we use `bootstrap`, `setup` (make the repo ready + for development after a fresh clone: runs `bootstrap`, then + `install-precommit`, plus any repo-specific initialization), `test`, and + `cibuild`. `script/bootstrap` installs all dependencies idempotently and + assumes nothing is present: base tools come from nix, apt, brew, or apk + (detected in that order; apt runs noninteractive). For node it uses the + installed node if present; otherwise it installs a PINNED node version via + nvm, first installing nvm itself if missing — from a hash-verified GitHub + release archive (never `curl | sh`), with bash installed as an explicit + prerequisite since nvm requires bash. yarn is then pinned via + `corepack prepare yarn@ --activate`. Never install "latest" or "lts"; + always exact versions. `script/cibuild` runs the CI build: it changes to the + repo root and runs `docker build .`; the Gitea workflow calls it. Four further + scripts are our own extensions to the standard: `script/check` runs + `script/test`, `script/lint`, and `script/fmt-check`; `script/precommit` is + what the git pre-commit hook runs, and it calls `script/check`; + `script/install-precommit` installs the git pre-commit hook (the `make hooks` + target shims to it); and `script/projectname` (literally that filename) simply + outputs the project's name. Scripts that need the name call + `script/projectname` — e.g. `script/docker` assembles its image tag from it — + so those scripts stay byte-identical across all repos. Repo-type-specific + pre-commit extras (e.g. `go mod tidy` verification in Go repos) belong in + `script/precommit`, not in the hook itself. Model scripts are at + `https://git.eeqj.de/sneak/prompts/raw/branch/main/script/`. The README + must document the provided scripts in an **Entrypoints** section (see the + README requirements below). - Always use Makefile targets (`make fmt`, `make test`, `make lint`, etc.) instead of invoking the underlying tools directly. The Makefile is the single @@ -57,11 +93,83 @@ style conventions are in separate documents: as a build step so the build fails if the branch is not green. For non-server repos, the Dockerfile should bring up a development environment and run `make check`. For server repos, `make check` should run as an early build - stage before the final image is assembled. + stage before the final image is assembled. Dockerfiles install development + prerequisites by running `script/bootstrap` rather than duplicating installs + inline; COPY `script/` and the dependency manifests (`package.json` + + `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it so the bootstrap + layer stays cached until dependencies change. + +- **Dockerfiles must use a separate lint stage for fail-fast feedback.** Go + repos use a multistage build where linting runs in an independent stage based + on the `golangci/golangci-lint` image (pinned by hash). This stage runs + `make fmt-check` and `make lint` before the full build begins. The build stage + then declares an explicit dependency on the lint stage via + `COPY --from=lint /src/go.sum /dev/null`, which forces BuildKit to complete + linting before proceeding to compilation and tests. This ensures lint failures + surface in seconds rather than minutes, without blocking on dependency + download or compilation in the build stage. + + The standard pattern for a Go repo Dockerfile is: + + ```dockerfile + # Lint stage — fast feedback on formatting and lint issues + # golangci/golangci-lint:v2.x.x, YYYY-MM-DD + FROM golangci/golangci-lint@sha256:... AS lint + WORKDIR /src + COPY go.mod go.sum ./ + RUN go mod download + COPY . . + RUN make fmt-check + RUN make lint + + # Build stage + # golang:1.x-alpine, YYYY-MM-DD + FROM golang@sha256:... AS builder + WORKDIR /src + + # Force BuildKit to run the lint stage before proceeding + COPY --from=lint /src/go.sum /dev/null + + COPY go.mod go.sum ./ + RUN go mod download + COPY . . + RUN make test + + ARG VERSION=dev + RUN CGO_ENABLED=0 go build -trimpath \ + -ldflags="-s -w -X main.Version=${VERSION}" \ + -o /app ./cmd/app/ + + # Runtime stage + FROM alpine@sha256:... + COPY --from=builder /app /usr/local/bin/app + ENTRYPOINT ["app"] + ``` + + Key points: + - The lint stage uses the `golangci/golangci-lint` image directly (it + includes both Go and the linter), so there is no need to install the + linter separately. + - `COPY --from=lint /src/go.sum /dev/null` is a no-op file copy that creates + a stage dependency. BuildKit runs stages in parallel by default; without + this line, the build stage would not wait for lint to finish and a lint + failure might not fail the overall build. + - If the project uses `//go:embed` directives that reference build artifacts + (e.g. a web frontend compiled in a separate stage), the lint stage must + create placeholder files so the embed directives resolve. Example: + `RUN mkdir -p web/dist && touch web/dist/index.html web/dist/style.css`. + The lint stage should not depend on the actual build output — it exists to + fail fast. + - If the project requires CGO or system libraries for linting (e.g. + `vips-dev`), install them in the lint stage with `apk add`. + - The build stage runs `make test` after compilation setup. Tests run in the + build stage, not the lint stage, because they may require compiled + artifacts or heavier dependencies. - Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that - runs `docker build .` on push. Since the Dockerfile already runs `make check`, - a successful build implies all checks pass. + runs `script/cibuild` (which runs `docker build .`) on push. Since the + Dockerfile already runs `make check`, a successful build implies all checks + pass. - Use platform-standard formatters: `black` for Python, `prettier` for JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with @@ -69,9 +177,11 @@ style conventions are in separate documents: Markdown (hard-wrap at 80 columns). Documentation and writing repos (Markdown, HTML, CSS) should also have `.prettierrc` and `.prettierignore`. -- Pre-commit hook: `make check` if local testing is possible, otherwise - `make lint && make fmt-check`. The Makefile should provide a `make hooks` - target to install the pre-commit hook. +- Pre-commit hook: runs `script/precommit`, which calls `script/check`. If local + testing is not possible in the repo, `script/precommit` may skip `script/test` + and run only `script/lint` and `script/fmt-check`. The hook is installed by + `script/install-precommit`; the Makefile must provide a `make hooks` target + that shims to it. - All repos with software must have tests that run via the platform-standard test framework (`go test`, `pytest`, `jest`/`vitest`, etc.). If no meaningful @@ -82,6 +192,42 @@ style conventions are in separate documents: - `make test` must complete in under 20 seconds. Add a 30-second timeout in the Makefile. +- **`make test` should use the conditional verbose rerun pattern.** Run tests + without `-v` (verbose) first. If tests fail, automatically rerun with `-v` to + show full output. This keeps CI logs and `docker build` output clean on + success (just package/suite summaries) while providing full diagnostic detail + on failure (every test case, every assertion). The general shell pattern: + + ```makefile + test: + @ || \ + { echo "--- Rerunning with -v for details ---"; \ + ; exit 1; } + ``` + + Go example: + + ```makefile + test: + @go test -timeout 30s -race -cover ./... || \ + { echo "--- Rerunning with -v for details ---"; \ + go test -timeout 30s -race -v ./...; exit 1; } + ``` + + Python example: + + ```makefile + test: + @python -m pytest || \ + { echo "--- Rerunning with -v for details ---"; \ + python -m pytest -v; exit 1; } + ``` + + The `exit 1` ensures the target always fails after a rerun — the first run + already proved the tests are broken, so the build must not pass even if a + flaky test happens to succeed on the second attempt. The rerun exists solely + for diagnostic output. + - Docker builds must complete in under 5 minutes. - `make check` must not modify any files in the repo. Tests may use temporary @@ -98,6 +244,13 @@ style conventions are in separate documents: `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up a new repo. +- **No build artifacts in version control.** Code-derived data (compiled + bundles, minified output, generated assets) must never be committed to the + repository if it can be avoided. The build process (e.g. Dockerfile, Makefile) + should generate these at build time. Notable exception: Go protobuf generated + files (`.pb.go`) ARE committed because repos need to work with `go get`, which + downloads code but does not execute code generation. + - Never use `git add -A` or `git add .`. Always stage files explicitly by name. - Never force-push to `main`. @@ -121,12 +274,76 @@ style conventions are in separate documents: - Dockerized web services listen on port 8080 by default, overridable with `PORT`. +- **HTTP/web services must be hardened for production internet exposure before + tagging 1.0.** This means full compliance with security best practices + including, without limitation, all of the following: + - **Security headers** on every response: + - `Strict-Transport-Security` (HSTS) with `max-age` of at least one year + and `includeSubDomains`. + - `Content-Security-Policy` (CSP) with a restrictive default policy + (`default-src 'self'` as a baseline, tightened per-resource as + needed). Never use `unsafe-inline` or `unsafe-eval` unless + unavoidable, and document the reason. + - `X-Frame-Options: DENY` (or `SAMEORIGIN` if framing is required). + Prefer the `frame-ancestors` CSP directive as the primary control. + - `X-Content-Type-Options: nosniff`. + - `Referrer-Policy: strict-origin-when-cross-origin` (or stricter). + - `Permissions-Policy` restricting access to browser features the + application does not use (camera, microphone, geolocation, etc.). + - **Request and response limits:** + - Maximum request body size enforced on all endpoints (e.g. Go + `http.MaxBytesReader`). Choose a sane default per-route; never accept + unbounded input. + - Maximum response body size where applicable (e.g. paginated APIs). + - `ReadTimeout` and `ReadHeaderTimeout` on the `http.Server` to defend + against slowloris attacks. + - `WriteTimeout` on the `http.Server`. + - `IdleTimeout` on the `http.Server`. + - Per-handler execution time limits via `context.WithTimeout` or + chi/stdlib `middleware.Timeout`. + - **Authentication and session security:** + - Rate limiting on password-based authentication endpoints. API keys are + high-entropy and not susceptible to brute force, so they are exempt. + - CSRF tokens on all state-mutating HTML forms. API endpoints + authenticated via `Authorization` header (Bearer token, API key) are + exempt because the browser does not attach these automatically. + - Passwords stored using bcrypt, scrypt, or argon2 — never plain-text, + MD5, or SHA. + - Session cookies set with `HttpOnly`, `Secure`, and `SameSite=Lax` (or + `Strict`) attributes. + - **Reverse proxy awareness:** + - True client IP detection when behind a reverse proxy + (`X-Forwarded-For`, `X-Real-IP`). The application must accept + forwarded headers only from a configured set of trusted proxy + addresses — never trust `X-Forwarded-For` unconditionally. + - **CORS:** + - Authenticated endpoints must restrict `Access-Control-Allow-Origin` to + an explicit allowlist of known origins. Wildcard (`*`) is acceptable + only for public, unauthenticated read-only APIs. + - **Error handling:** + - Internal errors must never leak stack traces, SQL queries, file paths, + or other implementation details to the client. Return generic error + messages in production; detailed errors only when `DEBUG` is enabled. + - **TLS:** + - Services never terminate TLS directly. They are always deployed behind + a TLS-terminating reverse proxy. The service itself listens on plain + HTTP. However, HSTS headers and `Secure` cookie flags must still be + set by the application so that the browser enforces HTTPS end-to-end. + + This list is non-exhaustive. Apply defense-in-depth: if a standard security + hardening measure exists for HTTP services and is not listed here, it is + still expected. When in doubt, harden. + - `README.md` is the primary documentation. Required sections: - **Description**: First line must include the project name, purpose, category (web server, SPA, CLI tool, etc.), license, and author. Example: "µPaaS is an MIT-licensed Go web application by @sneak that receives git-frontend webhooks and deploys applications via Docker in realtime." - **Getting Started**: Copy-pasteable install/usage code block. + - **Entrypoints**: Opens by stating that the repo adheres to the + [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all) + standard (with that link), then documents each provided `script/` + entrypoint and its purpose. - **Rationale**: Why does this exist? - **Design**: How is the program structured? - **TODO**: Update meticulously, even between commits. When planning, put @@ -144,8 +361,14 @@ style conventions are in separate documents: - Use SemVer. - Database migrations live in `internal/db/migrations/` and must be embedded in - the binary. Pre-1.0.0: modify existing migrations (no installed base assumed). - Post-1.0.0: add new migration files. + the binary. + - `000_migration.sql` — contains ONLY the creation of the migrations + tracking table itself. Nothing else. + - `001_schema.sql` — the full application schema. + - **Pre-1.0.0:** never add additional migration files (002, 003, etc.). + There is no installed base to migrate. Edit `001_schema.sql` directly. + - **Post-1.0.0:** add new numbered migration files for each schema change. + Never edit existing migrations after release. - All repos should have an `.editorconfig` enforcing the project's indentation settings. @@ -175,6 +398,9 @@ style conventions are in separate documents: - `README.md`, `.git`, `.gitignore`, `.editorconfig` - `LICENSE`, `REPO_POLICIES.md` (copy from the `prompts` repo) - `Makefile` + - `script/` entrypoints (`bootstrap`, `setup`, `projectname`, `test`, + `lint`, `fmt`, `fmt-check`, `check`, `docker`, `cibuild`, `precommit`, + `install-precommit`) - `Dockerfile`, `.dockerignore` - `.gitea/workflows/check.yml` - Go: `go.mod`, `go.sum`, `.golangci.yml` -- 2.49.1