summercms/scripts/check-phase19.3.sh

#!/usr/bin/env bash
# check-phase19.3: fail-closed gate for Phase 19.3, framework transport and
# infrastructure. The framework pieces in this repository (bouncer token
# cookies and Turnstile, surf CORS hardening, CORS profiles, the api-docs page
# and the rate-limit store lookup, cabana's reorder hook, summer.yaml build
# tags, the attach S3 build tag, DiskExtension and public_url, and the cooler
# module: caches, the Redis rate-limit store, Install and the site-cache
# purge), the purge wiring in the FAQ, menu and Journal plugins, and the
# shared purge route of the FAQ, menu and Journal Nuxt layers.
#
# Stages:
#   go        go vet ./... and go vet -tags summercms_s3 ./modules/lagoon/...;
#             go test -short ./...; then the Docker-free framework suites by
#             required name, the attach ones in both build-tag modes.
#   docker    Docker host only: the testcontainers suites by required name
#             (Postgres and Redis) in the framework and the plugins.
#   plugins   go vet ./... and go test -short ./... in the three plugins, then
#             their Docker-free suites by required name.
#   layers    pnpm test (node --test, TAP) in the three layers with required
#             test files and names, and cmp equality of the shared purge files
#             and spec across the layers.
#   docs      TestDocsTree, summer docs:build --check and a check that no file
#             this phase added to the framework names a consuming application.
#
# A stage exits non-zero on a failing command, or on a go test -json run that
# fails, skips a test, matches zero tests, prints "no tests to run" or misses a
# required name; or a TAP run with a "not ok", a fail, cancelled, skipped or
# todo count, no passing test or a missing required name.
# --self-test proves the detectors fail on planted output.
#
# --all runs self-test, go, plugins, layers and docs, then docker when a
# Docker daemon answers. When none does, --all prints NOT RUN docker and the
# Docker suites stay a manual step for a Docker host:
#   bash scripts/check-phase19.3.sh docker
# Set PHASE193_REQUIRE_DOCKER=1 to make --all fail instead.
#
# Environment overrides (default: the sibling checkouts next to this
# repository): PHASE193_ROOT (this repository), FAQ_PLUGIN, MENU_PLUGIN,
# JOURNAL_PLUGIN, FAQ_LAYER, MENU_LAYER, JOURNAL_LAYER.
set -euo pipefail

unset FORCE_COLOR
export NO_COLOR=1

ROOT="${PHASE193_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
FAQ_PLUGIN="${FAQ_PLUGIN:-$ROOT/../sm-faq-plugin}"
MENU_PLUGIN="${MENU_PLUGIN:-$ROOT/../sm-menu-plugin}"
JOURNAL_PLUGIN="${JOURNAL_PLUGIN:-$ROOT/../sm-journal-plugin}"
FAQ_LAYER="${FAQ_LAYER:-$ROOT/../vue-faq-layer}"
MENU_LAYER="${MENU_LAYER:-$ROOT/../vue-menu-layer}"
JOURNAL_LAYER="${JOURNAL_LAYER:-$ROOT/../vue-journal-layer}"

# ---------------------------------------------------------------------------
# Required test names. Each list runs with -run '^(a|b|...)$' and every name
# must pass; a name that skips or does not run fails the stage.

# go stage: Docker-free framework suites (-short).
BOUNCER_TESTS=(
	TestLoadCookieConfigDefaults TestLoadCookieConfigErrors
	TestTokenCookieAttributes TestTokenCookieMaxAgeIsRefreshWindow TestForgetTokenCookie
	TestCookieRefreshHandlerRotatesAndBlacklists TestCookieRefreshHandlerMissingCookie
	TestCookieRefreshHandlerRefreshError TestCookieLogoutHandler TestCookieHandlerOptionsValidated
	TestTurnstileVerifyMatrix TestTurnstileVerifyTimeout TestTurnstileFormFields
	TestTurnstileMiddlewareTokenSources TestTurnstileMiddlewareRestoresBody
	TestTurnstileMiddlewareStatuses TestTurnstileNeverLogsSecret
)

