Adopt scripts-to-rule-them-all: script/ entrypoints, Makefile shims

.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

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..."
+	@script/fmt-check
-	@test -z "$$(gofmt -l . | grep -v '^vendor/')" || (echo "Files need formatting:"; gofmt -l . | grep -v '^vendor/'; exit 1)
 
 # Format code
 fmt:
-	@echo "Formatting code..."
+	@script/fmt
-	gofmt -w $$(find . -name '*.go' -not -path './vendor/*')
 
 # Run linter
 lint:
-	@echo "Running linter..."
+	@script/lint
-	$(NIX_RUN_PREFIX)golangci-lint run$(NIX_RUN_SUFFIX)
 
 # Run tests (30-second timeout)
 test:
-	@echo "Running tests..."
+	@script/test
-	$(NIX_RUN_PREFIX)CGO_ENABLED=1 go test -timeout 30s -v ./...$(NIX_RUN_SUFFIX)
 
 # 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
+	@script/install-precommit
-	@printf 'make check\n' >> .git/hooks/pre-commit
-	@chmod +x .git/hooks/pre-commit

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.

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)

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-<arch>.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 <nix-attr> <apt-pkg> <brew-formula> <apk-pkg>
+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 <file> <expected-hash>
+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 "$@"

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 "$@"

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 "$@"

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 "$@"

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 "$@"

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 "$@"

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 "$@"

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 "$@"

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 "$@"

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 "$@"

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 "$@"

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 "$@"