From 58f75147bed9aa78bf06716db7d67f80e303e56e Mon Sep 17 00:00:00 2001 From: sneak Date: Tue, 8 Sep 2026 04:58:31 +0000 Subject: [PATCH 1/5] Build with --no-cache so the check layer actually runs (closes #26) script/cibuild was a plain `docker build .` and the Dockerfile does `COPY . .` followed by `RUN make check`, so on an unchanged tree Docker served the check layer from cache: the suite never ran and the build still exited 0. Measured here before the change, a second run on a byte-identical tree returned in 0.286s with `RUN make check` CACHED. script/cibuild and script/docker now pass --no-cache. The canonical text asserting that a bare `docker build .` proves the checks ran was wrong in REPO_POLICIES.md, both checklists and the Go styleguide, and is corrected in all of them. Model: opus-5 --- README.md | 7 ++++--- TODO.md | 5 +++++ prompts/CODE_STYLEGUIDE_GO.md | 11 +++++++---- prompts/EXISTING_REPO_CHECKLIST.md | 10 ++++++---- prompts/NEW_REPO_CHECKLIST.md | 11 ++++++++--- prompts/REPO_POLICIES.md | 26 ++++++++++++++++++-------- script/cibuild | 7 ++++--- script/docker | 4 +++- 8 files changed, 55 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 3991bfc..169f3c7 100644 --- a/README.md +++ b/README.md @@ -123,9 +123,10 @@ alpine. We provide: - `script/check` — run all checks: `test`, `lint`, `fmt-check` (our own extension) - `script/docker` — build the Docker image, tagged via `script/projectname` - (byte-identical across repos) -- `script/cibuild` — cd to the repo root and `docker build .` (what CI runs; the - image build runs `script/check`) + (byte-identical across repos); builds with `--no-cache`, like `script/cibuild` +- `script/cibuild` — cd to the repo root and `docker build --no-cache .` (what + CI runs; the image build runs `script/check`, and `--no-cache` is what stops + Docker serving those checks from cache on an unchanged tree) - `script/precommit` — run by the git pre-commit hook (our own extension); calls `script/check` - `script/install-precommit` — installs the git pre-commit hook (our own diff --git a/TODO.md b/TODO.md index 721e9ab..fe066ae 100644 --- a/TODO.md +++ b/TODO.md @@ -21,6 +21,11 @@ fmt-check, and commit. # Completed Steps +- 2026-09-08: Closed the false green in the canonical CI gate: `script/cibuild` + and `script/docker` now build with `--no-cache`, so the Dockerfile's check + layers cannot be served from cache on an unchanged tree, and the text claiming + a bare `docker build .` proves the checks ran is corrected in + `REPO_POLICIES.md`, both checklists and the Go styleguide. - 2026-09-03: Added `-count=1` to both `go test` invocations in the canonical Go `make test` example in `REPO_POLICIES.md`, so the target cannot report a cached pass it did not earn, and documented that Go's test-result cache is a diff --git a/prompts/CODE_STYLEGUIDE_GO.md b/prompts/CODE_STYLEGUIDE_GO.md index ce2b903..39c4957 100644 --- a/prompts/CODE_STYLEGUIDE_GO.md +++ b/prompts/CODE_STYLEGUIDE_GO.md @@ -1,6 +1,6 @@ --- title: Code Styleguide — Go -last_modified: 2026-03-18 +last_modified: 2026-09-08 --- 1. Try to hard wrap long lines at 77 characters or less. @@ -101,9 +101,12 @@ last_modified: 2026-03-18 `golangci-lint`. 1. Write a `Dockerfile` for every repo, even if it only runs the tests and - linting. `docker build .` should always make sure that the code is in an - able-to-be-compiled state, linted, and any tests run. The Docker build - should fail if linting doesn't pass. + linting. `script/cibuild` and `script/docker` should always make sure that + the code is in an able-to-be-compiled state, linted, and any tests run, and + the build should fail if linting doesn't pass. Go through those scripts + rather than a bare `docker build .`: they pass `--no-cache`, without which + an unchanged tree serves the check layers from cache and the build reports a + green it never ran. 1. Every repo must have a `Makefile`. See [Repository Policies](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md) diff --git a/prompts/EXISTING_REPO_CHECKLIST.md b/prompts/EXISTING_REPO_CHECKLIST.md index 53be732..037cda7 100644 --- a/prompts/EXISTING_REPO_CHECKLIST.md +++ b/prompts/EXISTING_REPO_CHECKLIST.md @@ -1,6 +1,6 @@ --- title: Existing Repo Checklist -last_modified: 2026-07-06 +last_modified: 2026-09-08 --- Use this checklist when beginning work in a repo that may not yet conform to our @@ -30,9 +30,10 @@ with your task. - [ ] `.editorconfig` exists — fetch from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig` - [ ] `Dockerfile` and `.dockerignore` exist; Dockerfile runs `make check` as a - build step — fetch `.dockerignore` from + build step, and `script/cibuild` and `script/docker` build it with + `--no-cache` — fetch `.dockerignore` from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` -- [ ] Gitea Actions workflow in `.gitea/workflows/` runs `docker build .` on +- [ ] Gitea Actions workflow in `.gitea/workflows/` runs `script/cibuild` on push — reference `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitea/workflows/check.yml` - [ ] Language-specific config: @@ -106,5 +107,6 @@ with your task. # Final - [ ] `make check` passes -- [ ] `docker build` succeeds +- [ ] `script/cibuild` succeeds and demonstrably executed the checks — a + sub-second build, or `CACHED` on a check layer, means nothing ran - [ ] Commit and merge fixes before starting your actual task diff --git a/prompts/NEW_REPO_CHECKLIST.md b/prompts/NEW_REPO_CHECKLIST.md index 5f46b40..6f3dc8b 100644 --- a/prompts/NEW_REPO_CHECKLIST.md +++ b/prompts/NEW_REPO_CHECKLIST.md @@ -1,6 +1,6 @@ --- title: New Repo Checklist -last_modified: 2026-07-06 +last_modified: 2026-09-08 --- Use this checklist when creating a new repository from scratch. Follow the steps @@ -90,8 +90,11 @@ are thin shims calling them. Model scripts: - [ ] `script/projectname` — outputs the project name (used by `script/docker` for the image tag) - [ ] `script/docker` / `make docker` — builds Docker image, tagged via - `script/projectname` (byte-identical across repos) -- [ ] `script/cibuild` — cd to repo root, `docker build .` (what CI runs) + `script/projectname` (byte-identical across repos); passes `--no-cache` + like `script/cibuild` +- [ ] `script/cibuild` — cd to repo root, `docker build --no-cache .` (what CI + runs; without `--no-cache` an unchanged tree serves the check layers from + cache and the build reports a green it never ran) - [ ] `script/precommit` — called by the pre-commit hook; runs `script/check` - [ ] `script/install-precommit` — installs the pre-commit hook that runs `script/precommit` @@ -103,6 +106,8 @@ are thin shims calling them. Model scripts: - [ ] `make check` passes - [ ] `make docker` succeeds +- [ ] `script/cibuild` succeeds and demonstrably executed the checks — a + sub-second build, or `CACHED` on a check layer, means nothing ran - [ ] No secrets in repo - [ ] No mutable image/package references - [ ] No unnecessary files in repo root diff --git a/prompts/REPO_POLICIES.md b/prompts/REPO_POLICIES.md index 2213b27..72c0a0f 100644 --- a/prompts/REPO_POLICIES.md +++ b/prompts/REPO_POLICIES.md @@ -1,6 +1,6 @@ --- title: Repository Policies -last_modified: 2026-09-03 +last_modified: 2026-09-08 --- This document covers repository structure, tooling, and workflow standards. Code @@ -60,10 +60,10 @@ style conventions are in separate documents: 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`; + repo root and runs `docker build --no-cache .`; 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 @@ -99,6 +99,15 @@ style conventions are in separate documents: `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it so the bootstrap layer stays cached until dependencies change. +- **Any build that runs checks is built with `--no-cache`.** Docker invalidates + a `COPY` layer only when the copied content changes, so on an unchanged tree + the check `RUN` is served from cache, nothing executes, and the build still + exits 0. `script/cibuild` and `script/docker` therefore pass `--no-cache`, and + a bare `docker build .` is not evidence that anything ran: a sub-second build + reporting success is a cache hit, not a result. Never invalidate by pruning — + `docker builder prune` and friends destroy a build cache shared with every + other build on the host. + - **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 @@ -167,9 +176,10 @@ style conventions are in separate documents: artifacts or heavier dependencies. - Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that - runs `script/cibuild` (which 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 --no-cache .`) on push. Since + the Dockerfile already runs `make check`, a successful build implies all + checks pass — an implication that holds only because of the `--no-cache` + above. - Use platform-standard formatters: `black` for Python, `prettier` for JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with diff --git a/script/cibuild b/script/cibuild index 75cc3e6..51d3b80 100755 --- a/script/cibuild +++ b/script/cibuild @@ -1,13 +1,14 @@ #!/bin/sh -# script/cibuild: run the CI build. The Dockerfile runs script/check, so -# a successful build implies all checks pass. +# script/cibuild: run the CI build. --no-cache because the checks are +# RUN steps: on an unchanged tree Docker serves them from cache and the +# build exits 0 having run nothing. set -eu ROOT="$(cd "$(dirname "$0")/.." && pwd -P)" main() { cd "$ROOT" - docker build . + docker build --no-cache . } main "$@" diff --git a/script/docker b/script/docker index 9b9ea86..f72ee15 100755 --- a/script/docker +++ b/script/docker @@ -1,6 +1,8 @@ #!/bin/sh # script/docker: build the Docker image tagged with the project name. # Identical in all repos; the tag comes from script/projectname. +# --no-cache for the same reason as script/cibuild: a cached check layer +# is a check that did not run. set -eu SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)" @@ -8,7 +10,7 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)" main() { cd "$ROOT" - docker build -t "$("$SCRIPT_DIR/projectname")" . + docker build --no-cache -t "$("$SCRIPT_DIR/projectname")" . } main "$@" From 85bea7681e5163a4f449392e20a1020bfd1420d2 Mon Sep 17 00:00:00 2001 From: sneak Date: Tue, 8 Sep 2026 04:58:31 +0000 Subject: [PATCH 2/5] Compare versions when bootstrap installs a pinned tool (closes #28) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The canonical `if missing ; then install; fi` guard tests PATH presence and never version, so on any already-provisioned machine a pin is inert and a version bump is a no-op, while the Dockerfile installs the pinned version into a clean image and CI then disagrees with local about what the tool is. Comparing versions alone is not enough either: an installer writes to its own directory while callers resolve through PATH, so a shadowing binary lets the install succeed and change nothing anyone sees. REPO_POLICIES.md now states the whole form — exact whole-token comparison, mis-parse falling through to a reinstall, re-resolution through PATH after installing, and a call site that prints the version. Model: opus-5 --- TODO.md | 5 +++++ prompts/REPO_POLICIES.md | 22 ++++++++++++++++++++++ 2 files changed, 27 insertions(+) diff --git a/TODO.md b/TODO.md index fe066ae..44b3d27 100644 --- a/TODO.md +++ b/TODO.md @@ -21,6 +21,11 @@ fmt-check, and commit. # Completed Steps +- 2026-09-08: Made a pinned tool in `script/bootstrap` actually reach the host. + `REPO_POLICIES.md` now requires comparing the installed version against the + pin rather than testing `PATH` presence, and re-resolving the binary through + `PATH` after installing, so a version bump cannot be a silent no-op and a + shadowed install cannot report success. - 2026-09-08: Closed the false green in the canonical CI gate: `script/cibuild` and `script/docker` now build with `--no-cache`, so the Dockerfile's check layers cannot be served from cache on an unchanged tree, and the text claiming diff --git a/prompts/REPO_POLICIES.md b/prompts/REPO_POLICIES.md index 72c0a0f..d634e99 100644 --- a/prompts/REPO_POLICIES.md +++ b/prompts/REPO_POLICIES.md @@ -300,6 +300,28 @@ style conventions are in separate documents: v2.12.2 (released 2026-05-06), installed commit-pinned via `go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@c0d3ddc9cf3faa61a4e378e879ece580256d76e5`. +- **`script/bootstrap` installs a pinned tool by comparing versions, never by + testing presence.** An `if ! command -v ; then install; fi` guard tests + `PATH` only, so on an already-provisioned machine the pin is inert and a + version bump is a silent no-op — while the Dockerfile, installing into a clean + image, gets the pinned version, so a local `make check` and `make docker` can + disagree about what the tool even is. The canonical form: + - compares the installed version against the pin over the **whole** version + token; a parser that stops at the first `-` reports `2.12.2` for a host + running `2.12.2-rc1` and skips the install; + - treats absent, non-zero, empty or unrecognised `--version` output as a + mismatch, so the failure direction is a redundant install and never a + skipped one; + - after installing, re-resolves the binary the way callers do — `hash -r`, + then through `PATH`, not through the directory the installer wrote to — + and fails naming the resolved path, since an install that a shadowing + binary hides succeeds while changing nothing any caller sees; + - is actually called, and prints the version on both success paths: a + function defined and never invoked has the same exit status and the same + empty output as one that worked. + + Keep it POSIX sh: no arrays, no `[[`, no `grep -P`. + - When pinning images or packages by hash, add a comment above the reference with the version and date (YYYY-MM-DD). From c3a504f647e2b8a2be225b000e1f28740a79957c Mon Sep 17 00:00:00 2001 From: sneak Date: Tue, 8 Sep 2026 04:58:31 +0000 Subject: [PATCH 3/5] Keep secrets out of the Docker build context at every depth (closes #29) The canonical .dockerignore was three lines while the canonical Dockerfile does `COPY . .`, so a local .env, *.pem or *.key shipped into the build context and could land in an image layer, invisible to every git-based check. Copying .gitignore's patterns across is not the repair: .dockerignore anchors an unprefixed pattern at the context root, so that form protects only the repository root while reading as solved. Every depth-independent pattern here carries `**/`, and secret names are character ranges because matching is case-sensitive and an ALL-CAPS twin still misses `Server.Key`. Public certificates are deliberately left in as a legitimate build input. Verified by enumerating a probe image. Model: opus-5 --- .dockerignore | 50 ++++++++++++++++++++++++++++-- TODO.md | 6 ++++ prompts/EXISTING_REPO_CHECKLIST.md | 9 ++++++ prompts/NEW_REPO_CHECKLIST.md | 10 +++++- prompts/REPO_POLICIES.md | 33 +++++++++++++++++++- 5 files changed, 104 insertions(+), 4 deletions(-) diff --git a/.dockerignore b/.dockerignore index 5414d56..d8b9731 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,3 +1,49 @@ +# .dockerignore does NOT use .gitignore semantics. Docker matches with +# moby/patternmatcher: filepath.Match plus `**`, so `*` does not cross +# `/` and an unprefixed pattern is anchored at the context root. Every +# depth-independent pattern therefore needs `**/`, or `config/.env` and +# `certs/server.key` still ship while this file reads as solved. Only +# genuinely root-anchored entries go unprefixed. Never transplant these +# into .gitignore, where `**/` is wrong. +# +# Matching is case-sensitive, so secrets use character ranges rather +# than an ALL-CAPS twin, which would still miss `Server.Key`. +# +# Extend with this repo's own host-built artifacts, written anchored: +# `/myapp`, never `**/myapp`, which also matches `cmd/myapp/` and +# deletes the package directory from the context. .git -node_modules -.DS_Store + +# Environment files. `*.env` covers bare `.env` and the `prod.env` +# convention. Re-include a committed template with a negation if the +# build needs one: `!docs/example.env`. +**/*.[eE][nN][vV] +**/.[eE][nN][vV].* +**/.[eE][nN][vV][rR][cC] + +# Private keys and the bundles carrying them. Public certificates +# (*.crt, *.cer) are deliberately absent: they are legitimate inputs. +**/*.[pP][eE][mM] +**/*.[kK][eE][yY] +**/*.[pP]12 +**/*.[pP][fF][xX] +**/[iI][dD]_[rR][sS][aA] +**/[iI][dD]_[dD][sS][aA] +**/[iI][dD]_[eE][cC][dD][sS][aA] +**/[iI][dD]_[eE][dD]25519 + +# Dependencies: restored inside the image, never copied in. +**/node_modules + +# OS metadata. +**/.DS_Store +**/Thumbs.db + +# Editor state: never a build input, and it churns COPY. +**/*.swp +**/*.swo +**/*~ +**/*.bak +**/.idea +**/.vscode +**/*.sublime-* diff --git a/TODO.md b/TODO.md index 44b3d27..8e02938 100644 --- a/TODO.md +++ b/TODO.md @@ -21,6 +21,12 @@ fmt-check, and commit. # Completed Steps +- 2026-09-08: Closed the secret exposure in the canonical `.dockerignore`: a + local `.env`, `*.pem` or `*.key` was reaching the build context under + `COPY . .`, invisible to every git-based check. The patterns are now written + to `.dockerignore`'s own semantics — `**/`-prefixed so they hold at every + depth, case-folded with character ranges — and `REPO_POLICIES.md` requires + verifying by enumerating the image rather than by reading the file. - 2026-09-08: Made a pinned tool in `script/bootstrap` actually reach the host. `REPO_POLICIES.md` now requires comparing the installed version against the pin rather than testing `PATH` presence, and re-resolving the binary through diff --git a/prompts/EXISTING_REPO_CHECKLIST.md b/prompts/EXISTING_REPO_CHECKLIST.md index 037cda7..1d5ab1c 100644 --- a/prompts/EXISTING_REPO_CHECKLIST.md +++ b/prompts/EXISTING_REPO_CHECKLIST.md @@ -33,6 +33,15 @@ with your task. build step, and `script/cibuild` and `script/docker` build it with `--no-cache` — fetch `.dockerignore` from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` +- [ ] Every depth-independent pattern in `.dockerignore` carries a `**/` prefix, + only genuinely root-anchored entries such as `.git` are unprefixed, and + `.gitignore`'s patterns have not been transplanted unmodified — the + transplanted form leaves `config/.env` and `certs/server.key` in the build + context while reading as solved +- [ ] `.dockerignore` excludes the repo's own host-built artifacts (compiled + binaries, test binaries, coverage output), written root-anchored — + `/myapp`, never `**/myapp`. An existing repo is where such a binary is + likeliest to already be sitting in the build context, invisible to git. - [ ] Gitea Actions workflow in `.gitea/workflows/` runs `script/cibuild` on push — reference `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitea/workflows/check.yml` diff --git a/prompts/NEW_REPO_CHECKLIST.md b/prompts/NEW_REPO_CHECKLIST.md index 6f3dc8b..df92f15 100644 --- a/prompts/NEW_REPO_CHECKLIST.md +++ b/prompts/NEW_REPO_CHECKLIST.md @@ -52,6 +52,13 @@ Template files can be fetched from: `https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md` - [ ] `Dockerfile` and `.dockerignore` — fetch `.dockerignore` from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` + - Extend `.dockerignore` with the repo's own host-built artifacts, giving + every depth-independent pattern a `**/` prefix — but write a repo-root + binary anchored, `/myapp` and never `**/myapp`, which would also match + `cmd/myapp/` and delete the package directory. Do not transplant + `.gitignore`'s patterns: `.dockerignore` anchors an unprefixed pattern at + the context root, so the copied form leaves `config/.env` in the build + context while reading as solved. - All Dockerfiles must run `make check` as a build step - Server: also builds and runs the application - Non-server: brings up dev environment and runs `make check` @@ -108,7 +115,8 @@ are thin shims calling them. Model scripts: - [ ] `make docker` succeeds - [ ] `script/cibuild` succeeds and demonstrably executed the checks — a sub-second build, or `CACHED` on a check layer, means nothing ran -- [ ] No secrets in repo +- [ ] No secrets in repo, and none in the build context: enumerate a probe image + rather than reading `.dockerignore` - [ ] No mutable image/package references - [ ] No unnecessary files in repo root - [ ] All dates written as YYYY-MM-DD diff --git a/prompts/REPO_POLICIES.md b/prompts/REPO_POLICIES.md index d634e99..54780f7 100644 --- a/prompts/REPO_POLICIES.md +++ b/prompts/REPO_POLICIES.md @@ -270,7 +270,38 @@ style conventions are in separate documents: editor files (`.swp`, `*~`), language build artifacts, and `node_modules/`. Fetch the standard `.gitignore` from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up - a new repo. + a new repo. These patterns are written to `.gitignore`'s own semantics, in + which an unanchored pattern already matches at every depth; they are not a + `.dockerignore` and must not be transplanted into one unmodified. + +- **`.dockerignore` does not use `.gitignore` semantics, and copying patterns + across unmodified leaves secrets in the build context.** Docker matches with + `moby/patternmatcher`: `filepath.Match` semantics plus a `**` extension, so + `*` does not cross `/` and a pattern without a leading `**/` is anchored at + the build-context root. A `.dockerignore` listing `.env`, `*.pem` and `*.key` + therefore excludes only the copies at the repository root, while `config/.env` + and `certs/server.key` still reach the context and can land in an image layer + — which is more dangerous than a short file with no secret patterns at all, + because it reads as solved and stops anyone looking. Give every + depth-independent pattern the `**/` prefix and leave only genuinely + root-anchored entries unprefixed: `.git`, and the repo's own host-built + binary, written `/myapp` and never `**/myapp`, which would also match + `cmd/myapp/` and delete the package directory from the context. Matching is + case-sensitive, and an ALL-CAPS twin per pattern still misses `Server.Key`, so + secret names use character ranges — `**/*.[kK][eE][yY]`, `**/*.[pP][eE][mM]`, + and likewise for `.envrc` and the extensionless SSH keys. Where such a pattern + also catches something the build needs, re-include it with a negation + (`!docs/example.env`); deleting the pattern reopens the exposure for every + other file it covers. Fetch the standard `.dockerignore` from + `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` and extend + it with the repo's own artifacts. + +- **Verify `.dockerignore` by enumerating the image, not by reading the + patterns.** Plant files at the root _and_ at least two directories deep, build + a probe image that does `COPY . .`, and list what actually landed + (`docker run --rm --entrypoint find IMAGE /app`). The `transferring context` + size is not a substitute: a nested secret is a few bytes, and BuildKit + transfers only the delta from the previous build. - **No build artifacts in version control.** Code-derived data (compiled bundles, minified output, generated assets) must never be committed to the From 7b55c444ae90518a0afc9e4686850c547db93ae8 Mon Sep 17 00:00:00 2001 From: sneak Date: Tue, 8 Sep 2026 04:58:31 +0000 Subject: [PATCH 4/5] Keep in-repo agent scratch out of the build context and out of git (closes #27) The canonical .dockerignore and .gitignore both omitted the in-repo agent scratch directory, which holds one worktree per in-flight agent, so under `COPY . .` an entire extra checkout of the repo reached the image. The two entries are deliberately different shapes: anchored in .dockerignore, where the `**/` form would also delete a legitimately named nested directory, and unanchored in .gitignore, where a pattern already matches at every depth. Anchoring leaves a gap where agents run in subdirectories, stated in the vendored file itself. The second half is the consequence of excluding .git: `git describe` in a build stage yields an empty version without erroring, so the version is now computed on the host and passed in. Model: opus-5 --- .dockerignore | 9 +++++ .gitignore | 6 ++++ README.md | 11 +++--- TODO.md | 6 ++++ prompts/CODE_STYLEGUIDE_GO.md | 9 ++++- prompts/EXISTING_REPO_CHECKLIST.md | 19 ++++++++-- prompts/GO_HTTP_SERVER_CONVENTIONS.md | 11 ++++-- prompts/NEW_REPO_CHECKLIST.md | 17 +++++++-- prompts/REPO_POLICIES.md | 52 +++++++++++++++++++++++---- script/cibuild | 9 ++++- script/docker | 11 +++++- 11 files changed, 140 insertions(+), 20 deletions(-) diff --git a/.dockerignore b/.dockerignore index d8b9731..fc4fd74 100644 --- a/.dockerignore +++ b/.dockerignore @@ -12,8 +12,17 @@ # Extend with this repo's own host-built artifacts, written anchored: # `/myapp`, never `**/myapp`, which also matches `cmd/myapp/` and # deletes the package directory from the context. + +# Excluding .git means `git describe` cannot run in any build stage and +# fails quietly there; pass the version in with --build-arg VERSION. .git +# Agent scratch: one full checkout of the repo per in-flight agent. +# Anchored because it occurs once where agents run at the repo root. +# KNOWN GAP: a repo running agents in subdirectories still ships +# `services/api/.claude/` and must add its own anchored entry. +.claude + # Environment files. `*.env` covers bare `.env` and the `prod.env` # convention. Re-include a committed template with a negation if the # build needs one: `!docs/example.env`. diff --git a/.gitignore b/.gitignore index c5a0882..3558b76 100644 --- a/.gitignore +++ b/.gitignore @@ -11,6 +11,12 @@ Thumbs.db .vscode/ *.sublime-* +# Agent scratch (worktrees of this repo, created and destroyed by +# in-flight tooling). Unanchored: .gitignore patterns already match at +# every depth, so no prefix is wanted here. This is not a .dockerignore +# entry and must not be given a `**/` prefix on the way into one. +.claude/ + # Node node_modules/ diff --git a/README.md b/README.md index 169f3c7..261beb1 100644 --- a/README.md +++ b/README.md @@ -123,10 +123,13 @@ alpine. We provide: - `script/check` — run all checks: `test`, `lint`, `fmt-check` (our own extension) - `script/docker` — build the Docker image, tagged via `script/projectname` - (byte-identical across repos); builds with `--no-cache`, like `script/cibuild` -- `script/cibuild` — cd to the repo root and `docker build --no-cache .` (what - CI runs; the image build runs `script/check`, and `--no-cache` is what stops - Docker serving those checks from cache on an unchanged tree) + (byte-identical across repos); same `--no-cache` and `VERSION` as + `script/cibuild` +- `script/cibuild` — cd to the repo root, compute `version` from `git describe`, + then `docker build --no-cache --build-arg VERSION="$version" .` (what CI runs; + the image build runs `script/check`, `--no-cache` is what stops Docker serving + those checks from cache on an unchanged tree, and the version is computed on + the host because `.dockerignore` excludes `.git`) - `script/precommit` — run by the git pre-commit hook (our own extension); calls `script/check` - `script/install-precommit` — installs the git pre-commit hook (our own diff --git a/TODO.md b/TODO.md index 8e02938..ed2796a 100644 --- a/TODO.md +++ b/TODO.md @@ -21,6 +21,12 @@ fmt-check, and commit. # Completed Steps +- 2026-09-08: Kept in-repo agent scratch out of the Docker build context and out + of version control: `.claude/` is one full checkout of the repo per in-flight + agent, and under `COPY . .` all of it was reaching the image. Also closed the + consequence of excluding `.git` — `git describe` yields an empty version + inside a build stage without failing, so `script/docker` and `script/cibuild` + now compute the version on the host and pass `--build-arg VERSION`. - 2026-09-08: Closed the secret exposure in the canonical `.dockerignore`: a local `.env`, `*.pem` or `*.key` was reaching the build context under `COPY . .`, invisible to every git-based check. The patterns are now written diff --git a/prompts/CODE_STYLEGUIDE_GO.md b/prompts/CODE_STYLEGUIDE_GO.md index 39c4957..c0756ff 100644 --- a/prompts/CODE_STYLEGUIDE_GO.md +++ b/prompts/CODE_STYLEGUIDE_GO.md @@ -49,7 +49,14 @@ last_modified: 2026-09-08 ``` ```make - VERSION := $(shell git describe --always --dirty) + # ?= rather than := because this `$(shell git describe ...)` is only + # correct on the host: `.dockerignore` excludes `.git`, so evaluated + # inside a build stage it expands to the empty string without failing + # and the binary reports no version. The version is computed on the + # host by `script/docker` / `script/cibuild` and passed with + # `--build-arg VERSION=...`; where a build stage invokes make, + # `ARG VERSION` puts it in the environment and `?=` defers to it. + VERSION ?= $(shell git describe --always --dirty) BUILDARCH := $(shell uname -m) GOLDFLAGS += -X main.Version=$(VERSION) diff --git a/prompts/EXISTING_REPO_CHECKLIST.md b/prompts/EXISTING_REPO_CHECKLIST.md index 1d5ab1c..6c13a30 100644 --- a/prompts/EXISTING_REPO_CHECKLIST.md +++ b/prompts/EXISTING_REPO_CHECKLIST.md @@ -24,9 +24,11 @@ with your task. - [ ] `LICENSE` file exists and matches the README - [ ] `REPO_POLICIES.md` exists and version date is current — fetch from `https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md` -- [ ] `.gitignore` is comprehensive (OS, editor, language artifacts, secrets) — - fetch from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` - if missing +- [ ] `.gitignore` is comprehensive (OS, editor, agent scratch, language + artifacts, secrets) — fetch from + `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` if missing. + An existing repo usually has a hand-written one that is never re-fetched, + so check the entries rather than the file's presence. - [ ] `.editorconfig` exists — fetch from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig` - [ ] `Dockerfile` and `.dockerignore` exist; Dockerfile runs `make check` as a @@ -42,6 +44,17 @@ with your task. binaries, test binaries, coverage output), written root-anchored — `/myapp`, never `**/myapp`. An existing repo is where such a binary is likeliest to already be sitting in the build context, invisible to git. +- [ ] `.claude/` is in `.gitignore` (unanchored) and `.claude` in + `.dockerignore` (anchored, no `**/` prefix). Agent worktrees are entire + checkouts of the repo, so they inflate the context by a multiple of it and + can copy another session's unreviewed work into an image layer. If agents + here run anywhere other than the repo root, the anchored entry misses + `services/api/.claude/`: add anchored entries for those directories. +- [ ] If the repo embeds a version in a binary, that version is computed on the + host and passed with `--build-arg VERSION=...` by `script/docker` and + `script/cibuild`, and no stage calls `git describe`. A tag-derived version + additionally needs `fetch-depth: 0` on the CI checkout step, which clones + shallow and fetches no tags by default. - [ ] Gitea Actions workflow in `.gitea/workflows/` runs `script/cibuild` on push — reference `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitea/workflows/check.yml` diff --git a/prompts/GO_HTTP_SERVER_CONVENTIONS.md b/prompts/GO_HTTP_SERVER_CONVENTIONS.md index 3a53b3c..3ee41d2 100644 --- a/prompts/GO_HTTP_SERVER_CONVENTIONS.md +++ b/prompts/GO_HTTP_SERVER_CONVENTIONS.md @@ -1,6 +1,6 @@ --- title: Go HTTP Server Conventions -last_modified: 2026-02-22 +last_modified: 2026-09-08 --- This document defines the architectural patterns, design decisions, and @@ -991,7 +991,14 @@ func main() { Use ldflags to inject version information at build time: ```makefile -VERSION := $(shell git describe --tags --always) +# ?= rather than := because this `$(shell git describe ...)` is only correct +# on the host: `.dockerignore` excludes `.git`, so evaluated inside a build +# stage it expands to the empty string without failing and the binary reports +# no version. The version is computed on the host by `script/docker` / +# `script/cibuild` and passed with `--build-arg VERSION=...`; where the build +# stage invokes make, `ARG VERSION` puts it in the environment and `?=` defers +# to it. +VERSION ?= $(shell git describe --tags --always) BUILDARCH := $(shell go env GOARCH) build: diff --git a/prompts/NEW_REPO_CHECKLIST.md b/prompts/NEW_REPO_CHECKLIST.md index df92f15..8b7296e 100644 --- a/prompts/NEW_REPO_CHECKLIST.md +++ b/prompts/NEW_REPO_CHECKLIST.md @@ -35,7 +35,11 @@ Template files can be fetched from: - [ ] `.gitignore` — fetch from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore`, extend for - language-specific artifacts + language-specific artifacts. Extensions are written to `.gitignore`'s own + semantics, where an unanchored pattern already matches at every depth: + never add a `**/` prefix here, which is a `.dockerignore` form. The + canonical file already carries `.claude/` so agent worktrees cannot be + committed by accident. - [ ] `.editorconfig` — fetch from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig` - [ ] `Makefile` — fetch from @@ -58,7 +62,16 @@ Template files can be fetched from: `cmd/myapp/` and delete the package directory. Do not transplant `.gitignore`'s patterns: `.dockerignore` anchors an unprefixed pattern at the context root, so the copied form leaves `config/.env` in the build - context while reading as solved. + context while reading as solved. The canonical file's `.claude` entry is + anchored for the same reason as a repo-root binary; leave it that way, but + note that it only covers agents running at the repo root — if this repo + will run them in subdirectories, `services/api/.claude/` needs its own + anchored entry. + - If the image embeds a version in a binary, the version is computed on the + host and passed with `--build-arg VERSION=...`, and `ARG VERSION=dev` is + declared in the stage that compiles. **No stage calls `git describe`** — + `.dockerignore` excludes `.git`, so it yields an empty version without + failing the build. - All Dockerfiles must run `make check` as a build step - Server: also builds and runs the application - Non-server: brings up dev environment and runs `make check` diff --git a/prompts/REPO_POLICIES.md b/prompts/REPO_POLICIES.md index 54780f7..269166c 100644 --- a/prompts/REPO_POLICIES.md +++ b/prompts/REPO_POLICIES.md @@ -267,12 +267,12 @@ style conventions are in separate documents: must be in `.gitignore`. No exceptions. - `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`), - editor files (`.swp`, `*~`), language build artifacts, and `node_modules/`. - Fetch the standard `.gitignore` from - `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up - a new repo. These patterns are written to `.gitignore`'s own semantics, in - which an unanchored pattern already matches at every depth; they are not a - `.dockerignore` and must not be transplanted into one unmodified. + editor files (`.swp`, `*~`), in-repo agent scratch directories (`.claude/`), + language build artifacts, and `node_modules/`. Fetch the standard `.gitignore` + from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when + setting up a new repo. These patterns are written to `.gitignore`'s own + semantics, in which an unanchored pattern already matches at every depth; they + are not a `.dockerignore` and must not be transplanted into one unmodified. - **`.dockerignore` does not use `.gitignore` semantics, and copying patterns across unmodified leaves secrets in the build context.** Docker matches with @@ -296,6 +296,46 @@ style conventions are in separate documents: `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` and extend it with the repo's own artifacts. +- **In-repo agent scratch belongs in both files, written to each file's own + semantics.** `.claude/` holds one worktree per in-flight agent — an entire + additional checkout of the repo — so under `COPY . .` the build context + inflates by a multiple of the repo and another session's unreviewed work can + be copied into an image layer. In `.gitignore` the entry is `.claude/`, + unanchored. In `.dockerignore` it is `.claude`, anchored and with **no** `**/` + prefix, because the prefixed form would also delete any nested directory of + that name from the build. Anchoring carries a known gap that the canonical + `.dockerignore` states in its own comment, since consuming repos receive the + file and not the tracker: the directory is created in the agent's working + directory, so a repo running agents in subdirectories still ships + `services/api/.claude/` and must add its own anchored entry there. + +- **Excluding `.git` means `git describe` cannot run inside any build stage, and + it fails quietly there.** In a build stage there is no repository, so + `git describe` writes nothing to stdout, `-X main.Version=` comes out empty, + the binary reports no version at all, and the build still exits 0. Compute the + version on the host and thread it in as a build arg. `script/docker` and + `script/cibuild` do this, byte-identically across repos: + + ```sh + # Own line: a failing command substitution inside an argument does not + # trip `set -e`, so the inline form degrades to an empty constant. + version="$(git describe --tags --always --dirty 2>/dev/null || true)" + [ -n "$version" ] || version="unknown" + docker build --no-cache --build-arg VERSION="$version" . + ``` + + `--always` makes an untagged repo yield an abbreviated commit hash rather + than failing, and the `[ -n "$version" ]` line is the single place the + fallback is applied — a live check that fires on a build from an export with + no `.git` and on a repository with no commits yet. Do not fold it into the + substitution as `|| echo unknown`, which makes the guard unreachable. The + Dockerfile's side is `ARG VERSION=dev` in the stage that compiles, declared + there because `ARG` is stage-scoped; passing `VERSION` to a repo whose + Dockerfile declares no such `ARG` is ignored and costs nothing, which is why + the scripts stay byte-identical. One consequence for CI: the standard + checkout action clones shallow and fetches no tags, so a repo that embeds a + tag-derived version must set `fetch-depth: 0` on its checkout step. + - **Verify `.dockerignore` by enumerating the image, not by reading the patterns.** Plant files at the root _and_ at least two directories deep, build a probe image that does `COPY . .`, and list what actually landed diff --git a/script/cibuild b/script/cibuild index 51d3b80..4ad2f9c 100755 --- a/script/cibuild +++ b/script/cibuild @@ -8,7 +8,14 @@ ROOT="$(cd "$(dirname "$0")/.." && pwd -P)" main() { cd "$ROOT" - docker build --no-cache . + # Own line: a failing command substitution inside an argument does + # not trip `set -e`, so the inline form degrades silently to an + # empty constant. VERSION is computed here because .dockerignore + # excludes .git, so `git describe` in a build stage yields an empty + # version without failing. + version="$(git describe --tags --always --dirty 2>/dev/null || true)" + [ -n "$version" ] || version="unknown" + docker build --no-cache --build-arg VERSION="$version" . } main "$@" diff --git a/script/docker b/script/docker index f72ee15..222a355 100755 --- a/script/docker +++ b/script/docker @@ -10,7 +10,16 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)" main() { cd "$ROOT" - docker build --no-cache -t "$("$SCRIPT_DIR/projectname")" . + # Own line: a failing command substitution inside an argument does + # not trip `set -e`, so the inline form degrades silently to an + # empty constant. VERSION is computed here because .dockerignore + # excludes .git, so `git describe` in a build stage yields an empty + # version without failing. + version="$(git describe --tags --always --dirty 2>/dev/null || true)" + [ -n "$version" ] || version="unknown" + docker build --no-cache \ + --build-arg VERSION="$version" \ + -t "$("$SCRIPT_DIR/projectname")" . } main "$@" From c4d5546e867f5ce0e687e77fae40a218d3e2668d Mon Sep 17 00:00:00 2001 From: sneak Date: Tue, 8 Sep 2026 04:58:31 +0000 Subject: [PATCH 5/5] Gate the build on Docker lint and test phases (closes #40, closes #30) Per the owner ruling on issue 40, linting and testing are phases of the main Dockerfile rather than a separate lint file. script/lint and script/test build one phase each by name with caching disabled, and the final stage copies a harmless file from each so the image cannot be built unless both passed. A stage that is not the last is built only when something depends on it or --target names it, so the gates are invoked by name and the edges kept. script/check runs the gates and builds no image of its own; script/cibuild bootstraps first, because CI runs it alone and fmt-check is native. fmt and fmt-check source nvm for the pinned node before calling yarn, which bootstrap installs but leaves off its caller's PATH. Every build in script/ is tagged and uncached. Issue 30 closes too: a container has its own lint cache and lock. Model: opus-5 --- Dockerfile | 55 +++++++- README.md | 30 ++-- TODO.md | 10 ++ prompts/CODE_STYLEGUIDE_GO.md | 14 +- prompts/EXISTING_REPO_CHECKLIST.md | 45 +++++- prompts/NEW_REPO_CHECKLIST.md | 52 +++++-- prompts/REPO_POLICIES.md | 214 +++++++++++++++++++---------- script/check | 4 +- script/cibuild | 18 ++- script/docker | 4 +- script/fmt | 21 ++- script/fmt-check | 21 ++- script/lint | 18 ++- script/test | 13 +- 14 files changed, 382 insertions(+), 137 deletions(-) diff --git a/Dockerfile b/Dockerfile index cb6489a..da25dee 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,15 +1,58 @@ +# Lint phase. The linter is invoked directly rather than through `make +# lint` or `script/lint`, which are themselves a docker build and would +# recurse into a daemon that does not exist in a build step. +# # node 22-alpine, 2026-02-22 -FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 +FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 AS lint WORKDIR /app -# script/bootstrap installs all prerequisites (make via apk here; node -# and yarn are already in the base image, so those steps are skipped). -# Dependency manifests are copied first so the bootstrap layer is -# cached until they change. COPY script/ script/ COPY package.json yarn.lock ./ RUN script/bootstrap COPY . . -RUN make check + +RUN yarn run prettier --check '**/*.md' --tab-width 4 --prose-wrap always + +# Test phase, same shape and for the same reason. +# +# node 22-alpine, 2026-02-22 +FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 AS test + +WORKDIR /app + +COPY script/ script/ +COPY package.json yarn.lock ./ +RUN script/bootstrap + +COPY . . + +RUN echo "No tests defined." + +# Development environment, and the last stage: a plain `docker build .` +# names no target and so builds this one. Nothing is wanted from the two +# phases above; the copies are what make BuildKit build them first, so +# this image cannot be produced unless lint and test passed. A stage +# appended after this one would drop all three out of a plain build. +# +# node 22-alpine, 2026-02-22 +FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 + +WORKDIR /app + +COPY --from=lint /app/package.json /dev/null +COPY --from=test /app/package.json /dev/null + +# script/bootstrap installs all prerequisites. Manifests are copied +# first so that layer stays cached until dependencies change. +COPY script/ script/ +COPY package.json yarn.lock ./ +RUN script/bootstrap + +COPY . . + +# The version is computed on the host and passed in, because +# .dockerignore excludes .git. +ARG VERSION=dev +LABEL org.opencontainers.image.version="${VERSION}" diff --git a/README.md b/README.md index 261beb1..68dca9c 100644 --- a/README.md +++ b/README.md @@ -116,20 +116,24 @@ alpine. We provide: `script/bootstrap`, then `script/install-precommit` - `script/projectname` — output the project name (our own extension); used by `script/docker` for the image tag -- `script/test` — run the test suite (no tests defined here) -- `script/lint` — lint the markdown files with prettier -- `script/fmt` — format all markdown files with prettier (writes) -- `script/fmt-check` — check formatting (read-only) +- `script/test` — `docker build --no-cache --target test -t prompts-test .`, + building the `test` phase of the `Dockerfile` (no tests defined here) +- `script/lint` — `docker build --no-cache --target lint -t prompts-lint .`, + building the `lint` phase, which runs prettier over the markdown files +- `script/fmt` — format all markdown files with prettier (writes; native, not in + a container) +- `script/fmt-check` — check formatting (read-only; native) - `script/check` — run all checks: `test`, `lint`, `fmt-check` (our own - extension) -- `script/docker` — build the Docker image, tagged via `script/projectname` - (byte-identical across repos); same `--no-cache` and `VERSION` as - `script/cibuild` -- `script/cibuild` — cd to the repo root, compute `version` from `git describe`, - then `docker build --no-cache --build-arg VERSION="$version" .` (what CI runs; - the image build runs `script/check`, `--no-cache` is what stops Docker serving - those checks from cache on an unchanged tree, and the version is computed on - the host because `.dockerignore` excludes `.git`) + extension); builds no image of its own +- `script/docker` — + `docker build --no-cache --build-arg VERSION="$version" -t prompts .`, the tag + coming from `script/projectname` (byte-identical across repos) +- `script/cibuild` — cd to the repo root, run `script/bootstrap`, run + `script/check`, compute `version` from `git describe`, then + `docker build --no-cache --build-arg VERSION="$version" -t prompts .` (what CI + runs; it bootstraps because CI checks out and runs this alone while + `script/fmt-check` is native, and the version is computed on the host because + `.dockerignore` excludes `.git`) - `script/precommit` — run by the git pre-commit hook (our own extension); calls `script/check` - `script/install-precommit` — installs the git pre-commit hook (our own diff --git a/TODO.md b/TODO.md index ed2796a..94e34be 100644 --- a/TODO.md +++ b/TODO.md @@ -21,6 +21,16 @@ fmt-check, and commit. # Completed Steps +- 2026-09-08: Moved linting and testing into Docker as phases of the main + `Dockerfile`, per the owner ruling on issue 40. `script/lint` and + `script/test` build one phase each by name with `--no-cache` — the same answer + issue 26 got, so no separate cache-busting mechanism survives — and the final + stage copies a harmless file from both, so the image cannot be built unless + they pass. This also closes issue 30: a container has its own result cache and + its own lock, so a lint verdict can no longer belong to another checkout. No + separate lint Dockerfile, and no `golangci-lint config verify` step. + `script/check` runs the gates and nothing else, and `script/cibuild` + bootstraps first, since it is all CI runs and `script/fmt-check` is native. - 2026-09-08: Kept in-repo agent scratch out of the Docker build context and out of version control: `.claude/` is one full checkout of the repo per in-flight agent, and under `COPY . .` all of it was reaching the image. Also closed the diff --git a/prompts/CODE_STYLEGUIDE_GO.md b/prompts/CODE_STYLEGUIDE_GO.md index c0756ff..2869855 100644 --- a/prompts/CODE_STYLEGUIDE_GO.md +++ b/prompts/CODE_STYLEGUIDE_GO.md @@ -105,14 +105,18 @@ last_modified: 2026-09-08 1. For anything beyond a simple script or tool, or anything that is going to run in any sort of "production" anywhere, make sure it passes - `golangci-lint`. + `golangci-lint`. Run it with `make lint`, never by invoking the binary: the + linter runs as a phase of the `Dockerfile` and is not installed on the host + by any repo. Invoked directly on a shared host it reads a result cache keyed + on file content rather than location, and a host-global lock, so its answer + may belong to another checkout entirely. 1. Write a `Dockerfile` for every repo, even if it only runs the tests and - linting. `script/cibuild` and `script/docker` should always make sure that - the code is in an able-to-be-compiled state, linted, and any tests run, and - the build should fail if linting doesn't pass. Go through those scripts + linting. It carries the lint and test phases, and the final stage depends on + both, so a build makes sure the code is in an able-to-be-compiled state, + linted, and its tests run. Go through `script/cibuild` or `script/docker` rather than a bare `docker build .`: they pass `--no-cache`, without which - an unchanged tree serves the check layers from cache and the build reports a + an unchanged tree serves the gate layers from cache and the build reports a green it never ran. 1. Every repo must have a `Makefile`. See diff --git a/prompts/EXISTING_REPO_CHECKLIST.md b/prompts/EXISTING_REPO_CHECKLIST.md index 6c13a30..70b5f58 100644 --- a/prompts/EXISTING_REPO_CHECKLIST.md +++ b/prompts/EXISTING_REPO_CHECKLIST.md @@ -31,10 +31,18 @@ with your task. so check the entries rather than the file's presence. - [ ] `.editorconfig` exists — fetch from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig` -- [ ] `Dockerfile` and `.dockerignore` exist; Dockerfile runs `make check` as a - build step, and `script/cibuild` and `script/docker` build it with - `--no-cache` — fetch `.dockerignore` from +- [ ] `Dockerfile` and `.dockerignore` exist; the Dockerfile carries a `lint` + phase and a `test` phase, and the final stage carries a `COPY --from=` of + a harmless file from each — fetch `.dockerignore` from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` +- [ ] Nothing has been appended after the final stage, and the gate phases are + reachable from it. A stage nothing depends on is built only when + `--target` names it, so a lost `COPY --from=` edge leaves `docker build .` + passing while the gate never runs. Confirm by planting a violation, not by + reading the file. +- [ ] The gate phases invoke their tools directly, never through `make lint` or + `script/test` — those are themselves a `docker build` and would recurse + inside a build step - [ ] Every depth-independent pattern in `.dockerignore` carries a `**/` prefix, only genuinely root-anchored entries such as `.git` are unprefixed, and `.gitignore`'s patterns have not been transplanted unmodified — the @@ -81,6 +89,29 @@ with your task. `script/install-precommit`, shimmed by `make hooks`) runs it - [ ] README has an **Entrypoints** section documenting the `script/` entrypoints and linking the standard +- [ ] `script/lint` and `script/test` build their phase by name + (`docker build --no-cache --target -t - .`), and no + host invocation anywhere in the repo can produce a lint verdict — grep for + the linter's own name across `script/`, the `Makefile` and CI config, not + just `script/lint`. A second path is likeliest here: a `make lint-fast`, + an older host-versus-container branch, or a CI step calling the binary + directly. `script/fmt` and `script/fmt-check` are expected hits and stay + on the host. +- [ ] Every `docker build` in `script/` is tagged — an untagged one leaves a + dangling image behind on every run, on every host and CI runner +- [ ] `script/cibuild` runs `script/bootstrap` before `script/check`, and builds + the image with `--no-cache`. Without the bootstrap the CI run dies in + `script/fmt-check`, which runs the formatter on the host and finds nothing + installed. +- [ ] `script/fmt` and `script/fmt-check` source nvm for the pinned node version + before invoking `yarn`, as `script/bootstrap`'s own install step does. + `script/bootstrap` leaves the node and yarn it installs off the `PATH` of + the shell that called it, so a bare `yarn` exits 127 on a runner carrying + nothing but docker and git. +- [ ] `script/bootstrap` installs no linter of its own — delete the block, its + version variables and its call site. A JS repo's `yarn install` stays; it + brings a linter along with every other dependency, and no verdict is taken + from it. - [ ] `make check` does not modify any files in the repo - [ ] `make test` has a 90-second timeout and completes within the 60-second hard cap (over 20 seconds is green but must be filed as an improvement @@ -129,6 +160,10 @@ with your task. # Final - [ ] `make check` passes -- [ ] `script/cibuild` succeeds and demonstrably executed the checks — a - sub-second build, or `CACHED` on a check layer, means nothing ran +- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying nothing but + docker and git, with no node or yarn on `PATH`, which is what CI has, and + demonstrably executed the checks — a sub-second build, or `CACHED` on a + gate layer, means nothing ran +- [ ] A planted lint violation fails both `make lint` and a plain + `docker build .`; revert it afterwards - [ ] Commit and merge fixes before starting your actual task diff --git a/prompts/NEW_REPO_CHECKLIST.md b/prompts/NEW_REPO_CHECKLIST.md index 8b7296e..4789182 100644 --- a/prompts/NEW_REPO_CHECKLIST.md +++ b/prompts/NEW_REPO_CHECKLIST.md @@ -72,9 +72,13 @@ Template files can be fetched from: declared in the stage that compiles. **No stage calls `git describe`** — `.dockerignore` excludes `.git`, so it yields an empty version without failing the build. - - All Dockerfiles must run `make check` as a build step - - Server: also builds and runs the application - - Non-server: brings up dev environment and runs `make check` + - The Dockerfile carries a `lint` phase and a `test` phase, each invoking + its tool directly rather than through `make` or `script/`, and the final + stage carries a `COPY --from=` of a harmless file from each so the image + cannot be built unless both passed. Keep the final stage last: a stage + nothing depends on is built only when `--target` names it. + - Server: the final stage builds and runs the application + - Non-server: the final stage brings up the dev environment - Image pinned by sha256 hash with version/date comment - [ ] Gitea Actions workflow at `.gitea/workflows/check.yml` that runs `script/cibuild` on push — reference @@ -100,21 +104,34 @@ are thin shims calling them. Model scripts: installs - [ ] `script/setup` / `make setup` — readies a fresh clone: runs `bootstrap`, then `install-precommit`, plus repo-specific init -- [ ] `script/test` / `make test` — runs real tests, not a no-op (90-second - timeout, 60-second hard cap on wall time) -- [ ] `script/lint` / `make lint` — runs linter -- [ ] `script/fmt` / `make fmt` — formats code (writes) -- [ ] `script/fmt-check` / `make fmt-check` — checks formatting (read-only) +- [ ] `script/test` / `make test` — `docker build --no-cache --target test .`, + tagged; the phase runs real tests, not a no-op (90-second timeout, + 60-second hard cap on wall time) +- [ ] `script/lint` / `make lint` — `docker build --no-cache --target lint .`, + tagged. No lint verdict may come from a host invocation of the linter. +- [ ] `script/fmt` / `make fmt` — formats code (writes; native, never in a + container) +- [ ] `script/fmt-check` / `make fmt-check` — checks formatting (read-only; + native) - [ ] `script/check` / `make check` — runs `test`, `lint`, `fmt-check`; must not modify files - [ ] `script/projectname` — outputs the project name (used by `script/docker` for the image tag) - [ ] `script/docker` / `make docker` — builds Docker image, tagged via - `script/projectname` (byte-identical across repos); passes `--no-cache` - like `script/cibuild` -- [ ] `script/cibuild` — cd to repo root, `docker build --no-cache .` (what CI - runs; without `--no-cache` an unchanged tree serves the check layers from - cache and the build reports a green it never ran) + `script/projectname` (byte-identical across repos); `--no-cache`, plus the + version as a build arg +- [ ] `script/cibuild` — cd to repo root, run `script/bootstrap`, run + `script/check`, then + `docker build --no-cache --build-arg VERSION="$version" .` (what CI runs). + The bootstrap is required: CI checks out and runs this alone, and + `script/fmt-check` runs the formatter on the host. +- [ ] `script/fmt` and `script/fmt-check` source nvm for the pinned node version + before invoking `yarn`, as `script/bootstrap`'s own install step does. + `script/bootstrap` leaves the node and yarn it installs off the `PATH` of + the shell that called it, so a bare `yarn` exits 127 on a runner carrying + nothing but docker and git. +- [ ] Every `docker build` in `script/` is tagged, so no invocation leaves a + dangling image behind - [ ] `script/precommit` — called by the pre-commit hook; runs `script/check` - [ ] `script/install-precommit` — installs the pre-commit hook that runs `script/precommit` @@ -126,8 +143,13 @@ are thin shims calling them. Model scripts: - [ ] `make check` passes - [ ] `make docker` succeeds -- [ ] `script/cibuild` succeeds and demonstrably executed the checks — a - sub-second build, or `CACHED` on a check layer, means nothing ran +- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying nothing but + docker and git, with no node or yarn on `PATH`, which is what CI has, and + demonstrably executed the checks — a sub-second build, or `CACHED` on a + gate layer, means nothing ran +- [ ] Plant a lint violation and confirm both `make lint` and a plain + `docker build .` fail on it; revert. A plain build that passes proves the + final stage is missing its `COPY --from=` edge to the gate phases. - [ ] No secrets in repo, and none in the build context: enumerate a probe image rather than reading `.dockerignore` - [ ] No mutable image/package references diff --git a/prompts/REPO_POLICIES.md b/prompts/REPO_POLICIES.md index 269166c..2256291 100644 --- a/prompts/REPO_POLICIES.md +++ b/prompts/REPO_POLICIES.md @@ -60,17 +60,28 @@ style conventions are in separate documents: 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 --no-cache .`; 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 + repo root, runs `script/bootstrap`, runs `script/check`, and builds the image + with the version; the Gitea workflow calls it. **`script/cibuild` runs + `script/bootstrap` first**, because the workflow checks out the repo and runs + nothing else, while `script/fmt-check` runs the formatter on the host: on a + pristine checkout with nothing installed the run dies there, after the + containerised gates have passed. **The bootstrap alone is not enough**: + `script/bootstrap` installs node and yarn under nvm and leaves neither on the + `PATH` of the shell that called it, so a bare `yarn` still exits 127. The host + entrypoints that need yarn — `script/fmt` and `script/fmt-check` — therefore + source nvm for the pinned node version before invoking it, exactly as + `script/bootstrap`'s own install step does. A runner carrying nothing but + docker and git then gets through `script/check`. 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). @@ -89,97 +100,140 @@ style conventions are in separate documents: contributor should be able to understand the entire development workflow by reading the Makefile. -- Every repo should have a `Dockerfile`. All Dockerfiles must run `make check` - 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. 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. +- Every repo should have a `Dockerfile`, and it carries the repo's gates: a + `lint` phase and a `test` phase, with the final stage depending on both so the + image cannot be built unless they pass. For non-server repos the final stage + brings up a development environment; for server repos it is the runtime image. + 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. + +- **Linting and testing run in Docker, as phases of the `Dockerfile`.** There is + no separate lint file. `script/lint` and `script/test` each build one phase + and nothing else: + + ```sh + docker build --no-cache --target lint -t "$(script/projectname)-lint" . + docker build --no-cache --target test -t "$(script/projectname)-test" . + ``` + + **A stage that is not the last one in the file is built only when the final + stage's chain depends on it, or when `--target` names it.** That is why the + two gates are always invoked by name here, and why the final stage carries a + `COPY --from=` of a harmless file from each of them: without that edge a + plain `docker build .` builds the last stage alone and exits 0 having linted + and tested nothing. + + **Every `docker build` in `script/` is tagged**, here and in + `script/cibuild` and `script/docker`. An untagged build leaves a dangling + image behind on every invocation, on every developer host and every CI + runner; a tagged one replaces the previous image. + + Inside a phase the tool is invoked directly — `golangci-lint`, `go test`, + `eslint`, `prettier` — never through `make lint` or `script/test`, which are + themselves a `docker build` and would recurse into a daemon that does not + exist in a build step. Formatting is the exception and stays on the host: + `script/fmt` writes the working tree, and `script/fmt-check` is its + read-only twin. + + **No lint verdict may come from a host invocation of the linter.** On a + shared host golangci-lint reads a result cache keyed on file content rather + than location, so a second checkout of the same content is served the first + one's findings, and a host-global lock in `$TMPDIR` makes concurrent runs + exit non-zero with `parallel golangci-lint is running` — a status a caller + cannot tell from real findings. Both have produced wrong verdicts in this + org, in both directions. A container has its own cache, its own `TMPDIR` and + a digest-pinned binary, so neither is reachable. - **Any build that runs checks is built with `--no-cache`.** Docker invalidates a `COPY` layer only when the copied content changes, so on an unchanged tree the check `RUN` is served from cache, nothing executes, and the build still - exits 0. `script/cibuild` and `script/docker` therefore pass `--no-cache`, and - a bare `docker build .` is not evidence that anything ran: a sub-second build - reporting success is a cache hit, not a result. Never invalidate by pruning — - `docker builder prune` and friends destroy a build cache shared with every - other build on the host. + exits 0. Every `docker build` in `script/` therefore passes `--no-cache`: + `script/lint`, `script/test`, `script/cibuild` and `script/docker` are the + four, and there is no fifth — `script/check` runs the two gate phases and + `script/fmt-check`, and builds no image of its own. A bare `docker build .` is + not evidence that anything ran: a sub-second build reporting success is a + cache hit, not a result. Never invalidate by pruning — `docker builder prune` + and friends destroy a build cache shared with every other build on the host. -- **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: +- **The gate phases are separate stages, and the build stage depends on both.** + The lint phase is based on the `golangci/golangci-lint` image (pinned by + hash), so lint failures surface in seconds rather than after a full compile, + and the test phase is based on the Go image. The canonical Go repo + `Dockerfile`: ```dockerfile - # Lint stage — fast feedback on formatting and lint issues + # Lint phase # 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 + RUN golangci-lint run --config .golangci.yml ./... - # Build stage + # Test phase # golang:1.x-alpine, YYYY-MM-DD - FROM golang@sha256:... AS builder + FROM golang@sha256:... AS test + WORKDIR /src + COPY go.mod go.sum ./ + RUN go mod download + COPY . . + RUN go test -timeout 90s -race -cover ./... || \ + { echo "--- Rerunning with -v for details ---"; \ + go test -timeout 90s -race -v ./...; exit 1; } + + # Build stage. Nothing is wanted from either phase above; the copies + # are what make BuildKit build them first, so this stage cannot run + # unless lint and test passed. + # golang:1.x-alpine, YYYY-MM-DD + FROM golang@sha256:... AS builder + COPY --from=lint /src/go.sum /dev/null + COPY --from=test /src/go.sum /dev/null 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 + # Runtime stage, and the last one 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. + - The lint phase uses the `golangci/golangci-lint` image directly (it has + both Go and the linter), so nothing needs installing. + - `COPY --from= /src/go.sum /dev/null` is a no-op copy whose only + purpose is the ordering edge. BuildKit runs stages in parallel by default, + and a stage nothing depends on is not built at all, so without these two + lines a red gate would not fail the build. + - Keep the runtime stage last, and if you add a stage after it, give it the + same two copies. A plain `docker build .` builds the last stage's chain + and nothing else. - 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 + (e.g. a web frontend compiled in a separate stage), the lint phase 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. + `vips-dev`), install them in the lint phase with `apk add`. + - `ARG VERSION=dev` is declared in the stage that compiles and supplied by + `script/docker` and `script/cibuild`; no stage may call `git describe`. - Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that - runs `script/cibuild` (which runs `docker build --no-cache .`) on push. Since - the Dockerfile already runs `make check`, a successful build implies all - checks pass — an implication that holds only because of the `--no-cache` - above. + runs `script/cibuild` on push, and checks out the repo as its only other step. + That script bootstraps, runs the gate phases, and then builds the image, so a + successful run means every check passed; a bare `docker build .` does not + carry the same guarantee, because its gate phases may come from the cache. The + image build is uncached and so runs the gate phases a second time. That is the + price of the rule above, and it is worth paying: the image that ships is built + from a run of its own gates rather than from a cache entry. - Use platform-standard formatters: `black` for Python, `prettier` for JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with @@ -203,15 +257,17 @@ style conventions are in separate documents: suite that exceeds it fails. Under 20 seconds is the target. A suite between 20 and 60 seconds is still green, but the overage must be filed as an improvement bug against that repo. Add a 90-second timeout to the test - invocation in the Makefile (`go test -timeout 90s`). The backstop deliberately - sits above the hard cap so that it catches a genuinely hung test rather than a - merely slow one. + invocation (`go test -timeout 90s`). The backstop deliberately sits above the + hard cap so that it catches a genuinely hung test rather than a merely slow + one. -- **`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: +- **The test command 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 command lives in the + `test` phase of the `Dockerfile`, since `script/test` builds that phase; the + Makefile form below is the same pattern for any repo-local invocation: ```makefile test: @@ -321,7 +377,9 @@ style conventions are in separate documents: # trip `set -e`, so the inline form degrades to an empty constant. version="$(git describe --tags --always --dirty 2>/dev/null || true)" [ -n "$version" ] || version="unknown" - docker build --no-cache --build-arg VERSION="$version" . + docker build --no-cache \ + --build-arg VERSION="$version" \ + -t "$(script/projectname)" . ``` `--always` makes an untagged repo yield an abbreviated commit hash rather @@ -368,8 +426,12 @@ style conventions are in separate documents: `test-support` depguard rule, where a repo names its own test-support packages by full import path. A repo adds entries there and changes nothing else, and a re-vendor carries its entries forward. The canonical golangci-lint version is - v2.12.2 (released 2026-05-06), installed commit-pinned via - `go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@c0d3ddc9cf3faa61a4e378e879ece580256d76e5`. + v2.12.2 (released 2026-05-06), pinned as the digest of the lint phase's base + image + (`golangci/golangci-lint@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240`, + which reports `2.12.2 built with go1.26.2 from c0d3ddc9`). That digest is the + only pin, since no repo installs golangci-lint on the host: bumping the + version means changing it and nothing else. - **`script/bootstrap` installs a pinned tool by comparing versions, never by testing presence.** An `if ! command -v ; then install; fi` guard tests diff --git a/script/check b/script/check index 3e1778c..92875f7 100755 --- a/script/check +++ b/script/check @@ -1,6 +1,8 @@ #!/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. +# extension to scripts-to-rule-them-all. test and lint are Docker +# phases; fmt-check is native, because a formatter writes the working +# tree. Must not modify any files. set -eu SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)" diff --git a/script/cibuild b/script/cibuild index 4ad2f9c..688299f 100755 --- a/script/cibuild +++ b/script/cibuild @@ -1,13 +1,19 @@ #!/bin/sh -# script/cibuild: run the CI build. --no-cache because the checks are -# RUN steps: on an unchanged tree Docker serves them from cache and the -# build exits 0 having run nothing. +# script/cibuild: run the CI build. It bootstraps first: a CI runner +# checks out and runs this and nothing else, and script/fmt-check runs +# the formatter on the host, which a pristine checkout cannot do. +# --no-cache for the same reason as script/docker: the gate phases the +# final stage depends on are RUN steps, and a cached one is a check that +# did not run. set -eu -ROOT="$(cd "$(dirname "$0")/.." && pwd -P)" +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)" +ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)" main() { cd "$ROOT" + "$SCRIPT_DIR/bootstrap" + "$SCRIPT_DIR/check" # Own line: a failing command substitution inside an argument does # not trip `set -e`, so the inline form degrades silently to an # empty constant. VERSION is computed here because .dockerignore @@ -15,7 +21,9 @@ main() { # version without failing. version="$(git describe --tags --always --dirty 2>/dev/null || true)" [ -n "$version" ] || version="unknown" - docker build --no-cache --build-arg VERSION="$version" . + docker build --no-cache \ + --build-arg VERSION="$version" \ + -t "$("$SCRIPT_DIR/projectname")" . } main "$@" diff --git a/script/docker b/script/docker index 222a355..c4688e8 100755 --- a/script/docker +++ b/script/docker @@ -1,8 +1,8 @@ #!/bin/sh # script/docker: build the Docker image tagged with the project name. # Identical in all repos; the tag comes from script/projectname. -# --no-cache for the same reason as script/cibuild: a cached check layer -# is a check that did not run. +# --no-cache because the gate phases the final stage depends on are RUN +# steps, and a cached one is a check that did not run. set -eu SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)" diff --git a/script/fmt b/script/fmt index 62d88e9..68cb9af 100755 --- a/script/fmt +++ b/script/fmt @@ -4,9 +4,28 @@ set -eu ROOT="$(cd "$(dirname "$0")/.." && pwd -P)" +# Must match the pin in script/bootstrap. +NODE_VERSION="22.17.0" + +# script/bootstrap installs node and yarn under nvm and leaves neither +# on the PATH of the shell that called it, so resolve the pinned +# toolchain here the way bootstrap's own install step does. nvm is a +# bash script, hence the subshell. +run_yarn() { + if command -v yarn >/dev/null 2>&1; then + exec yarn "$@" + fi + if [ ! -s "$HOME/.nvm/nvm.sh" ]; then + echo "fmt: no yarn; run script/bootstrap first" >&2 + exit 1 + fi + exec bash -c '. "$HOME/.nvm/nvm.sh" && nvm use "$1" >/dev/null && + shift && exec yarn "$@"' bash "$NODE_VERSION" "$@" +} + main() { cd "$ROOT" - yarn run prettier --write '**/*.md' --tab-width 4 --prose-wrap always + run_yarn run prettier --write '**/*.md' --tab-width 4 --prose-wrap always } main "$@" diff --git a/script/fmt-check b/script/fmt-check index d089ccf..c7ff266 100755 --- a/script/fmt-check +++ b/script/fmt-check @@ -4,9 +4,28 @@ set -eu ROOT="$(cd "$(dirname "$0")/.." && pwd -P)" +# Must match the pin in script/bootstrap. +NODE_VERSION="22.17.0" + +# script/bootstrap installs node and yarn under nvm and leaves neither +# on the PATH of the shell that called it, so resolve the pinned +# toolchain here the way bootstrap's own install step does. nvm is a +# bash script, hence the subshell. +run_yarn() { + if command -v yarn >/dev/null 2>&1; then + exec yarn "$@" + fi + if [ ! -s "$HOME/.nvm/nvm.sh" ]; then + echo "fmt-check: no yarn; run script/bootstrap first" >&2 + exit 1 + fi + exec bash -c '. "$HOME/.nvm/nvm.sh" && nvm use "$1" >/dev/null && + shift && exec yarn "$@"' bash "$NODE_VERSION" "$@" +} + main() { cd "$ROOT" - yarn run prettier --check '**/*.md' --tab-width 4 --prose-wrap always + run_yarn run prettier --check '**/*.md' --tab-width 4 --prose-wrap always } main "$@" diff --git a/script/lint b/script/lint index c489634..2d8b075 100755 --- a/script/lint +++ b/script/lint @@ -1,13 +1,23 @@ #!/bin/sh -# script/lint: run the linter. +# script/lint: run the linter. Linting is a phase of the Dockerfile and +# this builds that phase alone; the linter is never installed or run on +# a developer host, where a shared result cache and a host-global lock +# make its answer untrustworthy. +# +# The phase is not the last stage in the file, so it is built only when +# --target names it. --no-cache because a cached lint layer is a lint +# that did not run. The tag makes each build replace the previous image +# instead of leaving a dangling one behind. set -eu -ROOT="$(cd "$(dirname "$0")/.." && pwd -P)" +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)" +ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)" main() { cd "$ROOT" - echo "Linting markdown files..." - yarn run prettier --check '**/*.md' --tab-width 4 --prose-wrap always + docker build --no-cache \ + --target lint \ + -t "$("$SCRIPT_DIR/projectname")-lint" . } main "$@" diff --git a/script/test b/script/test index cbfda0e..cd239f2 100755 --- a/script/test +++ b/script/test @@ -1,12 +1,19 @@ #!/bin/sh -# script/test: run the test suite. +# script/test: run the test suite. Testing is a phase of the Dockerfile +# and this builds that phase alone, on the same terms as script/lint: +# --target because a phase that is not the last stage is built only when +# named, --no-cache because a cached test layer is a test that did not +# run, and a tag so each build replaces the previous image. set -eu -ROOT="$(cd "$(dirname "$0")/.." && pwd -P)" +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)" +ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)" main() { cd "$ROOT" - echo "No tests defined." + docker build --no-cache \ + --target test \ + -t "$("$SCRIPT_DIR/projectname")-test" . } main "$@"