SURF_TESTS=(
	TestCORSCredentialsWildcardRefused TestCORSPatternErrors TestCORSWildcardOriginEntry
	TestCORSVaryOnDynamicAnswers TestCORSSubdomainCredentialed TestCORSStarUnchanged
	TestCORSOptionsMatchesLaravel
	TestCORSProfilePreflightRoute TestCORSProfileUnknown TestCORSProfileWithPathsRefused
	TestCORSProfileOverlapGlobal TestCORSProfileConflictingProfilesSamePath
	TestCORSProfileHeadersOnRefusals TestCORSProfileVaryKeptWithHandlerVary
	TestTurnstileFactoryParams
	TestAPIDocsOffByDefault TestAPIDocsServesPinnedPage TestAPIDocsSpecJSONOrder
	TestAPIDocsJSONSpecInput TestAPIDocsProviderCount TestAPIDocsPathValidation
	TestAPIDocsTitleEscaped
	TestBuildRouterStoreFallback TestBuildRouterUsesPublishedStore TestBuildRouterNeverDials
)
BUILD_TESTS=(
	TestManifestBuildTags
	TestManifestBuildTagsInvalid
	TestSaveManifestKeepsBuildTags
	TestGoBuildArgs
)
# The attach names run twice: untagged and with -tags summercms_s3.
ATTACH_TESTS=(
	TestOpenBucketS3
	TestDiskExtensionTable
	TestPublicURLBase
	TestPublicURLValidation
)

# cooler: caches, rate-limit parity with surf.MemoryStore (miniredis),
# Install, FromApp and the site-cache purger.
COOLER_TESTS=(
	TestMemoryCache TestMemoryCacheTTL TestMemoryCacheBounded
	TestMemoryIncrementConcurrent TestRememberDegrades
	TestRedisCache TestRedisFlushOnlyPrefix
	TestRateLimitParity
	TestRateLimitConcurrentNeverExceedsMax
	TestRateLimitFallbackOnError TestRateLimitKeyPrefix
	TestInstallConfigErrors TestInstallPingWarning TestInstallReusesFromApp
	TestFromAppLazy TestInstallSiteCacheValidation
	TestSiteCachePurgeConfig TestSiteCachePurgeRequest TestSiteCacheFromApp
)

# docker stage: testcontainers suites.
DOCKER_CABANA_TESTS=(TestReorderHookRunsInTx TestReorderHookErrorRollsBack TestReorderWithoutHookUnchanged)
DOCKER_ATTACH_TESTS=(
	TestStoreDiskExtension
)
# Postgres for the after-commit purge, redis:7-alpine for the rest.
DOCKER_COOLER_TESTS=(
	TestRateLimitParityDocker
	TestRedisCacheDocker
	TestSiteCacheAfterCommitOnly
	TestSiteCacheFailureNeverFails
)
DOCKER_FAQ_TESTS=(TestFaqAdminPurgesSiteCache)
DOCKER_MENU_TESTS=(TestMenuAdminPurgesSiteCache)
DOCKER_JOURNAL_TESTS=(
	TestCategoriesAdminPurgesSiteCache
	TestPostsAdminPurgesSiteCache
	TestCategoriesAdminFrameworkKeysWin
)

# plugins stage: the purge helpers and the Journal's deprecated keys (-short).
FAQ_CONTROLLERS_TESTS=(
	TestPurgeSiteCacheWithoutTx
	TestPurgeSiteCacheWithoutPurger
)
MENU_CONTROLLERS_TESTS=("${FAQ_CONTROLLERS_TESTS[@]}")
JOURNAL_ROOT_TESTS=(
	TestSiteCacheFrameworkKeysWin
	TestSiteCacheAliasKeysDeprecated
	TestSiteCacheNoKeys
)
JOURNAL_CLASSES_TESTS=(TestSiteCachePurgeConfig TestSiteCachePurgeRequest)

