From 36e63296028a1c939cf36a952c698e461bef2ad5 Mon Sep 17 00:00:00 2001 From: sneak Date: Wed, 4 Nov 2026 01:18:41 +0000 Subject: [PATCH] Rewrite REPO_POLICIES.md sentence by sentence (closes #136) Every sentence of prompts/REPO_POLICIES.md is rewritten against the sentence rules: one idea per sentence, about 30 words at most, lists as bulleted lists, subject and verb early, the main rule before any exception. No rule's meaning changed: nothing is added, removed, loosened or tightened, every reason stays, and code blocks, digests, URLs, file names, commands and quoted strings are unchanged. Both repo checklists carry the same rewrite of the sentences they quote word for word. Model: fable-5-1 --- TODO.md | 7 + prompts/EXISTING_REPO_CHECKLIST.md | 70 +-- prompts/NEW_REPO_CHECKLIST.md | 67 ++- prompts/REPO_POLICIES.md | 818 +++++++++++++++++------------ 4 files changed, 556 insertions(+), 406 deletions(-) diff --git a/TODO.md b/TODO.md index e3fb63a..3127448 100644 --- a/TODO.md +++ b/TODO.md @@ -21,6 +21,13 @@ fmt-check, and commit. # Completed Steps +- 2026-11-04: Rewrote `prompts/REPO_POLICIES.md` sentence by sentence + (https://git.eeqj.de/sneak/prompts/issues/136), on sneak's yes at + https://git.eeqj.de/sneak/prompts/issues/136#issuecomment-165193. Every rule + keeps its meaning and its place, and `must` and `should` stay as they were. + Long sentences are split, comma-chained lists are now bulleted lists, and + every reason stays. Code blocks, digests, URLs, file names, commands and + quoted strings are unchanged. - 2026-11-03: The canonical golangci-lint is now v2.15.0, still built with go1.27.0, so the `go` directive rule is unchanged (issue 142). Repositories pick this up on their next re-vendor. Each item in the canonical diff --git a/prompts/EXISTING_REPO_CHECKLIST.md b/prompts/EXISTING_REPO_CHECKLIST.md index 0c18893..d955c03 100644 --- a/prompts/EXISTING_REPO_CHECKLIST.md +++ b/prompts/EXISTING_REPO_CHECKLIST.md @@ -1,6 +1,6 @@ --- title: Existing Repo Checklist -last_modified: 2026-11-03 +last_modified: 2026-11-04 --- Use this checklist when beginning work in a repo that may not yet conform to our @@ -105,37 +105,43 @@ with your task. `services/api/.claude/`: add anchored entries for those directories. - [ ] If the repo embeds a version in a binary: `.dockerignore` lets `.git` into the build context. It keeps out every git `config` at any depth - (`**/.git/config`, `**/.git/modules/**/config`): the repository's own, - each submodule's under `.git/modules/`, and that of a submodule keeping - its own `.git` directory. `git describe` does not need them, and each can - hold a credential: a password in a remote URL, or the token the CI - checkout step stores there. A submodule whose name has a `config` segment - (`config`, `deploy/config`, `config/lib`) loses its whole git directory to - `**/.git/modules/**/config`, and Go's version stamping then fails the - build: give it a name without that segment (`git submodule add --name`). - The stage that compiles has `git` (the Debian Go image has it; an alpine - one needs `apk add --no-cache git`) and takes the version from the - `VERSION` build argument when one is given, otherwise from - `git describe --tags --always`. That gives the tag on a tagged commit; on - a later commit, the tag, the number of commits since it and the short - commit (`v1.2.3-4-gabc1234`); and the short commit when no tag is - reachable. The stage that compiles also marks its working directory safe - for git (`git config --system --add safe.directory /src`): a context sent - as a tar stream keeps the sender's file owners, and git refuses a checkout - owned by another user, so the version would come out empty. `ARG VERSION` - has no default, and the build fails if the context carries `.git` and the - version still comes out empty, `dev` or `unknown`. A plain - `docker build .` with no build arguments must succeed; a Dockerfile that - refuses an empty build argument drops that refusal and keeps the argument. - A checkout whose `.git` is a file (a linked worktree, or a repository - checked out as a submodule) is the exception: that file points to a git - directory outside the build context, so the build cannot read the version - and a plain `docker build .` fails; pass the version with - `--build-arg VERSION=...`. `script/docker` and `script/cibuild` already - pass the version they compute on the host; it takes precedence. The - canonical `.gitea/workflows/check.yml` sets `fetch-depth: 0` on its - checkout step, which otherwise clones shallow and fetches no tags, so a CI - build finds the tag too. + (`**/.git/config`, `**/.git/modules/**/config`): + - the repository's own + - each submodule's under `.git/modules/` + - that of a submodule keeping its own `.git` directory + + `git describe` does not need them, and each can hold a credential: a + password in a remote URL, or the token the CI checkout step stores there. A + submodule name may have a `config` segment, as in `config`, `deploy/config` + or `config/lib`. Such a submodule loses its whole git directory to + `**/.git/modules/**/config`, and Go's version stamping then fails the build. + Give it a name without that segment (`git submodule add --name`). The stage + that compiles has `git`: the Debian Go image has it, and an alpine one needs + `apk add --no-cache git`. That stage takes the version from the `VERSION` + build argument when one is given, otherwise from + `git describe --tags --always`. That gives: + - the tag, on a tagged commit + - the tag, the number of commits since it and the short commit + (`v1.2.3-4-gabc1234`), on a later commit + - the short commit, when no tag is reachable + + The stage that compiles also marks its working directory safe for git + (`git config --system --add safe.directory /src`). A context sent as a tar + stream keeps the sender's file owners, and git refuses a checkout owned by + another user, so the version would come out empty. `ARG VERSION` has no + default. The build fails if the context carries `.git` and the version still + comes out empty, `dev` or `unknown`. A plain `docker build .` with no build + arguments must succeed; a Dockerfile that refuses an empty build argument + drops that refusal and keeps the argument. A checkout whose `.git` is a file + is the exception: a linked worktree, or a repository checked out as a + submodule. That file points to a git directory outside the build context, so + the build cannot read the version and a plain `docker build .` fails. Pass + the version with `--build-arg VERSION=...`. `script/docker` and + `script/cibuild` already pass the version they compute on the host; it takes + precedence. The canonical `.gitea/workflows/check.yml` sets `fetch-depth: 0` + on its checkout step, which otherwise clones shallow and fetches no tags, so + a CI build finds the tag too. + - [ ] Gitea Actions workflow in `.gitea/workflows/` runs `script/cibuild` on push, checks out with `persist-credentials: false` and with `fetch-depth: 0` (which fetches the tags `git describe` needs), carries diff --git a/prompts/NEW_REPO_CHECKLIST.md b/prompts/NEW_REPO_CHECKLIST.md index 2e8a6b8..994c98b 100644 --- a/prompts/NEW_REPO_CHECKLIST.md +++ b/prompts/NEW_REPO_CHECKLIST.md @@ -1,6 +1,6 @@ --- title: New Repo Checklist -last_modified: 2026-11-03 +last_modified: 2026-11-04 --- Use this checklist when creating a new repository from scratch. Follow the steps @@ -75,34 +75,42 @@ Template files can be fetched from: anchored entry. - If the image embeds a version in a binary: `.dockerignore` lets `.git` into the build context. It keeps out every git `config` at any depth - (`**/.git/config`, `**/.git/modules/**/config`): the repository's own, - each submodule's under `.git/modules/`, and that of a submodule keeping - its own `.git` directory. `git describe` does not need them, and each can - hold a credential: a password in a remote URL, or the token the CI - checkout step stores there. A submodule whose name has a `config` segment - (`config`, `deploy/config`, `config/lib`) loses its whole git directory to - `**/.git/modules/**/config`, and Go's version stamping then fails the - build: give it a name without that segment (`git submodule add --name`). - The stage that compiles has `git` (the Debian Go image has it; an alpine - one needs `apk add --no-cache git`) and takes the version from the - `VERSION` build argument when one is given, otherwise from - `git describe --tags --always`. That gives the tag on a tagged commit; on - a later commit, the tag, the number of commits since it and the short - commit (`v1.2.3-4-gabc1234`); and the short commit when no tag is - reachable. The stage that compiles also marks its working directory safe - for git (`git config --system --add safe.directory /src`): a context sent - as a tar stream keeps the sender's file owners, and git refuses a checkout - owned by another user, so the version would come out empty. `ARG VERSION` - has no default, and the build fails if the context carries `.git` and the - version still comes out empty, `dev` or `unknown`. A plain - `docker build .` with no build arguments must succeed; a Dockerfile that - refuses an empty build argument drops that refusal and keeps the argument. - A checkout whose `.git` is a file (a linked worktree, or a repository - checked out as a submodule) is the exception: that file points to a git - directory outside the build context, so the build cannot read the version - and a plain `docker build .` fails; pass the version with - `--build-arg VERSION=...`, as `script/docker` and `script/cibuild` already - do. + (`**/.git/config`, `**/.git/modules/**/config`): + - the repository's own + - each submodule's under `.git/modules/` + - that of a submodule keeping its own `.git` directory + + `git describe` does not need them, and each can hold a credential: a + password in a remote URL, or the token the CI checkout step stores + there. A submodule name may have a `config` segment, as in `config`, + `deploy/config` or `config/lib`. Such a submodule loses its whole git + directory to `**/.git/modules/**/config`, and Go's version stamping then + fails the build. Give it a name without that segment + (`git submodule add --name`). The stage that compiles has `git`: the + Debian Go image has it, and an alpine one needs + `apk add --no-cache git`. That stage takes the version from the + `VERSION` build argument when one is given, otherwise from + `git describe --tags --always`. That gives: + - the tag, on a tagged commit + - the tag, the number of commits since it and the short commit + (`v1.2.3-4-gabc1234`), on a later commit + - the short commit, when no tag is reachable + + The stage that compiles also marks its working directory safe for git + (`git config --system --add safe.directory /src`). A context sent as a + tar stream keeps the sender's file owners, and git refuses a checkout + owned by another user, so the version would come out empty. + `ARG VERSION` has no default. The build fails if the context carries + `.git` and the version still comes out empty, `dev` or `unknown`. A + plain `docker build .` with no build arguments must succeed; a + Dockerfile that refuses an empty build argument drops that refusal and + keeps the argument. A checkout whose `.git` is a file is the exception: + a linked worktree, or a repository checked out as a submodule. That file + points to a git directory outside the build context, so the build cannot + read the version and a plain `docker build .` fails. Pass the version + with `--build-arg VERSION=...`, as `script/docker` and `script/cibuild` + already do. + - 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 @@ -147,6 +155,7 @@ Template files can be fetched from: - 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, checks out with `persist-credentials: false` and with `fetch-depth: 0` (which fetches the tags `git describe` needs), diff --git a/prompts/REPO_POLICIES.md b/prompts/REPO_POLICIES.md index 5cf6158..2a6fec3 100644 --- a/prompts/REPO_POLICIES.md +++ b/prompts/REPO_POLICIES.md @@ -1,6 +1,6 @@ --- title: Repository Policies -last_modified: 2026-11-03 +last_modified: 2026-11-04 --- This document covers repository structure, tooling, and workflow standards. Code @@ -20,18 +20,28 @@ style conventions are in separate documents: `last_modified: YYYY-MM-DD` in the YAML front matter so it can be kept in sync with the authoritative source as policies evolve. -- **External references must be pinned by cryptographic hash.** This includes - Docker base images, Go modules, npm packages, GitHub Actions, and anything - else fetched from a remote source. Version tags (`@v4`, `@latest`, `:3.21`, - etc.) are server-mutable and therefore remote code execution vulnerabilities. - Reference an external dependency by its content hash (Docker `@sha256:...`, Go - module hash in `go.sum`, npm integrity hash in lockfile, GitHub Actions - `@`). This also means never `curl | bash` to install tools like - pyenv, nvm, rustup, etc. Instead, download a specific release archive from - GitHub, verify its hash (hardcoded in the Dockerfile or script), and only then - install. Unverified install scripts are arbitrary remote code execution. This - is the single most important rule in this document. Double-check every - external reference in every file before committing. +- **External references must be pinned by cryptographic hash.** This is the + single most important rule in this document. It covers everything fetched from + a remote source, including: + - Docker base images + - Go modules + - npm packages + - GitHub Actions + + A version tag such as `@v4`, `@latest` or `:3.21` is server-mutable, and + therefore a remote code execution vulnerability. Reference an external + dependency by its content hash: + - Docker: `@sha256:...` + - Go: the module hash in `go.sum` + - npm: the integrity hash in the lockfile + - GitHub Actions: `@` + + This also means never `curl | bash` to install tools like pyenv, nvm, + rustup, etc. Instead, download a specific release archive from GitHub, + verify its hash, and only then install. The hash is hardcoded in the + Dockerfile or script. Unverified install scripts are arbitrary remote code + execution. Double-check every external reference in every file before + committing. There is one exception: a package from the distribution's own package index needs no version and no hash. Pulling that index is also allowed. The @@ -52,62 +62,89 @@ style conventions are in separate documents: own, so the exception does not cover it. - Every repo with software must have a root `Makefile` with these targets: - `make bootstrap`, `make setup`, `make test`, `make lint`, `make fmt` (writes), - `make fmt-check` (read-only), `make check` (runs `test`, `lint`, `fmt-check`), - `make docker`, and `make hooks` (installs pre-commit hook). A model Makefile - is at `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`. + - `make bootstrap` + - `make setup` + - `make test` + - `make lint` + - `make fmt` (writes) + - `make fmt-check` (read-only) + - `make check` (runs `test`, `lint`, `fmt-check`) + - `make docker` + - `make hooks` (installs pre-commit hook) + + A model Makefile is at + `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`. - Repos follow the [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all) - pattern: the implementation of each Makefile target lives in an executable - script in `script/` (`script/bootstrap`, `script/setup`, `script/test`, - `script/lint`, `script/fmt`, `script/fmt-check`, `script/check`, - `script/docker`), and the Makefile targets are thin shims that call them. The - scripts must be POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they run in - minimal containers (e.g. alpine images have no bash); locate the repo root - with `$(cd "$(dirname "$0")/.." && pwd -P)` and `cd` there before acting. From - the standard's canonical set we use `bootstrap`, `setup` (make the repo ready - for development after a fresh clone: runs `bootstrap`, then - `install-precommit`, plus any repo-specific initialization), `test`, and - `cibuild`. `script/bootstrap` installs all dependencies idempotently and - assumes nothing is present: base tools come from nix, apt, brew, or apk - (detected in that order; apt runs noninteractive). For node it uses the - installed node only when its major version is the pinned one; otherwise (node - missing, or another major, such as the node 24 the CI runner image ships) it - installs the PINNED node version via nvm and installs yarn and the packages - under it. nvm itself is installed first if missing, from a hash-verified - GitHub release archive (never `curl | sh`), with bash installed as an explicit - prerequisite since nvm requires bash. Only the major version is compared - because the `Dockerfile` stages start from a node image whose exact version is - not the pin, and nvm cannot install a prebuilt node on alpine. yarn is 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, 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**: when - `script/bootstrap` installs node and yarn under nvm it leaves neither on the - `PATH` of the shell that called it, so a bare `yarn` either exits 127 or runs - under another node. The host entrypoints that need yarn — `script/fmt` and - `script/fmt-check` — therefore use the same test as `script/bootstrap`: when - the node on `PATH` has the pinned major version they run the `yarn` on `PATH`, - and otherwise they load nvm through `$HOME/.nvm/nvm.sh` and run yarn under the - pinned node. 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). + pattern. The implementation of each Makefile target lives in an executable + script in `script/`, and the Makefile targets are thin shims that call them: + - `script/bootstrap` + - `script/setup` + - `script/test` + - `script/lint` + - `script/fmt` + - `script/fmt-check` + - `script/check` + - `script/docker` + + The scripts must be POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they + run in minimal containers; alpine images, for example, have no bash. Locate + the repo root with `$(cd "$(dirname "$0")/.." && pwd -P)`, and `cd` there + before acting. + + From the standard's canonical set we use `bootstrap`, `setup`, `test`, and + `cibuild`. `setup` makes the repo ready for development after a fresh clone: + it runs `bootstrap`, then `install-precommit`, plus any repo-specific + initialization. + + `script/bootstrap` installs all dependencies idempotently and assumes + nothing is present. Base tools come from nix, apt, brew, or apk, detected in + that order; apt runs noninteractive. For node it uses the installed node + only when its major version is the pinned one. When node is missing or has + another major, it installs the PINNED node version via nvm, and installs + yarn and the packages under it. The CI runner image ships node 24, for + example. nvm itself is installed first if missing, from a hash-verified + GitHub release archive, never `curl | sh`. bash is installed as an explicit + prerequisite, since nvm requires bash. Only the major version is compared + because the `Dockerfile` stages start from a node image whose exact version + is not the pin, and nvm cannot install a prebuilt node on alpine. yarn is + pinned via `corepack prepare yarn@ --activate`. Never install + "latest" or "lts"; always exact versions. + + `script/cibuild` runs the CI build, and the Gitea workflow calls it. The + script changes to the repo root, runs `script/bootstrap`, runs + `script/check`, and builds the image with the version. **`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.** When `script/bootstrap` installs node and yarn under nvm, it + leaves neither on the `PATH` of the shell that called it. A bare `yarn` then + either exits 127 or runs under another node. The host entrypoints that need + yarn, `script/fmt` and `script/fmt-check`, therefore use the same test as + `script/bootstrap`. When the node on `PATH` has the pinned major version, + they run the `yarn` on `PATH`. Otherwise they load nvm through + `$HOME/.nvm/nvm.sh` and run yarn under the pinned node. 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. + - `script/projectname` (literally that filename) simply outputs the + project's name. + + Scripts that need the name call `script/projectname`, so those scripts stay + byte-identical across all repos. `script/docker`, for example, assembles its + image tag from it. Repo-type-specific pre-commit extras belong in + `script/precommit`, not in the hook itself; `go mod tidy` verification in Go + repos is one. Model scripts are at + `https://git.eeqj.de/sneak/prompts/raw/branch/main/script/`. The + README must document the provided scripts in an **Entrypoints** section (see + the README requirements below). - Always use Makefile targets (`make fmt`, `make test`, `make lint`, etc.) instead of invoking the underlying tools directly. The Makefile is the single @@ -115,26 +152,33 @@ style conventions are in separate documents: - The Makefile is authoritative documentation for how the repo is used. Beyond the required targets above, it should have targets for every common operation: - running a local development server (`make run`, `make dev`), re-initializing - or migrating the database (`make db-reset`, `make migrate`), building - artifacts (`make build`), generating code, seeding data, or anything else a - developer would do regularly. If someone checks out the repo and types - `make`, they should see every meaningful operation available. A new - contributor should be able to understand the entire development workflow by - reading the Makefile. + - running a local development server (`make run`, `make dev`) + - re-initializing or migrating the database (`make db-reset`, + `make migrate`) + - building artifacts (`make build`) + - generating code + - seeding data + - anything else a developer would do regularly + + If someone checks out the repo and types `make`, they should see every + meaningful operation available. A new contributor should be able to + understand the entire development workflow by reading the Makefile. - 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. - The gate phases and the build stage start from their pinned base images and - install what those images lack either inline, as the canonical Go `Dockerfile` - below does for `git`, or by running `script/bootstrap`, as the `prompts` - repo's own `Dockerfile` does for its yarn packages. The development - environment stage installs development prerequisites by running - `script/bootstrap` rather than duplicating its installs inline. A stage that - runs `script/bootstrap` COPYs `script/` and the dependency manifests - (`package.json` + `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it. + `lint` phase and a `test` phase. The final stage depends 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. The + gate phases and the build stage start from their pinned base images and + install what those images lack in either of these ways: + - inline, as the canonical Go `Dockerfile` below does for `git` + - by running `script/bootstrap`, as the `prompts` repo's own `Dockerfile` + does for its yarn packages + + The development environment stage installs development prerequisites by + running `script/bootstrap` rather than duplicating its installs inline. A + stage that runs `script/bootstrap` COPYs `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 @@ -150,9 +194,9 @@ style conventions are in separate documents: **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. + `COPY --from=` of a harmless file from each of them. Without that + dependency, a plain `docker build .` builds the last stage alone and exits 0 + having linted and tested nothing. **The gate builds write no image.** With `--output type=cacheonly` the phase runs and a failing step fails the build, but the result is not exported. @@ -160,69 +204,84 @@ style conventions are in separate documents: image holds the toolchain. A build given neither `--output` nor `-t` writes an untagged image and leaves it dangling, on every developer host and every CI runner. `script/cibuild` and `script/docker` build the image that ships - and tag it, so each build replaces the previous image; each assigns the tag - on its own line before the build, so `set -e` stops it where + and tag it, so each build replaces the previous image. Each script assigns + the tag on its own line before the build, so `set -e` stops it where `script/projectname` fails. - 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. + Inside a phase the tool is invoked directly: `golangci-lint`, `go test`, + `eslint`, `prettier`. The tool is never invoked through `make lint` or + `script/test`. Those 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 `TMPDIR`, so the lock is - out of reach. The lint phase does keep golangci-lint's cache between check - builds (below), but it lints every checkout at `/src`, and a finding is - taken from that cache only for the same files, settings and golangci-lint - version. + than location. A second checkout of the same content is therefore served the + first one's findings. A host-global lock in `$TMPDIR` also 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 `TMPDIR`, so the lock + is out of reach. The lint phase does keep golangci-lint's cache between + check builds (below), but it lints every checkout at `/src`. A finding is + taken from that cache only when all of these are the same: + - the files + - the settings + - the golangci-lint version - **Any build that runs checks is given a new `CACHEBUST` value.** 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. Every `docker build` in `script/` therefore passes - `--build-arg CACHEBUST="$(date +%s)-$$"`, the time and the script's process - id, so no two builds share a value, not even the three in one - `script/cibuild`. `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. In - every stage of the `Dockerfile`, every step that lints, tests or compiles - comes after `ARG CACHEBUST`. `ARG CACHEBUST` comes right after these steps: + invalidates a `COPY` layer only when the copied content changes. On an + unchanged tree the check `RUN` is therefore served from cache, nothing + executes, and the build still exits 0. Every `docker build` in `script/` + therefore passes `--build-arg CACHEBUST="$(date +%s)-$$"`, the time and the + script's process id. So no two builds share a value, not even the three in one + `script/cibuild`. These are the four, and there is no fifth: + - `script/lint` + - `script/test` + - `script/cibuild` + - `script/docker` + + `script/check` runs the two gate phases and `script/fmt-check`, and builds + no image of its own. In every stage of the `Dockerfile`, every step that + lints, tests or compiles comes after `ARG CACHEBUST`. `ARG CACHEBUST` comes + right after these steps: - the steps that install system packages - the steps that download Go's modules - the step that runs `script/bootstrap` to install a Python `test` phase's packages from `Pipfile.lock` A stage with none of these steps declares `ARG CACHEBUST` right after - `FROM`. A step that installs anything else as well, such as a - `script/bootstrap` that also installs node packages, comes after it too. A - new value reruns every `RUN` step after that line; `COPY` steps are compared - by content and need nothing. Docker keeps the layers above the line until - the base image, their own lines or the files they copy change. A stage - without the `ARG` line is served from cache on an unchanged tree, so a - repository re-vendors the scripts and adds the `ARG` lines in one commit. - The scripts do not pass `--no-cache`: it reruns every step too, but it also - builds the layers above the line again and empties every cache mount, so - Go's build cache and golangci-lint's, which the canonical Go `Dockerfile` - below mounts so that they survive between check builds, would start empty - every time. 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. When a check is added or - changed, prove it works by planting a defect it must catch and watching the - run fail on it, then revert the defect. A green run alone shows neither that - the check ran nor that it covers what it should. + `FROM`. A step that also installs anything else comes after `ARG CACHEBUST` + too. A `script/bootstrap` that also installs node packages is one. A new + value reruns every `RUN` step after that line; `COPY` steps are compared by + content and need nothing. Docker keeps the layers above the line until one + of these changes: + - the base image + - their own lines + - the files they copy + + A stage without the `ARG` line is served from cache on an unchanged tree, so + a repository re-vendors the scripts and adds the `ARG` lines in one commit. + The scripts do not pass `--no-cache`. That flag reruns every step too, but + it also builds the layers above the line again and empties every cache + mount. Go's build cache and golangci-lint's would then start empty every + time; the canonical Go `Dockerfile` below mounts them so that they survive + between check builds. 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. When a check is added + or changed, prove it works: + - plant a defect it must catch + - watch the run fail on it + - revert the defect + + A green run alone shows neither that the check ran nor that it covers what + it should. - **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 Debian Go image. The canonical Go repo + hash), so lint failures surface in seconds rather than after a full compile. + The test phase is based on the Debian Go image. The canonical Go repo `Dockerfile`: ```dockerfile @@ -314,24 +373,24 @@ style conventions are in separate documents: ``` Key points: - - The lint phase uses the `golangci/golangci-lint` image directly (it has - both Go and the linter), so nothing needs installing. + - The lint phase uses the `golangci/golangci-lint` image directly, so + nothing needs installing: it has both Go and the linter. - `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. + purpose is the dependency on that phase. BuildKit runs stages in parallel + by default, and a stage nothing depends on is not built at all. Without + these two lines a red gate would not fail the build. + - Keep the runtime stage last. 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. - Check builds keep these, and none of them can hand back a stale result: - The layers above `ARG CACHEBUST`: the system packages and Go's modules. Docker installs the packages again when the base image or the - install line changes, and downloads the modules again when `go.mod` or - `go.sum` changes. Go checks every module against `go.sum` as it + install line changes. Docker downloads the modules again when `go.mod` + or `go.sum` changes. Go checks every module against `go.sum` as it downloads it, and no later build can change a kept layer. The modules - are kept in a layer rather than a cache mount because a cache mount is - shared by every build on the host, and Go builds from whatever files - it holds without checking them again (only `go mod verify` does), so a + are kept in a layer rather than a cache mount. A cache mount is shared + by every build on the host, and Go builds from whatever files the + mount holds without checking them again (only `go mod verify` does). A file changed there would go unnoticed. - Go's build cache (`/root/.cache/go-build`, where Go keeps it for root), mounted on the steps that compile: `golangci-lint run`, both @@ -340,19 +399,22 @@ style conventions are in separate documents: is why both `go test` runs carry `-count=1`. - golangci-lint's cache (`/root/.cache/golangci-lint`, where the pinned image keeps it), mounted on `golangci-lint run`. golangci-lint reuses - a package's findings only when the package's files and those of every - package it imports, `go.mod`, the linters and their settings in - `.golangci.yml`, and the golangci-lint version are all unchanged. + a package's findings only when all of these are unchanged: + - the package's files and those of every package it imports + - `go.mod` + - the linters and their settings in `.golangci.yml` + - the golangci-lint version - In a Python `test` phase, the layer of the step that runs `script/bootstrap` to install the packages from `Pipfile.lock`, as described for that phase below. - - If the project uses `//go:embed` directives that reference build artifacts - (e.g. a web frontend compiled in a separate stage), the lint phase must - create placeholder files so the embed directives resolve. Example: + - If the project uses `//go:embed` directives that reference build + artifacts, the lint phase must create placeholder files so the embed + directives resolve. A web frontend compiled in a separate stage is such an + artifact. Example: `RUN mkdir -p web/dist && touch web/dist/index.html web/dist/style.css`. - If the project requires CGO or system libraries for linting, install them in the lint phase. The `golangci/golangci-lint` image is Debian-based and - has no `apk`, so install with `apt-get` under the Debian package name + has no `apk`. So install with `apt-get` under the Debian package name (`libvips-dev`, where alpine says `vips-dev`), and delete the package lists in the same `RUN`, so the layer does not keep them. The test phase, on the Debian Go image, installs the libraries its tests need the same @@ -371,73 +433,96 @@ style conventions are in separate documents: ``` - `.dockerignore` lets `.git` into the build context. It keeps out every git - `config` at any depth (`**/.git/config`, `**/.git/modules/**/config`): the - repository's own, each submodule's under `.git/modules/`, and that of a - submodule keeping its own `.git` directory. `git describe` does not need - them, and each can hold a credential: a password in a remote URL, or the - token the CI checkout step stores there. A submodule whose name has a - `config` segment (`config`, `deploy/config`, `config/lib`) loses its whole - git directory to `**/.git/modules/**/config`, and Go's version stamping - then fails the build: give it a name without that segment - (`git submodule add --name`). The stage that compiles has `git` (the - Debian Go image has it; an alpine one needs `apk add --no-cache git`) and - takes the version from the `VERSION` build argument when one is given, - otherwise from `git describe --tags --always`. That gives the tag on a - tagged commit; on a later commit, the tag, the number of commits since it - and the short commit (`v1.2.3-4-gabc1234`); and the short commit when no - tag is reachable. The stage that compiles also marks its working directory - safe for git (`git config --system --add safe.directory /src`): a context - sent as a tar stream keeps the sender's file owners, and git refuses a - checkout owned by another user, so the version would come out empty. - `ARG VERSION` has no default, and the build fails if the context carries - `.git` and the version still comes out empty, `dev` or `unknown`. A plain - `docker build .` with no build arguments must succeed; a Dockerfile that - refuses an empty build argument drops that refusal and keeps the argument. - A checkout whose `.git` is a file (a linked worktree, or a repository - checked out as a submodule) is the exception: that file points to a git - directory outside the build context, so the build cannot read the version - and a plain `docker build .` fails; pass the version with - `--build-arg VERSION=...`, as `script/docker` and `script/cibuild` already - do. + `config` at any depth (`**/.git/config`, `**/.git/modules/**/config`): + - the repository's own + - each submodule's under `.git/modules/` + - that of a submodule keeping its own `.git` directory + + `git describe` does not need them, and each can hold a credential: a + password in a remote URL, or the token the CI checkout step stores + there. A submodule name may have a `config` segment, as in `config`, + `deploy/config` or `config/lib`. Such a submodule loses its whole git + directory to `**/.git/modules/**/config`, and Go's version stamping then + fails the build. Give it a name without that segment + (`git submodule add --name`). The stage that compiles has `git`: the + Debian Go image has it, and an alpine one needs + `apk add --no-cache git`. That stage takes the version from the + `VERSION` build argument when one is given, otherwise from + `git describe --tags --always`. That gives: + - the tag, on a tagged commit + - the tag, the number of commits since it and the short commit + (`v1.2.3-4-gabc1234`), on a later commit + - the short commit, when no tag is reachable + + The stage that compiles also marks its working directory safe for git + (`git config --system --add safe.directory /src`). A context sent as a + tar stream keeps the sender's file owners, and git refuses a checkout + owned by another user, so the version would come out empty. + `ARG VERSION` has no default. The build fails if the context carries + `.git` and the version still comes out empty, `dev` or `unknown`. A + plain `docker build .` with no build arguments must succeed; a + Dockerfile that refuses an empty build argument drops that refusal and + keeps the argument. A checkout whose `.git` is a file is the exception: + a linked worktree, or a repository checked out as a submodule. That file + points to a git directory outside the build context, so the build cannot + read the version and a plain `docker build .` fails. Pass the version + with `--build-arg VERSION=...`, as `script/docker` and `script/cibuild` + already do. - **A Python `test` phase that installs its packages from `Pipfile.lock` does it - above `ARG CACHEBUST`, so check builds keep them.** The steps are - `COPY script/ script/`, `COPY Pipfile Pipfile.lock ./` and - `RUN script/bootstrap`, with `ARG CACHEBUST` right after them. Docker keeps - what that `RUN` installed until the base image, `script/`, `Pipfile`, - `Pipfile.lock` or a line up to and including the `RUN` changes. The tests run - after `ARG CACHEBUST`, on every check build. In every other stage, a step that - installs Python packages comes after `ARG CACHEBUST`. + above `ARG CACHEBUST`, so check builds keep them.** The steps are: + - `COPY script/ script/` + - `COPY Pipfile Pipfile.lock ./` + - `RUN script/bootstrap` + + `ARG CACHEBUST` comes right after them. Docker keeps what that `RUN` + installed until one of these changes: + - the base image + - `script/` + - `Pipfile` + - `Pipfile.lock` + - a line up to and including the `RUN` + + The tests run after `ARG CACHEBUST`, on every check build. In every other + stage, a step that installs Python packages comes after `ARG CACHEBUST`. - When `script/bootstrap` runs in that step, it installs nothing beyond - system packages, pipenv and its dependencies, and the packages from - `Pipfile.lock`. It installs no Python there: the tests use the base - image's Python, which the image's hash pins. If it installs anything else - there, the step goes after `ARG CACHEBUST`. + these: + - system packages + - pipenv and its dependencies + - the packages from `Pipfile.lock` + + `script/bootstrap` installs no Python there: the tests use the base + image's Python, which the image's hash pins. If it installs anything + else there, the step goes after `ARG CACHEBUST`. + - PyPI is not trusted, so `script/bootstrap` installs pipenv and its dependencies by hash. It does so with `pip install --require-hashes -r` and a requirements file in `script/` that lists each of them with `==` and its `--hash`. pip refuses to install a dependency the file does not list. - It then runs `pipenv install --deploy`, with `--dev` when the tests need - the development packages. `--deploy` installs only what `Pipfile.lock` - names, checks every package against the lockfile's hashes, and fails when - the lockfile is out of date with `Pipfile`. - - A kept layer holds nothing a new install would refuse: pip checked pipenv - and its dependencies, and pipenv checked the lockfile's packages, against - their hashes. pipenv creates its virtual environment with the `virtualenv` - package. The packages that `virtualenv` adds come from wheels inside that - package, so the hash pip checked for it covers them. Two things in the - layer are not fixed by a hash. A package with no ready-built wheel for the - image is built from source. pip downloads the build tools without a hash - check, so a kept layer's build of such a package may differ from a new - one. And system packages keep the versions the package manager gave when - the layer was built; a new install may get newer ones. + the development packages. `--deploy` does all of these: + - installs only what `Pipfile.lock` names + - checks every package against the lockfile's hashes + - fails when the lockfile is out of date with `Pipfile` + - A kept layer holds nothing a new install would refuse: pip checked the + hashes of pipenv and its dependencies, and pipenv checked the hashes of + the lockfile's packages. pipenv creates its virtual environment with the + `virtualenv` package. The packages that `virtualenv` adds come from wheels + inside that package, so the hash pip checked for it covers them. Two + things in the layer are not fixed by a hash: + - A package with no ready-built wheel for the image is built from + source. pip downloads the build tools without a hash check, so a kept + layer's build of such a package may differ from a new one. + - System packages keep the versions the package manager gave when the + layer was built; a new install may get newer ones. - As with Go's modules, the packages are kept in a layer, not a cache mount. A cache mount is shared by every build on the host, and nothing checks its files again. - In this example, `script/bootstrap` finds `make` and `git` already - installed, installs pipenv and its dependencies by hash, and runs - `pipenv install --dev --deploy`: + In the example below, `script/bootstrap` does all of these: + - finds `make` and `git` already installed + - installs pipenv and its dependencies by hash + - runs `pipenv install --dev --deploy` ```dockerfile # Test phase. Both pytest runs share one 90-second timeout, so a hang @@ -462,48 +547,54 @@ style conventions are in separate documents: ``` - Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that - runs `script/cibuild` on push, and checks out the repo as its only other step, - with `persist-credentials: false`: `script/cibuild` needs no token, and - without it the checkout leaves the job's token in `.git/config` for every - later step. The checkout step also sets `fetch-depth: 0`, which fetches the - tags `git describe` needs: by default it clones shallow with no tags, and a - tagged repository's CI build would stamp a bare short commit id. The + runs `script/cibuild` on push. The workflow's only other step checks out the + repo, with `persist-credentials: false`. `script/cibuild` needs no token, and + without that setting the checkout leaves the job's token in `.git/config` for + every later step. The checkout step also sets `fetch-depth: 0`, which fetches + the tags `git describe` needs. By default it clones shallow with no tags, and + a tagged repository's CI build would stamp a bare short commit id. The workflow's `concurrency` block groups runs by workflow and branch - (`${{ github.workflow }}-${{ github.ref }}`) with `cancel-in-progress: true`, - so a new push cancels the older run on the same branch, queued or running, and - no other: runs for replaced commits do not hold up the shared runner. + (`${{ github.workflow }}-${{ github.ref }}`) with `cancel-in-progress: true`. + A new push then cancels the older run on the same branch, queued or running, + and no other: runs for replaced commits do not hold up the shared runner. `script/cibuild` bootstraps, runs the gate phases, and then builds the image, - so a successful run means every check passed; a bare `docker build .` does not + 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 gets a `CACHEBUST` value of its own and so runs the gate phases a - second time. That is the price of the rule above, and it is worth paying: the + 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. The `check` job sets `timeout-minutes: 20`, so a hung build frees the shared runner after 20 minutes. That allows for the three Docker builds - described above (the test phase, the lint phase, then the image), each held to - the 5-minute Docker build limit below, plus the bootstrap. A separate workflow - limited to `main` by a `branches` list under `on: push` cannot be checked by - review: to try a change to it, add the feature branch to that list and push, - then remove the branch from the list again before merging. Keep any job in it - that publishes behind `if: github.ref_name == 'main'`, so the run from the - feature branch publishes nothing. + described above, each held to the 5-minute Docker build limit below, plus the + bootstrap. Those builds are the test phase, the lint phase, then the image. A + separate workflow limited to `main` by a `branches` list under `on: push` + cannot be checked by review. To try a change to it, add the feature branch to + that list and push, then remove the branch from the list again before merging. + Keep any job in it that publishes behind `if: github.ref_name == 'main'`, so + the run from the feature branch publishes nothing. -- Use platform-standard formatters: `black` for Python, `prettier` for - JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with - two exceptions: four-space indents (except Go), and `proseWrap: always` for - Markdown (hard-wrap at 80 columns). Documentation and writing repos (Markdown, - HTML, CSS) should also have `.prettierrc` and `.prettierignore`. +- Use platform-standard formatters: + - `black` for Python + - `prettier` for JS/CSS/Markdown/HTML + - `go fmt` for Go + + Always use default configuration, with two exceptions: + - four-space indents (except Go) + - `proseWrap: always` for Markdown (hard-wrap at 80 columns) + + Documentation and writing repos (Markdown, HTML, CSS) should also have + `.prettierrc` and `.prettierignore`. - Pre-commit hook: runs `script/precommit`, which calls `script/check`. If local testing is not possible in the repo, `script/precommit` may skip `script/test` - and run only `script/lint` and `script/fmt-check`. The hook is installed by - `script/install-precommit`; the Makefile must provide a `make hooks` target - that shims to it. + and run only `script/lint` and `script/fmt-check`. `script/install-precommit` + installs the hook; the Makefile must provide a `make hooks` target that shims + to it. - All repos with software must have tests that run via the platform-standard test framework (`go test`, `pytest`, `jest`/`vitest`, etc.). If no meaningful - tests exist yet, add the most minimal test possible — e.g. importing the - module under test to verify it compiles/parses. There is no excuse for + tests exist yet, add the most minimal test possible: importing the module + under test to verify it compiles/parses, for example. There is no excuse for `make test` to be a no-op. - `make test` must complete in under 60 seconds. That is the hard cap, and a @@ -519,11 +610,11 @@ style conventions are in separate documents: - **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). A first run that timed + on success, with just package/suite summaries. On failure it provides full + diagnostic detail: every test case, every assertion. A first run that timed out gets no rerun, because the rerun would only wait for the same hang. 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 + builds that phase. The Makefile form below is the same pattern for any repo-local invocation: ```makefile @@ -560,18 +651,18 @@ style conventions are in separate documents: exits 1. A failure with neither line in its output reruns with `-v`. The kept output prints when the first run ends, not while it runs. - `-count=1` is required on both invocations: it defeats Go's test _result_ + `-count=1` is required on both invocations. It defeats Go's test _result_ cache, so neither run can report a stored pass in place of running the tests. It leaves the build cache alone, so it costs the runtime of the suite and no recompilation. That cache is Go's own, separate from Docker's layer cache. Go stores a - passing result in its cache directory (`GOCACHE`), and when the same tests - run again on unchanged code it prints that result, marked `(cached)`, - without running them. The directory lasts from one run to the next on a - developer's machine, where this target runs, and in the `test` phase of the - `Dockerfile`, which mounts it to keep compiled packages between check - builds, so the phase's `go test` runs carry `-count=1` too. A new + passing result in its cache directory (`GOCACHE`). When the same tests run + again on unchanged code, it prints that result, marked `(cached)`, without + running them. The directory lasts from one run to the next on a developer's + machine, where this target runs. The directory also lasts in the `test` + phase of the `Dockerfile`, which mounts it to keep compiled packages between + check builds, so the phase's `go test` runs carry `-count=1` too. A new `CACHEBUST` value (above) is what makes that step run on an unchanged tree. Python example: @@ -589,7 +680,7 @@ style conventions are in separate documents: seconds run out. On a Mac without `timeout`, the target fails until it is installed. - The `exit 1` ensures the target always fails after a rerun — the first run + The `exit 1` ensures the target always fails after a rerun. The first run already proved the tests are broken, so the build must not pass even if a flaky test happens to succeed on the second attempt. The rerun exists solely for diagnostic output. @@ -606,59 +697,66 @@ style conventions are in separate documents: - Never commit secrets. `.env` files, credentials, API keys, and private keys must be in `.gitignore`. No exceptions. -- `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`), - editor files (`.swp`, `*~`), in-repo agent scratch directories (`.claude/`), - `node_modules/`, and the repo's own build outputs. Fetch the standard - `.gitignore` from - `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up - a new repo. A repo's `.gitignore` is the standard file followed by the repo's - own entries, such as its binaries; a re-vendor replaces the standard part and - keeps those entries. 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. +- `.gitignore` should be comprehensive from the start: + - OS files (`.DS_Store`) + - editor files (`.swp`, `*~`) + - in-repo agent scratch directories (`.claude/`) + - `node_modules/` + - the repo's own build outputs + + Fetch the standard `.gitignore` from + `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting + up a new repo. A repo's `.gitignore` is the standard file followed by the + repo's own entries, such as its binaries. A re-vendor replaces the standard + part and keeps those entries. 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 + `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: `.claude`, 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 + therefore excludes only the copies at the repository root. `config/.env` and + `certs/server.key` still reach the context and can land in an image layer. + Such a `.dockerignore` 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. Those are `.claude`, and the repo's own + host-built binary. The binary is 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 copy of each 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. - **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 + semantics.** `.claude/` holds one worktree per in-flight agent, an entire + additional checkout of the repo. Under `COPY . .` the build context therefore + 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. + that name from the build. Anchoring carries a known gap. The canonical + `.dockerignore` states the gap in its own comment, since consuming repos + receive the file and not the tracker. The gap is that the directory is created + in the agent's working directory. A repo running agents in subdirectories + therefore still ships `services/api/.claude/` and must add its own anchored + entry there. - **A plain `docker build .` of a clone stamps the version that - `git describe --tags --always` gives**, derived from the `.git` in the build - context as the canonical `Dockerfile` above shows. Without its failure check, - a missing `git` or an unreadable checkout would leave `-X main.Version=` empty - and the build would still exit 0. `script/docker` and `script/cibuild` pass - the version they compute on the host; it takes precedence. They do this - byte-identically across repos: + `git describe --tags --always` gives.** The version is derived from the `.git` + in the build context, as the canonical `Dockerfile` above shows. Without its + failure check, a missing `git` or an unreadable checkout would leave + `-X main.Version=` empty, and the build would still exit 0. `script/docker` + and `script/cibuild` pass the version they compute on the host; it takes + precedence. They do this byte-identically across repos: ```sh # The version and the tag each get their own line: a failing command @@ -673,30 +771,34 @@ style conventions are in separate documents: ``` `--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` in the stage that compiles, declared - there because `ARG` is stage-scoped; passing `VERSION` to a repo whose + than failing. The `[ -n "$version" ]` line is the single place the fallback + is applied. That line is 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` 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 the canonical `.gitea/workflows/check.yml` sets `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 + 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 - repository if it can be avoided. The build process (e.g. Dockerfile, Makefile) - should generate these at build time. Notable exception: Go protobuf generated - files (`.pb.go`) ARE committed because repos need to work with `go get`, which - downloads code but does not execute code generation. +- **No build artifacts in version control.** Code-derived data must never be + committed to the repository if it can be avoided. Code-derived data includes: + - compiled bundles + - minified output + - generated assets + + The build process (e.g. Dockerfile, Makefile) should generate these at build + time. Notable exception: Go protobuf generated files (`.pb.go`) ARE + committed because repos need to work with `go get`, which downloads code but + does not execute code generation. - Never use `git add -A` or `git add .`. Always stage files explicitly by name. @@ -706,53 +808,58 @@ style conventions are in separate documents: feature branch. - `.golangci.yml` is standardized. The vendored copy in a consuming repo must - _NEVER_ be modified by an agent: fetch it from + _NEVER_ be modified by an agent. Fetch it from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml` and keep it byte-identical, so that no repo can quietly loosen its own linting. Linter configuration changes are made to the canonical copy in the `prompts` repo and - reach consuming repos by re-vendoring; an agent may open a PR against + reach consuming repos by re-vendoring. An agent may open a PR against canonical, which only the user merges. One list is exempt from byte-identity, because it cannot be written once for every repo: the `deny` list of the - `test-support` depguard rule, where a repo names its own test-support packages + `test-support` depguard rule. There 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.15.0 (released 2026-10-16), pinned as the digest of the lint phase's base - image - (`golangci/golangci-lint@sha256:fbfcfd12a6f8d7f1b97b3362ca80fc2a244d46863148c73cb88e7793af96c481`, - which reports `2.15.0 built with go1.27.0 from 25c5369a`). A module's `go` + v2.15.0 (released 2026-10-16). The version is pinned as the digest of the lint + phase's base image, + `golangci/golangci-lint@sha256:fbfcfd12a6f8d7f1b97b3362ca80fc2a244d46863148c73cb88e7793af96c481`, + which reports `2.15.0 built with go1.27.0 from 25c5369a`. A module's `go` directive must not name a newer Go minor version than the one golangci-lint - was built with, or golangci-lint refuses to lint it: this release lints + was built with, or golangci-lint refuses to lint it. This release lints `go 1.27.1` but not `go 1.28`. That digest is the only pin, since no repo installs golangci-lint on the host. A repo sets the lint phase digest to the one named here and re-vendors `.golangci.yml` in the same commit, whichever of - the two prompted the change: the canonical copy can name linters that an older - golangci-lint rejects, and a newer golangci-lint can add linters that + the two prompted the change. The canonical copy can name linters that an older + golangci-lint rejects. A newer golangci-lint can add linters that `default: all` switches on until the canonical copy disables them. - **`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 + `PATH` only. On an already-provisioned machine the pin is then inert, and a + version bump is a silent no-op. 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 + 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 `--version` output as a mismatch when it is any of these: + - absent + - non-zero + - empty + - unrecognised + + So a failure causes a redundant install, never a skipped one. + + - after installing, re-resolves the binary the way callers do, with + `hash -r` and then through `PATH`, not through the directory the installer + wrote to. It fails and names the resolved path. A shadowing binary can + hide an install, which then succeeds while no caller sees any change. + - 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. - Node is the exception to the whole-token comparison: the canonical - `script/bootstrap` compares only its major version, because the node 22 - alpine image the `Dockerfile` stages start from is not the exact pin, and - nvm cannot install a prebuilt node on alpine. + Node is the exception to the whole-token comparison. The canonical + `script/bootstrap` compares only node's major version, because the + `Dockerfile` stages start from a node 22 alpine image, which is not the + exact pin, and nvm cannot install a prebuilt node on alpine. Keep it POSIX sh: no arrays, no `[[`, no `grep -P`. @@ -814,15 +921,21 @@ style conventions are in separate documents: - True client IP detection when behind a reverse proxy (`X-Forwarded-For`, `X-Real-IP`). The application must accept forwarded headers only from a configured set of trusted proxy - addresses — never trust `X-Forwarded-For` unconditionally. + addresses. Never trust `X-Forwarded-For` unconditionally. - **CORS:** - Authenticated endpoints must restrict `Access-Control-Allow-Origin` to an explicit allowlist of known origins. Wildcard (`*`) is acceptable only for public, unauthenticated read-only APIs. - **Error handling:** - - Internal errors must never leak stack traces, SQL queries, file paths, - or other implementation details to the client. Return generic error - messages in production; detailed errors only when `DEBUG` is enabled. + - Internal errors must never leak implementation details to the client, + such as: + - stack traces + - SQL queries + - file paths + + Return generic error messages in production; detailed errors only + when `DEBUG` is enabled. + - **TLS:** - Services never terminate TLS directly. They are always deployed behind a TLS-terminating reverse proxy. The service itself listens on plain @@ -834,10 +947,17 @@ style conventions are in separate documents: still expected. When in doubt, harden. - `README.md` is the primary documentation. Required sections: - - **Description**: First line must include the project name, purpose, - category (web server, SPA, CLI tool, etc.), license, and author. Example: - "µPaaS is an MIT-licensed Go web application by @sneak that receives - git-frontend webhooks and deploys applications via Docker in realtime." + - **Description**: First line must include: + - the project name + - purpose + - category (web server, SPA, CLI tool, etc.) + - license + - author + + Example: "µPaaS is an MIT-licensed Go web application by @sneak that + receives git-frontend webhooks and deploys applications via Docker in + realtime." + - **Getting Started**: Copy-pasteable install/usage code block. - **Entrypoints**: Opens by stating that the repo adheres to the [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all) @@ -870,17 +990,25 @@ style conventions are in separate documents: Never edit existing migrations after release. - All repos should have an `.editorconfig` enforcing the project's indentation - settings: the standard file from - `https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig`, which sets - tabs for `Makefile` and Go files, followed by the repo's own sections, such as - one for another language it uses. A re-vendor replaces the standard part and - keeps those sections. + settings. It is the standard file from + `https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig`, followed by + the repo's own sections, such as one for another language it uses. The + standard file sets tabs for `Makefile` and Go files. A re-vendor replaces the + standard part and keeps those sections. - Avoid putting files in the repo root unless necessary. Root should contain - only project-level config files (`README.md`, `AGENTS.md`, `Makefile`, - `Dockerfile`, `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`, - and language-specific config). Everything else goes in a subdirectory. - Canonical subdirectory names: + only project-level config files: + - `README.md` + - `AGENTS.md` + - `Makefile` + - `Dockerfile` + - `LICENSE` + - `.gitignore` + - `.editorconfig` + - `REPO_POLICIES.md` + - language-specific config + + Everything else goes in a subdirectory. Canonical subdirectory names: - `bin/` — executable scripts and tools - `cmd/` — Go command entrypoints; thin only: one `main.go` per binary whose body is a single call into `internal/` or `pkg/`, no project logic in