fmt: format and check Markdown with prettier in a container (closes #119)

make fmt and make fmt-check now cover every Markdown file with prettier
(4-space tabs, proseWrap always), as template-app-go does: prettier is
pinned by package.json and yarn.lock and runs in a docker build on a
digest-pinned node image, never on the host. The check is forced to run
with --no-cache-filter, as script/lint is.

script/fmt-check is split into a Go half and a Markdown half because the
Dockerfile lint stage cannot run docker: that stage now runs the Go half
and script/cibuild runs the Markdown half after the build. *.md leaves
.dockerignore so documents reach the build context.

README.md, TESTING.md and TODO.md are reformatted by make fmt; apart from
the README Entrypoints entries, its make fmt line under Building and the
TODO entry, that diff is mechanical.

Model: opus-5-5

script/bootstrap

@@ -3,11 +3,12 @@
 # this repo. Idempotent: every install is guarded by a check so already
 # installed tools are skipped. Base tooling comes from nix, apt, brew,
 # or apk (detected in that order); assumes nothing is present.
-# goimports is not installed here: script/fmt and script/fmt-check run
-# it with `go run` at a pinned commit.
+# goimports is not installed here: script/fmt and script/fmt-check-go
+# run it with `go run` at a pinned commit.
 # The linter is NOT installed here: golangci-lint runs via docker only
 # (script/lint), pinned by image digest, so its only prerequisite is a
-# working docker.
+# working docker. Nor is prettier: script/fmt and
+# script/fmt-check-markdown run it in a container from Dockerfile.fmt.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
@@ -66,11 +67,12 @@ main() {
     if missing make; then pkg_install gnumake make make make; fi
     if missing go; then pkg_install go golang go go; fi
 
-    # Linting runs via docker only (script/lint). Warn, don't fail:
-    # everything except `make lint` works without it.
+    # Linting and the markdown formatter run via docker only. Warn,
+    # don't fail: building and testing work without it.
     if missing docker; then
         echo "bootstrap: WARNING: docker not found; install it to" \
-            "run make lint and make docker." >&2
+            "run make lint, make fmt, make fmt-check, make check" \
+            "and make docker." >&2
     fi
 
     go mod download

script/cibuild

@@ -1,18 +1,23 @@
 #!/bin/sh
 # script/cibuild: run the CI build. The Dockerfile's lint stage runs
-# make fmt-check and golangci-lint; its builder stage runs make test
-# and make build.
+# the Go half of make fmt-check and golangci-lint; its builder stage
+# runs make test and make build. The markdown half of make fmt-check
+# runs after that build, as its own build of Dockerfile.fmt, because
+# there is no docker inside a docker build.
 #
 # --no-cache-filter=lint,builder runs both stages on every invocation;
 # otherwise an unchanged tree is served from the layer cache and passes
-# without linting or querying live DNS.
+# without linting or querying live DNS. script/fmt-check-markdown busts
+# its own cache the same way.
 set -eu
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
     docker build --no-cache-filter=lint,builder .
+    "$SCRIPT_DIR/fmt-check-markdown"
 }
 
 main "$@"

script/fmt

@@ -1,19 +1,65 @@
 #!/bin/sh
-# script/fmt: format all files (writes).
+# script/fmt: format all files (writes). Go with gofmt and goimports on
+# the host, markdown with the prettier pinned by Dockerfile.fmt.
 #
 # goimports runs with `go run` at a pinned commit, never from PATH, so
 # every machine formats with the same version and nothing installs it.
+#
+# The markdown pass is a `docker build --output type=local` rather than a
+# `docker run -v`, so it needs no bind mount and behaves the same against
+# a remote daemon; the formatted documents come back out of the build and
+# are copied over the tree here.
+#
+# Unlike script/fmt-check-markdown this does not bust the cache: it is
+# not a gate, and any edit to a document changes the COPY layer above the
+# prettier step, so a cached result is a result over this exact tree.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
-# goimports v0.42.0, 2026-08-07. Must match script/fmt-check.
+# goimports v0.42.0, 2026-08-07. Must match script/fmt-check-go.
 GOIMPORTS_REF="golang.org/x/tools/cmd/goimports@009367f5c17a8d4c45a961a3a509277190a9a6f0"
 
+# Must match the export stage name in Dockerfile.fmt.
+stage=fmt-out
+
+die() {
+    echo "script/fmt: $*" >&2
+    exit 1
+}
+
 main() {
     cd "$ROOT"
     gofmt -s -w .
     go run "$GOIMPORTS_REF" -w .
+
+    tmp="$(mktemp -d "${TMPDIR:-/tmp}/dnswatcher-fmt.XXXXXX")"
+    trap 'rm -rf "$tmp"' EXIT INT TERM
+
+    docker build \
+        --target "$stage" \
+        --output "type=local,dest=$tmp/out" \
+        -f Dockerfile.fmt .
+
+    # An empty export means prettier was handed nothing, which must not
+    # read as "already formatted".
+    (cd "$tmp/out" && find . -type f -name '*.md') |
+        sed 's|^\./||' | LC_ALL=C sort >"$tmp/files"
+
+    [ -s "$tmp/files" ] ||
+        die "the formatting build produced no markdown; the build" \
+            "context reached prettier empty"
+
+    # Copied only where the bytes differ, so an already-formatted tree
+    # keeps its timestamps and says nothing.
+    while IFS= read -r f; do
+        [ -n "$f" ] || continue
+        if [ -f "$f" ] && cmp -s "$tmp/out/$f" "$f"; then
+            continue
+        fi
+        cp "$tmp/out/$f" "$f"
+        echo "prettier: reformatted $f"
+    done <"$tmp/files"
 }
 
 main "$@"

script/fmt-check

@@ -1,27 +1,14 @@
 #!/bin/sh
 # script/fmt-check: check formatting (read-only). Same tools and scope
-# as script/fmt, but fails instead of writing.
+# as script/fmt, but fails instead of writing: the Go on the host, the
+# markdown with prettier in a container.
 set -eu
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
-
-# goimports v0.42.0, 2026-08-07. Must match script/fmt.
-GOIMPORTS_REF="golang.org/x/tools/cmd/goimports@009367f5c17a8d4c45a961a3a509277190a9a6f0"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
 
 main() {
-    cd "$ROOT"
-    files="$(gofmt -s -l .)"
-    if [ -n "$files" ]; then
-        echo "gofmt: files not formatted:" >&2
-        echo "$files" >&2
-        exit 1
-    fi
-    files="$(go run "$GOIMPORTS_REF" -l .)"
-    if [ -n "$files" ]; then
-        echo "goimports: files not formatted:" >&2
-        echo "$files" >&2
-        exit 1
-    fi
+    "$SCRIPT_DIR/fmt-check-go"
+    "$SCRIPT_DIR/fmt-check-markdown"
 }
 
 main "$@"

script/fmt-check-go

@@ -0,0 +1,31 @@
+#!/bin/sh
+# script/fmt-check-go: fail unless every Go source is formatted the way
+# script/fmt would leave it, and name the files that are not. Read-only.
+#
+# Its own script because the Dockerfile's lint stage runs this half
+# alone: there is no docker inside a docker build to run the markdown
+# half in.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+# goimports v0.42.0, 2026-08-07. Must match script/fmt.
+GOIMPORTS_REF="golang.org/x/tools/cmd/goimports@009367f5c17a8d4c45a961a3a509277190a9a6f0"
+
+main() {
+    cd "$ROOT"
+    files="$(gofmt -s -l .)"
+    if [ -n "$files" ]; then
+        echo "gofmt: files not formatted:" >&2
+        echo "$files" >&2
+        exit 1
+    fi
+    files="$(go run "$GOIMPORTS_REF" -l .)"
+    if [ -n "$files" ]; then
+        echo "goimports: files not formatted:" >&2
+        echo "$files" >&2
+        exit 1
+    fi
+}
+
+main "$@"

script/fmt-check-markdown

@@ -0,0 +1,29 @@
+#!/bin/sh
+# script/fmt-check-markdown: fail unless every .md is formatted the way
+# script/fmt would leave it. Read-only.
+#
+# prettier is never installed on the host: it runs in a container built
+# from Dockerfile.fmt, pinned by package.json and yarn.lock.
+# --no-cache-filter is here for the reason script/lint gives: a cached
+# build checks nothing.
+#
+# Its own script because script/cibuild runs this half alone, after the
+# Dockerfile's lint stage has checked the Go.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+# Must match the markdown check stage name in Dockerfile.fmt.
+stage=fmt-check
+
+main() {
+    cd "$ROOT"
+    docker build \
+        --progress=plain \
+        --no-cache-filter="$stage" \
+        --target "$stage" \
+        -f Dockerfile.fmt \
+        .
+}
+
+main "$@"