# layers stage: the shared purge spec, byte-identical in the three layers.
LAYER_REQUIRE=(
	"sitePurge: the shared files match the pinned hashes"
	"sitePurge: a missing or short token disables the route"
	"sitePurge: a proxied request is refused before the token is checked"
	"sitePurge: authorize ok with the token and unauthorized otherwise"
	"sitePurge: purge removes only nitro:routes: keys"
	"sitePurge: purge event kinds and slugs"
	"sitePurge: ok in constant time over sha256 digests, whatever the bearer length"
	"sitePurge: purge works with a synchronous storage and skips the bare base key"
	"sitePurge: purge event edge cases"
	"sitePurge: route answers 404 when disabled or proxied and 401 for a wrong bearer"
	"sitePurge: route purges, answers the count and logs kind and slug only"
)
# Files every layer ships byte for byte.
LAYER_SHARED=(
	server/lib/siteCachePurge.ts
	server/api/__site__/cache/purge.post.ts
	tests/sitePurge.test.ts
)

# docs stage: names of consuming applications that framework lines added by
# this phase must not carry (split so this file does not match itself).
APP_NAMES=("fono""teka" "p[lł]yta""rium" "grzy""by" "summercms""io" "wave""path" "stu""dia")

usage() {
	cat >&2 <<'EOF'
usage:
  check-phase19.3.sh --self-test
  check-phase19.3.sh go | docker | plugins | layers | docs
  check-phase19.3.sh --go | --docker | --plugins | --layers | --docs
  check-phase19.3.sh --all
EOF
	exit 2
}

# detect_go reads go test -json. Exit 1 fail/build, 2 skip, 3 zero/no-tests,
# 4 non-JSON, 5 missing required name.
detect_go() {
	python3 - "$1" <<'PY'
import json, os, sys
path = sys.argv[1]
require = [n for n in os.environ.get("REQUIRE_TESTS", "").split() if n]
passed = set()
failed = []
with open(path, encoding="utf-8", errors="replace") as fh:
    for raw in fh:
        line = raw.strip()
        if not line.startswith("{"):
            continue
        try:
            ev = json.loads(line)
        except json.JSONDecodeError:
            print("refuse: non-json test output", file=sys.stderr)
            sys.exit(4)
        action = ev.get("Action")
        test = ev.get("Test") or ""
        pkg = ev.get("Package") or ev.get("ImportPath") or ""
        if action == "build-fail" or (action == "fail" and ev.get("FailedBuild")):
            print(f"refuse: build failed {pkg}", file=sys.stderr)
            sys.exit(1)
        text = ev.get("Output") or ""
        if action == "output" and "no tests to run" in text:
            print(f"refuse: no tests to run in {pkg}", file=sys.stderr)
            sys.exit(3)
        if action == "skip" and test:
            print(f"refuse: skipped {pkg} {test}", file=sys.stderr)
            sys.exit(2)
        if action == "fail":
            failed.append(f"{pkg} {test}".strip())
        if action == "pass" and test:
            passed.add(test)
if failed:
    print("refuse: failed " + ", ".join(failed), file=sys.stderr)
    sys.exit(1)
if not passed:
    print("refuse: zero tests", file=sys.stderr)
    sys.exit(3)
missing = [n for n in require if n not in passed]
if missing:
    print("refuse: required tests did not pass: " + ", ".join(missing), file=sys.stderr)
    sys.exit(5)
PY
}

