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

---
 .gitea/workflows/check.yml |  2 +-
 Makefile                   | 30 +++++++++-------
 README.md                  | 29 +++++++++++++++
 TODO.md                    |  2 ++
 script/bootstrap           | 73 ++++++++++++++++++++++++++++++++++++++
 script/check               | 15 ++++++++
 script/cibuild             | 14 ++++++++
 script/docker              | 15 ++++++++
 script/fmt                 | 12 +++++++
 script/fmt-check           | 18 ++++++++++
 script/install-precommit   | 17 +++++++++
 script/lint                | 12 +++++++
 script/precommit           | 21 +++++++++++
 script/projectname         | 12 +++++++
 script/setup               | 14 ++++++++
 script/test                | 18 ++++++++++
 16 files changed, 291 insertions(+), 13 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 fb6ef70..0a914ad 100644
--- a/.gitea/workflows/check.yml
+++ b/.gitea/workflows/check.yml
@@ -11,4 +11,4 @@ jobs:
       # actions/checkout v4, 2024-09-16
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
       - name: Build and check
-        run: docker build .
+        run: script/cibuild
diff --git a/Makefile b/Makefile
index ee3f835..04ff721 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: all check test lint fmt fmt-check build clean deps test-coverage test-integration install release release-snapshot docker hooks
+.PHONY: all bootstrap setup check test lint fmt fmt-check build clean deps test-coverage test-integration install release release-snapshot docker hooks
 
 # Version number
 VERSION := 0.1.0-dev
@@ -6,24 +6,33 @@ VERSION := 0.1.0-dev
 # Default target
 all: bsdaily
 
-# Combined pre-commit/CI gate: lint, format check, then tests.
-check: lint fmt-check test
+# Install all development dependencies.
+bootstrap:
+	@script/bootstrap
+
+# Prepare a fresh clone: bootstrap plus pre-commit hook.
+setup:
+	@script/setup
+
+# Combined pre-commit/CI gate: tests, lint, format check.
+check:
+	@script/check
 
 # Run tests only.
 test:
-	go test -race -timeout 30s ./...
+	@script/test
 
 # Check if code is formatted (read-only).
 fmt-check:
-	@test -z "$$(gofmt -l .)" || (echo "Files not formatted:" && gofmt -l . && exit 1)
+	@script/fmt-check
 
 # Format code.
 fmt:
-	go fmt ./...
+	@script/fmt
 
 # Run linter only.
 lint:
