fetch: destination directory, skip files already present, save the manifest, require a signer (closes #101)

fetch takes --dest (default .) and writes every file there through the
existing symlink and hard-link guards, which now work relative to that
directory. A file already there with the listed size and hash is
skipped; a leftover temp file is still replaced. Once every file
verifies, the manifest is saved as index.mf through the same temp file
and rename, so check runs on the result. --require-signature is shared
with check and enforced through verifyRequiredSigner, on a Checker over
the manifest held in memory, before anything is downloaded or written.

Model: opus-5-5

.dockerignore

@@ -17,17 +17,7 @@
 # stage that compiles runs `git describe --tags --always` on .git, which
 # does not need .git/config; that file can hold a credential, such as a
 # password in a remote URL or the token the CI checkout step stores there.
-# Each submodule keeps a config with the same exposure in its git directory
+.git/config
-# under .git/modules/, nested again for a submodule's own submodules, or in
-# its own .git directory when it keeps one.
-# KNOWN GAP: a submodule whose name has a `config` segment (`config`,
-# `deploy/config`, `config/lib`) loses its whole git directory, because
-# `**/.git/modules/**/config` also matches that segment's directory
-# under .git/modules/. Go's version stamping then fails the build;
-# nothing leaks. Name such a submodule without that segment:
-# `git submodule add --name`.
-**/.git/config
-**/.git/modules/**/config
 
 # Agent scratch: one full checkout of the repo per in-flight agent.
 # Anchored because it occurs once where agents run at the repo root.
@@ -51,9 +41,7 @@
 **/[iI][dD]_[rR][sS][aA]
 **/[iI][dD]_[dD][sS][aA]
 **/[iI][dD]_[eE][cC][dD][sS][aA]
-**/[iI][dD]_[eE][cC][dD][sS][aA]_[sS][kK]
 **/[iI][dD]_[eE][dD]25519
-**/[iI][dD]_[eE][dD]25519_[sS][kK]
 
 # Dependencies: restored inside the image, never copied in.
 **/node_modules
@@ -71,11 +59,6 @@
 **/.vscode
 **/*.sublime-*
 
-# This repo's own host-built binary (make build).
+# This repo's own host-built archives (Makefile).
-/bin/mfer
+*.tmp
-
+*.dockerimage
-# The tools script/bootstrap installs for script/gofumpt and
-# script/generate.
-/bin/gofumpt
-/bin/protoc
-/bin/protoc-gen-go

.editorconfig

@@ -10,6 +10,3 @@ insert_final_newline = true
 
 [Makefile]
 indent_style = tab
-
-[*.go]
-indent_style = tab

.gitea/workflows/check.yml

@@ -4,6 +4,6 @@ jobs:
     check:
         runs-on: ubuntu-latest
         steps:
-            # actions/checkout v4.2.2, 2026-02-22
+            # actions/checkout v4.2.2, 2026-03-16
             - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
             - run: script/cibuild

.gitignore

@@ -1,63 +1,33 @@
-# OS
+/bin/mfer
+/tmp
+/node_modules/
+*.tmp
+*.dockerimage
+/vendor
+vendor.tzst
+modcache.tzst
+
+# Generated manifest files
+/index.mf
+
+# Secrets
+.env
+.env.*
+*.key
+*.pem
+
+# OS files
 .DS_Store
 Thumbs.db
 
-# Editors
+# Editor files
 *.swp
 *.swo
 *~
-*.bak
 .idea/
 .vscode/
-*.sublime-*
 
-# Agent scratch (worktrees of this repo, created and destroyed by
+# Go build artifacts
-# in-flight tooling). Unanchored: .gitignore patterns already match at
-# every depth, so no prefix is wanted here. This is not a .dockerignore
-# entry and must not be given a `**/` prefix on the way into one.
-.claude/
-
-# Node
-node_modules/
-
-# Secrets. Unanchored like every entry above, so each matches at every
-# depth. Matching is case-sensitive on Linux, so names use character
-# ranges rather than a lowercase form that misses `Server.Key`.
-
-# Environment files. `*.env` covers bare `.env` and the `prod.env`
-# convention. Only the templates `example.env` and `sample.env` are
-# re-included below. A repository that commits any other template adds
-# its own negation after these lines, for example `!.env.example`.
-*.[eE][nN][vV]
-.[eE][nN][vV].*
-.[eE][nN][vV][rR][cC]
-!example.env
-!sample.env
-
-# Private keys and the bundles carrying them.
-*.[pP][eE][mM]
-*.[kK][eE][yY]
-*.[pP]12
-*.[pP][fF][xX]
-[iI][dD]_[rR][sS][aA]
-[iI][dD]_[dD][sS][aA]
-[iI][dD]_[eE][cC][dD][sS][aA]
-[iI][dD]_[eE][cC][dD][sS][aA]_[sS][kK]
-[iI][dD]_[eE][dD]25519
-[iI][dD]_[eE][dD]25519_[sS][kK]
-
-# Go build and test artifacts.
 *.log
 *.out
 *.test
-
-# This repo's own binary (make build), and the tools script/bootstrap
-# installs into bin/.
-/bin/mfer
-/bin/gofumpt
-/bin/protoc/
-/bin/protoc-gen-go
-
-# A manifest generated at the repo root, and local scratch.
-/index.mf
-/tmp

.golangci.yml

@@ -10,21 +10,14 @@ run:
 
 linters:
   default: all
-  enable:
-    # Successor to the deprecated gomodguard. Named explicitly, rather than
-    # left to `default: all`, because it carries the module policy below.
-    - gomodguard_v2
   disable:
     # Genuinely incompatible with project patterns
     - exhaustruct      # Requires all struct fields
-    - exhaustruct_v5   # Requires all struct fields (successor to exhaustruct)
+    - depguard         # Dependency allow/block lists
     - godot            # Requires comments to end with periods
+    - wsl              # Deprecated, replaced by wsl_v5
     - wrapcheck        # Too verbose for internal packages
     - varnamelen       # Short names like db, id are idiomatic Go
-    # Deprecated: the warning is attached to the old name, so it is
-    # silenced by disabling that name, not by enabling the successor.
-    - wsl              # Deprecated, replaced by wsl_v5
-    - gomodguard       # Deprecated, replaced by gomodguard_v2
   settings:
     lll:
       line-length: 88
@@ -35,64 +28,6 @@ linters:
       max-complexity: 15
     dupl:
       threshold: 100
-    depguard:
-      # Test-support code must not be compiled into the shipped binary. A
-      # test-support package exists to hand a test privileges the program
-      # itself must never have, so a file that is not a test must not import
-      # one. Test files, and the files inside a package whose directory name
-      # ends in `test`, are where that code belongs, and are exempt.
-      #
-      # The deny list below is the one part of this file a repository is
-      # expected to extend, and the only part it may. depguard matches an
-      # import path against a list of prefixes, so it cannot be told "any path
-      # whose last segment ends in test"; a repository's own test-support
-      # packages have to be named here one at a time, by full import path,
-      # under a module path that differs from repository to repository. Add
-      # them; change nothing else.
-      rules:
-        test-support:
-          list-mode: lax
-          files:
-            - "$all"
-            - "!$test"
-            - "!**/*test/**"
-          deny:
-            - pkg: net/http/httptest
-              desc: >-
-                Test-support code belongs in test files and in packages whose
-                directory name ends in test, not in the shipped binary.
-    # Only decisions already recorded in the Go package defaults are
-    # listed here. Every entry matches the module path exactly.
-    gomodguard_v2:
-      blocked:
-        - module: github.com/rs/zerolog
-          recommendations:
-            - log/slog
-          reason: "Structured logging is stdlib log/slog."
-        # One entry per pre-fork module path, because the later releases
-        # are separate paths. A prefix match would be shorter but would
-        # also reach github.com/go-redis/redismock, the test double for
-        # the successor these entries recommend.
-        - module: github.com/go-redis/redis
-          recommendations:
-            - github.com/redis/go-redis/v9
-          reason: "Pre-fork module; use the maintained go-redis v9."
-        - module: github.com/go-redis/redis/v7
-          recommendations:
-            - github.com/redis/go-redis/v9
-          reason: "Pre-fork module; use the maintained go-redis v9."
-        - module: github.com/go-redis/redis/v8
-          recommendations:
-            - github.com/redis/go-redis/v9
-          reason: "Pre-fork module; use the maintained go-redis v9."
-        - module: github.com/sergi/go-diff
-          recommendations:
-            - github.com/aymanbagabas/go-udiff
-          reason: "No unified diff output; use go-udiff."
-        - module: github.com/hexops/gotextdiff
-          recommendations:
-            - github.com/aymanbagabas/go-udiff
-          reason: "Unmaintained fork; use go-udiff."
 
 issues:
   max-issues-per-linter: 0

.nvmrc

@@ -1 +0,0 @@
-22.17.0

.prettierignore

@@ -1,2 +1,14 @@
+# REPO_POLICIES.md is a verbatim copy of an authoritative upstream
+# document (sneak/prompts). Local tooling must never rewrite it: any
+# reformatting is silent drift from the source of truth.
+REPO_POLICIES.md
+
+# User-owned configuration, copied verbatim from upstream. Not matched by
+# the current prettier file set, but listed so widening that set can never
+# start rewriting it.
+.golangci.yml
+
+# Dependencies and build output
 node_modules/
-yarn.lock
+vendor/
+bin/

Dockerfile

@@ -1,62 +1,73 @@
-# Lint phase. The linter is invoked directly rather than through `make
+# Lint stage — fast feedback on formatting and lint issues
-# lint` or `script/lint`, which are themselves a docker build and would
+# golangci/golangci-lint:v2.12.2 (Debian-based), 2026-08-07
-# recurse into a daemon that does not exist in a build step.
+FROM golangci/golangci-lint:v2.12.2@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240 AS lint
-# golangci/golangci-lint:v2.14.0, 2026-09-24
+
-FROM golangci/golangci-lint@sha256:ad862ba6b3798cbe0fd9fd7408d498fd74fbd2623a92406b2fd3898faf0bf98f AS lint
 WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download
+
 COPY . .
+
+# Go half of fmt-check only: this image has no node, so no prettier. The
+# markdown half runs in the mdfmt stage below.
+RUN make fmt-check-go
+# The linter directly, not `make lint`: script/lint builds this stage, and
+# there is no docker inside this build.
 RUN golangci-lint run --config .golangci.yml ./...
 
-# Test phase. -race needs cgo and so a C compiler, which the Debian Go
+# Markdown/JSON format stage — prettier needs node, which the Go images
-# image ships and the alpine one does not.
+# do not have. node:22.17.0-bookworm-slim (2026-08-09); ships node
-# golang:1.23.12, 2026-03-14
+# 22.17.0 and yarn 1.22.22, the versions script/bootstrap pins.
-FROM golang@sha256:60deed95d3888cc5e4d9ff8a10c54e5edc008c6ae3fba6187be6fb592e19e8c0 AS test
+FROM node@sha256:b04ce4ae4e95b522112c2e5c52f781471a5cbc3b594527bcddedee9bc48c03a0 AS mdfmt
-WORKDIR /src
-COPY go.mod go.sum ./
-RUN go mod download
-COPY . .
-RUN go test -timeout 90s -race -cover ./... || \
-    { echo "--- Rerunning with -v for details ---"; \
-      go test -timeout 90s -race -v ./...; exit 1; }
 
-# Build stage. Nothing is wanted from either phase above; the copies
+WORKDIR /src
-# are what make BuildKit build them first, so this stage cannot run
+COPY package.json yarn.lock ./
-# unless lint and test passed. The Debian Go image ships git, which the
+RUN yarn install --frozen-lockfile
-# version step below needs.
+
-# golang:1.23.12, 2026-03-14
+COPY . .
+
+# No make in this image; call the script entrypoint directly.
+RUN script/prettier --check
+
+# Build stage — tests and compilation
+# golang:1.23 (2026-03-14)
 FROM golang@sha256:60deed95d3888cc5e4d9ff8a10c54e5edc008c6ae3fba6187be6fb592e19e8c0 AS builder
+
+# Force BuildKit to run the lint and mdfmt stages by creating stage dependencies
 COPY --from=lint /src/go.sum /dev/null
-COPY --from=test /src/go.sum /dev/null
+COPY --from=mdfmt /src/go.sum /dev/null
-# A tar-stream context keeps the sender's file owners, which git refuses.
+
-RUN git config --system --add safe.directory /src
 WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download
+
 COPY . .
 
-# The revision `mfer version` prints, stamped into main.Gitrev: the
+RUN make test
-# VERSION build arg when one is given, otherwise `git describe --tags
+
-# --always` on the .git in the build context. With .git present, a
+# A build context sent as a tar archive, as upaas sends it, keeps its files'
-# version that is still empty, dev or unknown fails the build: git is
+# owners, and git refuses to read a checkout owned by another user.
-# missing or could not read the checkout.
+RUN git config --system --add safe.directory /src
+
+# The revision `mfer version` prints, stamped into main.Gitrev: the VERSION
+# build argument when one is given (script/docker passes one), otherwise
+# `git describe --tags --always` of the .git the build context carries: the
+# tag on a tagged commit, tag-N-gHASH on a commit after one, the short commit
+# when no tag is reachable. git ships in this base image. A context that
+# carries .git and still yields no version fails the build.
 ARG VERSION
-RUN VERSION="${VERSION:-$(git describe --tags --always)}"; \
+RUN version="${VERSION:-$(git describe --tags --always)}"; \
-    if [ -e .git ]; then \
+    if [ -e .git ] && { [ -z "$version" ] || [ "$version" = dev ] || \
-        case "$VERSION" in ""|dev|unknown) \
+        [ "$version" = unknown ]; }; then \
-            echo "version is '$VERSION' although .git is present" >&2; \
+        echo "no version could be derived although the build context carries .git" >&2; \
-            exit 1 ;; \
+        exit 1; \
-        esac; \
     fi; \
-    CGO_ENABLED=0 go build -trimpath \
+    cd cmd/mfer && \
-        -ldflags="-s -w -X main.Gitrev=${VERSION}" \
+    CGO_ENABLED=0 go build -tags urfave_cli_no_docs -ldflags "-X main.Gitrev=$version" -o /mfer .
-        -o /mfer ./cmd/mfer/
 
 # Fail unless /mfer is statically linked: scratch has no C library to run it.
 RUN ldd /mfer 2>&1 | grep -q 'not a dynamic executable'
 
-# Runtime stage, and the last one.
 FROM scratch
 # scratch has no CA certificates; fetch needs them to verify HTTPS servers.
 COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/

Makefile

