From eaa164e83d2aef352467c54d6467cbb245b2628d Mon Sep 17 00:00:00 2001
From: sneak <sneak@sneak.berlin>
Date: Tue, 7 Jul 2026 01:56:42 +0200
Subject: [PATCH] Adopt scripts-to-rule-them-all: script/ entrypoints, Makefile
 shims

---
 .gitea/workflows/check.yml |   2 +-
 Makefile                   |  30 ++++-----
 README.md                  |  31 +++++++++-
 TODO.md                    |   2 +
 script/bootstrap           | 121 +++++++++++++++++++++++++++++++++++++
 script/check               |  15 +++++
 script/cibuild             |  15 +++++
 script/docker              |  15 +++++
 script/fmt                 |  14 +++++
 script/fmt-check           |  17 ++++++
 script/install-precommit   |  16 +++++
 script/lint                |  12 ++++
 script/precommit           |  21 +++++++
 script/projectname         |  12 ++++
 script/setup               |  14 +++++
 script/test                |  12 ++++
 16 files changed, 331 insertions(+), 18 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 f1dc0cb..3ea8e88 100644
--- a/.gitea/workflows/check.yml
+++ b/.gitea/workflows/check.yml
@@ -13,4 +13,4 @@ jobs:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4, 2024-10-13
 
       - name: Build (runs make check inside Dockerfile)
-        run: docker build .
+        run: script/cibuild
diff --git a/Makefile b/Makefile
index 31ee1f5..6a669f4 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: all build lint fmt fmt-check test check clean docker hooks
+.PHONY: all bootstrap setup build lint fmt fmt-check test check clean docker hooks
 
 BINARY := upaasd
 VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
@@ -7,37 +7,37 @@ LDFLAGS := -X main.Version=$(VERSION) -X main.Buildarch=$(BUILDARCH)
 
 all: check build
 
+bootstrap:
+	@script/bootstrap
+
+setup:
+	@script/setup
+
 build:
 	go build -ldflags "$(LDFLAGS)" -o bin/$(BINARY) ./cmd/upaasd
 
 lint:
-	golangci-lint run --config .golangci.yml ./...
+	@script/lint
 
 fmt:
-	gofmt -s -w .
-	goimports -w .
-	npx prettier --write --tab-width 4 static/js/*.js
+	@script/fmt
 
 fmt-check:
-	@test -z "$$(gofmt -l .)" || (echo "Files not formatted:" && gofmt -l . && exit 1)
+	@script/fmt-check
 
 test:
-	go test -v -race -cover -timeout 30s ./...
+	@script/test
 
 # Check runs all validation without making changes
 # Used by CI and Docker build - fails if anything is wrong
-check: fmt-check lint test
-	@echo "==> All checks passed!"
+check:
+	@script/check
 
 docker:
-	docker build .
+	@script/docker
 
 hooks:
-	@echo "Installing pre-commit hook..."
-	@mkdir -p .git/hooks
-	@printf '#!/bin/sh\nmake check\n' > .git/hooks/pre-commit
-	@chmod +x .git/hooks/pre-commit
-	@echo "Pre-commit hook installed."
+	@script/install-precommit
 
 clean:
 	rm -rf bin/
diff --git a/README.md b/README.md
index 6c66e75..832a4a0 100644
--- a/README.md
+++ b/README.md
@@ -100,6 +100,31 @@ chi Router ──► Middleware Stack ──► Handler
 - **Async deployments**: Webhook triggers deploy via goroutine with `context.WithoutCancel()`
 - **Embedded assets**: Templates and static files embedded via `//go:embed`
 
+## 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 ("upaas")
+- `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`
+
 ## Development
 
 ### Prerequisites
@@ -111,14 +136,16 @@ chi Router ──► Middleware Stack ──► Handler
 ### Commands
 
 ```bash
+make bootstrap # Install all dependencies (idempotent)
+make setup     # Bootstrap + install git pre-commit hook
 make fmt       # Format code
 make fmt-check # Check formatting (read-only, fails if unformatted)
 make lint      # Run comprehensive linting
 make test      # Run tests with race detection (30s timeout)
-make check     # Verify everything passes (fmt-check, lint, test)
+make check     # Verify everything passes (test, lint, fmt-check)
 make build     # Build binary
 make docker    # Build Docker image
-make hooks     # Install pre-commit hook (runs make check)
+make hooks     # Install pre-commit hook (runs script/precommit)
 ```
 
 ### Commit Requirements
diff --git a/TODO.md b/TODO.md
index b5d970d..6b9d428 100644
--- a/TODO.md
+++ b/TODO.md
@@ -22,6 +22,8 @@ of the three lint classes blocking a green main.
 
 # Completed Steps
 
+- 2026-07-07 Adopted scripts-to-rule-them-all: `script/` entrypoints,
+  Makefile shims, README Entrypoints section
 - 2026-03-11: Monolithic env var editing with bulk save (#158).
 - 2026-03-10: Webhook event history UI page (#164); added missing
   Makefile docker and hooks targets plus test timeout (#159);
diff --git a/script/bootstrap b/script/bootstrap
new file mode 100755
index 0000000..b848b23
--- /dev/null
+++ b/script/bootstrap
@@ -0,0 +1,121 @@
+#!/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).
+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
+}
+
+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
+
+    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..2c9c55c
--- /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"
+    gofmt -s -w .
+    goimports -w .
+    npx prettier --write --tab-width 4 static/js/*.js
+}
+
+main "$@"
diff --git a/script/fmt-check b/script/fmt-check
new file mode 100755
index 0000000..b2111bc
--- /dev/null
+++ b/script/fmt-check
@@ -0,0 +1,17 @@
+#!/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"
+    if [ -n "$(gofmt -l .)" ]; then
+        echo "Files not formatted:"
+        gofmt -l .
+        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..8017180
--- /dev/null
+++ b/script/lint
@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/lint: run the linter.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    golangci-lint run --config .golangci.yml ./...
+}
+
+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..4784aba
--- /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 "upaas"
+}
+
+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..82f68ef
--- /dev/null
+++ b/script/test
@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/test: run the test suite.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    go test -v -race -cover -timeout 30s ./...
+}
+
+main "$@"