-	golangci-lint run ./...
+	@script/lint
 
 # Build binary (pure Go; no CGO required since we use modernc.org/sqlite).
 bsdaily: internal/*/*.go cmd/bsdaily/*.go
@@ -61,11 +70,8 @@ release-snapshot:
 
 # Build Docker image.
 docker:
-	docker build -t bsdaily .
+	@script/docker
 
 # Install pre-commit hook.
 hooks:
-	@printf '#!/bin/sh\nset -e\n' > .git/hooks/pre-commit
-	@printf 'go mod tidy\ngo fmt ./...\ngit diff --exit-code -- go.mod go.sum || { echo "go mod tidy changed files; please stage and retry"; exit 1; }\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 01a2967..f8defea 100644
--- a/README.md
+++ b/README.md
@@ -45,6 +45,35 @@ requests](https://git.eeqj.de/sneak/bsdaily/pulls) and pass CI to be merged.
 See [`REPO_POLICIES.md`](REPO_POLICIES.md) for detailed coding standards,
 tooling requirements, and workflow conventions.
 
+# 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 development dependencies (go,
+  golangci-lint, Go module download)
+- `script/setup` — make a fresh clone ready for development: runs
+  `script/bootstrap`, then `script/install-precommit`
+- `script/projectname` — print the project name (used for the Docker
+  image tag)
+- `script/test` — run the test suite (verbose rerun on failure)
+- `script/lint` — run `golangci-lint run ./...`
+- `script/fmt` — format all code (writes)
+- `script/fmt-check` — check formatting (read-only)
+- `script/check` — run `script/test`, `script/lint`, and
+  `script/fmt-check`
+- `script/docker` — build the Docker image tagged via
+  `script/projectname`
+- `script/cibuild` — CI entrypoint: `docker build .` (the Dockerfile
+  runs the checks)
+- `script/precommit` — pre-commit gate: `go mod tidy` + `go fmt` (must
+  not change files), then `script/check`
+- `script/install-precommit` — install the git pre-commit hook that
+  runs `script/precommit`
+
 # Problem Statement
 
 A Bluesky firehose ingester writes every observed post (and associated
diff --git a/TODO.md b/TODO.md
index 5da4bed..611a0b9 100644
--- a/TODO.md
+++ b/TODO.md
@@ -20,6 +20,8 @@ green with the new lint config.
 
 # Completed Steps
 
+- 2026-07-07 Adopted scripts-to-rule-them-all: `script/` entrypoints,
+  Makefile shims, README Entrypoints section
 - 2026-06-28: Fixed errcheck lint failures; added compilation smoke test;
   tidied go.mod.
 - 2026-06-28: Added repo scaffolding: README, LICENSE, Makefile,
diff --git a/script/bootstrap b/script/bootstrap
new file mode 100755
index 0000000..3a156e5
--- /dev/null
+++ b/script/bootstrap
@@ -0,0 +1,73 @@
+#!/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).
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+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
+}
+
+main() {
+    cd "$ROOT"
+
+    # Base tooling (every repo)
+    if missing git; then pkg_install git git git git; fi
+    if missing make; then pkg_install gnumake make make make; fi
+
+    # Go toolchain
+    if missing go; then pkg_install go golang go go; fi
+
+    # golangci-lint: packaged in nix, brew, and apk. There is no apt
+    # package; on apt systems install it manually from a hash-verified
+    # GitHub release archive (never curl | sh).
+    if missing golangci-lint; then
+        pkg_install golangci-lint golangci-lint golangci-lint golangci-lint
+    fi
+
+    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..3da5857
--- /dev/null
+++ b/script/cibuild
@@ -0,0 +1,14 @@
+#!/bin/sh
+# script/cibuild: run the CI build. The Dockerfile runs script/check
+# (via make check), so a successful build implies all checks pass.
+# 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..e95d111
--- /dev/null
+++ b/script/fmt
@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/fmt: format all files (writes).
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    go fmt ./...
+}
+
+main "$@"
diff --git a/script/fmt-check b/script/fmt-check
new file mode 100755
index 0000000..57e8e5c
--- /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"
+    unformatted="$(gofmt -l .)"
+    if [ -n "$unformatted" ]; then
+        echo "Files not formatted:" >&2
+        echo "$unformatted" >&2
+        exit 1
+    fi
+}
+
+main "$@"
diff --git a/script/install-precommit b/script/install-precommit
new file mode 100755
index 0000000..3519de6
--- /dev/null
+++ b/script/install-precommit
@@ -0,0 +1,17 @@
+#!/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"
+    hook=".git/hooks/pre-commit"
+    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..9b57aea
--- /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 ./...
+}
+
+main "$@"
diff --git a/script/precommit b/script/precommit
new file mode 100755
index 0000000..50f02ae
--- /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 and go fmt must leave the tree unchanged.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    go mod tidy
+    go fmt ./...
+    git diff --exit-code -- go.mod go.sum || {
+        echo "go mod tidy changed files; please stage and retry"
+        exit 1
+    }
+    "$SCRIPT_DIR/check"
+}
+
+main "$@"
diff --git a/script/projectname b/script/projectname
new file mode 100755
index 0000000..0b02f37
--- /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 "bsdaily"
+}
+
+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..f1a8a6a
--- /dev/null
+++ b/script/test
@@ -0,0 +1,18 @@
+#!/bin/sh
+# script/test: run the test suite. Quiet on success; on failure, rerun
+# verbosely for full diagnostic output (the exit 1 ensures the rerun
+# never turns a failure into a pass).
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    go test -race -timeout 30s ./... || {
+        echo "--- Rerunning with -v for details ---"
+        go test -race -timeout 30s -v ./...
+        exit 1
+    }
+}
+
+main "$@"