# detect_tap reads node --test --test-reporter=tap output. Exit 1 "not ok" or
# a fail/cancelled count, 2 a skip/todo directive or count, 3 no passing test,
# 5 a missing required name. REQUIRE_NAMES holds one test name per line.
detect_tap() {
	python3 - "$1" <<'PY'
import os, re, sys
path = sys.argv[1]
require = [n for n in os.environ.get("REQUIRE_NAMES", "").split("\n") if n.strip()]
passed = set()
counts = {}
with open(path, encoding="utf-8", errors="replace") as fh:
    for raw in fh:
        line = raw.rstrip("\n")
        body = line.lstrip()
        if body.startswith("not ok"):
            print(f"refuse: {body}", file=sys.stderr)
            sys.exit(1)
        m = re.match(r"ok \d+ - (.*?)(\s+#\s*(SKIP|TODO)\b.*)?$", body, re.I)
        if m:
            if m.group(2):
                print(f"refuse: {body}", file=sys.stderr)
                sys.exit(2)
            passed.add(m.group(1).replace("\\#", "#"))
            continue
        m = re.match(r"# (tests|suites|pass|fail|cancelled|skipped|todo) (\d+)$", line)
        if m:
            counts[m.group(1)] = int(m.group(2))
for key in ("fail", "cancelled"):
    if counts.get(key, 0) > 0:
        print(f"refuse: {counts[key]} {key}", file=sys.stderr)
        sys.exit(1)
for key in ("skipped", "todo"):
    if counts.get(key, 0) > 0:
        print(f"refuse: {counts[key]} {key}", file=sys.stderr)
        sys.exit(2)
if counts.get("pass", 0) < 1 or not passed:
    print("refuse: no passing tests", file=sys.stderr)
    sys.exit(3)
missing = [n for n in require if n not in passed]
if missing:
    print("refuse: required tests did not pass: " + "; ".join(missing), file=sys.stderr)
    sys.exit(5)
PY
}

go_json() {
	local dir="$1"
	shift
	local log err rc=0 dc=0
	log="$(mktemp)"
	err="$(mktemp)"
	(cd "$dir" && go test -json "$@") >"$log" 2>"$err" || rc=$?
	detect_go "$log" || dc=$?
	if [[ "$rc" -ne 0 || "$dc" -ne 0 ]]; then
		cat "$err" >&2 || true
		grep -v '^{' "$log" | tail -n 40 >&2 || true
		python3 -c 'import json,sys
for raw in open(sys.argv[1], errors="replace"):
    try: ev = json.loads(raw)
    except ValueError: continue
    if ev.get("Action") == "output" and ("FAIL" in ev.get("Output", "") or "_test.go:" in ev.get("Output", "")):
        sys.stderr.write(ev["Output"])' "$log" 2>&1 | tail -n 40 >&2 || true
		rm -f "$log" "$err"
		echo "refuse: go test $* in $dir (test=$rc detect=$dc)" >&2
		return 1
	fi
	echo "go: $(grep -c '"Action":"pass","Package":"[^"]*","Test":"[^"/]*","Elapsed"' "$log") top-level tests passed in $dir ($*)"
	rm -f "$log" "$err"
}

# go_named DIR PACKAGES FLAGS NAME... runs exactly the named top-level tests
# and requires every one of them to pass. PACKAGES and FLAGS are word-split.
go_named() {
	local dir="$1" pkgs="$2" flags="$3"
	shift 3
	if [[ "$#" -eq 0 ]]; then
		echo "refuse: go_named $pkgs in $dir without required names" >&2
		return 1
	fi
	local names=("$@") regex
	regex="^($(IFS='|'; echo "${names[*]}"))\$"
	# shellcheck disable=SC2086
	REQUIRE_TESTS="${names[*]}" go_json "$dir" $flags -count=1 -run "$regex" $pkgs
}

# go_short DIR runs go test -short ./... in DIR; on failure it prints the tail
# of the output and fails.
go_short() {
	local out
	if ! out="$(cd "$1" && go test -count=1 -short ./... 2>&1)"; then
		printf '%s\n' "$out" | grep -v '^ok ' | tail -n 60 >&2
		echo "refuse: go test -short ./... in $1" >&2
		return 1
	fi
	echo "short: $1"
}

expect_detector() {
	local detector="$1" name="$2" want="$3" payload="$4" log dc=0
	log="$(mktemp)"
	printf '%s\n' "$payload" >"$log"
	"$detector" "$log" >/dev/null 2>&1 || dc=$?
	rm -f "$log"
	if [[ "$dc" -ne "$want" ]]; then
		echo "refuse: self-test $detector $name: exit $dc, want $want" >&2
		return 1
	fi
}