@@ -1,8 +1,20 @@
-.PHONY: bootstrap setup test lint fmt fmt-check check docker hooks build generate fuzz
+export DOCKER_BUILDKIT := 1
+export PROGRESS_NO_TRUNC := 1
+GOPATH := $(shell go env GOPATH)
+export PATH := $(PATH):$(GOPATH)/bin
+SOURCEFILES := mfer/*.go mfer/*.proto internal/*/*.go cmd/*/*.go go.mod go.sum
+ARCH := $(shell uname -m)
+GITREV_BUILD := $(shell bash $(PWD)/bin/gitrev.sh 2>/dev/null || echo unknown)
+APPNAME := mfer
+VERSION := 0.1.0
+export DOCKER_IMAGE_CACHE_DIR := $(HOME)/Library/Caches/Docker/$(APPNAME)-$(ARCH)
+GOLDFLAGS += -X main.Version=$(VERSION)
+GOLDFLAGS += -X main.Gitrev=$(GITREV_BUILD)
+GOFLAGS := -ldflags "$(GOLDFLAGS)"
 
-# Makefile targets are thin shims; the implementations live in script/
+.PHONY: bootstrap setup docker default run ci test fuzz check lint fmt fmt-check fmt-check-go fmt-check-md hooks fixme generate
-# per the scripts-to-rule-them-all pattern (see the Entrypoints section
+
-# of README.md).
+default: fmt test
 
 bootstrap:
 	@script/bootstrap
@@ -10,32 +22,75 @@ bootstrap:
 setup:
 	@script/setup
 
+run: ./bin/mfer
+	./$<
+	./$< gen
+
+ci: test
+
 test:
 	@script/test
 
-lint:
+fuzz:
-	@script/lint
+	@script/fuzz
 
-fmt:
+fixme:
-	@script/fmt
+	@grep -nir fixme . | grep -v Makefile
-
-fmt-check:
-	@script/fmt-check
 
 check:
 	@script/check
 
-docker:
+fmt-check:
-	@script/docker
+	@script/fmt-check
+
+# Halves of fmt-check, for environments that have only one toolchain:
+# the Docker lint stage has Go but no node, the markdown stage the reverse.
+fmt-check-go:
+	@script/fmt-check-go
+
+fmt-check-md:
+	@script/prettier --check
 
 hooks:
 	@script/install-precommit
 
-build:
-	@script/build
-
 generate:
 	@script/generate
 
-fuzz:
+bin/mfer: $(SOURCEFILES)
-	@script/fuzz
+	cd cmd/mfer && go build -tags urfave_cli_no_docs -o ../../bin/mfer $(GOFLAGS) .
+
+clean:
+	rm -rfv bin/mfer cmd/mfer/mfer *.dockerimage
+
+fmt:
+	@script/fmt
+
+lint:
+	@script/lint
+
+docker:
+	@script/docker
+
+sneak-mfer.$(ARCH).tzst.dockerimage: $(SOURCEFILES) vendor.tzst modcache.tzst
+	docker build --progress plain --build-arg GITREV=$(GITREV_BUILD) -t sneak/mfer .
+	docker save sneak/mfer | pv | zstdmt -19 > $@
+	du -sh $@
+
+godoc:
+	open http://127.0.0.1:6060
+	godoc -http=:6060
+
+vendor.tzst: go.mod go.sum
+	go mod tidy
+	go mod vendor
+	cd vendor && tar -c . | pv | zstdmt -19 > $(PWD)/$@.tmp
+	rm -rf vendor
+	mv $@.tmp $@
+
+modcache.tzst: go.mod go.sum
+	go mod tidy
+	cd $(HOME)/go/pkg && chmod -R u+rw . && rm -rf mod sumdb
+	go mod download -x
+	cd $(shell go env GOMODCACHE) && tar -c . | pv | zstdmt -19 > $(PWD)/$@.tmp
+	mv $@.tmp $@

README.md

@@ -29,7 +29,7 @@ is committed, so no `protoc` toolchain is required:
 ```sh
 git clone https://git.eeqj.de/sneak/mfer.git
 cd mfer
-make build
+go build -o bin/mfer ./cmd/mfer
 ```
 
 Generate a manifest for a directory tree, verify it later, and fetch a published
@@ -40,7 +40,7 @@ tree by URL:
 bin/mfer gen .
 
 # Verify the files on disk against the manifest. Exits nonzero if any file
-# it lists is missing or corrupted; warns about files it does not list.
+# is missing or corrupted.
 bin/mfer check index.mf
 
 # Download and cryptographically verify a tree published over HTTP into
@@ -55,9 +55,9 @@ for a single command's options.
 
 # Build Status
 
-CI runs `script/cibuild`, which runs `script/bootstrap` and `script/check`, then
+CI runs `script/cibuild`, which builds the Docker image with `--no-cache`, so
-builds the Docker image with `--no-cache`, so the lint and test phases in the
+the formatting, lint and test steps in the `Dockerfile` run on every build. The
-`Dockerfile` run on every build. The `main` branch must always be green.
+`main` branch must always be green.
 
 # Entrypoints
 
@@ -67,57 +67,46 @@ standard: normalized scripts in `script/` are the entrypoints for the
 development workflow, and the Makefile targets are thin shims that call them. We
 provide:
 
-- `script/bootstrap` — install all dependencies, idempotently: Go and the
+- `script/bootstrap` — install all dependencies (Go, Go module download, and
-  modules of `go.mod`; node (the version `.nvmrc` names, through nvm when there
+  node/yarn plus the prettier version pinned in `package.json`/`yarn.lock`),
-  is no node on `PATH`) and yarn, plus the prettier version pinned in
+  idempotently; golangci-lint is not installed, it runs only in Docker
-  `package.json`/`yarn.lock`; `gofumpt` v0.12.0 and `protoc-gen-go` v1.36.11,
-  installed into `bin/` with `go install`, each pinned to a commit; and `protoc`
-  33.4, unpacked into `bin/protoc` from its release archive once the archive
-  matches the sha256 the script holds for this platform. Each of those three is
-  installed again whenever the one in `bin/` reports another version.
-  golangci-lint is not installed, it runs only in Docker
 - `script/setup` — make a fresh clone ready for development: runs
   `script/bootstrap`, then `script/install-precommit`
 - `script/projectname` — output the project name (`mfer`); used by other scripts
   such as `script/docker`
-- `script/test` — run the test suite in Docker: builds only the `test` stage of
+- `script/test` — run the test suite (`go test`); one test fails when
-  the `Dockerfile`, whose build runs `go test -race`, uncached so it runs every
+  `mfer/mf.proto` no longer matches the hash `script/generate` recorded
-  time; one test fails when `mfer/mf.proto` no longer matches the hash
-  `script/generate` recorded
-- `script/build` (`make build`) — build the `mfer` binary into `bin/mfer`,
-  stamped with the revision `mfer version` prints: the output of
-  `git describe --tags --always --dirty`, as `script/docker` passes it
 - `script/generate` (`make generate`) — regenerate `mfer/mf.pb.go` from
   `mfer/mf.proto` and record the hash of that `mfer/mf.proto` in
   `mfer/mf.proto.sha256`; the only thing that regenerates the committed
-  `mfer/mf.pb.go`. It runs the `protoc` that `script/bootstrap` unpacks into
+  `mfer/mf.pb.go`. It needs the exact versions that wrote the committed file,
-  `bin/protoc` and the `protoc-gen-go` it installs into `bin/`, refusing any
+  and refuses to run with any other: `protoc` 33.4 (unpack
-  version of either but the pinned one
+  `protoc-33.4-<platform>.zip` from
+  [its release](https://github.com/protocolbuffers/protobuf/releases/tag/v33.4)
+  and put its `bin/protoc` on `PATH`) and `protoc-gen-go` v1.36.11
+  (`go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.36.11`, which
+  installs it in `$(go env GOPATH)/bin`; `make generate` adds that directory to
+  `PATH`)
 - `script/fuzz` — fuzz the manifest parser for one minute; run by hand
   (`make fuzz`), never by CI, while `script/test` runs its committed seed corpus
   as ordinary tests
 - `script/lint` — run `golangci-lint` in Docker: builds only the `lint` stage of
-  the `Dockerfile`, whose build runs the linter, uncached so it runs every time
+  the `Dockerfile` (the Go format check, then the linter), uncached so it runs
-- `script/fmt` — format all code and docs (writes): `script/gofumpt --write` and
+  every time, then removes the image
+- `script/fmt` — format all code and docs (writes): `gofumpt` and
   `script/prettier --write`
-- `script/gofumpt` — run `gofumpt` over every Go file in the repository in the
-  given mode, `--write` or `--check`, with the `bin/gofumpt` that
-  `script/bootstrap` installs, refusing any version but the pinned one;
-  `script/fmt` and `script/fmt-check` both go through it, so they cannot
-  disagree about Go formatting
 - `script/prettier` — run prettier over the repository's canonical file set
   (Markdown and JSON, minus `.prettierignore`) in the given mode, `--write` or
-  `--check`, with the prettier version `yarn.lock` pins, run by the node on
+  `--check`; the single definition of that file set, so `script/fmt` and
-  `PATH` or else the one `script/bootstrap` installed through nvm; the single
+  `script/fmt-check` cannot disagree about it
-  definition of that file set, so `script/fmt` and `script/fmt-check` cannot
+- `script/fmt-check` — check formatting without writing: `script/fmt-check-go`
-  disagree about it
+  plus `script/prettier --check`
-- `script/fmt-check` — check formatting without writing:
+- `script/fmt-check-go` — the Go half of `script/fmt-check`, on its own, for the
-  `script/gofumpt --check` plus `script/prettier --check`
+  Docker lint stage, whose image has no node
 - `script/check` — run `script/test`, `script/lint`, and `script/fmt-check`
 - `script/docker` — build the Docker image tagged with the project name
-- `script/cibuild` — CI entrypoint: runs `script/bootstrap` and `script/check`,
+- `script/cibuild` — CI entrypoint: builds the image with the same command as
-  then builds the image with the same command as `script/docker`, uncached, so
+  `script/docker`, uncached, so the checks in the Dockerfile run every time
-  the lint and test phases in the `Dockerfile` run every time
 - `script/precommit` — pre-commit checks: `go mod tidy` verification, then
   `script/check`
 - `script/install-precommit` — install the git pre-commit hook that runs
@@ -264,23 +253,13 @@ are now tracked only in the [issues](https://git.eeqj.de/sneak/mfer/issues).
 - `mfer check` / `mfer check .`
     - verifies checksums of all files in manifest, displaying error and exiting
       nonzero if any files are missing or corrupted
-    - warns about each file under the base directory that the manifest does not
-      list, hidden files included; with `--no-extra-files` each one is a failure
-      instead
 - `mfer fetch https://example.com/stuff/`
     - fetches `/stuff/index.mf` and downloads all files listed in manifest into
       the current directory, or the one given with `--dest`, and assures
       cryptographic integrity of downloaded files. A file already there with the
       size and hash the manifest lists is skipped. Once every file is in place,
       the manifest is saved there as `index.mf`, so `mfer check` can verify the
-      tree later. Each file is downloaded to a temp file beside it, such as
+      tree later.
-      `.a.txt.tmp` for `a.txt`, then moved into place. A manifest is refused
-      before any file is downloaded if it lists a file where fetch writes
-      another: at another listed file or a directory one is in, at the temp file
-      of a listed file, or at `index.mf` or `.index.mf.tmp` at the top of the
-      tree. Names are compared in any letter case, on every filesystem, since on
-      a case-insensitive one `A.txt` and `a.txt` are one file; a directory two
-      listed files are in must be spelled alike in both.
 - `mfer fetch --require-signature <fingerprint> https://example.com/stuff/`
     - as above, but first refuses a manifest not signed by the key with that
       fingerprint, as `mfer check --require-signature` does, before downloading

REPO_POLICIES.md

@@ -1,6 +1,6 @@
 ---
 title: Repository Policies
-last_modified: 2026-10-04
+last_modified: 2026-07-06
 ---
 
 This document covers repository structure, tooling, and workflow standards. Code
@@ -60,28 +60,17 @@ style conventions are in separate documents:
   prerequisite since nvm requires bash. yarn is then pinned via
   `corepack prepare yarn@<version> --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
+  repo root and runs `docker build .`; the Gitea workflow calls it. Four further
-  with the version; the Gitea workflow calls it. **`script/cibuild` runs
+  scripts are our own extensions to the standard: `script/check` runs
-  `script/bootstrap` first**, because the workflow checks out the repo and runs
+  `script/test`, `script/lint`, and `script/fmt-check`; `script/precommit` is
-  nothing else, while `script/fmt-check` runs the formatter on the host: on a
+  what the git pre-commit hook runs, and it calls `script/check`;
-  pristine checkout with nothing installed the run dies there, after the
+  `script/install-precommit` installs the git pre-commit hook (the `make hooks`
-  containerised gates have passed. **The bootstrap alone is not enough**:
+  target shims to it); and `script/projectname` (literally that filename) simply
-  `script/bootstrap` installs node and yarn under nvm and leaves neither on the
+  outputs the project's name. Scripts that need the name call
-  `PATH` of the shell that called it, so a bare `yarn` still exits 127. The host
+  `script/projectname` — e.g. `script/docker` assembles its image tag from it —
-  entrypoints that need yarn — `script/fmt` and `script/fmt-check` — therefore
+  so those scripts stay byte-identical across all repos. Repo-type-specific
-  source nvm for the pinned node version before invoking it, exactly as
+  pre-commit extras (e.g. `go mod tidy` verification in Go repos) belong in
-  `script/bootstrap`'s own install step does. A runner carrying nothing but
+  `script/precommit`, not in the hook itself. Model scripts are at
-  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/<name>`. The README
   must document the provided scripts in an **Entrypoints** section (see the
   README requirements below).
@@ -100,198 +89,87 @@ style conventions are in separate documents:
   contributor should be able to understand the entire development workflow by
   reading the Makefile.
 
-- Every repo should have a `Dockerfile`, and it carries the repo's gates: a
+- Every repo should have a `Dockerfile`. All Dockerfiles must run `make check`
-  `lint` phase and a `test` phase, with the final stage depending on both so the
+  as a build step so the build fails if the branch is not green. For non-server
-  image cannot be built unless they pass. For non-server repos the final stage
+  repos, the Dockerfile should bring up a development environment and run
-  brings up a development environment; for server repos it is the runtime image.
+  `make check`. For server repos, `make check` should run as an early build
-  The gate phases and the build stage start from their pinned base images and
+  stage before the final image is assembled. Dockerfiles install development
-  install what those images lack either inline, as the canonical Go `Dockerfile`
+  prerequisites by running `script/bootstrap` rather than duplicating installs
-  below does for `git`, or by running `script/bootstrap`, as the `prompts`
+  inline; COPY `script/` and the dependency manifests (`package.json` +
-  repo's own `Dockerfile` does for its yarn packages. The development
+  `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it so the bootstrap
-  environment stage installs development prerequisites by running
+  layer stays cached until dependencies change.
-  `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
+- **Dockerfiles must use a separate lint stage for fail-fast feedback.** Go
-  no separate lint file. `script/lint` and `script/test` each build one phase
+  repos use a multistage build where linting runs in an independent stage based
-  and nothing else:
+  on the `golangci/golangci-lint` image (pinned by hash). This stage runs
+  `make fmt-check` and `make lint` before the full build begins. The build stage
+  then declares an explicit dependency on the lint stage via
+  `COPY --from=lint /src/go.sum /dev/null`, which forces BuildKit to complete
+  linting before proceeding to compilation and tests. This ensures lint failures
+  surface in seconds rather than minutes, without blocking on dependency
+  download or compilation in the build stage.
 
-    ```sh
+    The standard pattern for a Go repo Dockerfile is:
-    docker build --no-cache --target lint -t "$(script/projectname)-lint" .
-    docker build --no-cache --target test -t "$(script/projectname)-test" .
-    ```
-
-    **A stage that is not the last one in the file is built only when the final
-    stage's chain depends on it, or when `--target` names it.** That is why the
-    two gates are always invoked by name here, and why the final stage carries a
-    `COPY --from=` of a harmless file from each of them: without that edge a
-    plain `docker build .` builds the last stage alone and exits 0 having linted
-    and tested nothing.
-
-    **Every `docker build` in `script/` is tagged**, here and in
-    `script/cibuild` and `script/docker`. An untagged build leaves a dangling
-    image behind on every invocation, on every developer host and every CI
-    runner; a tagged one replaces the previous image.
-
-    Inside a phase the tool is invoked directly — `golangci-lint`, `go test`,
-    `eslint`, `prettier` — never through `make lint` or `script/test`, which are
-    themselves a `docker build` and would recurse into a daemon that does not
-    exist in a build step. Formatting is the exception and stays on the host:
-    `script/fmt` writes the working tree, and `script/fmt-check` is its
-    read-only twin.
-
-    **No lint verdict may come from a host invocation of the linter.** On a
-    shared host golangci-lint reads a result cache keyed on file content rather
-    than location, so a second checkout of the same content is served the first
-    one's findings, and a host-global lock in `$TMPDIR` makes concurrent runs
-    exit non-zero with `parallel golangci-lint is running` — a status a caller
-    cannot tell from real findings. Both have produced wrong verdicts in this
-    org, in both directions. A container has its own cache, its own `TMPDIR` and
-    a digest-pinned binary, so neither is reachable.
-
-- **Any build that runs checks is built with `--no-cache`.** Docker invalidates
-  a `COPY` layer only when the copied content changes, so on an unchanged tree
-  the check `RUN` is served from cache, nothing executes, and the build still
-  exits 0. Every `docker build` in `script/` therefore passes `--no-cache`:
-  `script/lint`, `script/test`, `script/cibuild` and `script/docker` are the
-  four, and there is no fifth — `script/check` runs the two gate phases and
-  `script/fmt-check`, and builds no image of its own. A bare `docker build .` is
-  not evidence that anything ran: a sub-second build reporting success is a
-  cache hit, not a result. Never invalidate by pruning — `docker builder prune`
-  and friends destroy a build cache shared with every other build on the host.
-  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.
-
-- **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
-  `Dockerfile`:
 
     ```dockerfile
-    # Lint phase
+    # Lint stage — fast feedback on formatting and lint issues
     # golangci/golangci-lint:v2.x.x, YYYY-MM-DD
     FROM golangci/golangci-lint@sha256:... AS lint
     WORKDIR /src
     COPY go.mod go.sum ./
     RUN go mod download
     COPY . .
-    RUN golangci-lint run --config .golangci.yml ./...
+    RUN make fmt-check
+    RUN make lint
 
-    # Test phase. -race needs cgo and so a C compiler, which the Debian Go
+    # Build stage
-    # image ships and the alpine one does not.
-    # golang:1.x, YYYY-MM-DD
-    FROM golang@sha256:... AS test
-    WORKDIR /src
-    COPY go.mod go.sum ./
-    RUN go mod download
-    COPY . .
-    RUN go test -timeout 90s -race -cover ./... || \
-        { echo "--- Rerunning with -v for details ---"; \
-          go test -timeout 90s -race -v ./...; exit 1; }
-
-    # Build stage. Nothing is wanted from either phase above; the copies
-    # are what make BuildKit build them first, so this stage cannot run
-    # unless lint and test passed.
     # golang:1.x-alpine, YYYY-MM-DD
     FROM golang@sha256:... AS builder
-    COPY --from=lint /src/go.sum /dev/null
-    COPY --from=test /src/go.sum /dev/null
-    RUN apk add --no-cache git
-    # A tar-stream context keeps the sender's file owners, which git refuses.
-    RUN git config --system --add safe.directory /src
     WORKDIR /src
+
+    # Force BuildKit to run the lint stage before proceeding
+    COPY --from=lint /src/go.sum /dev/null
+
     COPY go.mod go.sum ./
     RUN go mod download
     COPY . .
+    RUN make test
 
-    # The VERSION build arg when one is given, otherwise
+    ARG VERSION=dev
-    # `git describe --tags --always` on the .git in the build context. With
+    RUN CGO_ENABLED=0 go build -trimpath \
-    # .git present, a version that is still empty, dev or unknown fails the
+        -ldflags="-s -w -X main.Version=${VERSION}" \
-    # build: git is missing or could not read the checkout.
+        -o /app ./cmd/app/
-    ARG VERSION
-    RUN VERSION="${VERSION:-$(git describe --tags --always)}"; \
-        if [ -e .git ]; then \
-            case "$VERSION" in ""|dev|unknown) \
-                echo "version is '$VERSION' although .git is present" >&2; \
-                exit 1 ;; \
-            esac; \
-        fi; \
-        CGO_ENABLED=0 go build -trimpath \
-            -ldflags="-s -w -X main.Version=${VERSION}" \
-            -o /app ./cmd/app/
 
-    # Runtime stage, and the last one
+    # Runtime stage
     FROM alpine@sha256:...
     COPY --from=builder /app /usr/local/bin/app
     ENTRYPOINT ["app"]
     ```
 
     Key points:
-    - The lint phase uses the `golangci/golangci-lint` image directly (it has
+    - The lint stage uses the `golangci/golangci-lint` image directly (it
-      both Go and the linter), so nothing needs installing.
+      includes both Go and the linter), so there is no need to install the
-    - `COPY --from=<phase> /src/go.sum /dev/null` is a no-op copy whose only
+      linter separately.
-      purpose is the ordering edge. BuildKit runs stages in parallel by default,
+    - `COPY --from=lint /src/go.sum /dev/null` is a no-op file copy that creates
-      and a stage nothing depends on is not built at all, so without these two
+      a stage dependency. BuildKit runs stages in parallel by default; without
-      lines a red gate would not fail the build.
+      this line, the build stage would not wait for lint to finish and a lint
-    - Keep the runtime stage last, and if you add a stage after it, give it the
+      failure might not fail the overall build.
-      same two copies. A plain `docker build .` builds the last stage's chain
-      and nothing else.
     - If the project uses `//go:embed` directives that reference build artifacts
-      (e.g. a web frontend compiled in a separate stage), the lint phase must
+      (e.g. a web frontend compiled in a separate stage), the lint stage must
       create placeholder files so the embed directives resolve. 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
+      The lint stage should not depend on the actual build output — it exists to
-      in the lint phase. The `golangci/golangci-lint` image is Debian-based and
+      fail fast.
-      has no `apk`, so install with `apt-get` under the Debian package name
+    - If the project requires CGO or system libraries for linting (e.g.
-      (`libvips-dev`, where alpine says `vips-dev`), and delete the package
+      `vips-dev`), install them in the lint stage with `apk add`.
-      lists in the same `RUN`, so the layer does not keep them:
+    - The build stage runs `make test` after compilation setup. Tests run in the
-
+      build stage, not the lint stage, because they may require compiled
-        ```dockerfile
+      artifacts or heavier dependencies.
-        RUN apt-get update \
-            && apt-get install -y --no-install-recommends libvips-dev \
-            && rm -rf /var/lib/apt/lists/*
-        ```
-
-    - `.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.
 
 - 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.
+  runs `script/cibuild` (which runs `docker build .`) on push. Since the
-  That script bootstraps, runs the gate phases, and then builds the image, so a
+  Dockerfile already runs `make check`, a successful build implies all checks
-  successful run means every check passed; a bare `docker build .` does not
+  pass.
-  carry the same guarantee, because its gate phases may come from the cache. The
-  image build is uncached and so runs the gate phases a second time. That is the
-  price of the rule above, and it is worth paying: the image that ships is built
-  from a run of its own gates rather than from a cache entry. 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
@@ -311,21 +189,14 @@ style conventions are in separate documents:
   module under test to verify it compiles/parses. 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
+- `make test` must complete in under 20 seconds. Add a 30-second timeout in the
-  suite that exceeds it fails. Under 20 seconds is the target. A suite between
+  Makefile.
-  20 and 60 seconds is still green, but the overage must be filed as an
-  improvement bug against that repo. Add a 90-second timeout to the test
-  invocation (`go test -timeout 90s`). The backstop deliberately sits above the
-  hard cap so that it catches a genuinely hung test rather than a merely slow
-  one.
 
-- **The test command should use the conditional verbose rerun pattern.** Run
+- **`make test` should use the conditional verbose rerun pattern.** Run tests
-  tests without `-v` (verbose) first. If tests fail, automatically rerun with
+  without `-v` (verbose) first. If tests fail, automatically rerun with `-v` to
-  `-v` to show full output. This keeps CI logs and `docker build` output clean
+  show full output. This keeps CI logs and `docker build` output clean on
-  on success (just package/suite summaries) while providing full diagnostic
+  success (just package/suite summaries) while providing full diagnostic detail
-  detail on failure (every test case, every assertion). The command lives in the
+  on failure (every test case, every assertion). The general shell pattern:
-  `test` phase of the `Dockerfile`, since `script/test` builds that phase; the
-  Makefile form below is the same pattern for any repo-local invocation:
 
     ```makefile
     test:
@@ -338,26 +209,11 @@ style conventions are in separate documents:
 
     ```makefile
     test:
-    	@go test -count=1 -timeout 90s -race -cover ./... || \
+    	@go test -timeout 30s -race -cover ./... || \
     		{ echo "--- Rerunning with -v for details ---"; \
-    		  go test -count=1 -timeout 90s -race -v ./...; exit 1; }
+    		  go test -timeout 30s -race -v ./...; exit 1; }
     ```
 
-    `-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. That matters on a developer's machine, where this
-    target runs and the directory lasts from one run to the next. The `test`
-    phase of the `Dockerfile` needs no `-count=1`: its base image holds no
-    result for this repo's tests and nothing before its `go test` step runs a
-    test, so there is nothing to replay. `--no-cache` (above) is what makes that
-    step run on an unchanged tree.
-
     Python example:
 
     ```makefile
@@ -383,84 +239,10 @@ style conventions are in separate documents:
   must be in `.gitignore`. No exceptions.
 
 - `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`),
-  editor files (`.swp`, `*~`), in-repo agent scratch directories (`.claude/`),
+  editor files (`.swp`, `*~`), language build artifacts, and `node_modules/`.
-  language build artifacts, and `node_modules/`. Fetch the standard `.gitignore`
+  Fetch the standard `.gitignore` from
-  from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up
-  setting up a new repo. These patterns are written to `.gitignore`'s own
+  a new repo.
-  semantics, in which an unanchored pattern already matches at every depth; they
-  are not a `.dockerignore` and must not be transplanted into one unmodified.
-
-- **`.dockerignore` does not use `.gitignore` semantics, and copying patterns
-  across unmodified leaves secrets in the build context.** Docker matches with
-  `moby/patternmatcher`: `filepath.Match` semantics plus a `**` extension, so
-  `*` does not cross `/` and a pattern without a leading `**/` is anchored at
-  the build-context root. A `.dockerignore` listing `.env`, `*.pem` and `*.key`
-  therefore excludes only the copies at the repository root, while `config/.env`
-  and `certs/server.key` still reach the context and can land in an image layer
-  — which is more dangerous than a short file with no secret patterns at all,
-  because it reads as solved and stops anyone looking. Give every
-  depth-independent pattern the `**/` prefix and leave only genuinely
-  root-anchored entries unprefixed: `.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
-  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` and extend
-  it with the repo's own artifacts.
-
-- **In-repo agent scratch belongs in both files, written to each file's own
-  semantics.** `.claude/` holds one worktree per in-flight agent — an entire
-  additional checkout of the repo — so under `COPY . .` the build context
-  inflates by a multiple of the repo and another session's unreviewed work can
-  be copied into an image layer. In `.gitignore` the entry is `.claude/`,
-  unanchored. In `.dockerignore` it is `.claude`, anchored and with **no** `**/`
-  prefix, because the prefixed form would also delete any nested directory of
-  that name from the build. Anchoring carries a known gap that the canonical
-  `.dockerignore` states in its own comment, since consuming repos receive the
-  file and not the tracker: the directory is created in the agent's working
-  directory, so a repo running agents in subdirectories still ships
-  `services/api/.claude/` and must add its own anchored entry there.
-
-- **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:
-
-    ```sh
-    # Own line: a failing command substitution inside an argument does not
-    # trip `set -e`, so the inline form degrades to an empty constant.
-    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
-    [ -n "$version" ] || version="unknown"
-    docker build --no-cache \
-        --build-arg VERSION="$version" \
-        -t "$(script/projectname)" .
-    ```
-
-    `--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
-    Dockerfile declares no such `ARG` is ignored and costs nothing, which is why
-    the scripts stay byte-identical. One consequence for CI: the standard
-    checkout action clones shallow and fetches no tags, so a repo that embeds a
-    tag-derived version must set `fetch-depth: 0` on its checkout step.
-
-- **Verify `.dockerignore` by enumerating the image, not by reading the
-  patterns.** Plant files at the root _and_ at least two directories deep, build
-  a probe image that does `COPY . .`, and list what actually landed
-  (`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
@@ -476,56 +258,9 @@ style conventions are in separate documents:
 - Make all changes on a feature branch. You can do whatever you want on a
   feature branch.
 
-- `.golangci.yml` is standardized. The vendored copy in a consuming repo must
+- `.golangci.yml` is standardized and must _NEVER_ be modified by an agent, only
-  _NEVER_ be modified by an agent: fetch it from
+  manually by the user. Fetch from
-  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml` and keep it
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml`.
-  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
-  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
-  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.14.0 (released 2026-09-24), pinned as the digest of the lint phase's base
-  image
-  (`golangci/golangci-lint@sha256:ad862ba6b3798cbe0fd9fd7408d498fd74fbd2623a92406b2fd3898faf0bf98f`,
-  which reports `2.14.0 built with go1.27.0 from 114493f9`). 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
-  `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
-  `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 <tool>; then install; fi` guard tests
-  `PATH` only, so on an already-provisioned machine the pin is inert and a
-  version bump is a silent no-op — while the Dockerfile, installing into a clean
-  image, gets the pinned version, so a local `make check` and `make docker` can
-  disagree about what the tool even is. The canonical form:
-    - compares the installed version against the pin over the **whole** version
-      token; a parser that stops at the first `-` reports `2.12.2` for a host
-      running `2.12.2-rc1` and skips the install;
-    - treats absent, non-zero, empty or unrecognised `--version` output as a
-      mismatch, so the failure direction is a redundant install and never a
-      skipped one;
-    - after installing, re-resolves the binary the way callers do — `hash -r`,
-      then through `PATH`, not through the directory the installer wrote to —
-      and fails naming the resolved path, since an install that a shadowing
-      binary hides succeeds while changing nothing any caller sees;
-    - is actually called, and prints the version on both success paths: a
-      function defined and never invoked has the same exit status and the same
-      empty output as one that worked.
-
-    Keep it POSIX sh: no arrays, no `[[`, no `grep -P`.
-
-    A Go tool a repo needs on the host is installed with `go install` pinned to
-    a commit hash (`go install <package>@<commit hash>`). It is never tracked as
-    a `go.mod` tool dependency or through a `tools.go` file, either of which
-    pulls the tool's own dependencies into the repo's `go.mod` and `go.sum`.
 
 - When pinning images or packages by hash, add a comment above the reference
   with the version and date (YYYY-MM-DD).
@@ -639,14 +374,12 @@ style conventions are in separate documents:
   settings.
 
 - Avoid putting files in the repo root unless necessary. Root should contain
-  only project-level config files (`README.md`, `AGENTS.md`, `Makefile`,
+  only project-level config files (`README.md`, `Makefile`, `Dockerfile`,
-  `Dockerfile`, `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`,
+  `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`, and
-  and language-specific config). Everything else goes in a subdirectory.
+  language-specific config). Everything else goes in a subdirectory. Canonical
-  Canonical subdirectory names:
+  subdirectory names:
     - `bin/` — executable scripts and tools
-    - `cmd/` — Go command entrypoints; thin only: one `main.go` per binary whose
+    - `cmd/` — Go command entrypoints
-      body is a single call into `internal/` or `pkg/`, no project logic in
-      `cmd/`
     - `configs/` — configuration templates and examples
     - `deploy/` — deployment manifests (k8s, compose, terraform)
     - `docs/` — documentation and markdown (README.md stays in root)
@@ -673,7 +406,3 @@ style conventions are in separate documents:
     - Go: `go.mod`, `go.sum`, `.golangci.yml`
     - JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
     - Python: `pyproject.toml`
-
-- Guidance for coding agents lives in one `AGENTS.md` at the repository root. It
-  is never committed under a file or directory named after one agent tool, such
-  as `CLAUDE.md` or `.claude/`, and never split into separate memory files.

bin/gitrev.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+main() {
+    if [[ -n "${GITREV:-}" ]]; then
+        echo "$GITREV"
+    else
+        git describe --tags --always --dirty=-dirty
+    fi
+}
+
+main "$@"

docs/FORMAT.md

@@ -78,6 +78,9 @@ Each file entry contains:
 | `mtime`    | 302    | Timestamp (optional)      | Modification time                   |
 | `ctime`    | 303    | Timestamp (optional)      | Change time (inode metadata change) |
 
+Field 304 (`atime`) has been removed from the specification. Access time is
+volatile and non-deterministic; it is not useful for integrity verification.
+
 ## Path Rules
 
 All `path` values must satisfy these invariants:
@@ -127,6 +130,7 @@ By default, manifests are generated deterministically:
 
 - File entries are sorted by `path` in **lexicographic byte order**
 - `createdAt` is omitted unless explicitly requested
+- `atime` is never included (field removed from schema)
 
 This ensures that two independent runs over the same directory tree produce
 byte-identical `.mf` files (assuming file contents and metadata have not

go.mod

@@ -9,21 +9,27 @@ require (
 	github.com/klauspost/compress v1.18.2
 	github.com/multiformats/go-multihash v0.2.3
 	github.com/spf13/afero v1.8.0
-	github.com/stretchr/testify v1.12.1
+	github.com/stretchr/testify v1.8.1
-	github.com/urfave/cli/v3 v3.14.0
+	github.com/urfave/cli/v2 v2.27.7
 	golang.org/x/term v0.0.0-20210927222741-03fcf44c2211
 	google.golang.org/protobuf v1.28.1
 )
 
 require (
+	github.com/cpuguy83/go-md2man/v2 v2.0.7 // indirect
 	github.com/klauspost/cpuid/v2 v2.0.9 // indirect
+	github.com/kr/pretty v0.2.0 // indirect
 	github.com/minio/sha256-simd v1.0.0 // indirect
 	github.com/mr-tron/base58 v1.2.0 // indirect
 	github.com/multiformats/go-varint v0.0.6 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/spaolacci/murmur3 v1.1.0 // indirect
-	go.yaml.in/yaml/v3 v3.0.5 // indirect
+	github.com/xrash/smetrics v0.0.0-20240521201337-686a1a2994c1 // indirect
 	golang.org/x/crypto v0.0.0-20220525230936-793ad666bf5e // indirect
 	golang.org/x/sys v0.1.0 // indirect
 	golang.org/x/text v0.3.6 // indirect
+	gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
 	lukechampine.com/blake3 v1.1.6 // indirect
 )

go.sum

@@ -46,6 +46,8 @@ github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDk
 github.com/cncf/udpa/go v0.0.0-20191209042840-269d4d468f6f/go.mod h1:M8M6+tZqaGXZJjfX53e64911xZQV5JYwmTeXPW+k8Sc=
 github.com/cncf/udpa/go v0.0.0-20200629203442-efcf912fb354/go.mod h1:WmhPx2Nbnhtbo57+VJT5O0JRkEi1Wbu0z5j0R8u5Hbk=
 github.com/cncf/udpa/go v0.0.0-20201120205902-5459f2c99403/go.mod h1:WmhPx2Nbnhtbo57+VJT5O0JRkEi1Wbu0z5j0R8u5Hbk=
+github.com/cpuguy83/go-md2man/v2 v2.0.7 h1:zbFlGlXEAKlwXpmvle3d8Oe3YnkKIK4xSRTd3sHPnBo=
+github.com/cpuguy83/go-md2man/v2 v2.0.7/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -132,7 +134,10 @@ github.com/klauspost/cpuid/v2 v2.0.9 h1:lgaqFMSdTdQYdZ04uHyN2d/eKdOMyi2YLSvlQIBF
 github.com/klauspost/cpuid/v2 v2.0.9/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=
 github.com/kr/fs v0.1.0/go.mod h1:FFnZGqtBN9Gxj7eW1uZ42v5BccTP0vu6NEaFoC2HwRg=
 github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
+github.com/kr/pretty v0.2.0 h1:s5hAObm+yFO5uHYt5dYjxi2rXrsnmRpJx4OYvIWUaQs=
+github.com/kr/pretty v0.2.0/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
 github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0 h1:45sCR5RtlFHMR4UwH9sdQ5TC8v0qDQCHnXt+kaKSTVE=
 github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
 github.com/minio/sha256-simd v1.0.0 h1:v1ta+49hkWZyvaKwrQB8elexRqm6Y0aMLjCNsrYxo6g=
 github.com/minio/sha256-simd v1.0.0/go.mod h1:OuYzVNI5vcoYIAmbIvHPl3N3jUzVedXbKy5RFepssQM=
@@ -144,21 +149,30 @@ github.com/multiformats/go-varint v0.0.6 h1:gk85QWKxh3TazbLxED/NlDVv8+q+ReFJk7Y2
 github.com/multiformats/go-varint v0.0.6/go.mod h1:3Ls8CIEsrijN6+B7PbrXRPxHRPuXSrVKRY101jdMZYE=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pkg/sftp v1.13.1/go.mod h1:3HaPG6Dq1ILlpPZRO0HVMrsydcdLt6HRDccSgb87qRg=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
 github.com/rogpeppe/go-internal v1.3.0/go.mod h1:M8bDsm7K2OlrFYOpmOWEs/qY81heoFRclV5y23lUDJ4=
+github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/spaolacci/murmur3 v1.1.0 h1:7c1g84S4BPRrfL5Xrdp6fOJ206sU9y293DDHaoy0bLI=
 github.com/spaolacci/murmur3 v1.1.0/go.mod h1:JwIasOWyU6f++ZhiEuf87xNszmSA2myDM2Kzu9HwQUA=
 github.com/spf13/afero v1.8.0 h1:5MmtuhAgYeU6qpa7w7bP0dv6MBYuup0vekhSpSkoq60=
 github.com/spf13/afero v1.8.0/go.mod h1:CtAatgMJh6bJEIs48Ay/FOnkljP3WeGUG0MC1RfAqwo=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
 github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
 github.com/stretchr/testify v1.5.1/go.mod h1:5W2xD1RspED5o8YsWQXVCued0rvSQ+mT+I5cxcmMvtA=
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
-github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
-github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
-github.com/urfave/cli/v3 v3.14.0 h1:a8414NQlHJs0c/iBsulKLzlES0n/lEAskbL2LKpU4/s=
+github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
-github.com/urfave/cli/v3 v3.14.0/go.mod h1:vXn6HxPNccJSzQr2QvwVncOKrgYGIHU0HY5h8B2nQj4=
+github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
+github.com/urfave/cli/v2 v2.27.7 h1:bH59vdhbjLv3LAvIu6gd0usJHgoTTPhCFib8qqOwXYU=
+github.com/urfave/cli/v2 v2.27.7/go.mod h1:CyNAG/xg+iAOg0N4MPGZqVmv2rCoP267496AOXUZjA4=
+github.com/xrash/smetrics v0.0.0-20240521201337-686a1a2994c1 h1:gEOO8jv9F4OT7lGCjxCBTO/36wtF6j2nSip77qHd4x4=
+github.com/xrash/smetrics v0.0.0-20240521201337-686a1a2994c1/go.mod h1:Ohn+xnUBiLI6FVj/9LpzZWtj1/D6lUovWYBkxHVV3aM=
 github.com/yuin/goldmark v1.1.25/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.1.32/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
@@ -169,8 +183,6 @@ go.opencensus.io v0.22.2/go.mod h1:yxeiOL68Rb0Xd1ddK5vPZ/oVn4vY4Ynel7k9FzqtOIw=
 go.opencensus.io v0.22.3/go.mod h1:yxeiOL68Rb0Xd1ddK5vPZ/oVn4vY4Ynel7k9FzqtOIw=
 go.opencensus.io v0.22.4/go.mod h1:yxeiOL68Rb0Xd1ddK5vPZ/oVn4vY4Ynel7k9FzqtOIw=
 go.opencensus.io v0.22.5/go.mod h1:5pWMHQbX5EPX2/62yrJeAkowc+lfs/XD7Uxpq3pI6kk=
-go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw=
-go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20190510104115-cbcb75029529/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
 golang.org/x/crypto v0.0.0-20190605123033-f99c8df09eb5/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
@@ -458,9 +470,13 @@ google.golang.org/protobuf v1.28.1 h1:d0NfwRgPtno5B1Wa6L2DAG+KivqkdutMf1UhdNx175
 google.golang.org/protobuf v1.28.1/go.mod h1:HV8QOd/L58Z+nl8r43ehVNZIU/HEI6OcFqwMG9pJV4I=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 h1:YR8cESwS4TdDjEe65xsg0ogRM/Nc3DYOhEAlW+xobZo=
+gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/errgo.v2 v2.1.0/go.mod h1:hNsd1EY+bozCKY1Ytp96fpM3vjJbqLJn88ws8XvfDNI=
 gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
 honnef.co/go/tools v0.0.0-20190106161140-3f1c8253044a/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
 honnef.co/go/tools v0.0.0-20190418001031-e561f6794a2a/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=

internal/cli/check.go

@@ -16,7 +16,7 @@ import (
 
 	"github.com/dustin/go-humanize"
 	"github.com/spf13/afero"
-	"github.com/urfave/cli/v3"
+	"github.com/urfave/cli/v2"
 	"sneak.berlin/go/mfer/internal/log"
 	"sneak.berlin/go/mfer/mfer"
 )
@@ -96,10 +96,8 @@ func findManifest(fs afero.Fs, dir string) (string, error) {
 
 // fetchManifestToTemp downloads a manifest URL to a temporary file and
 // returns the temp file path. The caller is responsible for removing it.
-func (mfa *CLIApp) fetchManifestToTemp(
+func (mfa *CLIApp) fetchManifestToTemp(url string) (string, error) {
-	ctx context.Context, url string,
+	rc, fetchErr := mfa.openManifestReader(url)
-) (string, error) {
-	rc, fetchErr := mfa.openManifestReader(ctx, url)
 	if fetchErr != nil {
 		return "", fetchErr
 	}
@@ -208,29 +206,22 @@ func countCheckFailures(
 }
 
 // findExtraFiles reports files present on disk but absent from the
-// manifest, and anything the search cannot read: each is a failure under
+// manifest, counting each as a failure.
-// --no-extra-files, otherwise a warning.
+func findExtraFiles(ctx *cli.Context, chk *mfer.Checker, failures *int64) error {
-func findExtraFiles(
-	ctx context.Context, cmd *cli.Command, chk *mfer.Checker, failures *int64,
-) error {
 	extraResults := make(chan mfer.Result, 1)
 	extraDone := make(chan struct{})
 
 	go func() {
 		for result := range extraResults {
-			if cmd.Bool("no-extra-files") {
+			*failures++
-				*failures++
 
-				log.Infof("%s: %s (%s)", result.Status, result.Path, result.Message)
+			log.Infof("%s: %s (%s)", result.Status, result.Path, result.Message)
-			} else {
-				log.Warnf("%s: %s (%s)", result.Status, result.Path, result.Message)
-			}
 		}
 
 		close(extraDone)
 	}()
 
-	err := chk.FindExtraFiles(ctx, extraResults)
+	err := chk.FindExtraFiles(ctx.Context, extraResults)
 	if err != nil {
 		return fmt.Errorf("failed to check for extra files: %w", err)
 	}
@@ -242,9 +233,7 @@ func findExtraFiles(
 
 // runCheck runs the manifest check with progress and result reporting
 // and returns the number of failures.
-func runCheck(
+func runCheck(ctx *cli.Context, chk *mfer.Checker, showProgress bool) (int64, error) {
-	ctx context.Context, cmd *cli.Command, chk *mfer.Checker, showProgress bool,
-) (int64, error) {
 	// Set up results channel
 	results := make(chan mfer.Result, 1)
 
@@ -270,7 +259,7 @@ func runCheck(
 	go countCheckFailures(results, &failures, done)
 
 	// Run check
-	err := chk.Check(ctx, results, progress)
+	err := chk.Check(ctx.Context, results, progress)
 
 	progressWg.Wait()
 
@@ -281,27 +270,28 @@ func runCheck(
 	// Wait for results processing to complete
 	<-done
 
-	err = findExtraFiles(ctx, cmd, chk, &failures)
+	// Check for extra files if requested
-	if err != nil {
+	if ctx.Bool("no-extra-files") {
-		return 0, err
+		err = findExtraFiles(ctx, chk, &failures)
+		if err != nil {
+			return 0, err
+		}
 	}
 
 	return failures, nil
 }
 
-func (mfa *CLIApp) checkManifestOperation(
+func (mfa *CLIApp) checkManifestOperation(ctx *cli.Context) error {
-	ctx context.Context, cmd *cli.Command,
-) error {
 	log.Debug("checkManifestOperation()")
 
-	manifestPath, err := mfa.resolveManifestArg(cmd)
+	manifestPath, err := mfa.resolveManifestArg(ctx)
 	if err != nil {
 		return fmt.Errorf("check: %w", err)
 	}
 
 	// URL manifests need to be downloaded to a temp file for the checker
 	if isHTTPURL(manifestPath) {
-		tmpPath, tmpErr := mfa.fetchManifestToTemp(ctx, manifestPath)
+		tmpPath, tmpErr := mfa.fetchManifestToTemp(manifestPath)
 		if tmpErr != nil {
 			return fmt.Errorf("check: %w", tmpErr)
 		}
@@ -311,13 +301,12 @@ func (mfa *CLIApp) checkManifestOperation(
 		manifestPath = tmpPath
 	}
 
-	basePath := cmd.String("base")
+	basePath := ctx.String("base")
-	showProgress := cmd.Bool("progress")
+	showProgress := ctx.Bool("progress")
 
 	log.Infof("checking manifest %s with base %s", manifestPath, basePath)
 
 	// Create checker
-	//nolint:contextcheck // mfer loads a manifest without a context
 	chk, err := mfer.NewChecker(&mfer.CheckerOptions{
 		ManifestPath: manifestPath,
 		BasePath:     basePath,
@@ -328,9 +317,9 @@ func (mfa *CLIApp) checkManifestOperation(
 	}
 
 	// Check signature requirement
-	requiredSigner := cmd.String(flagRequireSignature)
+	requiredSigner := ctx.String(flagRequireSignature)
 	if requiredSigner != "" {
-		err = verifyRequiredSigner(ctx, chk, requiredSigner)
+		err = verifyRequiredSigner(ctx.Context, chk, requiredSigner)
 		if err != nil {
 			return err
 		}
@@ -339,7 +328,7 @@ func (mfa *CLIApp) checkManifestOperation(
 	log.Infof("manifest contains %d files, %s", chk.FileCount(),
 		humanize.IBytes(safeUint64(int64(chk.TotalBytes()))))
 
-	failures, err := runCheck(ctx, cmd, chk, showProgress)
+	failures, err := runCheck(ctx, chk, showProgress)
 	if err != nil {
 		return err
 	}

internal/cli/entry_test.go

@@ -18,7 +18,7 @@ import (
 	"github.com/spf13/afero"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
-	urfcli "github.com/urfave/cli/v3"
+	urfcli "github.com/urfave/cli/v2"
 	"sneak.berlin/go/mfer/internal/log"
 	"sneak.berlin/go/mfer/mfer"
 )
@@ -264,9 +264,8 @@ func commandsTakingVerbose() [][]string {
 }
 
 // TestVerboseCount asserts that one -v or --verbose gives verbose output and
-// two -v, or -v and --verbose, give debug output (issue #125). urfave/cli
+// two -v give debug output (issue #125). urfave/cli before v2.25.5 counted a
-// before v2.25.5 counted a flag given by its alias twice, so one -v gave debug
+// flag given by its alias twice, so one -v gave debug output.
-// output.
 func TestVerboseCount(t *testing.T) {
 	t.Parallel()
 
@@ -277,7 +276,6 @@ func TestVerboseCount(t *testing.T) {
 		{[]string{"-v"}, log.VerboseLevel},
 		{[]string{testFlagVerbose}, log.VerboseLevel},
 		{[]string{"-v", "-v"}, log.DebugLevel},
-		{[]string{"-v", testFlagVerbose}, log.DebugLevel},
 	}
 
 	for _, command := range commandsTakingVerbose() {
@@ -315,6 +313,28 @@ func TestCombinedShortVerboseRefused(t *testing.T) {
 	}
 }
 
+// TestShortAndLongVerboseRefused asserts that -v and --verbose given together
+// are refused (issue #125): urfave/cli v2 refuses a flag given under two of its
+// names, and one flag with an alias keeps help and parsing simple.
+func TestShortAndLongVerboseRefused(t *testing.T) {
+	t.Parallel()
+
+	for _, command := range commandsTakingVerbose() {
+		args := slices.Concat(command, []string{"-v", testFlagVerbose})
+
+		t.Run(strings.Join(args, " "), func(t *testing.T) {
+			t.Parallel()
+
+			opts := testOpts(args, afero.NewMemMapFs())
+			exitCode, level := runCLIWithLevel(opts)
+
+			assert.Equal(t, 1, exitCode)
+			assert.Contains(t, testStderr(t, opts), "Cannot use two forms of the same flag")
+			assert.Equal(t, log.InfoLevel, level)
+		})
+	}
+}
+
 func TestHelpCommand(t *testing.T) {
 	t.Parallel()
 
@@ -685,155 +705,30 @@ func TestNoExtraFilesWithSubdirectory(t *testing.T) {
 		"check should fail when extra files exist in subdirectory")
 }
 
-// TestCheckWarnsAboutUnlistedFiles adds one file the manifest does not list
+func TestCheckWithoutNoExtraFilesIgnoresExtra(t *testing.T) {
-// to a tree that had none: it gets one warning and the check passes, unless
-// --no-extra-files makes it a failure. --quiet hides the warning, not the
-// failure.
-func TestCheckWarnsAboutUnlistedFiles(t *testing.T) {
 	t.Parallel()
 
-	for name, unlisted := range map[string]string{
+	fs := afero.NewMemMapFs()
-		"regular file":             "extra.txt",
-		"dotfile":                  ".hidden",
-		"file in hidden directory": ".git/config",
-	} {
-		t.Run(name, func(t *testing.T) {
-			t.Parallel()
 
-			fs := afero.NewMemMapFs()
+	// Create test file
-			require.NoError(t, fs.MkdirAll(testDir, 0o755))
+	require.NoError(t, fs.MkdirAll(testDir, 0o755))
-			writeTestFile(t, fs, testFile1, "hello")
+	writeTestFile(t, fs, testFile1, "hello")
 
-			opts := testOpts([]string{
+	// Generate manifest
-				testApp, cmdGenerate, "-q", "-o", testManifest, testDir,
+	opts := testOpts([]string{testApp, cmdGenerate, "-q", "-o", testManifest, testDir}, fs)
-			}, fs)
+	exitCode := runCLI(opts)
-			require.Equal(t, 0, runCLI(opts), "stderr: %s", testStderr(t, opts))
+	require.Equal(t, 0, exitCode)
 
-			check := func(flags ...string) (int, string) {
+	// Add extra file
-				args := append([]string{testApp, cmdCheck, testFlagBase, testDir}, flags...)
+	writeTestFile(t, fs, "/testdir/extra.txt", "extra")
-				opts := testOpts(append(args, testManifest), fs)
-
-				return runCLI(opts), testStderr(t, opts)
-			}
-
-			exitCode, stderr := check()
-			assert.Equal(t, 0, exitCode, "stderr: %s", stderr)
-			assert.NotContains(t, stderr, "not in manifest")
-
-			writeTestFile(t, fs, filepath.Join(testDir, unlisted), "unlisted")
-
-			exitCode, stderr = check()
-			assert.Equal(t, 0, exitCode, "stderr: %s", stderr)
-			assert.Equal(t, 1, strings.Count(stderr, "not in manifest"), stderr)
-			assert.Contains(t, stderr, unlisted)
-
-			exitCode, stderr = check("-q")
-			assert.Equal(t, 0, exitCode, "stderr: %s", stderr)
-			assert.NotContains(t, stderr, "not in manifest")
-
-			exitCode, stderr = check(testFlagNoExtra)
-			assert.Equal(t, 1, exitCode, "stderr: %s", stderr)
-			assert.Contains(t, stderr, unlisted)
-
-			exitCode, _ = check("-q", testFlagNoExtra)
-			assert.Equal(t, 1, exitCode)
-		})
-	}
-}
-
-// TestCheckNeverReportsManifest keeps the manifest inside the checked tree,
-// under several names and path spellings, and names the tree both directly
-// and through a symlink: the manifest is never reported, even under
-// --no-extra-files. The manifest is recognized by file identity, which needs
-// the real filesystem.
-func TestCheckNeverReportsManifest(t *testing.T) {
-	t.Parallel()
-
-	// Manifest paths are relative to the checked tree.
-	for name, manifest := range map[string]string{
-		"default name":                 defaultManifestName,
-		"hidden name":                  ".index.mf",
-		"other name in a subdirectory": "sub/listing.mf",
-		"path spelled through ..":      "sub/../index.mf",
-	} {
-		t.Run(name, func(t *testing.T) {
-			t.Parallel()
-
-			// A temp dir holding data/tree and link, a symlink to data.
-			root := t.TempDir()
-			tree := filepath.Join(root, "data", "tree")
-			// Not filepath.Join, which would clean away a "..".
-			manifestPath := tree + "/" + manifest
-
-			fs := afero.NewOsFs()
-			require.NoError(t, fs.MkdirAll(filepath.Join(tree, "sub"), 0o750))
-			require.NoError(t,
-				os.Symlink(filepath.Join(root, "data"), filepath.Join(root, "link")))
-			writeTestFile(t, fs, filepath.Join(tree, testFileTxt), "hello")
-
-			opts := testOpts([]string{
-				testApp, cmdGenerate, "-q", "-o", manifestPath, tree,
-			}, fs)
-			require.Equal(t, 0, runCLI(opts), "stderr: %s", testStderr(t, opts))
-
-			for _, base := range []string{tree, filepath.Join(root, "link", "tree")} {
-				opts = testOpts([]string{
-					testApp, cmdCheck, testFlagNoExtra, testFlagBase, base, manifestPath,
-				}, fs)
-				assert.Equal(t, 0, runCLI(opts),
-					"base %s, stderr: %s", base, testStderr(t, opts))
-				assert.NotContains(t, testStderr(t, opts), "not in manifest")
-			}
-		})
-	}
-}
-
-// unlistableDirFs is a filesystem on which one directory cannot be listed.
-type unlistableDirFs struct {
-	afero.Fs
-
-	dir string
-}
-
-//nolint:ireturn // Open must return afero.File to satisfy afero.Fs.
-func (f unlistableDirFs) Open(name string) (afero.File, error) {
-	if name == f.dir {
-		return nil, os.ErrPermission
-	}
-
-	return f.Fs.Open(name)
-}
-
-// TestCheckWithUnlistableDirectory has a directory under the base that
-// cannot be listed, followed by an unlisted file: both are warned about and
-// the check still passes, unless --no-extra-files is given.
-func TestCheckWithUnlistableDirectory(t *testing.T) {
-	t.Parallel()
-
-	mem := afero.NewMemMapFs()
-	require.NoError(t, mem.MkdirAll("/testdir/locked", 0o755))
-	writeTestFile(t, mem, testFile1, "hello")
-
-	opts := testOpts([]string{
-		testApp, cmdGenerate, "-q", "-o", testManifest, testDir,
-	}, mem)
-	require.Equal(t, 0, runCLI(opts), "stderr: %s", testStderr(t, opts))
-
-	// Directories are searched in name order, so this comes after "locked".
-	writeTestFile(t, mem, "/testdir/unlisted.txt", "unlisted")
-
-	fs := unlistableDirFs{Fs: mem, dir: "/testdir/locked"}
-
-	opts = testOpts([]string{testApp, cmdCheck, testFlagBase, testDir, testManifest}, fs)
-	assert.Equal(t, 0, runCLI(opts), "stderr: %s", testStderr(t, opts))
-	assert.Contains(t, testStderr(t, opts), os.ErrPermission.Error())
-	assert.Contains(t, testStderr(t, opts), "unlisted.txt")
 
+	// Check WITHOUT --no-extra-files (should pass - extra files ignored)
 	opts = testOpts([]string{
-		testApp, cmdCheck, testFlagNoExtra, testFlagBase, testDir, testManifest,
+		testApp, cmdCheck, "-q", testFlagBase, testDir, testManifest,
 	}, fs)
-	assert.Equal(t, 1, runCLI(opts), "stderr: %s", testStderr(t, opts))
+	exitCode = runCLI(opts)
-	assert.Contains(t, testStderr(t, opts), "unlisted.txt")
+	assert.Equal(t, 0, exitCode,
+		"check without --no-extra-files should ignore extra files")
 }
 
 func TestGenerateAtomicWriteNoTempFileOnSuccess(t *testing.T) {
@@ -1170,22 +1065,6 @@ func TestGenerateValidatesInputPaths(t *testing.T) {
 	})
 }
 
-// TestFlagAfterArgumentIsArgument asserts that flags are read only before a
-// command's first argument: after it, -v is a path, not the verbose flag.
-func TestFlagAfterArgumentIsArgument(t *testing.T) {
-	t.Parallel()
-
-	fs := afero.NewMemMapFs()
-	require.NoError(t, fs.MkdirAll(testDir, 0o755))
-	writeTestFile(t, fs, testFile1, "content")
-
-	opts := testOpts([]string{testApp, cmdGenerate, testDir, "-v"}, fs)
-	exitCode := runCLI(opts)
-
-	assert.Equal(t, 1, exitCode)
-	assert.Contains(t, testStderr(t, opts), "path does not exist: -v")
-}
-
 func TestCheckDetectsManifestCorruption(t *testing.T) {
 	t.Parallel()
 

internal/cli/errmsg_test.go

@@ -4,6 +4,7 @@ package cli
 import (
 	"bytes"
 	"context"
+	"flag"
 	"net/http"
 	"net/http/httptest"
 	"os"
@@ -14,7 +15,7 @@ import (
 	"github.com/spf13/afero"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
-	urfcli "github.com/urfave/cli/v3"
+	urfcli "github.com/urfave/cli/v2"
 	"sneak.berlin/go/mfer/mfer"
 )
 
@@ -194,17 +195,13 @@ func signedChecker(t *testing.T, manifest []byte) *mfer.Checker {
 func TestPathDoesNotExistMessage(t *testing.T) {
 	t.Parallel()
 
+	set := flag.NewFlagSet("gen", flag.ContinueOnError)
+	require.NoError(t, set.Parse([]string{"nope"}))
+
 	mfa := &CLIApp{Fs: afero.NewMemMapFs()}
-	cmd := &urfcli.Command{
+	ctx := urfcli.NewContext(nil, set, nil)
-		Name: cmdGenerate,
-		Action: func(_ context.Context, c *urfcli.Command) error {
-			_, err := mfa.collectInputPaths(c.Args())
 
-			return err
+	_, err := mfa.collectInputPaths(ctx.Args())
-		},
-	}
-
-	err := cmd.Run(context.Background(), []string{cmdGenerate, "nope"})
 	require.ErrorIs(t, err, errPathNotExist)
 	assert.EqualError(t, err, "path does not exist: nope")
 }
@@ -217,22 +214,18 @@ func TestOutputFileExistsMessage(t *testing.T) {
 	require.NoError(t, afero.WriteFile(fs, "/d/f.txt", []byte("hi"), 0o644))
 	require.NoError(t, afero.WriteFile(fs, "/out.mf", []byte("old"), 0o644))
 
+	set := flag.NewFlagSet("gen", flag.ContinueOnError)
+	set.String("output", "", "")
+	set.Bool("force", false, "")
+	require.NoError(t, set.Parse([]string{"/d"}))
+	require.NoError(t, set.Set("output", "/out.mf"))
+
 	mfa := &CLIApp{Fs: fs}
-	cmd := &urfcli.Command{
+	ctx := urfcli.NewContext(nil, set, nil)
-		Name: cmdGenerate,
-		Flags: []urfcli.Flag{
-			&urfcli.StringFlag{Name: "output"},
-			&urfcli.BoolFlag{Name: "force"},
-		},
-		Action: mfa.generateManifestOperation,
-	}
 
 	// generateManifestOperation writes to the process-global logger during
 	// enumeration, so serialize with the other CLI runs.
-	err := runLocked(func() error {
+	err := runLocked(func() error { return mfa.generateManifestOperation(ctx) })
-		return cmd.Run(context.Background(),
-			[]string{cmdGenerate, "--output", "/out.mf", "/d"})
-	})
 	require.ErrorIs(t, err, errOutputExists)
 	assert.EqualError(t, err,
 		"output file /out.mf already exists (use --force to overwrite)")
@@ -257,7 +250,7 @@ func TestUnknownCommandMessage(t *testing.T) {
 	err := runLocked(func() error {
 		mfa.run([]string{testApp})
 
-		return mfa.app.Run(context.Background(), []string{testApp, "bogus"})
+		return mfa.app.Run([]string{testApp, "bogus"})
 	})
 	require.ErrorIs(t, err, errUnknownCommand)
 	assert.EqualError(t, err, `unknown command "bogus"`)
@@ -274,7 +267,7 @@ func TestManifestLoaderHTTPStatusMessage(t *testing.T) {
 
 	mfa := &CLIApp{Fs: afero.NewMemMapFs()}
 
-	_, err := mfa.openManifestReader(context.Background(), server.URL+"/foo.mf")
+	_, err := mfa.openManifestReader(server.URL + "/foo.mf")
 	require.ErrorIs(t, err, errHTTPStatus)
 	assert.EqualError(t, err,
 		"failed to fetch "+server.URL+"/foo.mf: HTTP 404")
@@ -291,13 +284,17 @@ func TestFetchManifestHTTPStatusMessage(t *testing.T) {
 
 	mfa := &CLIApp{Fs: afero.NewMemMapFs()}
 
-	cmd := mfa.fetchCommand()
+	set := flag.NewFlagSet(cmdFetch, flag.ContinueOnError)
-	cmd.Action = mfa.fetchManifestOperation
+	for _, f := range mfa.fetchCommand().Flags {
+		require.NoError(t, f.Apply(set))
+	}
+
+	require.NoError(t, set.Parse([]string{server.URL}))
+
+	ctx := urfcli.NewContext(nil, set, nil)
 
 	// fetchManifestOperation logs to the process-global logger.
-	err := runLocked(func() error {
+	err := runLocked(func() error { return mfa.fetchManifestOperation(ctx) })
-		return cmd.Run(context.Background(), []string{cmdFetch, server.URL})
-	})
 	require.ErrorIs(t, err, errHTTPStatus)
 	assert.EqualError(t, err, "failed to fetch manifest: HTTP 404")
 }
@@ -323,13 +320,14 @@ func TestFetchFileHTTPStatusMessage(t *testing.T) {
 func TestURLRequiredMessage(t *testing.T) {
 	t.Parallel()
 
+	set := flag.NewFlagSet("fetch", flag.ContinueOnError)
+	require.NoError(t, set.Parse([]string{}))
+
 	mfa := &CLIApp{Fs: afero.NewMemMapFs()}
-	cmd := &urfcli.Command{Name: cmdFetch, Action: mfa.fetchManifestOperation}
+	ctx := urfcli.NewContext(nil, set, nil)
 
 	// fetchManifestOperation logs to the process-global logger.
-	err := runLocked(func() error {
+	err := runLocked(func() error { return mfa.fetchManifestOperation(ctx) })
-		return cmd.Run(context.Background(), []string{cmdFetch})
-	})
 	require.ErrorIs(t, err, errURLRequired)
 	assert.EqualError(t, err, "URL argument required")
 }

internal/cli/export.go

@@ -1,13 +1,12 @@
 package cli
 
 import (
-	"context"
 	"encoding/hex"
 	"encoding/json"
 	"fmt"
 	"time"
 
-	"github.com/urfave/cli/v3"
+	"github.com/urfave/cli/v2"
 	"sneak.berlin/go/mfer/mfer"
 )
 
@@ -20,22 +19,19 @@ type ExportEntry struct {
 	Ctime  *string  `json:"ctime,omitempty"`
 }
 
-func (mfa *CLIApp) exportManifestOperation(
+func (mfa *CLIApp) exportManifestOperation(ctx *cli.Context) error {
-	ctx context.Context, cmd *cli.Command,
+	pathOrURL, err := mfa.resolveManifestArg(ctx)
-) error {
-	pathOrURL, err := mfa.resolveManifestArg(cmd)
 	if err != nil {
 		return fmt.Errorf("export: %w", err)
 	}
 
-	rc, err := mfa.openManifestReader(ctx, pathOrURL)
+	rc, err := mfa.openManifestReader(pathOrURL)
 	if err != nil {
 		return fmt.Errorf("export: %w", err)
 	}
 
 	defer func() { _ = rc.Close() }()
 
-	//nolint:contextcheck // mfer loads a manifest without a context
 	manifest, err := mfer.NewManifestFromReader(rc)
 	if err != nil {
 		return fmt.Errorf("export: failed to parse manifest: %w", err)

internal/cli/fetch.go

@@ -20,7 +20,7 @@ import (
 	"github.com/dustin/go-humanize"
 	"github.com/multiformats/go-multihash"
 	"github.com/spf13/afero"
-	"github.com/urfave/cli/v3"
+	"github.com/urfave/cli/v2"
 	"sneak.berlin/go/mfer/internal/log"
 	"sneak.berlin/go/mfer/mfer"
 )
@@ -91,10 +91,6 @@ var (
 	// errHashMismatch indicates a downloaded file whose hash matches no
 	// manifest hash.
 	errHashMismatch = errors.New("hash mismatch")
-	// errNameClash indicates a manifest that lists a file where fetch
-	// writes another file.
-	errNameClash = errors.New(
-		"manifest lists a file where fetch writes another file")
 )
 
 // DownloadProgress reports the progress of a single file download.
@@ -328,21 +324,19 @@ func alreadyPresent(dest, localPath string, entry *mfer.MFFilePath) bool {
 	return verifyDownloadedHash(h.Sum(nil), entry) == nil
 }
 
-func (mfa *CLIApp) fetchManifestOperation(
+func (mfa *CLIApp) fetchManifestOperation(ctx *cli.Context) error {
-	ctx context.Context, cmd *cli.Command,
-) error {
 	log.Debug("fetchManifestOperation()")
 
-	if cmd.Args().Len() == 0 {
+	if ctx.Args().Len() == 0 {
 		return errURLRequired
 	}
 
-	timeout := cmd.Duration(flagTimeout)
+	timeout := ctx.Duration(flagTimeout)
 	if timeout <= 0 {
 		return errInvalidTimeout
 	}
 
-	manifestURL, err := resolveManifestURL(cmd.Args().Get(0))
+	manifestURL, err := resolveManifestURL(ctx.Args().Get(0))
 	if err != nil {
 		return fmt.Errorf("invalid URL: %w", err)
 	}
@@ -352,7 +346,7 @@ func (mfa *CLIApp) fetchManifestOperation(
 		firstDelay: firstRetryDelay,
 	}
 
-	manifestData, files, err := fetchManifest(ctx, cmd, client, manifestURL)
+	manifestData, files, err := fetchManifest(ctx, client, manifestURL)
 	if err != nil {
 		return err
 	}
@@ -363,7 +357,7 @@ func (mfa *CLIApp) fetchManifestOperation(
 		return err
 	}
 
-	dest := cmd.String(flagDest)
+	dest := ctx.String(flagDest)
 
 	err = os.MkdirAll(dest, dirPerms)
 	if err != nil {
@@ -381,7 +375,7 @@ func (mfa *CLIApp) fetchManifestOperation(
 
 	// Download each file
 	downloaded, downloadedBytes, dlErr := downloadManifestFiles(
-		ctx, client, baseURL, dest, files, progress)
+		ctx.Context, client, baseURL, dest, files, progress)
 
 	close(progress)
 	<-done
@@ -413,12 +407,11 @@ func (mfa *CLIApp) fetchManifestOperation(
 }
 
 // fetchManifest downloads the manifest at manifestURL and parses it,
-// enforcing --require-signature if it is given and refusing a manifest
+// enforcing --require-signature if it is given. It returns the manifest as
-// that lists a file where fetch writes another. It returns the manifest as
 // downloaded, to be saved once the files are in place, and the files it
 // lists.
 func fetchManifest(
-	ctx context.Context, cmd *cli.Command, client retryingClient, manifestURL string,
+	ctx *cli.Context, client retryingClient, manifestURL string,
 ) ([]byte, []*mfer.MFFilePath, error) {
 	log.Infof("fetching manifest from %s", manifestURL)
 
@@ -427,7 +420,7 @@ func fetchManifest(
 	// manifest.
 	var manifestData []byte
 
-	err := client.get(ctx, manifestURL, func(resp *http.Response) error {
+	err := client.get(ctx.Context, manifestURL, func(resp *http.Response) error {
 		var readErr error
 
 		manifestData, readErr = io.ReadAll(resp.Body)
@@ -439,13 +432,12 @@ func fetchManifest(
 	}
 
 	// Parse manifest
-	//nolint:contextcheck // mfer loads a manifest without a context
 	manifest, err := mfer.NewManifestFromReader(bytes.NewReader(manifestData))
 	if err != nil {
 		return nil, nil, fmt.Errorf("failed to parse manifest: %w", err)
 	}
 
-	requiredSigner := cmd.String(flagRequireSignature)
+	requiredSigner := ctx.String(flagRequireSignature)
 	if requiredSigner != "" {
 		err = verifyFetchedSigner(ctx, manifestData, requiredSigner)
 		if err != nil {
@@ -454,73 +446,17 @@ func fetchManifest(
 	}
 
 	files := manifest.Files()
-
-	err = checkNoNameClash(files)
-	if err != nil {
-		return nil, nil, err
-	}
-
 	log.Infof("manifest contains %d files", len(files))
 
 	return manifestData, files, nil
 }
 
-// checkNoNameClash returns an error if files lists a file, or a directory
-// a file is in, under a name where fetch writes another file: another
-// listed file, a directory another listed file is in, the temp file it
-// downloads a listed file to, or, at the top of the tree, the saved
-// manifest or its temp file. fetch would remove or replace what is
-// listed there, or fail partway, leaving a tree check rejects. Names are
-// compared ignoring case, on every filesystem, since on a
-// case-insensitive one A.txt and a.txt are one file.
-func checkNoNameClash(files []*mfer.MFFilePath) error {
-	sep := string(filepath.Separator)
-
-	// written maps each name fetch writes, in lower case, to the file or
-	// directory it writes there.
-	written := map[string]string{
-		defaultManifestName:              "the saved manifest",
-		tempPathFor(defaultManifestName): "the saved manifest's temp file",
-	}
-
-	for _, f := range files {
-		tmpPath := tempPathFor(filepath.Clean(f.GetPath()))
-		written[strings.ToLower(tmpPath)] = "the temp file for " + f.GetPath()
-	}
-
-	for _, f := range files {
-		// Look up and add each directory on the file's path, then the
-		// file itself. Only the same directory, spelled alike, may
-		// already be there.
-		parts := strings.Split(filepath.Clean(f.GetPath()), sep)
-		last := len(parts) - 1
-
-		for i := range parts {
-			name := strings.Join(parts[:i+1], sep)
-
-			what := "the directory " + name
-			if i == last {
-				what = "the file " + f.GetPath()
-			}
-
-			other, ok := written[strings.ToLower(name)]
-			if ok && (i == last || other != what) {
-				return fmt.Errorf("%w: %s (%s)", errNameClash, f.GetPath(), other)
-			}
-
-			written[strings.ToLower(name)] = what
-		}
-	}
-
-	return nil
-}
-
 // verifyFetchedSigner enforces --require-signature on the fetched manifest
 // exactly as check does. verifyRequiredSigner takes a Checker, which loads
 // its manifest from a file, so the manifest is handed to it as a file in
 // memory.
 func verifyFetchedSigner(
-	ctx context.Context, manifestData []byte, requiredSigner string,
+	ctx *cli.Context, manifestData []byte, requiredSigner string,
 ) error {
 	memFs := afero.NewMemMapFs()
 	manifestPath := "/" + defaultManifestName
@@ -530,7 +466,6 @@ func verifyFetchedSigner(
 		return err
 	}
 
-	//nolint:contextcheck // mfer loads a manifest without a context
 	chk, err := mfer.NewChecker(&mfer.CheckerOptions{
 		ManifestPath: manifestPath,
 		BasePath:     "/",
@@ -540,7 +475,7 @@ func verifyFetchedSigner(
 		return fmt.Errorf("failed to load manifest: %w", err)
 	}
 
-	return verifyRequiredSigner(ctx, chk, requiredSigner)
+	return verifyRequiredSigner(ctx.Context, chk, requiredSigner)
 }
 
 // saveManifest writes the fetched manifest into dest under the default

internal/cli/fetch_test.go

@@ -4,6 +4,7 @@ package cli
 import (
 	"bytes"
 	"context"
+	"flag"
 	"fmt"
 	"io"
 	"maps"
@@ -12,7 +13,6 @@ import (
 	"net/http/httptest"
 	"os"
 	"path/filepath"
-	"slices"
 	"strconv"
 	"sync"
 	"sync/atomic"
@@ -22,6 +22,7 @@ import (
 	"github.com/spf13/afero"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	urfcli "github.com/urfave/cli/v2"
 	"sneak.berlin/go/mfer/mfer"
 )
 
@@ -512,51 +513,24 @@ func TestFetchProgress(t *testing.T) {
 	assert.Equal(t, content, downloaded)
 }
 
-// TestFetchRefusesSymlinks runs fetch with --dest naming a directory other
+// TestFetchRefusesSymlinks runs fetch into a destination directory that
-// than the current one, which holds a symlink pointing outside it, in each
+// holds a symlink pointing outside it, in each of the three places fetch
-// place fetch writes: a parent directory, the temp file, the file itself,
+// writes: a parent directory, the temp file, and the file itself, which
-// which the temp file is renamed onto, and the saved manifest's temp file
+// the temp file is renamed onto; and once as a directory inside a plain
-// and final name; and once as a directory inside a plain directory. The
+// directory. The fetch must fail and nothing outside may change.
-// fetch must fail, and neither the outside directory nor the current one
-// may change.
 //
 //nolint:paralleltest // changes the process-global working directory
 func TestFetchRefusesSymlinks(t *testing.T) {
-	// What a link standing for a file points to: a file outside that does
-	// not exist yet.
-	const newFile = "new.txt"
-
 	tests := []struct {
-		name    string
+		name   string
-		entry   string // the manifest's only file
+		entry  string // the manifest's only file
-		link    string // symlink placed in the destination directory
+		link   string // symlink placed in the destination directory
-		target  string // what link points to, relative to the outside directory
+		target string // what link points to, relative to the outside directory
-		failure string // what fetch reports it was doing when it found link
 	}{
-		{
+		{"parent directory", "sub/deeper/file.txt", "sub", "."},
-			"parent directory", "sub/deeper/file.txt", "sub", ".",
+		{"directory inside a plain directory", "docs/data/passwd", "docs/data", "."},
-			"failed to download sub/deeper/file.txt",
+		{"temp file", testFileTxt, ".file.txt.tmp", "new.txt"},
-		},
+		{"file", testFileTxt, testFileTxt, "new.txt"},
-		{
-			"directory inside a plain directory", "docs/data/passwd", "docs/data", ".",
-			"failed to download docs/data/passwd",
-		},
-		{
-			"temp file", testFileTxt, ".file.txt.tmp", newFile,
-			"failed to download " + testFileTxt,
-		},
-		{
-			"file", testFileTxt, testFileTxt, newFile,
-			"failed to download " + testFileTxt,
-		},
-		{
-			"manifest temp file", testFileTxt, tempPathFor(defaultManifestName), newFile,
-			"failed to save manifest",
-		},
-		{
-			"manifest", testFileTxt, defaultManifestName, newFile,
-			"failed to save manifest",
-		},
 	}
 
 	for _, tt := range tests {
@@ -571,61 +545,23 @@ func TestFetchRefusesSymlinks(t *testing.T) {
 			defer server.Close()
 
 			outside := t.TempDir()
-			cwd := chdirTemp(t)
-			dest := t.TempDir()
-			link := filepath.Join(dest, tt.link)
 
-			require.NoError(t, os.MkdirAll(filepath.Dir(link), 0o750))
+			chdirTemp(t)
-			require.NoError(t, os.Symlink(filepath.Join(outside, tt.target), link))
+			require.NoError(t, os.MkdirAll(filepath.Dir(tt.link), 0o750))
+			require.NoError(t, os.Symlink(filepath.Join(outside, tt.target), tt.link))
 
-			opts := testOpts([]string{
+			opts := testOpts([]string{testApp, cmdFetch, "-q", server.URL}, afero.NewOsFs())
-				testApp, cmdFetch, "-q", "--" + flagDest, dest, server.URL,
-			}, afero.NewOsFs())
 			assert.Equal(t, 1, runCLI(opts))
-			assert.Contains(t, testStderr(t, opts),
+			assert.Contains(t, testStderr(t, opts), "failed to download "+tt.entry+
-				tt.failure+": symlink in path not allowed: "+link)
+				": symlink in path not allowed: "+tt.link)
 
 			written, err := os.ReadDir(outside)
 			require.NoError(t, err)
 			assert.Empty(t, written, "fetch wrote outside the destination")
-
-			written, err = os.ReadDir(cwd)
-			require.NoError(t, err)
-			assert.Empty(t, written, "fetch wrote to the current directory")
 		})
 	}
 }
 
-// TestFetchDoesNotSkipThroughSymlink runs fetch with --dest holding a
-// symlink to a directory outside it, where the file the manifest lists
-// through that symlink already sits with the listed content. fetch must
-// not take that file as already present: it must fail on the symlink, as
-// the download would, and leave the outside file alone.
-func TestFetchDoesNotSkipThroughSymlink(t *testing.T) {
-	t.Parallel()
-
-	content := []byte("fetched")
-	files := map[string][]byte{"sub/" + testFileTxt: content}
-
-	server := httptest.NewServer(fetchTestHandler(manifestOf(t, files), files))
-	defer server.Close()
-
-	outside := t.TempDir()
-	require.NoError(t, os.WriteFile(filepath.Join(outside, testFileTxt), content, 0o600))
-
-	dest := t.TempDir()
-	link := filepath.Join(dest, "sub")
-	require.NoError(t, os.Symlink(outside, link))
-
-	opts := testOpts([]string{
-		testApp, cmdFetch, "-q", "--" + flagDest, dest, server.URL,
-	}, afero.NewOsFs())
-	assert.Equal(t, 1, runCLI(opts))
-	assert.Contains(t, testStderr(t, opts),
-		"failed to download sub/"+testFileTxt+": symlink in path not allowed: "+link)
-	assert.Equal(t, map[string][]byte{testFileTxt: content}, filesUnder(t, outside))
-}
-
 // TestFetchReplacesHardLinkAtTempName runs fetch into a destination
 // directory that holds, at the temp file's name, a hard link to a file
 // outside it. To fetch that is an ordinary leftover from an interrupted
@@ -1125,9 +1061,8 @@ func TestFetchRequireSignature(t *testing.T) {
 	files := map[string][]byte{testFileTxt: []byte("signed file")}
 
 	t.Run("unsigned", func(t *testing.T) {
-		assertFetchRefused(t, manifestOf(t, files), files,
+		assertFetchRefused(t, manifestOf(t, files), files, msgFpA,
-			"manifest is not signed, but signature from "+msgFpA+" is required",
+			"manifest is not signed, but signature from "+msgFpA+" is required")
-			"--"+flagRequireSignature, msgFpA)
 	})
 
 	t.Run("signed", func(t *testing.T) {
@@ -1137,9 +1072,8 @@ func TestFetchRequireSignature(t *testing.T) {
 			ExtractEmbeddedSigningKeyFP(context.Background())
 		require.NoError(t, err)
 
-		assertFetchRefused(t, manifest, files,
+		assertFetchRefused(t, manifest, files, msgFpB,
-			"embedded signing key fingerprint "+signer+" does not match required "+msgFpB,
+			"embedded signing key fingerprint "+signer+" does not match required "+msgFpB)
-			"--"+flagRequireSignature, msgFpB)
 
 		server := httptest.NewServer(fetchTestHandler(manifest, files))
 		defer server.Close()
@@ -1155,178 +1089,12 @@ func TestFetchRequireSignature(t *testing.T) {
 	})
 }
 
-// TestFetchRefusesListedManifestName fetches manifests that list, at the
-// top of the tree, the name fetch saves the manifest under or that name's
-// temp file: as a file, as a directory, in capitals, and with a leading
-// "./". Saving the manifest would replace or remove what is listed there,
-// so fetch must refuse the manifest before it creates the destination or
-// requests any file.
-func TestFetchRefusesListedManifestName(t *testing.T) {
-	t.Parallel()
-
-	for _, listed := range []string{
-		defaultManifestName,
-		tempPathFor(defaultManifestName),
-		defaultManifestName + "/" + testFileTxt,
-		"INDEX.MF",
-		"./" + defaultManifestName,
-	} {
-		t.Run(listed, func(t *testing.T) {
-			t.Parallel()
-
-			files := map[string][]byte{listed: []byte("listed")}
-
-			assertFetchRefused(t, builtManifest(t, files), files,
-				"manifest lists a file where fetch writes another file: "+listed)
-		})
-	}
-}
-
-// TestFetchRefusesListedTempName fetches manifests that list a.txt and
-// .a.txt.tmp, the temp file fetch downloads a.txt to, at the top of the
-// tree and in a directory. Downloading a.txt would remove .a.txt.tmp, so
-// fetch must refuse the manifest before it creates the destination or
-// requests any file. README with .README.tmp checks that temp names are
-// compared ignoring case. A manifest that lists only one of the two is
-// fetched in full.
-func TestFetchRefusesListedTempName(t *testing.T) {
-	t.Parallel()
-
-	for _, dir := range []string{"", "sub/"} {
-		for file, tmp := range map[string]string{
-			dir + "a.txt":  dir + ".a.txt.tmp",
-			dir + "README": dir + ".README.tmp",
-		} {
-			both := map[string][]byte{
-				file: []byte("a file"),
-				tmp:  []byte("a file at its temp name"),
-			}
-
-			t.Run(file+" and "+tmp, func(t *testing.T) {
-				t.Parallel()
-
-				assertFetchRefused(t, builtManifest(t, both), both,
-					"manifest lists a file where fetch writes another file: "+
-						tmp+" (the temp file for "+file+")")
-			})
-
-			for listed, content := range both {
-				t.Run("only "+listed, func(t *testing.T) {
-					t.Parallel()
-
-					files := map[string][]byte{listed: content}
-					manifest := builtManifest(t, files)
-
-					server := httptest.NewServer(fetchTestHandler(manifest, files))
-					defer server.Close()
-
-					dest := t.TempDir()
-
-					opts := testOpts([]string{
-						testApp, cmdFetch, "-q", "--" + flagDest, dest, server.URL,
-					}, afero.NewOsFs())
-					require.Equal(t, 0, runCLI(opts), testStderr(t, opts))
-
-					want := maps.Clone(files)
-					want[defaultManifestName] = manifest
-					assert.Equal(t, want, filesUnder(t, dest))
-				})
-			}
-		}
-	}
-}
-
-// TestFetchRefusesNamesEqualIgnoringCase fetches manifests that list two
-// paths that are one name on a case-insensitive filesystem. Fetched
-// there, of two such files, at the top of the tree or in a directory,
-// one replaces the other and fetch exits 0. A file and a directory
-// another file is in stop fetch partway with a non-zero exit, leaving a
-// partial tree. Two spellings of one directory put both files in one
-// directory, one of them under a spelling the manifest does not list,
-// and check reports that file as not in the manifest. So fetch must
-// refuse each on every filesystem before it creates the destination or
-// requests any file. A file and a directory with the same name, and a
-// file listed twice, are refused the same way. A manifest whose names
-// differ in more than letter case is fetched in full.
-func TestFetchRefusesNamesEqualIgnoringCase(t *testing.T) {
-	t.Parallel()
-
-	for _, tc := range []struct{ first, second, message string }{
-		{"X.txt", "x.txt", "x.txt (the file X.txt)"},
-		{"sub/X.txt", "sub/x.txt", "sub/x.txt (the file sub/X.txt)"},
-		{"Dir", "dir/x", "dir/x (the file Dir)"},
-		{"Dir/a.txt", "dir/b.txt", "dir/b.txt (the directory Dir)"},
-		{"dir", "dir/x", "dir/x (the file dir)"},
-		{"./x.txt", "x.txt", "x.txt (the file ./x.txt)"},
-	} {
-		t.Run(tc.first+" and "+tc.second, func(t *testing.T) {
-			t.Parallel()
-
-			files := map[string][]byte{
-				tc.first:  []byte("the first file"),
-				tc.second: []byte("the second file"),
-			}
-
-			assertFetchRefused(t, builtManifest(t, files), files,
-				"manifest lists a file where fetch writes another file: "+tc.message)
-		})
-	}
-
-	t.Run("names that differ in more than letter case", func(t *testing.T) {
-		t.Parallel()
-
-		files := map[string][]byte{
-			"A.txt":     []byte("at the top"),
-			"B.txt":     []byte("also at the top"),
-			"dir/a.txt": []byte("in a directory"),
-			"dir/b.txt": []byte("in the same directory"),
-		}
-		manifest := builtManifest(t, files)
-
-		server := httptest.NewServer(fetchTestHandler(manifest, files))
-		defer server.Close()
-
-		dest := t.TempDir()
-
-		opts := testOpts([]string{
-			testApp, cmdFetch, "-q", "--" + flagDest, dest, server.URL,
-		}, afero.NewOsFs())
-		require.Equal(t, 0, runCLI(opts), testStderr(t, opts))
-
-		want := maps.Clone(files)
-		want[defaultManifestName] = manifest
-		assert.Equal(t, want, filesUnder(t, dest))
-	})
-}
-
-// builtManifest returns a manifest of files, built directly rather than
-// scanned, since a scan lists no hidden files and never a path starting
-// with "./".
-func builtManifest(t *testing.T, files map[string][]byte) []byte {
-	t.Helper()
-
-	builder := mfer.NewBuilder()
-
-	for p, content := range files {
-		_, err := builder.AddFile(mfer.RelFilePath(p), mfer.FileSize(len(content)),
-			mfer.ModTime(time.Now()), bytes.NewReader(content), nil)
-		require.NoError(t, err)
-	}
-
-	var manifest bytes.Buffer
-
-	require.NoError(t, builder.Build(context.Background(), &manifest))
-
-	return manifest.Bytes()
-}
-
 // assertFetchRefused serves manifest, a manifest of files, and fetches it
-// with flags into a directory that does not exist yet. fetch must fail
+// with --require-signature signer into a directory that does not exist
-// with message after requesting only the manifest, and must not create
+// yet. fetch must fail with message after requesting only the manifest,
-// the directory.
+// and must not create the directory.
 func assertFetchRefused(
-	t *testing.T, manifest []byte, files map[string][]byte,
+	t *testing.T, manifest []byte, files map[string][]byte, signer, message string,
-	message string, flags ...string,
 ) {
 	t.Helper()
 
@@ -1351,12 +1119,13 @@ func assertFetchRefused(
 
 	dest := filepath.Join(t.TempDir(), "mirror")
 
-	opts := testOpts(slices.Concat(
+	opts := testOpts([]string{
-		[]string{testApp, cmdFetch, "-q", "--" + flagDest, dest}, flags, []string{server.URL},
+		testApp, cmdFetch, "-q", "--" + flagDest, dest,
-	), afero.NewOsFs())
+		"--" + flagRequireSignature, signer, server.URL,
+	}, afero.NewOsFs())
 	assert.Equal(t, 1, runCLI(opts))
 	assert.Contains(t, testStderr(t, opts), message)
-	assert.NoDirExists(t, dest, "fetch created the destination before refusing")
+	assert.NoDirExists(t, dest, "fetch wrote before checking the signer")
 
 	mu.Lock()
 	defer mu.Unlock()
@@ -1383,13 +1152,18 @@ func TestFetchTimeoutFlag(t *testing.T) {
 
 	mfa := &CLIApp{Fs: afero.NewMemMapFs()}
 
-	cmd := mfa.fetchCommand()
+	set := flag.NewFlagSet(cmdFetch, flag.ContinueOnError)
-	cmd.Action = mfa.fetchManifestOperation
+	for _, f := range mfa.fetchCommand().Flags {
+		require.NoError(t, f.Apply(set))
+	}
+
+	require.NoError(t, set.Parse([]string{"--" + flagTimeout, "100ms", server.URL}))
+
+	cliCtx := urfcli.NewContext(nil, set, nil)
+	cliCtx.Context = ctx
 
 	// fetchManifestOperation logs to the process-global logger.
-	err := runLocked(func() error {
+	err := runLocked(func() error { return mfa.fetchManifestOperation(cliCtx) })
-		return cmd.Run(ctx, []string{cmdFetch, "--" + flagTimeout, "100ms", server.URL})
-	})
 	require.Error(t, err)
 }
 

internal/cli/freshen.go

@@ -14,7 +14,7 @@ import (
 	"github.com/dustin/go-humanize"
 	"github.com/multiformats/go-multihash"
 	"github.com/spf13/afero"
-	"github.com/urfave/cli/v3"
+	"github.com/urfave/cli/v2"
 	"sneak.berlin/go/mfer/internal/log"
 	"sneak.berlin/go/mfer/mfer"
 )
@@ -202,12 +202,12 @@ func (s *freshenScanner) walk(path string, info fs.FileInfo, walkErr error) erro
 
 // resolveFreshenManifestPath determines the manifest path from the CLI
 // arguments, searching directories for a manifest where needed.
-func (mfa *CLIApp) resolveFreshenManifestPath(cmd *cli.Command) (string, error) {
+func (mfa *CLIApp) resolveFreshenManifestPath(ctx *cli.Context) (string, error) {
-	if cmd.Args().Len() == 0 {
+	if ctx.Args().Len() == 0 {
 		return findManifest(mfa.Fs, ".")
 	}
 
-	arg := cmd.Args().Get(0)
+	arg := ctx.Args().Get(0)
 
 	info, statErr := mfa.Fs.Stat(arg)
 	if statErr == nil && info.IsDir() {
@@ -338,14 +338,14 @@ func writeFreshenedManifest(
 
 // newFreshenBuilder constructs the manifest builder configured from CLI
 // flags.
-func newFreshenBuilder(cmd *cli.Command) *mfer.Builder {
+func newFreshenBuilder(ctx *cli.Context) *mfer.Builder {
 	builder := mfer.NewBuilder()
-	if cmd.Bool("include-timestamps") {
+	if ctx.Bool("include-timestamps") {
 		builder.SetIncludeTimestamps(true)
 	}
 
 	// Set up signing options if sign-key is provided
-	if signKey := cmd.String("sign-key"); signKey != "" {
+	if signKey := ctx.String("sign-key"); signKey != "" {
 		builder.SetSigningOptions(&mfer.SigningOptions{
 			KeyID: mfer.GPGKeyID(signKey),
 		})
@@ -358,13 +358,13 @@ func newFreshenBuilder(cmd *cli.Command) *mfer.Builder {
 // freshenScan runs the scan phase against the loaded manifest entries
 // and returns the populated scanner and the count of removed files.
 func (mfa *CLIApp) freshenScan(
-	cmd *cli.Command, manifestPath, absBase string,
+	ctx *cli.Context, manifestPath, absBase string,
 	existingByPath map[string]*mfer.MFFilePath,
 ) (*freshenScanner, int64, error) {
 	log.Infof("scanning filesystem...")
 
 	startScan := time.Now()
-	showProgress := cmd.Bool("progress")
+	showProgress := ctx.Bool("progress")
 
 	// Leave out the manifest and a temp file left by an interrupted run,
 	// as gen does. A path that cannot be stat'd, normally because no file
@@ -382,8 +382,8 @@ func (mfa *CLIApp) freshenScan(
 		fs:              mfa.Fs,
 		absBase:         absBase,
 		excluded:        excluded,
-		includeDotfiles: cmd.Bool("include-dotfiles"),
+		includeDotfiles: ctx.Bool("include-dotfiles"),
-		followSymlinks:  cmd.Bool("follow-symlinks"),
+		followSymlinks:  ctx.Bool("follow-symlinks"),
 		showProgress:    showProgress,
 		existingByPath:  existingByPath,
 	}
@@ -433,7 +433,7 @@ func hashTotals(entries []*freshenEntry) (int64, int64) {
 // runFreshenHash processes every entry through the hasher, aborting if
 // the context is canceled.
 func runFreshenHash(
-	ctx context.Context, hasher *freshenHasher, entries []*freshenEntry,
+	ctx *cli.Context, hasher *freshenHasher, entries []*freshenEntry,
 ) error {
 	for _, e := range entries {
 		select {
@@ -479,21 +479,18 @@ func (mfa *CLIApp) loadExistingEntries(
 	return existingByPath, nil
 }
 
-func (mfa *CLIApp) freshenManifestOperation(
+func (mfa *CLIApp) freshenManifestOperation(ctx *cli.Context) error {
-	ctx context.Context, cmd *cli.Command,
-) error {
 	log.Debug("freshenManifestOperation()")
 
-	basePath := cmd.String("base")
+	basePath := ctx.String("base")
-	showProgress := cmd.Bool("progress")
+	showProgress := ctx.Bool("progress")
 
 	// Find manifest file
-	manifestPath, err := mfa.resolveFreshenManifestPath(cmd)
+	manifestPath, err := mfa.resolveFreshenManifestPath(ctx)
 	if err != nil {
 		return fmt.Errorf("freshen: %w", err)
 	}
 
-	//nolint:contextcheck // mfer loads a manifest without a context
 	existingByPath, err := mfa.loadExistingEntries(manifestPath)
 	if err != nil {
 		return err
@@ -505,7 +502,7 @@ func (mfa *CLIApp) freshenManifestOperation(
 	}
 
 	// Phase 1: Scan filesystem
-	scanner, removed, err := mfa.freshenScan(cmd, manifestPath, absBase,
+	scanner, removed, err := mfa.freshenScan(ctx, manifestPath, absBase,
 		existingByPath)
 	if err != nil {
 		return err
@@ -527,7 +524,7 @@ func (mfa *CLIApp) freshenManifestOperation(
 		totalHashBytes: totalHashBytes,
 		filesToHash:    filesToHash,
 		startHash:      time.Now(),
-		builder:        newFreshenBuilder(cmd),
+		builder:        newFreshenBuilder(ctx),
 	}
 
 	err = runFreshenHash(ctx, hasher, scanner.entries)
@@ -551,7 +548,7 @@ func (mfa *CLIApp) freshenManifestOperation(
 	}
 
 	// Write updated manifest atomically (write to temp, then rename)
-	err = writeFreshenedManifest(ctx, mfa.Fs, hasher.builder, manifestPath)
+	err = writeFreshenedManifest(ctx.Context, mfa.Fs, hasher.builder, manifestPath)
 	if err != nil {
 		return err
 	}

internal/cli/gen.go

@@ -1,7 +1,6 @@
 package cli
 
 import (
-	"context"
 	"errors"
 	"fmt"
 	"os"
@@ -13,7 +12,7 @@ import (
 
 	"github.com/dustin/go-humanize"
 	"github.com/spf13/afero"
-	"github.com/urfave/cli/v3"
+	"github.com/urfave/cli/v2"
 	"sneak.berlin/go/mfer/internal/log"
 	"sneak.berlin/go/mfer/mfer"
 )
@@ -89,12 +88,12 @@ func (mfa *CLIApp) collectInputPaths(args cli.Args) ([]string, error) {
 }
 
 // buildScannerOptions constructs scanner options from the CLI flags.
-func (mfa *CLIApp) buildScannerOptions(cmd *cli.Command) *mfer.ScannerOptions {
+func (mfa *CLIApp) buildScannerOptions(ctx *cli.Context) *mfer.ScannerOptions {
-	output := cmd.String("output")
+	output := ctx.String("output")
 	opts := &mfer.ScannerOptions{
-		IncludeDotfiles:   cmd.Bool("include-dotfiles"),
+		IncludeDotfiles:   ctx.Bool("include-dotfiles"),
-		FollowSymLinks:    cmd.Bool("follow-symlinks"),
+		FollowSymLinks:    ctx.Bool("follow-symlinks"),
-		IncludeTimestamps: cmd.Bool("include-timestamps"),
+		IncludeTimestamps: ctx.Bool("include-timestamps"),
 		Fs:                mfa.Fs,
 		// Neither a manifest being replaced nor a temp file left by an
 		// interrupted run belongs in the new manifest.
@@ -102,14 +101,14 @@ func (mfa *CLIApp) buildScannerOptions(cmd *cli.Command) *mfer.ScannerOptions {
 	}
 
 	// Set seed for deterministic UUID if provided
-	if seed := cmd.String("seed"); seed != "" {
+	if seed := ctx.String("seed"); seed != "" {
 		opts.Seed = seed
 
 		log.Infof("using deterministic seed for manifest UUID")
 	}
 
 	// Set up signing options if sign-key is provided
-	if signKey := cmd.String("sign-key"); signKey != "" {
+	if signKey := ctx.String("sign-key"); signKey != "" {
 		opts.SigningOptions = &mfer.SigningOptions{
 			KeyID: mfer.GPGKeyID(signKey),
 		}
@@ -174,14 +173,14 @@ func (mfa *CLIApp) cleanupOnSignal(outFile afero.File, tmpPath string) chan os.S
 
 // runEnumeratePhase enumerates all input paths with optional progress
 // reporting and logs the totals.
-func (mfa *CLIApp) runEnumeratePhase(cmd *cli.Command, s *mfer.Scanner) error {
+func (mfa *CLIApp) runEnumeratePhase(ctx *cli.Context, s *mfer.Scanner) error {
 	// Set up enumeration progress reporting
 	var (
 		enumProgress chan mfer.EnumerateStatus
 		enumWg       sync.WaitGroup
 	)
 
-	if cmd.Bool("progress") {
+	if ctx.Bool("progress") {
 		enumProgress = make(chan mfer.EnumerateStatus, 1)
 
 		enumWg.Add(1)
@@ -189,7 +188,7 @@ func (mfa *CLIApp) runEnumeratePhase(cmd *cli.Command, s *mfer.Scanner) error {
 		go reportEnumProgress(enumProgress, &enumWg)
 	}
 
-	err := mfa.enumerateInputs(s, cmd.Args(), enumProgress)
+	err := mfa.enumerateInputs(s, ctx.Args(), enumProgress)
 	if err != nil {
 		return err
 	}
@@ -202,24 +201,22 @@ func (mfa *CLIApp) runEnumeratePhase(cmd *cli.Command, s *mfer.Scanner) error {
 	return nil
 }
 
-func (mfa *CLIApp) generateManifestOperation(
+func (mfa *CLIApp) generateManifestOperation(ctx *cli.Context) error {
-	ctx context.Context, cmd *cli.Command,
-) error {
 	log.Debug("generateManifestOperation()")
 
-	s := mfer.NewScannerWithOptions(mfa.buildScannerOptions(cmd))
+	s := mfer.NewScannerWithOptions(mfa.buildScannerOptions(ctx))
 
 	// Phase 1: Enumeration - collect paths and stat files
-	err := mfa.runEnumeratePhase(cmd, s)
+	err := mfa.runEnumeratePhase(ctx, s)
 	if err != nil {
 		return err
 	}
 
-	showProgress := cmd.Bool("progress")
+	showProgress := ctx.Bool("progress")
 
 	// Check if output file exists
-	outputPath := cmd.String("output")
+	outputPath := ctx.String("output")
-	if exists, _ := afero.Exists(mfa.Fs, outputPath); exists && !cmd.Bool("force") {
+	if exists, _ := afero.Exists(mfa.Fs, outputPath); exists && !ctx.Bool("force") {
 		return fmt.Errorf("output file %s %w", outputPath, errOutputExists)
 	}
 
@@ -262,7 +259,7 @@ func (mfa *CLIApp) generateManifestOperation(
 		go reportScanProgress(scanProgress, &scanWg)
 	}
 
-	err = s.ToManifest(ctx, outFile, scanProgress)
+	err = s.ToManifest(ctx.Context, outFile, scanProgress)
 
 	scanWg.Wait()
 

internal/cli/list.go

@@ -1,35 +1,33 @@
 package cli
 
 import (
-	"context"
 	"fmt"
 	"time"
 
-	"github.com/urfave/cli/v3"
+	"github.com/urfave/cli/v2"
 	"sneak.berlin/go/mfer/internal/log"
 	"sneak.berlin/go/mfer/mfer"
 )
 
-func (mfa *CLIApp) listManifestOperation(ctx context.Context, cmd *cli.Command) error {
+func (mfa *CLIApp) listManifestOperation(ctx *cli.Context) error {
 	// Default to ErrorLevel for clean output
 	log.SetLevel(log.ErrorLevel)
 
-	longFormat := cmd.Bool("long")
+	longFormat := ctx.Bool("long")
-	print0 := cmd.Bool("print0")
+	print0 := ctx.Bool("print0")
 
-	pathOrURL, err := mfa.resolveManifestArg(cmd)
+	pathOrURL, err := mfa.resolveManifestArg(ctx)
 	if err != nil {
 		return fmt.Errorf("list: %w", err)
 	}
 
-	rc, err := mfa.openManifestReader(ctx, pathOrURL)
+	rc, err := mfa.openManifestReader(pathOrURL)
 	if err != nil {
 		return fmt.Errorf("list: %w", err)
 	}
 
 	defer func() { _ = rc.Close() }()
 
-	//nolint:contextcheck // mfer loads a manifest without a context
 	manifest, err := mfer.NewManifestFromReader(rc)
 	if err != nil {
 		return fmt.Errorf("list: failed to parse manifest: %w", err)

internal/cli/manifest_loader.go

@@ -9,7 +9,7 @@ import (
 	"strings"
 	"time"
 
-	"github.com/urfave/cli/v3"
+	"github.com/urfave/cli/v2"
 )
 
 // manifestFetchTimeout bounds HTTP requests made to fetch a manifest.
@@ -30,13 +30,13 @@ func isHTTPURL(s string) bool {
 
 // openManifestReader opens a manifest from a path or URL and returns a ReadCloser.
 // The caller must close the returned reader.
-func (mfa *CLIApp) openManifestReader(
+func (mfa *CLIApp) openManifestReader(pathOrURL string) (io.ReadCloser, error) {
-	ctx context.Context, pathOrURL string,
-) (io.ReadCloser, error) {
 	if isHTTPURL(pathOrURL) {
 		client := &http.Client{Timeout: manifestFetchTimeout}
 
-		req, err := http.NewRequestWithContext(ctx, http.MethodGet, pathOrURL, nil)
+		req, err := http.NewRequestWithContext(
+			context.Background(), http.MethodGet, pathOrURL, nil,
+		)
 		if err != nil {
 			return nil, fmt.Errorf("failed to fetch %s: %w", pathOrURL, err)
 		}
@@ -67,9 +67,9 @@ func (mfa *CLIApp) openManifestReader(
 // resolveManifestArg resolves the manifest path from CLI arguments.
 // HTTP(S) URLs are returned as-is. Directories are searched for index.mf.
 // If no argument is given, the current directory is searched.
-func (mfa *CLIApp) resolveManifestArg(cmd *cli.Command) (string, error) {
+func (mfa *CLIApp) resolveManifestArg(ctx *cli.Context) (string, error) {
-	if cmd.Args().Len() > 0 {
+	if ctx.Args().Len() > 0 {
-		arg := cmd.Args().Get(0)
+		arg := ctx.Args().Get(0)
 		if isHTTPURL(arg) {
 			return arg, nil
 		}

internal/cli/mfer.go

@@ -1,7 +1,6 @@
 package cli
 
 import (
-	"context"
 	"errors"
 	"fmt"
 	"io"
@@ -9,7 +8,7 @@ import (
 	"time"
 
 	"github.com/spf13/afero"
-	"github.com/urfave/cli/v3"
+	"github.com/urfave/cli/v2"
 	"sneak.berlin/go/mfer/internal/log"
 	"sneak.berlin/go/mfer/mfer"
 )
@@ -55,7 +54,7 @@ type CLIApp struct {
 	gitrev      string
 	startupTime time.Time
 	exitCode    int
-	app         *cli.Command
+	app         *cli.App
 
 	Stdin  io.Reader // Standard input stream
 	Stdout io.Writer // Standard output stream for normal output
@@ -106,15 +105,15 @@ func (mfa *CLIApp) printBanner() {
 // urfave/cli reads a flag from the nearest command that defines it, so each
 // command in the lineage is asked. The highest -v count wins rather than the
 // sum, because a subcommand without its own copies reads the root's.
-func (mfa *CLIApp) setVerbosity(cmd *cli.Command) {
+func (mfa *CLIApp) setVerbosity(c *cli.Context) {
 	_, present := os.LookupEnv("MFER_DEBUG")
 
 	verbosity := 0
 	quiet := false
 
-	for _, c := range cmd.Lineage() {
+	for _, ctx := range c.Lineage() {
-		verbosity = max(verbosity, c.Count("verbose"))
+		verbosity = max(verbosity, ctx.Count("verbose"))
-		quiet = quiet || c.Bool("quiet")
+		quiet = quiet || ctx.Bool("quiet")
 	}
 
 	switch {
@@ -128,34 +127,23 @@ func (mfa *CLIApp) setVerbosity(cmd *cli.Command) {
 }
 
 // commonFlags returns the -v and -q flags taken by the root and by the
-// generate, check, freshen and fetch subcommands. They are local, so the
+// generate, check, freshen and fetch subcommands.
-// root's copies are not inherited by the subcommands that do not take them.
 func commonFlags() []cli.Flag {
 	return []cli.Flag{
 		&cli.BoolFlag{
 			Name:    "verbose",
 			Aliases: []string{"v"},
 			Usage:   "Increase verbosity (-v for verbose, -v -v for debug)",
-			Local:   true,
+			Count:   new(int),
 		},
 		&cli.BoolFlag{
 			Name:    "quiet",
 			Aliases: []string{"q"},
 			Usage:   "Suppress output except errors",
-			Local:   true,
 		},
 	}
 }
 
-// stopOnFirstArg returns the StopOnNthArg setting every command uses: flags
-// are read only before the command's first argument, and everything after it
-// is an argument, as with urfave/cli v2. So `mfer gen d -v` names a path "-v".
-func stopOnFirstArg() *int {
-	n := 1
-
-	return &n
-}
-
 // requireSignatureFlag returns the --require-signature flag taken by the
 // check and fetch subcommands.
 func requireSignatureFlag() *cli.StringFlag {
@@ -163,22 +151,21 @@ func requireSignatureFlag() *cli.StringFlag {
 		Name:    flagRequireSignature,
 		Aliases: []string{"S"},
 		Usage:   "Require manifest to be signed by the specified GPG key ID",
-		Sources: cli.EnvVars("MFER_REQUIRE_SIGNATURE"),
+		EnvVars: []string{"MFER_REQUIRE_SIGNATURE"},
 	}
 }
 
 func (mfa *CLIApp) generateCommand() *cli.Command {
 	return &cli.Command{
-		Name:         cmdGenerate,
+		Name:      cmdGenerate,
-		Aliases:      []string{"gen"},
+		Aliases:   []string{"gen"},
-		Usage:        "Generate manifest file",
+		Usage:     "Generate manifest file",
-		ArgsUsage:    "[path ...]",
+		ArgsUsage: "[path ...]",
-		StopOnNthArg: stopOnFirstArg(),
+		Action: func(c *cli.Context) error {
-		Action: func(ctx context.Context, cmd *cli.Command) error {
+			mfa.setVerbosity(c)
-			mfa.setVerbosity(cmd)
 			mfa.printBanner()
 
-			return mfa.generateManifestOperation(ctx, cmd)
+			return mfa.generateManifestOperation(c)
 		},
 		Flags: append(commonFlags(),
 			&cli.BoolFlag{
@@ -212,12 +199,12 @@ func (mfa *CLIApp) generateCommand() *cli.Command {
 				Name:    "sign-key",
 				Aliases: []string{"s"},
 				Usage:   "GPG key ID to sign the manifest with",
-				Sources: cli.EnvVars("MFER_SIGN_KEY"),
+				EnvVars: []string{"MFER_SIGN_KEY"},
 			},
 			&cli.StringFlag{
 				Name:    "seed",
 				Usage:   "Seed value for deterministic manifest UUID",
-				Sources: cli.EnvVars("MFER_SEED"),
+				EnvVars: []string{"MFER_SEED"},
 			},
 			&cli.BoolFlag{
 				Name: "include-timestamps",
@@ -230,15 +217,14 @@ func (mfa *CLIApp) generateCommand() *cli.Command {
 
 func (mfa *CLIApp) checkCommand() *cli.Command {
 	return &cli.Command{
-		Name:         cmdCheck,
+		Name:      cmdCheck,
-		Usage:        "Validate files using manifest file",
+		Usage:     "Validate files using manifest file",
-		ArgsUsage:    manifestArgsUsage,
+		ArgsUsage: manifestArgsUsage,
-		StopOnNthArg: stopOnFirstArg(),
+		Action: func(c *cli.Context) error {
-		Action: func(ctx context.Context, cmd *cli.Command) error {
+			mfa.setVerbosity(c)
-			mfa.setVerbosity(cmd)
 			mfa.printBanner()
 
-			return mfa.checkManifestOperation(ctx, cmd)
+			return mfa.checkManifestOperation(c)
 		},
 		Flags: append(commonFlags(),
 			&cli.StringFlag{
@@ -254,7 +240,7 @@ func (mfa *CLIApp) checkCommand() *cli.Command {
 			},
 			&cli.BoolFlag{
 				Name:  "no-extra-files",
-				Usage: "Fail, instead of warning, if files in base directory are not in manifest",
+				Usage: "Fail if files exist in base directory that are not in manifest",
 			},
 			requireSignatureFlag(),
 		),
@@ -263,15 +249,14 @@ func (mfa *CLIApp) checkCommand() *cli.Command {
 
 func (mfa *CLIApp) freshenCommand() *cli.Command {
 	return &cli.Command{
-		Name:         cmdFreshen,
+		Name:      cmdFreshen,
-		Usage:        "Update manifest with changed, new, and removed files",
+		Usage:     "Update manifest with changed, new, and removed files",
-		ArgsUsage:    manifestArgsUsage,
+		ArgsUsage: manifestArgsUsage,
-		StopOnNthArg: stopOnFirstArg(),
+		Action: func(c *cli.Context) error {
-		Action: func(ctx context.Context, cmd *cli.Command) error {
+			mfa.setVerbosity(c)
-			mfa.setVerbosity(cmd)
 			mfa.printBanner()
 
-			return mfa.freshenManifestOperation(ctx, cmd)
+			return mfa.freshenManifestOperation(c)
 		},
 		Flags: append(commonFlags(),
 			&cli.StringFlag{
@@ -300,7 +285,7 @@ func (mfa *CLIApp) freshenCommand() *cli.Command {
 				Name:    "sign-key",
 				Aliases: []string{"s"},
 				Usage:   "GPG key ID to sign the manifest with",
-				Sources: cli.EnvVars("MFER_SIGN_KEY"),
+				EnvVars: []string{"MFER_SIGN_KEY"},
 			},
 			&cli.BoolFlag{
 				Name: "include-timestamps",
@@ -313,24 +298,22 @@ func (mfa *CLIApp) freshenCommand() *cli.Command {
 
 func (mfa *CLIApp) exportCommand() *cli.Command {
 	return &cli.Command{
-		Name:         cmdExport,
+		Name:      cmdExport,
-		Usage:        "Export manifest contents as JSON",
+		Usage:     "Export manifest contents as JSON",
-		ArgsUsage:    "[manifest file or URL]",
+		ArgsUsage: "[manifest file or URL]",
-		StopOnNthArg: stopOnFirstArg(),
+		Action: func(c *cli.Context) error {
-		Action: func(ctx context.Context, cmd *cli.Command) error {
+			mfa.setVerbosity(c)
-			mfa.setVerbosity(cmd)
 
-			return mfa.exportManifestOperation(ctx, cmd)
+			return mfa.exportManifestOperation(c)
 		},
 	}
 }
 
 func (mfa *CLIApp) versionCommand() *cli.Command {
 	return &cli.Command{
-		Name:         cmdVersion,
+		Name:  cmdVersion,
-		Usage:        "Show version",
+		Usage: "Show version",
-		StopOnNthArg: stopOnFirstArg(),
+		Action: func(_ *cli.Context) error {
-		Action: func(context.Context, *cli.Command) error {
 			mfa.printVersion()
 
 			return nil
@@ -340,12 +323,13 @@ func (mfa *CLIApp) versionCommand() *cli.Command {
 
 func (mfa *CLIApp) listCommand() *cli.Command {
 	return &cli.Command{
-		Name:         "list",
+		Name:      "list",
-		Aliases:      []string{"ls"},
+		Aliases:   []string{"ls"},
-		Usage:        "List files in manifest",
+		Usage:     "List files in manifest",
-		ArgsUsage:    manifestArgsUsage,
+		ArgsUsage: manifestArgsUsage,
-		StopOnNthArg: stopOnFirstArg(),
+		Action: func(c *cli.Context) error {
-		Action:       mfa.listManifestOperation,
+			return mfa.listManifestOperation(c)
+		},
 		Flags: []cli.Flag{
 			&cli.BoolFlag{
 				Name:    "long",
@@ -362,15 +346,14 @@ func (mfa *CLIApp) listCommand() *cli.Command {
 
 func (mfa *CLIApp) fetchCommand() *cli.Command {
 	return &cli.Command{
-		Name:         cmdFetch,
+		Name:      cmdFetch,
-		Usage:        "fetch manifest and referenced files",
+		Usage:     "fetch manifest and referenced files",
-		ArgsUsage:    "URL",
+		ArgsUsage: "URL",
-		StopOnNthArg: stopOnFirstArg(),
+		Action: func(c *cli.Context) error {
-		Action: func(ctx context.Context, cmd *cli.Command) error {
+			mfa.setVerbosity(c)
-			mfa.setVerbosity(cmd)
 			mfa.printBanner()
 
-			return mfa.fetchManifestOperation(ctx, cmd)
+			return mfa.fetchManifestOperation(c)
 		},
 		Flags: append(commonFlags(),
 			&cli.DurationFlag{
@@ -402,40 +385,38 @@ func (mfa *CLIApp) run(args []string) {
 	log.SetOutput(mfa.Stdout, mfa.Stderr)
 	log.Init()
 
-	// -v means verbose, not version, at the root as on the generate, check,
+	// -v means verbose, not version. urfave/cli's built-in version flag
-	// freshen and fetch subcommands: verbose is the more common meaning of -v
+	// claims -v by default, which made "mfer -v --version" fail to parse and
-	// in tools that offer both. urfave/cli's built-in version flag claims -v
+	// gave -v a different meaning at the root than on the generate, check,
-	// by default, so the version flag takes the capital -V instead.
+	// freshen and fetch subcommands, where it means verbose. Verbose is the
+	// more common meaning of -v in tools that offer both, so -v means verbose
+	// at the root too and the version flag takes the capital -V.
 	// VersionFlag and VersionPrinter are urfave/cli package globals; run() is
 	// serialized in tests, so assigning them here is safe.
 	cli.VersionFlag = &cli.BoolFlag{
 		Name:    cmdVersion,
 		Aliases: []string{"V"},
 		Usage:   "print the version",
-		Local:   true,
 	}
-	cli.VersionPrinter = func(*cli.Command) { mfa.printVersion() }
+	cli.VersionPrinter = func(_ *cli.Context) { mfa.printVersion() }
 
-	mfa.app = &cli.Command{
+	mfa.app = &cli.App{
-		Name:                  mfa.appname,
+		Name:                 mfa.appname,
-		Usage:                 "Manifest generator",
+		Usage:                "Manifest generator",
-		Version:               mfa.VersionString(),
+		Version:              mfa.VersionString(),
-		EnableShellCompletion: true,
+		EnableBashCompletion: true,
-		Writer:                mfa.Stdout,
+		Writer:               mfa.Stdout,
-		// v3 writes its "Incorrect Usage" line to ErrWriter; v2 wrote it to
+		ErrWriter:            mfa.Stderr,
-		// stdout, before the help, so it stays on stdout.
+		Flags:                commonFlags(),
-		ErrWriter:    mfa.Stdout,
+		Action: func(c *cli.Context) error {
-		Flags:        commonFlags(),
+			if c.Args().Len() > 0 {
-		StopOnNthArg: stopOnFirstArg(),
+				return fmt.Errorf("%w %q", errUnknownCommand, c.Args().First())
-		Action: func(_ context.Context, cmd *cli.Command) error {
-			if cmd.Args().Len() > 0 {
-				return fmt.Errorf("%w %q", errUnknownCommand, cmd.Args().First())
 			}
 
-			mfa.setVerbosity(cmd)
+			mfa.setVerbosity(c)
 			mfa.printBanner()
 
-			return cli.ShowRootCommandHelp(cmd)
+			return cli.ShowAppHelp(c)
 		},
 		Commands: []*cli.Command{
 			mfa.generateCommand(),
@@ -450,7 +431,7 @@ func (mfa *CLIApp) run(args []string) {
 
 	mfa.app.HideVersion = false
 
-	err := mfa.app.Run(context.Background(), args)
+	err := mfa.app.Run(args)
 	if err != nil {
 		mfa.exitCode = 1
 

mfer/checker.go

@@ -77,9 +77,9 @@ type Checker struct {
 	fs       afero.Fs
 	// manifestPaths is a set of paths in the manifest for quick lookup
 	manifestPaths map[RelFilePath]struct{}
-	// manifestInfo is the manifest file, which FindExtraFiles leaves out,
+	// manifestRelPath is the relative path of the manifest file from
-	// matched with os.SameFile.
+	// basePath (for exclusion)
-	manifestInfo os.FileInfo
+	manifestRelPath RelFilePath
 	// signature info from the manifest
 	signature     []byte
 	signer        []byte
@@ -133,20 +133,26 @@ func NewChecker(opts *CheckerOptions) (*Checker, error) {
 		manifestPaths[RelFilePath(f.GetPath())] = struct{}{}
 	}
 
-	manifestInfo, err := fs.Stat(opts.ManifestPath)
+	// Compute manifest's relative path from basePath for exclusion in FindExtraFiles
+	absManifest, err := filepath.Abs(opts.ManifestPath)
 	if err != nil {
 		return nil, err
 	}
 
+	manifestRel, err := filepath.Rel(abs, absManifest)
+	if err != nil {
+		manifestRel = ""
+	}
+
 	return &Checker{
-		basePath:      AbsFilePath(abs),
+		basePath:        AbsFilePath(abs),
-		files:         files,
+		files:           files,
-		fs:            fs,
+		fs:              fs,
-		manifestPaths: manifestPaths,
+		manifestPaths:   manifestPaths,
-		manifestInfo:  manifestInfo,
+		manifestRelPath: RelFilePath(manifestRel),
-		signature:     m.pbOuter.GetSignature(),
+		signature:       m.pbOuter.GetSignature(),
-		signer:        m.pbOuter.GetSigner(),
+		signer:          m.pbOuter.GetSigner(),
-		signingPubKey: m.pbOuter.GetSigningPubKey(),
+		signingPubKey:   m.pbOuter.GetSigningPubKey(),
 	}, nil
 }
 
@@ -267,27 +273,20 @@ func (c *Checker) Check(
 	return nil
 }
 
-// FindExtraFiles walks the filesystem and reports files not in the manifest,
+// FindExtraFiles walks the filesystem and reports files not in the manifest.
-// hidden files and directories included. The manifest file itself is not
+// Results are sent to the results channel. The channel is closed when done.
-// reported. Anything the search cannot read, such as a directory that cannot
+// Hidden files/directories (starting with .) are skipped, as they are excluded
-// be listed, is reported with StatusError and the search goes on. Results are
+// from manifests by default. The manifest file itself is also skipped.
-// sent to the results channel. The channel is closed when done.
 func (c *Checker) FindExtraFiles(ctx context.Context, results chan<- Result) error {
 	if results != nil {
 		defer close(results)
 	}
 
-	// The search does not follow symlinks, so a base directory named
+	walkFn := func(walkPath string, info os.FileInfo, err error) error {
-	// through one is resolved first. If that fails, the base is searched as
+		if err != nil {
-	// named and the search reports the problem.
+			return err
-	root := string(c.basePath)
+		}
 
-	resolved, err := filepath.EvalSymlinks(root)
-	if err == nil {
-		root = resolved
-	}
-
-	walkFn := func(walkPath string, info os.FileInfo, walkErr error) error {
 		select {
 		case <-ctx.Done():
 			return ctx.Err()
@@ -295,22 +294,15 @@ func (c *Checker) FindExtraFiles(ctx context.Context, results chan<- Result) err
 		}
 
 		// Get relative path
-		rel, err := filepath.Rel(root, walkPath)
+		rel, err := filepath.Rel(string(c.basePath), walkPath)
 		if err != nil {
 			return err
 		}
 
-		relPath := RelFilePath(rel)
+		// Skip hidden files and directories (dotfiles)
-
+		if IsHiddenPath(filepath.ToSlash(rel)) {
-		// Report what cannot be read, such as a directory that cannot be
+			if info.IsDir() {
-		// listed, and go on with the rest.
+				return filepath.SkipDir
-		if walkErr != nil {
-			if results != nil {
-				results <- Result{
-					Path:    relPath,
-					Status:  StatusError,
-					Message: walkErr.Error(),
-				}
 			}
 
 			return nil
@@ -321,17 +313,10 @@ func (c *Checker) FindExtraFiles(ctx context.Context, results chan<- Result) err
 			return nil
 		}
 
-		// A symlink is compared by what it points to, so a manifest reached
+		relPath := RelFilePath(rel)
-		// through one is not reported either.
-		if info.Mode()&os.ModeSymlink != 0 {
-			target, statErr := c.fs.Stat(walkPath)
-			if statErr == nil {
-				info = target
-			}
-		}
 
-		// Skip the manifest file itself, however its path is spelled
+		// Skip the manifest file itself
-		if os.SameFile(info, c.manifestInfo) {
+		if relPath == c.manifestRelPath {
 			return nil
 		}
 
@@ -349,7 +334,7 @@ func (c *Checker) FindExtraFiles(ctx context.Context, results chan<- Result) err
 		return nil
 	}
 
-	return afero.Walk(c.fs, root, walkFn)
+	return afero.Walk(c.fs, string(c.basePath), walkFn)
 }
 
 func (c *Checker) checkFile(entry *MFFilePath, checkedBytes *FileSize) Result {

mfer/checker_test.go

@@ -21,6 +21,8 @@ const (
 	testExistsFile   = "exists.txt"
 	testManifestPath = "/manifest.mf"
 	testDataDir      = "/data"
+	// testDataManifestPath is a manifest kept inside the checked tree.
+	testDataManifestPath = testDataDir + "/index.mf"
 )
 
 func TestStatusString(t *testing.T) {
@@ -457,120 +459,50 @@ func TestFindExtraFiles(t *testing.T) {
 	assert.Equal(t, "not in manifest", extras[0].Message)
 }
 
-// TestFindExtraFilesReportsHiddenFilesButNotManifest keeps the manifest
+func TestFindExtraFilesSkipsManifestAndDotfiles(t *testing.T) {
-// inside the checked tree: hidden files and directories are reported, the
-// manifest is not. The manifest is recognized by file identity, which needs
-// the real filesystem.
-func TestFindExtraFilesReportsHiddenFilesButNotManifest(t *testing.T) {
 	t.Parallel()
 
-	dir := t.TempDir()
+	fs := afero.NewMemMapFs()
-	manifestPath := filepath.Join(dir, "index.mf")
+	manifestFiles := map[string][]byte{
-
+		testFile1: []byte("in manifest"),
-	fs := afero.NewOsFs()
+	}
-	createTestManifest(t, fs, manifestPath, map[string][]byte{
+	createTestManifest(t, fs, testDataManifestPath, manifestFiles)
+	createFilesOnDisk(t, fs, map[string][]byte{
 		testFile1: []byte("in manifest"),
 	})
-
+	// Create dotfile and manifest that should be skipped
-	unlisted := []RelFilePath{"extra.txt", ".hidden", ".git/config"}
+	require.NoError(t, afero.WriteFile(fs, "/data/.hidden", []byte("hidden"), 0o644))
-	for _, p := range append([]RelFilePath{testFile1}, unlisted...) {
+	require.NoError(t, afero.WriteFile(fs, "/data/.config/settings", []byte("cfg"), 0o644))
-		path := filepath.Join(dir, string(p))
+	// Create a real extra file
-		require.NoError(t, fs.MkdirAll(filepath.Dir(path), 0o750))
+	require.NoError(t, fs.MkdirAll(testDataDir, 0o755))
-		require.NoError(t, afero.WriteFile(fs, path, []byte("x"), 0o600))
+	require.NoError(t, afero.WriteFile(fs, "/data/extra.txt", []byte("extra"), 0o644))
-	}
 
 	chk, err := NewChecker(&CheckerOptions{
-		ManifestPath: manifestPath,
+		ManifestPath: testDataManifestPath,
-		BasePath:     dir,
+		BasePath:     testDataDir,
 		Fs:           fs,
 	})
 	require.NoError(t, err)
 
 	results := make(chan Result, 10)
-	require.NoError(t, chk.FindExtraFiles(context.Background(), results))
+	err = chk.FindExtraFiles(context.Background(), results)
-
-	var extras []RelFilePath
-	for r := range results {
-		extras = append(extras, r.Path)
-	}
-
-	assert.ElementsMatch(t, unlisted, extras)
-}
-
-// TestFindExtraFilesSkipsManifestReachedThroughSymlink checks a tree whose
-// index.mf is a symlink to the manifest kept outside the tree: the symlink is
-// not reported.
-func TestFindExtraFilesSkipsManifestReachedThroughSymlink(t *testing.T) {
-	t.Parallel()
-
-	dir := t.TempDir()
-	tree := filepath.Join(dir, "tree")
-	manifestPath := filepath.Join(dir, "real.mf")
-	linkPath := filepath.Join(tree, "index.mf")
-
-	fs := afero.NewOsFs()
-	createTestManifest(t, fs, manifestPath, map[string][]byte{testFile1: []byte("x")})
-	require.NoError(t, fs.MkdirAll(tree, 0o750))
-	require.NoError(t,
-		afero.WriteFile(fs, filepath.Join(tree, testFile1), []byte("x"), 0o600))
-	require.NoError(t, os.Symlink(manifestPath, linkPath))
-
-	chk, err := NewChecker(&CheckerOptions{
-		ManifestPath: linkPath,
-		BasePath:     tree,
-		Fs:           fs,
-	})
 	require.NoError(t, err)
 
-	results := make(chan Result, 10)
+	var extras []Result
-	require.NoError(t, chk.FindExtraFiles(context.Background(), results))
-
-	var extras []RelFilePath
 	for r := range results {
-		extras = append(extras, r.Path)
+		extras = append(extras, r)
 	}
 
-	assert.Empty(t, extras)
+	// Should only report extra.txt, not .hidden, .config/settings, or index.mf
-}
+	for _, e := range extras {
-
+		t.Logf("extra: %s", e.Path)
-// TestFindExtraFilesSearchesBaseNamedThroughSymlink names the checked tree
-// through a symlink to it: the files in the tree are searched, and the
-// symlink itself is not reported.
-func TestFindExtraFilesSearchesBaseNamedThroughSymlink(t *testing.T) {
-	t.Parallel()
-
-	dir := t.TempDir()
-	tree := filepath.Join(dir, "tree")
-	link := filepath.Join(dir, "link")
-	manifestPath := filepath.Join(dir, "index.mf")
-
-	fs := afero.NewOsFs()
-	createTestManifest(t, fs, manifestPath, map[string][]byte{testFile1: []byte("x")})
-	require.NoError(t, fs.MkdirAll(tree, 0o750))
-
-	for _, name := range []string{testFile1, testFile2} {
-		require.NoError(t,
-			afero.WriteFile(fs, filepath.Join(tree, name), []byte("x"), 0o600))
 	}
 
-	require.NoError(t, os.Symlink(tree, link))
+	assert.Len(t, extras, 1)
 
-	chk, err := NewChecker(&CheckerOptions{
+	if len(extras) > 0 {
-		ManifestPath: manifestPath,
+		assert.Equal(t, RelFilePath("extra.txt"), extras[0].Path)
-		BasePath:     link,
-		Fs:           fs,
-	})
-	require.NoError(t, err)
-
-	results := make(chan Result, 10)
-	require.NoError(t, chk.FindExtraFiles(context.Background(), results))
-
-	var extras []RelFilePath
-	for r := range results {
-		extras = append(extras, r.Path)
 	}
-
-	assert.Equal(t, []RelFilePath{testFile2}, extras)
 }
 
 func TestFindExtraFilesContextCancellation(t *testing.T) {
@@ -717,6 +649,77 @@ func TestCheckMissingFileDetectedWithoutFallback(t *testing.T) {
 	assert.Equal(t, 0, statusCounts[StatusError], "no files should be ERROR")
 }
 
+func TestFindExtraFilesSkipsDotfiles(t *testing.T) {
+	t.Parallel()
+
+	// Regression test for #16: FindExtraFiles should not report dotfiles
+	// or the manifest file itself as extra files.
+	fs := afero.NewMemMapFs()
+	files := map[string][]byte{
+		testFile1: []byte("in manifest"),
+	}
+	createTestManifest(t, fs, testDataManifestPath, files)
+	createFilesOnDisk(t, fs, files)
+
+	// Add dotfiles and manifest file on disk
+	require.NoError(t, afero.WriteFile(fs, "/data/.hidden", []byte("dotfile"), 0o644))
+	require.NoError(t, fs.MkdirAll("/data/.git", 0o755))
+	require.NoError(t,
+		afero.WriteFile(fs, "/data/.git/config", []byte("git config"), 0o644))
+
+	chk, err := NewChecker(&CheckerOptions{
+		ManifestPath: testDataManifestPath,
+		BasePath:     testDataDir,
+		Fs:           fs,
+	})
+	require.NoError(t, err)
+
+	results := make(chan Result, 10)
+	err = chk.FindExtraFiles(context.Background(), results)
+	require.NoError(t, err)
+
+	var extras []Result
+	for r := range results {
+		extras = append(extras, r)
+	}
+
+	// Should report NO extra files — dotfiles and manifest should be skipped
+	assert.Empty(t, extras,
+		"FindExtraFiles should not report dotfiles or manifest file as extra; got: %v",
+		extras)
+}
+
+func TestFindExtraFilesSkipsManifestFile(t *testing.T) {
+	t.Parallel()
+
+	// The manifest file itself should never be reported as extra
+	fs := afero.NewMemMapFs()
+	files := map[string][]byte{
+		testFile1: []byte("content"),
+	}
+	createTestManifest(t, fs, testDataManifestPath, files)
+	createFilesOnDisk(t, fs, files)
+
+	chk, err := NewChecker(&CheckerOptions{
+		ManifestPath: testDataManifestPath,
+		BasePath:     testDataDir,
+		Fs:           fs,
+	})
+	require.NoError(t, err)
+
+	results := make(chan Result, 10)
+	err = chk.FindExtraFiles(context.Background(), results)
+	require.NoError(t, err)
+
+	var extras []Result
+	for r := range results {
+		extras = append(extras, r)
+	}
+
+	assert.Empty(t, extras,
+		"manifest file should not be reported as extra; got: %v", extras)
+}
+
 func TestCheckEmptyManifest(t *testing.T) {
 	t.Parallel()
 

mfer/mf.go

@@ -0,0 +1,3 @@
+package mfer
+
+//go:generate protoc ./mf.proto --go_out=paths=source_relative:.

mfer/mf_test.go

@@ -8,8 +8,6 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/require"
-	"google.golang.org/protobuf/reflect/protoreflect"
-	"sneak.berlin/go/mfer/mfer"
 )
 
 // mf.pb.go is generated from mf.proto and committed. `make generate`
@@ -29,26 +27,3 @@ func TestGeneratedCodeMatchesProto(t *testing.T) {
 		"mfer/mf.proto has changed since mfer/mf.pb.go was generated "+
 			"from it: run `make generate` and commit the result")
 }
-
-// A file entry has exactly the fields docs/FORMAT.md lists for MFFilePath.
-func TestFileEntryFieldsMatchSpec(t *testing.T) {
-	t.Parallel()
-
-	want := map[string]protoreflect.FieldNumber{
-		"path":     1,
-		"size":     2,
-		"hashes":   3,
-		"mimeType": 301,
-		"mtime":    302,
-		"ctime":    303,
-	}
-
-	got := map[string]protoreflect.FieldNumber{}
-
-	fields := (&mfer.MFFilePath{}).ProtoReflect().Descriptor().Fields()
-	for i := range fields.Len() {
-		got[string(fields.Get(i).Name())] = fields.Get(i).Number()
-	}
-
-	require.Equal(t, want, got)
-}

package.json

@@ -1,5 +1,6 @@
 {
     "name": "mfer",
+    "version": "0.1.0",
     "private": true,
     "description": "Development tooling for the mfer repository: prettier, used by script/fmt and script/fmt-check to format and verify Markdown and JSON.",
     "license": "WTFPL",

script/bootstrap

@@ -13,23 +13,11 @@ set -eu
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 # Pinned versions, 2026-07-06. Never "latest" or "lts"; exact versions.
-# The node version is in .nvmrc, where script/prettier reads it too.
+NODE_VERSION="22.17.0"
-NODE_VERSION="$(cat "$ROOT/.nvmrc")"
 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"
-# protoc v33.4, 2026-10-04, for script/generate. The sha256 of each
-# platform's release archive is in ensure_protoc.
-PROTOC_VERSION="33.4"
-# gofumpt v0.12.0 for script/gofumpt and protoc-gen-go v1.36.11 for
-# script/generate, 2026-10-04: each is installed into bin/ with
-# `go install`, pinned to the commit its release tag names. Those two
-# scripts refuse any other version, so a new pin is changed there too.
-GOFUMPT_VERSION="v0.12.0"
-GOFUMPT_COMMIT="3e07e7e70ac93761d8e79ca0083a19e3d59f753d"
-PROTOC_GEN_GO_VERSION="v1.36.11"
-PROTOC_GEN_GO_COMMIT="96a179180f0ad6bba9b1e7b6e38d0affb0168e9a"
 
 PKGMGR=""
 SUDO=""
@@ -86,11 +74,9 @@ verify_sha256() {
     fi
 }
 
-# nvm is a bash script; run a command in a bash with nvm loaded.
+# nvm is a bash script; run a command in a bash with nvm loaded
-# --no-use: otherwise loading nvm here switches to the version .nvmrc
-# names, and fails silently while that version is not installed yet.
 nvm_sh() {
-    bash -c ". \"\$HOME/.nvm/nvm.sh\" --no-use && $*"
+    bash -c ". \"\$HOME/.nvm/nvm.sh\" && $*"
 }
 
 ensure_nvm() {
@@ -136,97 +122,6 @@ install_js_deps() {
     fi
 }
 
-# Unpack protoc's release archive for this platform into bin/protoc, after
-# checking the archive's sha256, unless bin/protoc already holds the pinned
-# version. script/generate runs bin/protoc/bin/protoc, so that is the
-# binary checked again after unpacking.
-ensure_protoc() {
-    dir="$ROOT/bin/protoc"
-    if [ "$("$dir/bin/protoc" --version 2>/dev/null)" = \
-        "libprotoc $PROTOC_VERSION" ]; then
-        echo "protoc $PROTOC_VERSION"
-        return 0
-    fi
-    case "$(uname -s) $(uname -m)" in
-        "Linux x86_64")
-            platform="linux-x86_64"
-            sha256="c0040ea9aef08fdeb2c74ca609b18d5fdbfc44ea0042fcfbfb38860d35f7dd66"
-            ;;
-        "Linux aarch64" | "Linux arm64")
-            platform="linux-aarch_64"
-            sha256="15aa988f4a6090636525ec236a8e4b3aab41eef402751bd5bb2df6afd9b7b5a5"
-            ;;
-        "Darwin x86_64")
-            platform="osx-x86_64"
-            sha256="a49bec10d039e902d3b43e49938c42526f90011467609864fa6386ac4014da58"
-            ;;
-        "Darwin arm64")
-            platform="osx-aarch_64"
-            sha256="726297dcfed58592fd35620a5a6246ae020c39e88f3fd4cb1827df7bcf3dfcf1"
-            ;;
-        *)
-            echo "bootstrap: no protoc archive pinned for $(uname -s) $(uname -m)" >&2
-            exit 1
-            ;;
-    esac
-    if missing curl; then pkg_install curl curl curl curl; fi
-    if missing unzip; then pkg_install unzip unzip unzip unzip; fi
-    tmp="$(mktemp -d)"
-    curl -fsSL -o "$tmp/protoc.zip" \
-        "https://github.com/protocolbuffers/protobuf/releases/download/v${PROTOC_VERSION}/protoc-${PROTOC_VERSION}-${platform}.zip"
-    verify_sha256 "$tmp/protoc.zip" "$sha256"
-    rm -rf "$dir"
-    unzip -q "$tmp/protoc.zip" -d "$dir"
-    rm -rf "$tmp"
-    actual="$("$dir/bin/protoc" --version 2>/dev/null || true)"
-    if [ "$actual" != "libprotoc $PROTOC_VERSION" ]; then
-        echo "bootstrap: $dir/bin/protoc reports '$actual'," \
-            "not libprotoc $PROTOC_VERSION" >&2
-        exit 1
-    fi
-    echo "protoc $PROTOC_VERSION"
-}
-
-# Install gofumpt into bin/ unless bin/gofumpt already reports the pinned
-# version. script/gofumpt runs bin/gofumpt, so that is the binary checked
-# again after installing. Its --version prints the version, then the Go
-# version it was built with. The old file is removed first because
-# `go install` refuses to replace a file that is not a Go binary.
-ensure_gofumpt() {
-    tool="$ROOT/bin/gofumpt"
-    if [ "$("$tool" --version 2>/dev/null | cut -d' ' -f1)" != \
-        "$GOFUMPT_VERSION" ]; then
-        rm -f "$tool"
-        GOBIN="$ROOT/bin" go install "mvdan.cc/gofumpt@$GOFUMPT_COMMIT"
-    fi
-    actual="$("$tool" --version 2>/dev/null | cut -d' ' -f1)"
-    if [ "$actual" != "$GOFUMPT_VERSION" ]; then
-        echo "bootstrap: $tool reports '$actual', not $GOFUMPT_VERSION" >&2
-        exit 1
-    fi
-    echo "gofumpt $GOFUMPT_VERSION"
-}
-
-# Install protoc-gen-go into bin/ unless bin/protoc-gen-go already reports
-# the pinned version, as ensure_gofumpt does. script/generate runs
-# bin/protoc-gen-go, so that is the binary checked again after installing.
-ensure_protoc_gen_go() {
-    tool="$ROOT/bin/protoc-gen-go"
-    if [ "$("$tool" --version 2>/dev/null)" != \
-        "protoc-gen-go $PROTOC_GEN_GO_VERSION" ]; then
-        rm -f "$tool"
-        GOBIN="$ROOT/bin" go install \
-            "google.golang.org/protobuf/cmd/protoc-gen-go@$PROTOC_GEN_GO_COMMIT"
-    fi
-    actual="$("$tool" --version 2>/dev/null || true)"
-    if [ "$actual" != "protoc-gen-go $PROTOC_GEN_GO_VERSION" ]; then
-        echo "bootstrap: $tool reports '$actual'," \
-            "not protoc-gen-go $PROTOC_GEN_GO_VERSION" >&2
-        exit 1
-    fi
-    echo "protoc-gen-go $PROTOC_GEN_GO_VERSION"
-}
-
 main() {
     cd "$ROOT"
 
@@ -237,10 +132,8 @@ main() {
     # ---- JS / docs repos ----
     # This is a Go repo, but node and yarn are required anyway: prettier
     # formats the Markdown and JSON, and script/fmt-check verifies it.
-    # The version is pinned by package.json/yarn.lock: yarn checks every
+    # The version is pinned by package.json/yarn.lock, whose integrity
-    # package it fetches against its yarn.lock integrity hash, and
+    # hashes --frozen-lockfile enforces.
-    # --frozen-lockfile fails instead of rewriting a yarn.lock that no
-    # longer matches package.json.
     ensure_node
     ensure_yarn
     install_js_deps
@@ -249,9 +142,6 @@ main() {
     if missing go; then pkg_install go golang go go; fi
     # No golangci-lint: script/lint runs it in Docker only.
     go mod download
-    ensure_gofumpt
-    ensure_protoc
-    ensure_protoc_gen_go
 
     # ---- Python repos ----
     # if missing python3; then pkg_install python3 python3 python3 python3; fi

script/build

@@ -1,18 +0,0 @@
-#!/bin/sh
-# script/build: build the mfer binary into bin/mfer, stamped with the
-# revision `mfer version` prints, derived as script/docker derives it.
-set -eu
-
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
-
-main() {
-    cd "$ROOT"
-    # Own line: a failing command substitution inside an argument does
-    # not trip `set -e`, so the inline form degrades silently to an
-    # empty constant.
-    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
-    [ -n "$version" ] || version="unknown"
-    go build -ldflags "-X main.Gitrev=$version" -o bin/mfer ./cmd/mfer
-}
-
-main "$@"

script/check

@@ -1,8 +1,7 @@
 #!/bin/sh
 # script/check: run all checks (test, lint, fmt-check). Our own
-# extension to scripts-to-rule-them-all. test and lint are Docker
+# extension to scripts-to-rule-them-all. Must not modify any files.
-# phases; fmt-check is native, because a formatter writes the working
+# Generic: usually needs no adaptation.
-# tree. Must not modify any files.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"

script/cibuild

@@ -1,10 +1,8 @@
 #!/bin/sh
-# script/cibuild: run the CI build. It bootstraps first: a CI runner
+# script/cibuild: run the CI build; the Gitea workflow runs this on push.
-# checks out and runs this and nothing else, and script/fmt-check runs
+# It builds the image with the same command as script/docker. --no-cache
-# the formatter on the host, which a pristine checkout cannot do.
+# because the checks the final stage depends on are RUN steps, and a
-# --no-cache for the same reason as script/docker: the gate phases the
+# cached one is a check that did not run.
-# final stage depends on are RUN steps, and a cached one is a check that
-# did not run.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -12,8 +10,6 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    "$SCRIPT_DIR/bootstrap"
-    "$SCRIPT_DIR/check"
     # Own line: a failing command substitution inside an argument does
     # not trip `set -e`, so the inline form degrades silently to an
     # empty constant. The VERSION build argument takes precedence over

script/fmt

@@ -7,9 +7,8 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    # Go, then Markdown and JSON, through the same scripts script/fmt-check
+    gofumpt -l -w mfer internal cmd
-    # uses, so both see the same files and the same tool versions.
+    # Markdown and JSON, over the same file set script/fmt-check verifies.
-    "$SCRIPT_DIR/gofumpt" --write
     "$SCRIPT_DIR/prettier" --write
 }
 

script/fmt-check

@@ -1,13 +1,13 @@
 #!/bin/sh
 # script/fmt-check: check formatting (read-only). Same scope as
-# script/fmt, but fails instead of writing: Go via script/gofumpt,
+# script/fmt, but fails instead of writing: Go via script/fmt-check-go,
 # Markdown and JSON via script/prettier.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
 
 main() {
-    "$SCRIPT_DIR/gofumpt" --check
+    "$SCRIPT_DIR/fmt-check-go"
     "$SCRIPT_DIR/prettier" --check
 }
 

script/fmt-check-go

@@ -0,0 +1,18 @@
+#!/bin/sh
+# script/fmt-check-go: check Go formatting (read-only). Split out from
+# script/fmt-check so the Docker lint stage, whose image has no node and
+# therefore no prettier, can run the Go half on its own.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    if [ -n "$(gofmt -l .)" ]; then
+        echo "gofmt: files need formatting:" >&2
+        gofmt -l . >&2
+        exit 1
+    fi
+}
+
+main "$@"

script/generate

@@ -4,19 +4,26 @@
 # regenerates mf.pb.go: it is committed, so building and checking need no
 # protoc. A test fails while mf.proto no longer matches the recorded hash.
 #
-# Runs the protoc that script/bootstrap unpacks into bin/protoc, and the
+# Needs exactly the protoc and protoc-gen-go versions named in the header of
-# protoc-gen-go it installs into bin/. Another version of either writes a
+# the committed mf.pb.go (README.md says how to install them). Another
-# different mf.pb.go.
+# version writes a different mf.pb.go, so the script refuses to run.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
-# The versions script/bootstrap installs. protoc 33.4 names itself v6.33.4
+# protoc 33.4 names itself v6.33.4 in the mf.pb.go header.
-# in the mf.pb.go header.
 PROTOC_VERSION="33.4"
-PROTOC="$ROOT/bin/protoc/bin/protoc"
 PROTOC_GEN_GO_VERSION="v1.36.11"
-PROTOC_GEN_GO="$ROOT/bin/protoc-gen-go"
+
+# require_version <command> <its exact --version output>
+require_version() {
+    actual="$("$1" --version 2>/dev/null || true)"
+    if [ "$actual" != "$2" ]; then
+        echo "generate: needs $2 on PATH, found: ${actual:-none}" >&2
+        echo "  README.md says how to install it." >&2
+        exit 1
+    fi
+}
 
 # sha256 <file>: print "<hash>  <file>", with sha256sum, or with shasum
 # where there is no sha256sum.
@@ -32,27 +39,13 @@ sha256() {
 }
 
 main() {
-    # A bin/protoc or bin/protoc-gen-go left from before its pin moved
-    # fails here, until script/bootstrap replaces it.
-    actual="$("$PROTOC" --version 2>/dev/null || true)"
-    if [ "$actual" != "libprotoc $PROTOC_VERSION" ]; then
-        echo "generate: needs protoc $PROTOC_VERSION in bin/protoc," \
-            "found: ${actual:-none}; run script/bootstrap" >&2
-        exit 1
-    fi
-    actual="$("$PROTOC_GEN_GO" --version 2>/dev/null || true)"
-    if [ "$actual" != "protoc-gen-go $PROTOC_GEN_GO_VERSION" ]; then
-        echo "generate: needs protoc-gen-go $PROTOC_GEN_GO_VERSION in" \
-            "bin/protoc-gen-go, found: ${actual:-none}; run script/bootstrap" >&2
-        exit 1
-    fi
-
     cd "$ROOT/mfer"
+    require_version protoc "libprotoc $PROTOC_VERSION"
+    require_version protoc-gen-go "protoc-gen-go $PROTOC_GEN_GO_VERSION"
     # Hashed before regenerating, so a missing hash tool stops the script
     # before it changes anything. Regenerating leaves mf.proto as it is.
     proto_hash="$(sha256 mf.proto)"
-    "$PROTOC" --plugin=protoc-gen-go="$PROTOC_GEN_GO" \
+    go generate .
-        --go_out=paths=source_relative:. ./mf.proto
     echo "$proto_hash" >mf.proto.sha256
 }
 

script/gofumpt

@@ -1,50 +0,0 @@
-#!/bin/sh
-# script/gofumpt: run gofumpt over this repo's Go files.
-#
-# Takes exactly one mode argument, --write or --check, and runs the same
-# gofumpt version over the same files in both modes. script/fmt and
-# script/fmt-check both go through here, so what gets formatted and what
-# gets verified cannot drift apart.
-set -eu
-
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
-
-# The gofumpt script/bootstrap installs into bin/. Must match the pin
-# there.
-GOFUMPT_VERSION="v0.12.0"
-GOFUMPT="$ROOT/bin/gofumpt"
-
-usage() {
-    echo "usage: script/gofumpt --write|--check" >&2
-    exit 2
-}
-
-main() {
-    [ "$#" -eq 1 ] || usage
-    # A bin/gofumpt left from before the pin moved formats differently, so
-    # it fails here until script/bootstrap replaces it.
-    actual="$("$GOFUMPT" --version 2>/dev/null | cut -d' ' -f1)"
-    if [ "$actual" != "$GOFUMPT_VERSION" ]; then
-        echo "gofumpt: needs $GOFUMPT_VERSION in bin/gofumpt," \
-            "found: ${actual:-none}; run script/bootstrap" >&2
-        exit 1
-    fi
-    # Every Go file in the repo, from $ROOT down. gofumpt holds generated
-    # files, such as mfer/mf.pb.go, to gofmt's rules only.
-    case "$1" in
-        --write) "$GOFUMPT" -l -w "$ROOT" ;;
-        --check)
-            # Own line: a failing command inside `[ -n "$(...)" ]` does
-            # not trip `set -e`, so a gofumpt that never ran would pass.
-            unformatted="$("$GOFUMPT" -l "$ROOT")"
-            if [ -n "$unformatted" ]; then
-                echo "gofumpt: files need formatting (run make fmt):" >&2
-                echo "$unformatted" >&2
-                exit 1
-            fi
-            ;;
-        *) usage ;;
-    esac
-}
-
-main "$@"

script/install-precommit

@@ -1,6 +1,7 @@
 #!/bin/sh
 # script/install-precommit: install the git pre-commit hook that runs
 # script/precommit. Our own extension to scripts-to-rule-them-all.
+# Generic: needs no adaptation.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"

script/lint

@@ -1,13 +1,8 @@
 #!/bin/sh
-# script/lint: run the linter. Linting is a phase of the Dockerfile and
+# script/lint: run golangci-lint, in Docker only. Builds the lint stage of
-# this builds that phase alone; the linter is never installed or run on
+# the Dockerfile, whose build runs the linter, so a successful build is a
-# a developer host, where a shared result cache and a host-global lock
+# clean lint. --no-cache because a cached build runs no linter. The image
-# make its answer untrustworthy.
+# is removed afterwards, whatever the outcome.
-#
-# The phase is not the last stage in the file, so it is built only when
-# --target names it. --no-cache because a cached lint layer is a lint
-# that did not run. The tag makes each build replace the previous image
-# instead of leaving a dangling one behind.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -15,9 +10,11 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build --no-cache \
+    # Tagged per run, so concurrent runs never remove each other's image.
-        --target lint \
+    image="$("$SCRIPT_DIR/projectname")-lint:$$"
-        -t "$("$SCRIPT_DIR/projectname")-lint" .
+    # A failed build leaves no image, so there is nothing to remove then.
+    trap 'docker image rm "$image" >/dev/null 2>&1 || true' EXIT INT TERM
+    docker build --no-cache --target lint -t "$image" .
 }
 
 main "$@"

script/prettier

@@ -18,9 +18,24 @@ usage() {
     exit 2
 }
 
-# Only the prettier yarn installed from yarn.lock, never one on PATH: a
+# Prefer the version pinned by package.json/yarn.lock so that CI and
-# different version formats differently.
+# developer machines format identically. Fall back to a prettier on PATH,
-PRETTIER="$ROOT/node_modules/.bin/prettier"
+# but say so, because a different version formats differently.
+find_prettier() {
+    if [ -x "$ROOT/node_modules/.bin/prettier" ]; then
+        printf '%s\n' "$ROOT/node_modules/.bin/prettier"
+        return 0
+    fi
+    if command -v prettier >/dev/null 2>&1; then
+        echo "prettier: node_modules/.bin/prettier is absent; using the" \
+            "prettier on PATH, which may be a different version than the" \
+            "one pinned in package.json. Run script/bootstrap to install" \
+            "the pinned version." >&2
+        command -v prettier
+        return 0
+    fi
+    return 1
+}
 
 main() {
     [ "$#" -eq 1 ] || usage
@@ -31,38 +46,24 @@ main() {
 
     cd "$ROOT"
 
-    # Where there is no node on PATH, script/bootstrap installs the version
+    if ! prettier_bin="$(find_prettier)"; then
-    # .nvmrc names through nvm, which keeps it in this directory.
+        echo "prettier: not found." >&2
-    if ! command -v node >/dev/null 2>&1; then
+        echo "  Install it with: script/bootstrap" >&2
-        PATH="$HOME/.nvm/versions/node/v$(cat .nvmrc)/bin:$PATH"
+        echo "  (installs the version pinned in package.json/yarn.lock)" >&2
-    fi
-    if ! command -v node >/dev/null 2>&1; then
-        echo "prettier: node is missing; run script/bootstrap" >&2
-        exit 1
-    fi
-
-    # node_modules keeps the old prettier after package.json moves to a new
-    # one, until script/bootstrap runs again, so compare the two.
-    if ! installed="$("$PRETTIER" --version 2>/dev/null)"; then
-        echo "prettier: not installed; run script/bootstrap" >&2
-        exit 1
-    fi
-    pinned="$(node -p 'require("./package.json").devDependencies.prettier')"
-    if [ "$installed" != "$pinned" ]; then
-        echo "prettier: package.json pins $pinned but $installed is" \
-            "installed; run script/bootstrap" >&2
         exit 1
     fi
 
     # Markdown and JSON, repo-wide rather than root-only, so files in
     # subdirectories (docs/, once it exists) are covered too. Exclusions
-    # live in .prettierignore.
+    # live in .prettierignore; REPO_POLICIES.md is excluded there because
+    # it is a verbatim copy of an upstream document.
     #
     # --no-error-on-unmatched-pattern is deliberately NOT used: both
     # patterns always match at least one tracked file (README.md,
     # package.json), so an empty match means the glob broke, and prettier
     # erroring out is exactly what we want rather than a vacuous pass.
-    "$PRETTIER" "$mode" "**/*.md" "**/*.json"
+    "$prettier_bin" "$mode" "**/*.md"
+    "$prettier_bin" "$mode" "**/*.json"
 }
 
 main "$@"

script/setup

@@ -1,6 +1,7 @@
 #!/bin/sh
 # script/setup: set up the repo for development after a fresh clone:
-# installs dependencies and the git pre-commit hook.
+# installs dependencies (script/bootstrap) and the git pre-commit hook.
+# Add any repo-specific initialization (db init, .env template) here.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"

script/test

@@ -1,19 +1,17 @@
 #!/bin/sh
-# script/test: run the test suite. Testing is a phase of the Dockerfile
+# script/test: run the test suite.
-# and this builds that phase alone, on the same terms as script/lint:
-# --target because a phase that is not the last stage is built only when
-# named, --no-cache because a cached test layer is a test that did not
-# run, and a tag so each build replaces the previous image.
 set -eu
 
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
-ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    docker build --no-cache \
+    go test -timeout 30s -race -cover ./... ||
-        --target test \
+        {
-        -t "$("$SCRIPT_DIR/projectname")-test" .
+            echo "--- Rerunning with -v for details ---"
+            go test -timeout 30s -race -v ./...
+            exit 1
+        }
 }
 
 main "$@"