diff --git a/Dockerfile b/Dockerfile index 8e55928..761c933 100644 --- a/Dockerfile +++ b/Dockerfile @@ -2,11 +2,15 @@ # lint` or `script/lint`, which are themselves a docker build and would # recurse into a daemon that does not exist in a build step. # -# Every stage declares ARG CACHEBUST first: script/ passes a new value on -# every build, which reruns every RUN step after it. +# In every stage, ARG CACHEBUST comes right after the step that installs +# system packages. script/ passes a new value on every build. That value +# reruns every RUN step below the ARG line, and the install step keeps +# its layer. node and yarn come from the distribution, which is trusted, +# so they need no version and no hash. # -# node 22-alpine, 2026-02-22 -FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 AS lint +# alpine 3.24.3, 2026-11-04 +FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a AS lint +RUN apk add --no-cache git make nodejs yarn ARG CACHEBUST WORKDIR /app @@ -21,8 +25,9 @@ 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 +# alpine 3.24.3, 2026-11-04 +FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a AS test +RUN apk add --no-cache git make nodejs yarn ARG CACHEBUST WORKDIR /app @@ -41,8 +46,9 @@ RUN echo "No tests defined." # 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 +# alpine 3.24.3, 2026-11-04 +FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a +RUN apk add --no-cache git make nodejs yarn ARG CACHEBUST WORKDIR /app @@ -50,8 +56,8 @@ 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. +# script/bootstrap finds the system packages above and installs the node +# packages. COPY script/ script/ COPY package.json yarn.lock ./ RUN script/bootstrap diff --git a/README.md b/README.md index cc9496d..7b8da4a 100644 --- a/README.md +++ b/README.md @@ -156,9 +156,9 @@ A stage with none of these steps declares `ARG CACHEBUST` right after `FROM`. The `script/` builds pass a new `CACHEBUST` value on every build, which reruns every `RUN` step after that line and leaves the layers above it and the cache mounts in place; `--no-cache` would build those layers again and empty the -mounts. This repo's own `Dockerfile` declares `ARG CACHEBUST` right after `FROM` -in every stage: each stage installs system packages and node packages together -in one `script/bootstrap` step, and check builds may keep system packages but +mounts. This repo's own `Dockerfile` installs git, make, node and yarn right +after `FROM` in every stage, above `ARG CACHEBUST`. `script/bootstrap` installs +the node packages below that line, because check builds keep system packages but not node packages. ## Rationale diff --git a/TODO.md b/TODO.md index 3127448..93c03bc 100644 --- a/TODO.md +++ b/TODO.md @@ -21,6 +21,23 @@ fmt-check, and commit. # Completed Steps +- 2026-11-04: node, yarn, npm, python, pip and venv now come from the + distribution with no version and no hash + (https://git.eeqj.de/sneak/prompts/issues/146), on sneak's ruling at + https://git.eeqj.de/sneak/prompts/issues/146#issuecomment-166033. Third-party + packages stay pinned by hash. These changed: + - `script/bootstrap` no longer uses nvm or corepack, and stops when yarn's + major version is not 1. + - `script/bootstrap` installs node, yarn and the node packages only when + `yarn.lock` is in the tree. + - `script/bootstrap`, `script/fmt` and `script/fmt-check` run `yarn` or + `yarnpkg`, whichever is present. + - This repository's `Dockerfile` starts from Alpine 3.24. + - The Python `test` phase example starts from `debian:trixie-slim`. + - A Python repository's `script/bootstrap` creates its virtual environment + at `$HOME/.pipenv`, so it works on a host and in a `Dockerfile`. + - `PIP_ONLY_BINARY=:all:` stops a package with no wheel, so pip downloads no + build tools without a hash check. - 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 diff --git a/prompts/CODE_STYLEGUIDE_JS.md b/prompts/CODE_STYLEGUIDE_JS.md index 08a0fcb..a05ff08 100644 --- a/prompts/CODE_STYLEGUIDE_JS.md +++ b/prompts/CODE_STYLEGUIDE_JS.md @@ -1,6 +1,6 @@ --- title: Code Styleguide — JavaScript -last_modified: 2026-02-22 +last_modified: 2026-11-04 --- 1. Use `const` for everything. If you need to reassign, use `let`. Never use @@ -8,7 +8,7 @@ last_modified: 2026-02-22 1. Use yarn for package management, avoid using npm. -1. Use LTS node versions. +1. Install node from the distribution, in whatever version it packages. 1. Use `prettier` for code formatting, with four spaces for indentation. diff --git a/prompts/EXISTING_REPO_CHECKLIST.md b/prompts/EXISTING_REPO_CHECKLIST.md index 8cc1a2f..11d18e7 100644 --- a/prompts/EXISTING_REPO_CHECKLIST.md +++ b/prompts/EXISTING_REPO_CHECKLIST.md @@ -81,13 +81,19 @@ with your task. - pipenv and its dependencies - the packages from `Pipfile.lock` - It installs pipenv and its dependencies by hash, with + It creates a virtual environment at `$HOME/.pipenv` with `python3 -m venv` + when it is missing, then uses that environment's `pip` and `pipenv`. On a + host, it first installs the distribution's python and venv packages when + they are missing. It installs pipenv and its dependencies by hash, with `pip install --require-hashes`. It installs the packages from `Pipfile.lock` with `pipenv install --deploy`, plus `--dev` when the tests need the - development packages. It installs no Python there, because the tests use the - base image's. The tests run after `ARG CACHEBUST`, and every other stage - installs its Python packages after it, as in the Python `test` phase example - in `REPO_POLICIES.md` + development packages. It sets `PIP_ONLY_BINARY=:all:` for both installs, so + a package with no wheel for the image stops the install. It installs no + Python there, because the tests use the distribution's, which a step above + it installs. `Pipfile` names no `python_version`, because `--deploy` stops + when the distribution's Python differs from it. The tests run after + `ARG CACHEBUST`, and every other stage installs its Python packages after + it, as in the Python `test` phase example in `REPO_POLICIES.md` - [ ] The gate phases invoke their tools directly, never through `make lint` or `script/test` — those are themselves a `docker build` and would recurse @@ -196,13 +202,17 @@ with your task. `docker build` in `script/`. 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` pick their `yarn` with the same test - as `script/bootstrap`: the `yarn` on `PATH` when the node on `PATH` has - the pinned major version, and otherwise yarn under the pinned node, with - nvm loaded through `$HOME/.nvm/nvm.sh`. `script/bootstrap` leaves the node - and yarn it installs under nvm off the `PATH` of the shell that called it, - so a bare `yarn` exits 127 on a runner carrying nothing but docker and - git, or runs under another node. +- [ ] `script/bootstrap` installs node, yarn and the node packages only when + `yarn.lock` is in the tree. node and yarn come from the distribution when + they are missing. With `yarn.lock` in the tree, `script/bootstrap` stops + with a one-line message when yarn's major version is not 1. +- [ ] A `Dockerfile` stage copies `yarn.lock` before it runs `script/bootstrap` + only if that stage needs yarn. A stage that needs yarn starts from an + image whose distribution packages yarn 1, which today means Alpine. +- [ ] `script/bootstrap`, `script/fmt` and `script/fmt-check` run yarn by + whichever name is present: `yarn`, or `yarnpkg` on Debian and Ubuntu. With + neither name on `PATH`, they print one line saying to run + `script/bootstrap`, and exit 1. - [ ] `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 @@ -230,8 +240,12 @@ with your task. is a package from the distribution's own package index, which needs no version and no hash. Pulling that index is also allowed. In a `Dockerfile`, the distribution is the pinned base image's. On a host, it - is the host's. A package source that a `Dockerfile` adds itself does not - get this exception + is the host's, and the host's package manager stands for it, nix and brew + included. A package source that a `Dockerfile` adds itself does not get + this exception +- [ ] node, yarn, npm, python, pip and venv come from the distribution wherever + possible, never from nvm, pyenv, corepack or `npm install -g yarn`. If the + distribution's version is too old, use a newer distribution - [ ] Using `yarn`, not `npm` (JS projects) # Directory Structure @@ -260,11 +274,12 @@ with your task. # Final - [ ] `make check` passes -- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has - (the runner image `docker.gitea.com/runner-images:ubuntu-latest`: docker, - git and node 24, with no yarn on `PATH`), and demonstrably executed the - checks — a sub-second build, or `CACHED` on a step that lints or tests, - one of the `RUN` steps below `ARG CACHEBUST`, means nothing ran. Above +- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has. + That host is the runner image + `docker.gitea.com/runner-images:ubuntu-latest`, which has docker, git and + node 24. Take any yarn off `PATH` first. The run must show that the checks + executed. A sub-second build means nothing ran. So does `CACHED` on a step + that lints or tests, one of the `RUN` steps below `ARG CACHEBUST`. Above that line, these steps are expected to show `CACHED`: - the steps that install system packages - the steps that download Go's modules diff --git a/prompts/NEW_REPO_CHECKLIST.md b/prompts/NEW_REPO_CHECKLIST.md index fd00231..8b9b388 100644 --- a/prompts/NEW_REPO_CHECKLIST.md +++ b/prompts/NEW_REPO_CHECKLIST.md @@ -148,11 +148,18 @@ Template files can be fetched from: - pipenv and its dependencies - the packages from `Pipfile.lock` - It installs pipenv and its dependencies by hash, with - `pip install --require-hashes`. It installs the packages from - `Pipfile.lock` with `pipenv install --deploy`, plus `--dev` when the - tests need the development packages. It installs no Python there, - because the tests use the base image's. The tests run after + It creates a virtual environment at `$HOME/.pipenv` with + `python3 -m venv` when it is missing, then uses that environment's `pip` + and `pipenv`. On a host, it first installs the distribution's python and + venv packages when they are missing. It installs pipenv and its + dependencies by hash, with `pip install --require-hashes`. It installs + the packages from `Pipfile.lock` with `pipenv install --deploy`, plus + `--dev` when the tests need the development packages. It sets + `PIP_ONLY_BINARY=:all:` for both installs, so a package with no wheel + for the image stops the install. It installs no Python there, because + the tests use the distribution's, which a step above it installs. + `Pipfile` names no `python_version`, because `--deploy` stops when the + distribution's Python differs from it. The tests run after `ARG CACHEBUST`, and every other stage installs its Python packages after it, as in the Python `test` phase example in `REPO_POLICIES.md` @@ -183,14 +190,21 @@ are thin shims calling them. Model scripts: - [ ] scripts are POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they run on alpine images without bash -- [ ] `script/bootstrap` / `make bootstrap` — installs all dependencies, - idempotently, assuming nothing (pkg manager detection nix/apt/brew/apk; - node used if its major version is the pinned one, else pinned version via - nvm from a hash-verified archive, with yarn and the packages installed - under it; pinned yarn via corepack); a non-server repo's development - environment stage runs it instead of inline installs; a gate phase or the - build stage installs what its base image lacks either inline or by running - it +- [ ] `script/bootstrap` / `make bootstrap` installs all dependencies, + idempotently, and assumes nothing is present: + - It detects the package manager: nix, apt, brew or apk. + - It installs node, yarn and the node packages only when `yarn.lock` is in + the tree. node and yarn come from that package manager when they are + missing. + - With `yarn.lock` in the tree, it stops with a one-line message when yarn's + major version is not 1. + - A non-server repo's development environment stage runs it, with only + system packages installed inline above it. + - A gate phase or the build stage installs what its base image lacks, either + inline or by running it. +- [ ] A `Dockerfile` stage copies `yarn.lock` before it runs `script/bootstrap` + only if that stage needs yarn. A stage that needs yarn starts from an + image whose distribution packages yarn 1, which today means Alpine. - [ ] `script/setup` / `make setup` — readies a fresh clone: runs `bootstrap`, then `install-precommit`, plus repo-specific init - [ ] `script/test` / `make test` — @@ -220,13 +234,10 @@ are thin shims calling them. Model scripts: from `script/projectname`, each assigned on its own line before the build. 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` pick their `yarn` with the same test - as `script/bootstrap`: the `yarn` on `PATH` when the node on `PATH` has - the pinned major version, and otherwise yarn under the pinned node, with - nvm loaded through `$HOME/.nvm/nvm.sh`. `script/bootstrap` leaves the node - and yarn it installs under nvm off the `PATH` of the shell that called it, - so a bare `yarn` exits 127 on a runner carrying nothing but docker and - git, or runs under another node. +- [ ] `script/bootstrap`, `script/fmt` and `script/fmt-check` run yarn by + whichever name is present: `yarn`, or `yarnpkg` on Debian and Ubuntu. With + neither name on `PATH`, they print one line saying to run + `script/bootstrap`, and exit 1. - [ ] No `docker build` in `script/` leaves a dangling image behind: `script/lint` and `script/test` write no image, and `script/docker` and `script/cibuild` tag theirs @@ -241,11 +252,12 @@ are thin shims calling them. Model scripts: - [ ] `make check` passes - [ ] `make docker` succeeds -- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has - (the runner image `docker.gitea.com/runner-images:ubuntu-latest`: docker, - git and node 24, with no yarn on `PATH`), and demonstrably executed the - checks — a sub-second build, or `CACHED` on a step that lints or tests, - one of the `RUN` steps below `ARG CACHEBUST`, means nothing ran. Above +- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has. + That host is the runner image + `docker.gitea.com/runner-images:ubuntu-latest`, which has docker, git and + node 24. Take any yarn off `PATH` first. The run must show that the checks + executed. A sub-second build means nothing ran. So does `CACHED` on a step + that lints or tests, one of the `RUN` steps below `ARG CACHEBUST`. Above that line, these steps are expected to show `CACHED`: - the steps that install system packages - the steps that download Go's modules @@ -259,8 +271,12 @@ are thin shims calling them. Model scripts: - [ ] No mutable image/package references. The one exception is a package from the distribution's own package index, which needs no version and no hash. Pulling that index is also allowed. In a `Dockerfile`, the distribution is - the pinned base image's. On a host, it is the host's. A package source + the pinned base image's. On a host, it is the host's, and the host's + package manager stands for it, nix and brew included. A package source that a `Dockerfile` adds itself does not get this exception +- [ ] node, yarn, npm, python, pip and venv come from the distribution wherever + possible, never from nvm, pyenv, corepack or `npm install -g yarn`. If the + distribution's version is too old, use a newer distribution - [ ] 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 5769030..cb6cd3c 100644 --- a/prompts/REPO_POLICIES.md +++ b/prompts/REPO_POLICIES.md @@ -25,6 +25,7 @@ style conventions are in separate documents: a remote source, including: - Docker base images - Go modules + - Python packages - npm packages - GitHub Actions @@ -33,29 +34,45 @@ style conventions are in separate documents: dependency by its content hash: - Docker: `@sha256:...` - Go: the module hash in `go.sum` + - Python: the package hash in `Pipfile.lock` - 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. + This also means never `curl | bash` to install a tool such as rustup. + 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 distribution is trusted. In a `Dockerfile`, it is the pinned base image's - distribution. On a host, it is the host's. These commands are examples: + distribution. On a host, it is the host's. The host's package manager stands + for its distribution, and that includes nix and brew. These commands are + examples: - `apt-get update` - `apt-get install` - `apk update` - `apk add` + These come from the distribution wherever possible: + - node + - yarn + - npm + - python + - pip and venv, the installer tools bundled with python + + If the distribution's version is too old, use a newer distribution, never a + download. That rules out all of these: + - nvm + - pyenv + - corepack + - `npm install -g yarn` + These are not trusted, so everything from them stays pinned by hash: - Docker Hub - PyPI - - npm + - the npm registry - `go get` A package source that a `Dockerfile` adds itself is not the distribution's @@ -99,18 +116,32 @@ style conventions are in separate documents: 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. + nothing is present. Base tools, node and yarn come from nix, apt, brew, or + apk, detected in that order; apt runs noninteractive. Each one is installed + only when it is missing. A tool from outside the distribution is never + installed as "latest" or "lts"; it is always an exact version. + + `script/bootstrap` installs node, yarn and the node packages only when + `yarn.lock` is in the tree. With no `yarn.lock`, it installs no node and no + yarn, and it does not check yarn's version. + + Debian and Ubuntu name the yarn command `yarnpkg`. `script/bootstrap`, + `script/fmt` and `script/fmt-check` each carry the same small function that + runs whichever name is present. With neither name on `PATH`, the function + prints one line saying to run `script/bootstrap`, and exits 1. + + With `yarn.lock` in the tree, `script/bootstrap` stops with a one-line + message when yarn's major version is not 1, before it installs any node + packages. Debian 13 and Ubuntu 26.04 package yarn 4. With + `--frozen-lockfile`, yarn 4 refuses a yarn 1 `yarn.lock`. Without that flag, + it rewrites the file in its own format, with its own hashes in place of + these. Alpine and Ubuntu 24.04 package yarn 1, so a host uses one of those. + + A `Dockerfile` stage copies `yarn.lock` before it runs `script/bootstrap` + only if that stage needs yarn. A stage that needs yarn starts from an image + whose distribution packages yarn 1, which today means Alpine. The Python and + Go stages below need no yarn, so they copy no `yarn.lock` before that step + and never reach the stop. `script/cibuild` runs the CI build, and the Gitea workflow calls it. The script changes to the repo root, runs `script/bootstrap`, runs @@ -118,15 +149,7 @@ style conventions are in separate documents: 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`. + after the containerised gates have passed. Four further scripts are our own extensions to the standard: - `script/check` runs `script/test`, `script/lint` and `script/fmt-check`. @@ -175,10 +198,11 @@ style conventions are in separate documents: 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. + running `script/bootstrap`. Only system packages may be installed inline + above it, so that check builds keep them; the `prompts` repo's own + `Dockerfile` does this. A stage that runs `script/bootstrap` COPYs `script/` + and the dependency manifests it needs (`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 @@ -491,10 +515,18 @@ style conventions are in separate documents: - 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`. + `script/bootstrap` installs no Python there: the tests use the + distribution's Python, which a step above it installs. If it installs + anything else there, the step goes after `ARG CACHEBUST`. + - Debian's Python refuses a system-wide `pip install`, so pipenv goes in a + virtual environment at `$HOME/.pipenv`. `script/bootstrap` creates it with + `python3 -m venv` when it is missing, then uses that environment's `pip` + and `pipenv`. On a host, it first installs the distribution's python and + venv packages when they are missing. One script then works on a host and + in a `Dockerfile`. `Pipfile` names no `python_version`, because + `pipenv install --deploy` stops when the distribution's Python differs + from it. - 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 @@ -504,37 +536,58 @@ style conventions are in separate documents: - installs only what `Pipfile.lock` names - checks every package against the lockfile's hashes - fails when the lockfile is out of date with `Pipfile` + - `script/bootstrap` sets `PIP_ONLY_BINARY=:all:` for both installs, and + pipenv passes it on to pip. A package with no ready-built wheel for the + image then stops the install. Without the setting, pip builds that package + from source and downloads the build tools without a hash check. - 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. + inside that package, so the hash pip checked for it covers them. System + packages, Python among them, are not fixed by a hash. They 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 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` + A Python repository's `script/bootstrap` adds these lines. The `ensurepip` + test fails when python is missing, and also when Debian's venv package is + missing: + + ```sh + if [ ! -x "$HOME/.pipenv/bin/pip" ]; then + if ! python3 -m ensurepip --version >/dev/null 2>&1; then + pkg_install python3 python3-venv python3 python3 + fi + python3 -m venv "$HOME/.pipenv" + fi + export PIP_ONLY_BINARY=:all: + "$HOME/.pipenv/bin/pip" install --require-hashes -r script/requirements.txt + "$HOME/.pipenv/bin/pipenv" install --dev --deploy + ``` + + In the example below, `script/bootstrap` finds `make`, `git`, python and + venv already installed. The example copies no `yarn.lock`, so + `script/bootstrap` installs no node and no yarn. ```dockerfile # Test phase. Both pytest runs share one 90-second timeout, so a hang # uses it once and gets no rerun. - # python:3.x-slim, YYYY-MM-DD - FROM python@sha256:... AS test - # make and git are base tools that script/bootstrap installs when they - # are missing. Installed here, they stay in their own layer when - # script/ changes. + # debian:trixie-slim, YYYY-MM-DD + FROM debian@sha256:... AS test + # Python, pip and venv come from the distribution, which is trusted, so + # they need no version and no hash. make and git are base tools that + # script/bootstrap installs when they are missing. Installed here, they + # stay in their own layer when script/ changes. RUN apt-get update \ - && apt-get install -y --no-install-recommends make git \ + && apt-get install -y --no-install-recommends ca-certificates make git \ + python3 python3-pip python3-venv \ && rm -rf /var/lib/apt/lists/* + # script/bootstrap installs pipenv in a virtual environment at + # $HOME/.pipenv, and the tests below run that pipenv. + ENV PATH=/root/.pipenv/bin:$PATH WORKDIR /app COPY script/ script/ COPY Pipfile Pipfile.lock ./ @@ -669,16 +722,16 @@ style conventions are in separate documents: ```makefile test: - @timeout 90 sh -c 'python -m pytest || { \ + @timeout 90 sh -c 'pipenv run pytest || { \ echo "--- Rerunning with -v for details ---"; \ - python -m pytest -v; exit 1; }' + pipenv run pytest -v; exit 1; }' ``` Both pytest runs share that one 90-second timeout, as in the `Dockerfile` example above, so a hang uses it once and gets no rerun. Ctrl-C does not stop a running `make test`, which goes on until the tests end or the 90 seconds run out. On a Mac without `timeout`, the target fails until it is - installed. + installed. On a host, the target needs `$HOME/.pipenv/bin` on `PATH`. 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 @@ -857,10 +910,8 @@ style conventions are in separate documents: 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 node's major version. That is 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. + A tool from the distribution has no pin, so `script/bootstrap` installs it + when it is missing. make, git, node and yarn are such tools. Keep it POSIX sh: no arrays, no `[[`, no `grep -P`. diff --git a/script/bootstrap b/script/bootstrap index 7d7c056..0a36e30 100755 --- a/script/bootstrap +++ b/script/bootstrap @@ -1,24 +1,15 @@ #!/bin/sh # script/bootstrap: install all dependencies needed to build and develop # this repo. Idempotent: every install is guarded by a check so already -# installed tools are skipped. Base tooling comes from nix, apt, brew, -# or apk (detected in that order); assumes nothing is present. The -# installed node is used only when its major version is the pinned one; -# otherwise (node missing, or another major) the pinned version is -# installed via nvm (installing nvm itself first, from a hash-verified -# release archive, never curl | sh), and yarn and the packages are -# installed under it. +# installed tools are skipped. Base tools, node and yarn come from nix, +# apt, brew, or apk (detected in that order), with no version and no +# hash, because the distribution is trusted. It installs node, yarn and +# the node packages only when yarn.lock is in the tree. Assumes nothing +# is present. set -eu ROOT="$(cd "$(dirname "$0")/.." && pwd -P)" -# Pinned versions, 2026-07-06 -NODE_VERSION="22.17.0" -NVM_VERSION="0.40.3" -# sha256 of https://github.com/nvm-sh/nvm/archive/refs/tags/v0.40.3.tar.gz -NVM_SHA256="5f4d6aaa04a177dc93c985e31dbc411ab6b8c6e1e21d8015dbc1372625fcd1d0" -YARN_VERSION="1.22.22" - PKGMGR="" SUDO="" APT_UPDATED="" @@ -67,99 +58,42 @@ missing() { ! command -v "$1" >/dev/null 2>&1 } -# verify_sha256 -verify_sha256() { - if command -v sha256sum >/dev/null 2>&1; then - actual="$(sha256sum "$1" | cut -d' ' -f1)" +# Debian and Ubuntu name the yarn command yarnpkg. +run_yarn() { + if command -v yarn >/dev/null 2>&1; then + yarn "$@" + elif command -v yarnpkg >/dev/null 2>&1; then + yarnpkg "$@" else - actual="$(shasum -a 256 "$1" | cut -d' ' -f1)" - fi - if [ "$actual" != "$2" ]; then - echo "bootstrap: sha256 mismatch for $1" >&2 - echo " expected: $2" >&2 - echo " actual: $actual" >&2 + echo "no yarn; run script/bootstrap first" >&2 exit 1 fi } -# nvm is a bash script; run a command in a bash with nvm loaded -nvm_sh() { - bash -c ". \"\$HOME/.nvm/nvm.sh\" && $*" -} - -ensure_nvm() { - [ -s "$HOME/.nvm/nvm.sh" ] && return 0 - # nvm prerequisites; nvm itself requires bash - if missing bash; then pkg_install bash bash bash bash; fi - if missing curl; then pkg_install curl curl curl curl; fi - if missing git; then pkg_install git git git git; fi - tmp="$(mktemp -d)" - curl -fsSL -o "$tmp/nvm.tar.gz" \ - "https://github.com/nvm-sh/nvm/archive/refs/tags/v${NVM_VERSION}.tar.gz" - verify_sha256 "$tmp/nvm.tar.gz" "$NVM_SHA256" - mkdir -p "$HOME/.nvm" - tar -xzf "$tmp/nvm.tar.gz" -C "$HOME/.nvm" --strip-components=1 - rm -rf "$tmp" -} - -# True when the node on PATH has the pinned major version. Only the -# major is compared: the Dockerfile stages start from a node 22 alpine -# image whose exact version is not the pin, and nvm cannot install a -# prebuilt node on alpine. Another major is not used: the pinned yarn 1 -# prints a deprecation warning under node 24. script/fmt and -# script/fmt-check carry this function unchanged, to run the yarn -# installed here. -node_is_pinned_major() { - if ! command -v node >/dev/null 2>&1; then return 1; fi - installed="$(node --version)" - installed="${installed#v}" - [ "${installed%%.*}" = "${NODE_VERSION%%.*}" ] -} - -ensure_node() { - if node_is_pinned_major; then - echo "bootstrap: using node $(node --version)" - return 0 - fi - ensure_nvm - nvm_sh "nvm install $NODE_VERSION" - nvm_sh "nvm use $NODE_VERSION >/dev/null && \ - echo \"bootstrap: using node \$(node --version)\"" -} - -ensure_yarn() { - if ! node_is_pinned_major; then - nvm_sh "nvm use $NODE_VERSION >/dev/null && corepack enable && \ - corepack prepare yarn@$YARN_VERSION --activate" - return 0 - fi - if ! missing yarn; then return 0; fi - if ! missing corepack; then - corepack enable - corepack prepare "yarn@$YARN_VERSION" --activate - else - npm install -g "yarn@$YARN_VERSION" - fi -} - -install_js_deps() { - if node_is_pinned_major; then - yarn install --frozen-lockfile - else - nvm_sh "nvm use $NODE_VERSION >/dev/null && cd \"$ROOT\" && \ - yarn install --frozen-lockfile" - fi -} - main() { cd "$ROOT" if missing make; then pkg_install gnumake make make make; fi if missing git; then pkg_install git git git git; fi - ensure_node - ensure_yarn - install_js_deps + # A Dockerfile stage that needs no yarn copies no yarn.lock. + if [ -f yarn.lock ]; then + if missing node; then pkg_install nodejs nodejs node nodejs; fi + if missing yarn && missing yarnpkg; then + pkg_install yarn yarnpkg yarn yarn + fi + + # Debian 13 and Ubuntu 26.04 package yarn 4, which refuses a yarn 1 + # yarn.lock, or rewrites it in its own format. + yarn_version="$(run_yarn --version)" + if [ "${yarn_version%%.*}" != "1" ]; then + echo "bootstrap: yarn $yarn_version refuses this yarn 1 yarn.lock;" \ + "use a distribution that packages yarn 1" >&2 + exit 1 + fi + + run_yarn install --frozen-lockfile + fi echo "bootstrap complete" } diff --git a/script/fmt b/script/fmt index 7525349..dc788c1 100755 --- a/script/fmt +++ b/script/fmt @@ -4,33 +4,16 @@ set -eu ROOT="$(cd "$(dirname "$0")/.." && pwd -P)" -# Must match the pin in script/bootstrap. -NODE_VERSION="22.17.0" - -# True when the node on PATH has the pinned major version: the same -# function as in script/bootstrap, which uses it to decide where it -# installs yarn. -node_is_pinned_major() { - if ! command -v node >/dev/null 2>&1; then return 1; fi - installed="$(node --version)" - installed="${installed#v}" - [ "${installed%%.*}" = "${NODE_VERSION%%.*}" ] -} - -# Run the yarn script/bootstrap installed: the yarn on PATH when the -# node on PATH has the pinned major version, and otherwise yarn under -# the pinned node in nvm, which bootstrap leaves off the PATH of the -# shell that called it. nvm is a bash script, hence the subshell. +# Debian and Ubuntu name the yarn command yarnpkg. run_yarn() { - if node_is_pinned_major && command -v yarn >/dev/null 2>&1; then - exec yarn "$@" - fi - if node_is_pinned_major || [ ! -s "$HOME/.nvm/nvm.sh" ]; then - echo "fmt: no yarn; run script/bootstrap first" >&2 + if command -v yarn >/dev/null 2>&1; then + yarn "$@" + elif command -v yarnpkg >/dev/null 2>&1; then + yarnpkg "$@" + else + echo "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() { diff --git a/script/fmt-check b/script/fmt-check index 939f2de..9f4e2d2 100755 --- a/script/fmt-check +++ b/script/fmt-check @@ -4,33 +4,16 @@ set -eu ROOT="$(cd "$(dirname "$0")/.." && pwd -P)" -# Must match the pin in script/bootstrap. -NODE_VERSION="22.17.0" - -# True when the node on PATH has the pinned major version: the same -# function as in script/bootstrap, which uses it to decide where it -# installs yarn. -node_is_pinned_major() { - if ! command -v node >/dev/null 2>&1; then return 1; fi - installed="$(node --version)" - installed="${installed#v}" - [ "${installed%%.*}" = "${NODE_VERSION%%.*}" ] -} - -# Run the yarn script/bootstrap installed: the yarn on PATH when the -# node on PATH has the pinned major version, and otherwise yarn under -# the pinned node in nvm, which bootstrap leaves off the PATH of the -# shell that called it. nvm is a bash script, hence the subshell. +# Debian and Ubuntu name the yarn command yarnpkg. run_yarn() { - if node_is_pinned_major && command -v yarn >/dev/null 2>&1; then - exec yarn "$@" - fi - if node_is_pinned_major || [ ! -s "$HOME/.nvm/nvm.sh" ]; then - echo "fmt-check: no yarn; run script/bootstrap first" >&2 + if command -v yarn >/dev/null 2>&1; then + yarn "$@" + elif command -v yarnpkg >/dev/null 2>&1; then + yarnpkg "$@" + else + echo "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() {