run_self_test() {
	bash -n "${BASH_SOURCE[0]}"

	expect_detector detect_go pass 0 '{"Action":"pass","Package":"p","Test":"TestTokenCookieAttributes"}'
	expect_detector detect_go fail 1 '{"Action":"pass","Package":"p","Test":"TestA"}
{"Action":"fail","Package":"p","Test":"TestTurnstileVerifyMatrix"}'
	expect_detector detect_go package-fail 1 '{"Action":"pass","Package":"p","Test":"TestA"}
{"Action":"fail","Package":"p"}'
	expect_detector detect_go build 1 '{"Action":"build-fail","ImportPath":"p"}'
	expect_detector detect_go skip 2 '{"Action":"pass","Package":"p","Test":"TestA"}
{"Action":"skip","Package":"p","Test":"TestCookieLogoutHandler"}'
	expect_detector detect_go zero 3 '{"Action":"pass","Package":"p"}'
	expect_detector detect_go no-tests 3 '{"Action":"output","Package":"p","Output":"testing: warning: no tests to run\n"}
{"Action":"pass","Package":"p"}'
	expect_detector detect_go nonjson 4 '{"Action":"pass",'
	REQUIRE_TESTS="TestTokenCookieAttributes TestTurnstileFormFields" expect_detector detect_go missing-named 5 \
		'{"Action":"pass","Package":"p","Test":"TestTokenCookieAttributes"}'
	REQUIRE_TESTS="TestTokenCookie" expect_detector detect_go prefix-is-not-the-test 5 \
		'{"Action":"pass","Package":"p","Test":"TestTokenCookieAttributes"}'
	REQUIRE_TESTS="TestRegistry" expect_detector detect_go subtest-is-not-the-test 5 \
		'{"Action":"pass","Package":"p","Test":"TestOuter/TestRegistry"}
{"Action":"pass","Package":"p","Test":"TestOther"}'

	local tok='TAP version 13
ok 1 - sitePurge: a plain test
ok 2 - sitePurge: escaped \# hash
1..2
# tests 2
# pass 2
# fail 0
# cancelled 0
# skipped 0
# todo 0'
	expect_detector detect_tap pass 0 "$tok"
	REQUIRE_NAMES=$'sitePurge: a plain test\nsitePurge: escaped # hash' expect_detector detect_tap named 0 "$tok"
	expect_detector detect_tap not-ok 1 'ok 1 - a
not ok 2 - b
# pass 1
# fail 1'
	expect_detector detect_tap nested-not-ok 1 '    not ok 1 - sub
ok 1 - a
# pass 1
# fail 0'
	expect_detector detect_tap fail-count 1 'ok 1 - a
# pass 1
# fail 1'
	expect_detector detect_tap cancelled 1 'ok 1 - a
# pass 1
# cancelled 1'
	expect_detector detect_tap skip 2 'ok 1 - a # SKIP later
# pass 1'
	expect_detector detect_tap todo-count 2 'ok 1 - a
# pass 1
# todo 1'
	expect_detector detect_tap zero 3 '# tests 0
# pass 0
# fail 0'
	expect_detector detect_tap no-output 3 ''
	REQUIRE_NAMES=$'sitePurge: a plain test\nmissing' expect_detector detect_tap missing-named 5 "$tok"

	grep -qF '"${PHASE193_REQUIRE_DOCKER:-0}" == "1"' "${BASH_SOURCE[0]}" || {
		echo "refuse: --all does not honour PHASE193_REQUIRE_DOCKER" >&2
		return 1
	}
	local mode
	for mode in self-test go docker plugins layers docs all; do
		grep -q -- "^	--$mode" "${BASH_SOURCE[0]}" || {
			echo "refuse: missing mode --$mode" >&2
			return 1
		}
	done
	echo "phase19.3 self-test passed"
}

require_dir() {
	[[ -d "$1" ]] || {
		echo "refuse: $2 $1 not found" >&2
		return 1
	}
}

run_go() {
	(cd "$ROOT" && go vet ./...)
	echo "vet: $ROOT"
	(cd "$ROOT" && go vet -tags summercms_s3 ./modules/lagoon/...)
	echo "vet -tags summercms_s3: $ROOT/modules/lagoon/..."
	go_short "$ROOT"
	go_named "$ROOT" ./modules/bouncer -short "${BOUNCER_TESTS[@]}"
	go_named "$ROOT" ./modules/surf -short "${SURF_TESTS[@]}"
	go_named "$ROOT" ./internal/build -short "${BUILD_TESTS[@]}"
	go_named "$ROOT" ./modules/lagoon/attach -short "${ATTACH_TESTS[@]}"
	go_named "$ROOT" ./modules/lagoon/attach "-short -tags summercms_s3" "${ATTACH_TESTS[@]}"
	go_named "$ROOT" ./modules/cooler -short "${COOLER_TESTS[@]}"
	echo "phase19.3 go passed"
}

docker_up() {
	command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1
}

run_docker() {
	if ! docker_up; then
		echo "refuse: the docker stage needs a reachable Docker daemon (testcontainers); run it on a Docker host" >&2
		return 1
	fi
	go_named "$ROOT" ./modules/cabana "-timeout 20m" "${DOCKER_CABANA_TESTS[@]}"
	go_named "$ROOT" ./modules/lagoon/attach "-timeout 20m" "${DOCKER_ATTACH_TESTS[@]}"
	go_named "$ROOT" ./modules/cooler "-timeout 20m" "${DOCKER_COOLER_TESTS[@]}"
	require_dir "$FAQ_PLUGIN" "FAQ plugin"
	require_dir "$MENU_PLUGIN" "menu plugin"
	require_dir "$JOURNAL_PLUGIN" "Journal plugin"
	go_named "$FAQ_PLUGIN" . "-timeout 20m" "${DOCKER_FAQ_TESTS[@]}"
	go_named "$MENU_PLUGIN" . "-timeout 20m" "${DOCKER_MENU_TESTS[@]}"
	go_named "$JOURNAL_PLUGIN" . "-timeout 20m" "${DOCKER_JOURNAL_TESTS[@]}"
	echo "phase19.3 docker passed"
}

run_plugins() {
	require_dir "$FAQ_PLUGIN" "FAQ plugin"
	require_dir "$MENU_PLUGIN" "menu plugin"
	require_dir "$JOURNAL_PLUGIN" "Journal plugin"
	local repo
	for repo in "$FAQ_PLUGIN" "$MENU_PLUGIN" "$JOURNAL_PLUGIN"; do
		go -C "$repo" vet ./...
		echo "vet: $repo"
		# The Docker suites skip here and run by name in the docker stage.
		go_short "$repo"
	done
	go_named "$FAQ_PLUGIN" ./controllers -short "${FAQ_CONTROLLERS_TESTS[@]}"
	go_named "$MENU_PLUGIN" ./controllers -short "${MENU_CONTROLLERS_TESTS[@]}"
	go_named "$JOURNAL_PLUGIN" . -short "${JOURNAL_ROOT_TESTS[@]}"
	go_named "$JOURNAL_PLUGIN" ./classes -short "${JOURNAL_CLASSES_TESTS[@]}"
	echo "phase19.3 plugins passed"
}

# pnpm_tap runs `pnpm -C <dir> test` (node --test, TAP) and checks the output
# with detect_tap. It never installs anything: when pnpm refuses to run
# because node_modules was installed against another store, it prints the
# offline, frozen-lockfile recovery and fails.
pnpm_tap() {
	local dir="$1" log rc=0 dc=0
	log="$(mktemp)"
	pnpm -C "$dir" test >"$log" 2>&1 || rc=$?
	if grep -q 'ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY' "$log"; then
		rm -f "$log"
		cat >&2 <<MSG
refuse: pnpm wants to reinstall node_modules in $dir (store-dir mismatch) and
aborted without a TTY. Restore the local install without changing the lockfile:
  pnpm -C "$dir" install --frozen-lockfile --offline --store-dir <the store named in node_modules/.modules.yaml without /v11>
then run this stage again.
MSG
		return 1
	fi
	detect_tap "$log" || dc=$?
	if [[ "$rc" -ne 0 || "$dc" -ne 0 ]]; then
		grep -E '^\s*(not ok|# )|Error' "$log" | tail -n 40 >&2 || true
		rm -f "$log"
		echo "refuse: pnpm test in $dir (test=$rc detect=$dc)" >&2
		return 1
	fi
	echo "tap: $(grep -E '^# (tests|pass|fail) ' "$log" | tr '\n' ' ')in $dir"
	rm -f "$log"
}

run_layers() {
	require_dir "$FAQ_LAYER" "FAQ layer"
	require_dir "$MENU_LAYER" "menu layer"
	require_dir "$JOURNAL_LAYER" "Journal layer"
	local file layer
	for file in "${LAYER_SHARED[@]}"; do
		for layer in "$MENU_LAYER" "$JOURNAL_LAYER"; do
			if ! cmp -s "$FAQ_LAYER/$file" "$layer/$file"; then
				echo "refuse: $file differs between $FAQ_LAYER and $layer (the shared files ship byte for byte)" >&2
				return 1
			fi
		done
	done
	echo "cmp: ${#LAYER_SHARED[@]} shared files identical in the three layers"
	for layer in "$FAQ_LAYER" "$MENU_LAYER" "$JOURNAL_LAYER"; do
		REQUIRE_NAMES="$(printf '%s\n' "${LAYER_REQUIRE[@]}")" pnpm_tap "$layer"
	done
	echo "phase19.3 layers passed"
}

# phase_base prints the parent of the phase's first commit; PHASE193_BASE
# overrides it.
phase_base() {
	if [[ -n "${PHASE193_BASE:-}" ]]; then
		echo "$PHASE193_BASE"
		return
	fi
	local first
	first="$(git -C "$ROOT" log --format=%H --reverse --grep='(19\.3' | head -n 1)"
	if [[ -z "$first" ]]; then
		echo "refuse: no commit of phase 19.3 found; set PHASE193_BASE" >&2
		return 1
	fi
	echo "${first}^"
}

run_docs() {
	go_named "$ROOT" ./cmd/summer "" TestDocsTree
	(cd "$ROOT" && go run ./cmd/summer docs:build --check)
	local base pattern hits
	base="$(phase_base)"
	pattern="$(IFS='|'; echo "${APP_NAMES[*]}")"
	# Lines this phase added to the framework (committed or not), planning
	# docs excluded.
	hits="$(git -C "$ROOT" diff "$base" -- . ':(exclude).planning' |
		grep -E '^\+' | grep -vE '^\+\+\+ ' | grep -inE "$pattern" || true)"
	if [[ -n "$hits" ]]; then
		printf '%s\n' "$hits" | head -n 20 >&2
		echo "refuse: framework lines added since $base name a consuming application" >&2
		return 1
	fi
	echo "names: no consuming application named in framework lines since $base"
	echo "phase19.3 docs passed"
}

run_all() {
	local stage
	for stage in self-test go plugins layers docs; do
		if bash "${BASH_SOURCE[0]}" "--$stage"; then
			echo "PASS $stage"
		else
			echo "FAIL $stage"
			exit 1
		fi
	done
	if docker_up; then
		if bash "${BASH_SOURCE[0]}" --docker; then
			echo "PASS docker"
		else
			echo "FAIL docker"
			exit 1
		fi
	elif [[ "${PHASE193_REQUIRE_DOCKER:-0}" == "1" ]]; then
		echo "FAIL docker: no reachable Docker daemon and PHASE193_REQUIRE_DOCKER=1"
		exit 1
	else
		cat >&2 <<'EOF'
************************************************************************
NOT RUN docker: no reachable Docker daemon on this host.
The testcontainers suites (Postgres and Redis) of the framework and the
plugins did NOT run. Run on a Docker host before /msd-verify-work:
  bash scripts/check-phase19.3.sh docker
************************************************************************
EOF
		echo "NOT RUN docker (Docker-host only; see the notice above)"
	fi
	echo "Phase 19.3 gate passed"
}

case "${1:---all}" in
	--self-test | self-test) run_self_test ;;
	--go | go) run_go ;;
	--docker | docker) run_docker ;;
	--plugins | plugins) run_plugins ;;
	--layers | layers) run_layers ;;
	--docs | docs) run_docs ;;
	--all | all) run_all ;;
	*) usage ;;
esac