@bensandee/tooling 0.67.0 → 0.68.0

package/README.md

@@ -530,6 +530,16 @@ Two things follow from this that are worth knowing:
 
 `docker-compose.check.env` is exempt from the bst-hook's env-file deny rules, so an agent working in the repo can create and read it. It is a committed, placeholder-holding file for a throwaway stack — do not put real secrets in it.
 
+### Derived HTTP health checks
+
+A service with a published port but no compose-level `healthcheck:` automatically gets an HTTP health check — no configuration needed. That check is probed **from inside the service's own container network namespace** (`docker run --network container:<id> curlimages/curl ... http://localhost:<containerPort>/`), not from the process running `bst docker:check`.
+
+This matters because compose publishes a port in the _host's_ network namespace, not the caller's. On a normal developer machine those are the same thing, so probing `localhost:<hostPort>` directly works fine — but on a CI runner that shares the host's docker daemon over a mounted socket (the standard Forgejo/GitHub Actions runner shape), the job container's `localhost` is its own netns, and the published port is unreachable from it. Probing from inside the target's own namespace works in every topology, including that one.
+
+The probe image (`curlimages/curl`) is pinned by digest, and a `docker run` exit code of `125` (Docker's convention for "the daemon failed to start the container at all" — missing image, pull denied, daemon unreachable) fails the check immediately instead of waiting out the full timeout.
+
+**This only applies to auto-derived checks.** A health check you configure yourself via `.tooling.json`'s `dockerCheck.healthChecks` is still probed with a direct `fetch()` from wherever `bst docker:check` runs — an arbitrary user-supplied URL isn't necessarily compose-related at all, so making it reachable from the caller remains your responsibility.
+
 ### Library API
 
 The `@bensandee/tooling/docker-check` export provides utilities for checking Docker Compose stacks programmatically.

package/dist/bin.mjs

@@ -993,7 +993,7 @@ const DEFAULT_STALE_DAYS = 30;
 /** `.tooling.json#docs` — overrides only; a conventional repo omits the key. */
 const DocsConfigSchema = z.strictObject({
 	enforced: z.union([z.boolean(), z.array(z.string())]).optional().meta({ description: "Which discovered pairs fail the build. true = all; an array names active dirs (e.g. [\"docs/plans\"]); default false = every violation is advisory." }),
-	dirs: z.array(z.string()).optional().meta({ description: "Extra active doc dirs beyond convention (e.g. [\"docs/rfcs\"]). Each retires into its own completed/ subdir." }),
+	dirs: z.array(z.string()).optional().meta({ description: "Extra active doc dirs beyond convention (e.g. [\"docs/rfcs\"]). Each retires into its own retired/ subdir." }),
 	staleDays: z.number().int().nonnegative().optional().meta({ description: "Days before an untouched active doc is flagged (default 30; 0 disables the rule)." }),
 	staleEnforced: z.boolean().optional().meta({ description: "Make the staleness rule fatal inside an enforced pair (default false: staleness is always advisory)." })
 });
@@ -3337,7 +3337,7 @@ function buildManagedDevDeps(ctx) {
 	const devDeps = { ...rootDevDeps(ctx.config) };
 	if (!isMonorepo) Object.assign(devDeps, perPackageDevDeps(ctx.config));
 	if (ctx.config.stack !== "none" || ctx.config.ci === "forgejo") devDeps["@bensandee/config"] = isWorkspacePackage(ctx, "@bensandee/config") ? "workspace:*" : "0.13.1";
-	if (!isWorkspacePackage(ctx, "@bensandee/tooling")) devDeps["@bensandee/tooling"] = "0.67.0";
+	if (!isWorkspacePackage(ctx, "@bensandee/tooling")) devDeps["@bensandee/tooling"] = "0.68.0";
 	if (ctx.config.useEslintPlugin && ctx.config.stack !== "none") devDeps["@bensandee/eslint-plugin"] = isWorkspacePackage(ctx, "@bensandee/eslint-plugin") ? "workspace:*" : "0.13.2";
 	if (ctx.config.formatter === "oxfmt") devDeps["oxfmt"] = {
 		"@changesets/cli": "2.31.0",
@@ -6677,7 +6677,7 @@ const AGENT_RULES_TAIL = [
 	"",
 	"A plan's **directory** is the source of truth for whether it shipped — not its `Status:` line, not its checkboxes. Read the source it names.",
 	"",
-	"Retiring the plan is the last task of the plan. Move it into `completed/` (`docs/plan-foo.md` → `docs/completed/completed-foo.md`, not `completed-plan-foo.md`; date-prefixed superpowers plans keep their name), set `Status: **completed YYYY-MM-DD**`, and add a short \"Shipped:\" paragraph naming what landed and where the truth now lives. Pick the honest verb — `completed` / `superseded` / `abandoned` — and never fabricate a `Shipped:` paragraph for code that isn't in the tree. A plan that lands one phase of a larger spec retires the plan and leaves the spec open.",
+	"Retiring the plan is the last task of the plan. The **directory** encodes one binary — retired or not; the **status word** carries the outcome. Move it into `retired/` (`docs/plan-foo.md` → `docs/retired/completed-foo.md`, not `completed-plan-foo.md`; date-prefixed superpowers plans keep their name), set `Status: **completed YYYY-MM-DD**`, and add a short \"Shipped:\" paragraph naming what landed and where the truth now lives. Pick the honest verb — `completed` / `superseded` / `abandoned` / `rejected` — and never fabricate a `Shipped:` paragraph for code that isn't in the tree. A plan that lands one phase of a larger spec retires the plan and leaves the spec open.",
 	"",
 	"`bst docs:check` enforces the mechanical half (status ↔ directory, dated retirements, links, staleness). It cannot tell whether the code shipped — that's your job."
 ];
@@ -7137,43 +7137,73 @@ function parseHostPortSegment(segment) {
 		port: parsed
 	};
 }
-/** Parse a single port mapping string and extract the host port. */
+/** Parse the container-port portion of a mapping — a plain literal number. */
+function parseContainerPortSegment(segment) {
+	const parsed = Number.parseInt(segment.trim(), 10);
+	return Number.isNaN(parsed) ? void 0 : parsed;
+}
+/** Parse a single port mapping string and extract both the host and container ports. */
 function parsePortString(port) {
 	const withoutProtocol = port.split("/")[0];
 	if (!withoutProtocol) return void 0;
 	if (withoutProtocol.startsWith("${")) {
 		const close = withoutProtocol.indexOf("}");
 		if (close === -1) return void 0;
-		return parseHostPortSegment(withoutProtocol.slice(0, close + 1));
+		const hostPort = parseHostPortSegment(withoutProtocol.slice(0, close + 1));
+		const rest = withoutProtocol.slice(close + 1);
+		return {
+			hostPort,
+			containerPort: rest.startsWith(":") ? parseContainerPortSegment(rest.slice(1)) : void 0
+		};
 	}
 	const parts = withoutProtocol.split(":");
-	if (parts.length === 2) return parts[0] ? parseHostPortSegment(parts[0]) : void 0;
-	if (parts.length === 3) return parts[1] ? parseHostPortSegment(parts[1]) : void 0;
+	if (parts.length === 2) return {
+		hostPort: parts[0] ? parseHostPortSegment(parts[0]) : void 0,
+		containerPort: parts[1] ? parseContainerPortSegment(parts[1]) : void 0
+	};
+	if (parts.length === 3) return {
+		hostPort: parts[1] ? parseHostPortSegment(parts[1]) : void 0,
+		containerPort: parts[2] ? parseContainerPortSegment(parts[2]) : void 0
+	};
 }
 /**
-* Find the first usable host port from a service's port mappings, returning
-* either a literal `hostPort` or a `portEnvVar` (with its default as `hostPort`).
+* Find the first usable port mapping from a service's port mappings, returning
+* either a literal `hostPort` or a `portEnvVar` (with its default as `hostPort`),
+* plus the container-side port from that same mapping.
 */
 function findHostPort(ports) {
 	for (const port of ports ?? []) {
-		const extracted = extractHostPort(port);
+		const extracted = extractPortMapping(port);
 		if (!extracted) continue;
-		if (extracted.kind === "literal") return { hostPort: extracted.port };
+		const { hostPort, containerPort } = extracted;
+		if (hostPort === void 0) return { containerPort };
+		if (hostPort.kind === "literal") return {
+			hostPort: hostPort.port,
+			containerPort
+		};
 		return {
-			portEnvVar: extracted.name,
-			hostPort: extracted.default
+			portEnvVar: hostPort.name,
+			hostPort: hostPort.default,
+			containerPort
 		};
 	}
 	return {};
 }
-function extractHostPort(port) {
+/** Parse the container-side literal from a long-syntax `target:` value. */
+function parseLongSyntaxTarget(target) {
+	if (typeof target === "number") return target;
+	if (typeof target === "string") return parseContainerPortSegment(target);
+}
+function extractPortMapping(port) {
 	if (typeof port === "string") return parsePortString(port);
 	const published = port.published;
-	if (typeof published === "number") return {
-		kind: "literal",
-		port: published
+	return {
+		hostPort: typeof published === "number" ? {
+			kind: "literal",
+			port: published
+		} : typeof published === "string" ? parseHostPortSegment(published) : void 0,
+		containerPort: parseLongSyntaxTarget(port.target)
 	};
-	if (typeof published === "string") return parseHostPortSegment(published);
 }
 /** Parse compose files and return service info (names, ports, healthcheck presence). */
 function parseComposeServices(cwd, composeFiles) {
@@ -7191,10 +7221,12 @@ function parseComposeServices(cwd, composeFiles) {
 			const existing = serviceMap.get(name);
 			let hostPort = existing?.hostPort;
 			let portEnvVar = existing?.portEnvVar;
+			let containerPort = existing?.containerPort;
 			if (hostPort === void 0 && portEnvVar === void 0) {
 				const found = findHostPort(service.ports);
 				hostPort = found.hostPort;
 				portEnvVar = found.portEnvVar;
+				containerPort = found.containerPort;
 			}
 			const buildDockerfile = resolveBuildDockerfile(cwd, service.build);
 			serviceMap.set(name, {
@@ -7203,6 +7235,7 @@ function parseComposeServices(cwd, composeFiles) {
 				buildDockerfile: existing?.buildDockerfile ?? buildDockerfile,
 				hostPort,
 				portEnvVar,
+				containerPort,
 				hasHealthcheck: existing?.hasHealthcheck ?? service.healthcheck !== void 0
 			});
 		}
@@ -7312,22 +7345,28 @@ function isLocallyBuiltService(service, locallyBuiltImageNames) {
 	return false;
 }
 /**
-* Generate health checks from parsed services: services with exposed ports get
-* HTTP checks, unless they define a compose-level healthcheck.
+* Generate health checks from parsed services: services with a discoverable
+* container port get an HTTP check, unless they define a compose-level
+* healthcheck.
 *
-* `resolvedPorts` maps service names to ports allocated at runtime (for
-* `${PORT}`-parameterized services); a resolved port overrides the parsed
-* `hostPort` so the check URL targets the port the stack actually binds.
-*/
-function deriveHealthChecks(services, resolvedPorts = /* @__PURE__ */ new Map()) {
+* The check probes from inside the target's own network namespace
+* (`viaNetworkService`) rather than via the host-published port — a
+* host-published port is unreachable when `docker:check` itself runs inside a
+* container sharing the host's docker daemon (e.g. a Forgejo/GitHub Actions
+* runner), since compose publishes the port in the *host's* netns, not the
+* caller's. Gating on `containerPort` (a static literal from the compose file)
+* rather than `hostPort` also means this works even when the host side is
+* `${PORT}`-parameterized and not yet resolved.
+*/
+function deriveHealthChecks(services) {
 	const checks = [];
 	for (const s of services) {
 		if (s.hasHealthcheck) continue;
-		const port = resolvedPorts.get(s.name) ?? s.hostPort;
-		if (port === void 0) continue;
+		if (s.containerPort === void 0) continue;
 		checks.push({
 			name: s.name,
-			url: `http://localhost:${String(port)}/`
+			url: `http://localhost:${String(s.containerPort)}/`,
+			viaNetworkService: s.name
 		});
 	}
 	return checks;
@@ -7455,7 +7494,7 @@ function createFileReader() {
 function generateMigratePrompt(results, config, detected) {
 	const sections = [];
 	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
-	sections.push(`# Migration Prompt\n\n_Generated by \`@bensandee/tooling@0.67.0 repo:sync\` on ${timestamp}_\n`);
+	sections.push(`# Migration Prompt\n\n_Generated by \`@bensandee/tooling@0.68.0 repo:sync\` on ${timestamp}_\n`);
 	const changed = results.filter((r) => r.action === "created" || r.action === "updated" || r.action === "archived");
 	if (changed.length > 0) {
 		const items = changed.map((r) => {
@@ -10039,13 +10078,15 @@ function findFreePort() {
 //#endregion
 //#region src/docker-check/compose.ts
 /** Zod schema for a single container entry from `docker compose ps --format json`.
-*  State/ExitCode are optional: older compose versions may omit them, in which
-*  case exit-code checking degrades to the pre-existing health-only gating. */
+*  State/ExitCode/ID are optional: older compose versions may omit them, in which
+*  case exit-code checking degrades to the pre-existing health-only gating, and a
+*  network-namespace probe (which needs `ID`) simply can't run. */
 const ContainerInfoSchema = z.object({
 	Service: z.string(),
 	Health: z.string(),
 	State: z.string().optional(),
-	ExitCode: z.number().optional()
+	ExitCode: z.number().optional(),
+	ID: z.string().optional()
 });
 /** Build the `docker compose` base args from config. */
 function composeArgs(config) {
@@ -10149,15 +10190,52 @@ function composeDown(executor, config) {
 		});
 	} catch (_error) {}
 }
-/** Show logs for a specific service (or all services if not specified). Swallows errors. */
+/**
+* Show logs for a specific service (or all services if not specified). Captured
+* via `executor.exec` (not streamed via `execInherit`) and re-emitted through
+* `executor.log`/`executor.logError`, with an explicit "(no log output)" marker
+* when both streams come back empty — a streamed dump gives no way to tell "the
+* app produced nothing because nothing ever reached it" from "the dump itself
+* silently failed", which cost real debugging time chasing issue #300's
+* shared-daemon timeout (the derived HTTP probe never reached the app, so its
+* logs were empty on every failing run). Swallows errors.
+*/
 function composeLogs(executor, config, service) {
 	try {
 		const args = [...composeArgs(config), "logs"];
 		if (service) args.push(service);
-		executor.execInherit("docker", args, {
+		const result = executor.exec("docker", args, {
+			cwd: config.cwd,
+			env: config.env
+		});
+		executor.log(service ? `-- ${service} logs --` : "-- logs --");
+		if (result.stdout.trim()) executor.log(result.stdout);
+		if (result.stderr.trim()) executor.logError(result.stderr);
+		if (!result.stdout.trim() && !result.stderr.trim()) executor.log("(no log output)");
+	} catch (_error) {}
+}
+/**
+* Dump `docker compose ps -a` in its default plain-text table alongside
+* `composeLogs()` at every failure/timeout site — a container-state snapshot
+* (exit code, "Restarting", etc.) survives even when the target emitted no
+* logs at all, which is exactly what happened chasing issue #300's
+* shared-daemon timeout (the probe never reached the app, so `composeLogs()`
+* alone gave no signal). Swallows errors, matching `composeLogs()`.
+*/
+function composePsDump(executor, config) {
+	try {
+		const result = executor.exec("docker", [
+			...composeArgs(config),
+			"ps",
+			"-a"
+		], {
 			cwd: config.cwd,
 			env: config.env
 		});
+		executor.log("-- compose ps -a --");
+		if (result.stdout.trim()) executor.log(result.stdout);
+		if (result.stderr.trim()) executor.logError(result.stderr);
+		if (!result.stdout.trim() && !result.stderr.trim()) executor.log("(no ps output)");
 	} catch (_error) {}
 }
 /**
@@ -10193,6 +10271,51 @@ function composePs(executor, config) {
 }
 //#endregion
 //#region src/docker-check/health.ts
+/**
+* `docker run`'s exit code when the *daemon* fails to start the container at
+* all (image not found, pull access denied/timeout, daemon unreachable) —
+* Docker's own longstanding CLI convention, distinct from the containerized
+* process's own exit code (curl's own failure codes — e.g. 7 = connection
+* refused, 28 = timeout — live in a disjoint, lower range). A 125 here means
+* the probe itself is broken and must fail fast, not degrade to "keep
+* polling" for the full timeout — the exact silent-timeout symptom this
+* feature exists to fix.
+*/
+const DOCKER_RUN_START_FAILURE_EXIT_CODE = 125;
+/**
+* `curl`'s per-attempt connect/total timeout, in seconds, for the network-mode
+* probe. Deliberately short — polling already retries every `pollIntervalMs`
+* (5s by default, see `check.ts`), so a stuck probe should fail that one
+* attempt quickly rather than block the next poll.
+*/
+const PROBE_TIMEOUT_SECONDS = "5";
+/**
+* The image used to probe a service from inside its own network namespace
+* (`docker run --network container:<id> ...`). `curlimages/curl` is tiny,
+* official, and guaranteed to have `curl` — unlike the target service's own
+* image, which the derived-check feature must assume nothing about beyond
+* "listens on a port" (see `deriveHealthChecks()` in `detect.ts`).
+*
+* Why a dedicated pinned image instead of reusing something already present:
+* this repo builds no always-present agent/runner image to piggyback on, so
+* there's nothing guaranteed to already be on a CI runner's docker host the
+* way there might be elsewhere. The no-new-image alternative — `docker
+* compose exec <service> curl ...` against the target's own, already-pulled
+* image — was considered and rejected: it would require every target image
+* to ship both a shell and an HTTP client, an assumption the derived-check
+* feature is designed to avoid (it only activates for services with no
+* compose-level healthcheck at all, so it must assume as little as possible
+* about what's actually in that image).
+*
+* Pinned by digest, not a tag: a tag-pinned probe image would re-pull (and
+* could silently change) on every check run, reintroducing this exact
+* issue's silent-timeout symptom on the very shared-daemon CI runners it
+* targets, since registry egress is often restricted there. Resolved from
+* `curlimages/curl:8.21.0` (the latest stable tag as of 2026-07-16) via the
+* Docker Hub registry API — this is the digest of the multi-arch manifest
+* list, so `docker run` still resolves the correct platform automatically.
+*/
+const PROBE_IMAGE = "curlimages/curl@sha256:7c12af72ceb38b7432ab85e1a265cff6ae58e06f95539d539b654f2cfa64bb13";
 /** Look up the health status of a specific service from container info. */
 function getContainerHealth(containers, serviceName) {
 	return containers.find((c) => c.Service === serviceName)?.Health ?? "unknown";
@@ -10207,8 +10330,69 @@ function getContainerExitCode(containers, serviceName) {
 	if (container?.State !== "exited") return void 0;
 	return container.ExitCode;
 }
+/**
+* The container ID of a service, when reported (an older compose may omit `ID`).
+* Used to probe a service from inside its own network namespace via
+* `docker run --network container:<id>`.
+*/
+function getContainerId(containers, serviceName) {
+	return containers.find((c) => c.Service === serviceName)?.ID;
+}
+/**
+* Probe a service from inside its own network namespace via a throwaway
+* `docker run --network container:<id>` using the pinned curl probe image
+* (see `PROBE_IMAGE`) — this is what makes the check work when the caller
+* (e.g. a Forgejo runner sharing the host docker daemon) can't reach the
+* target's published host port directly. Deliberately *not* wrapped in the
+* blanket try/catch `checkHttpHealth`'s direct-`fetch()` path uses: a
+* docker-level probe failure (missing image, unreachable daemon) must
+* surface, not silently degrade to "keep polling" for the full timeout —
+* the exact symptom this feature exists to fix. See
+* `DOCKER_RUN_START_FAILURE_EXIT_CODE` for the 125-exit fail-fast path, and
+* `executor.exec` throwing outright (e.g. the `docker` binary missing) is
+* likewise left unhandled here, to propagate the same way.
+*
+* `--network container:<id>` (join the target's own namespace) rather than
+* `--network <project>_default` (join the compose project's network) needs no
+* project/network name derivation, and keeps working regardless of a custom
+* top-level `networks:` stanza or `network_mode: host` on the target — it
+* just joins whatever namespace the target is already in, whatever that is.
+*/
+async function checkHttpHealthViaNetwork(executor, compose, check, viaNetworkService, containers) {
+	const containerId = getContainerId(containers, viaNetworkService);
+	if (containerId === void 0) return false;
+	const result = executor.exec("docker", [
+		"run",
+		"--rm",
+		"--network",
+		`container:${containerId}`,
+		PROBE_IMAGE,
+		"curl",
+		"-s",
+		"-o",
+		"/dev/null",
+		"-w",
+		"%{http_code}",
+		"--connect-timeout",
+		PROBE_TIMEOUT_SECONDS,
+		"--max-time",
+		PROBE_TIMEOUT_SECONDS,
+		check.url
+	], {
+		cwd: compose.cwd,
+		env: compose.env
+	});
+	if (result.exitCode === DOCKER_RUN_START_FAILURE_EXIT_CODE) throw new UnexpectedError(`docker run failed to start the probe image ${PROBE_IMAGE}: ${result.stderr.trim() || "(no stderr captured)"}`);
+	const status = Number.parseInt(result.stdout, 10);
+	const httpResult = {
+		status: Number.isNaN(status) ? 0 : status,
+		ok: status >= 200 && status < 300
+	};
+	return await check.validate(httpResult);
+}
 /** Run a single HTTP health check, returning true if the validator passes. */
-async function checkHttpHealth(executor, check) {
+async function checkHttpHealth(executor, compose, check, containers) {
+	if (check.viaNetworkService !== void 0) return checkHttpHealthViaNetwork(executor, compose, check, check.viaNetworkService, containers);
 	try {
 		const response = await executor.fetch(check.url);
 		return await check.validate(response);
@@ -10248,10 +10432,10 @@ function withFilledVariables(executor, config) {
 	};
 }
 /** Probe any not-yet-healthy HTTP endpoints, flipping them to healthy in `healthStatus`. */
-async function updateHttpHealth(executor, healthChecks, healthStatus) {
+async function updateHttpHealth(executor, compose, healthChecks, healthStatus, containers) {
 	for (const check of healthChecks) {
 		if (healthStatus.get(check.name)) continue;
-		if (await checkHttpHealth(executor, check)) {
+		if (await checkHttpHealth(executor, compose, check, containers)) {
 			healthStatus.set(check.name, true);
 			executor.log(`${check.name} is healthy!`);
 		}
@@ -10273,6 +10457,7 @@ function runSmoketestStep(executor, config, cleanup, startTime) {
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		executor.logError(`Smoketest failed: ${message}`);
+		composePsDump(executor, compose);
 		for (const service of compose.services) composeLogs(executor, compose, service);
 		cleanup();
 		return {
@@ -10320,6 +10505,7 @@ async function runDockerCheck(executor, rawConfig) {
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
 			executor.logError(`Compose stack failed to start — dumping logs`);
+			composePsDump(executor, compose);
 			for (const service of compose.services) composeLogs(executor, compose, service);
 			cleanup();
 			return {
@@ -10344,6 +10530,7 @@ async function runDockerCheck(executor, rawConfig) {
 				if (status !== "" && status !== "unknown") sawHealthcheck = true;
 				if (status === "unhealthy") {
 					executor.logError(`Container ${service} is unhealthy`);
+					composePsDump(executor, compose);
 					composeLogs(executor, compose, service);
 					cleanup();
 					return {
@@ -10358,6 +10545,7 @@ async function runDockerCheck(executor, rawConfig) {
 				if (exitCode !== void 0 && exitCode !== 0) {
 					const message = `${service} exited with code ${String(exitCode)}`;
 					executor.logError(`Container ${message}`);
+					composePsDump(executor, compose);
 					composeLogs(executor, compose, service);
 					cleanup();
 					return {
@@ -10368,7 +10556,7 @@ async function runDockerCheck(executor, rawConfig) {
 					};
 				}
 			}
-			await updateHttpHealth(executor, config.healthChecks, healthStatus);
+			await updateHttpHealth(executor, compose, config.healthChecks, healthStatus, containers);
 			if (allContainersHealthy && [...healthStatus.values()].every(Boolean)) {
 				if (!settlePolled && config.healthChecks.length === 0 && !sawHealthcheck) {
 					settlePolled = true;
@@ -10395,6 +10583,7 @@ async function runDockerCheck(executor, rawConfig) {
 			await executor.sleep(pollIntervalMs);
 		}
 		executor.logError("Timeout waiting for stack to become healthy");
+		composePsDump(executor, compose);
 		for (const service of compose.services) composeLogs(executor, compose, service);
 		cleanup();
 		return {
@@ -10444,7 +10633,8 @@ function toHttpHealthChecks(checks) {
 	return checks.map((check) => ({
 		name: check.name,
 		url: check.url,
-		validate: async (res) => check.status ? res.status === check.status : res.ok
+		validate: async (res) => check.status ? res.status === check.status : res.ok,
+		viaNetworkService: check.viaNetworkService
 	}));
 }
 /** Write the generated check overlay to a temp file. Returns the absolute path. */
@@ -10523,24 +10713,15 @@ const dockerCheckCommand = defineCommand({
 		];
 		const portVarServices = services.filter((s) => s.portEnvVar === "PORT");
 		let composeEnv;
-		let healthChecks = defaults.healthChecks;
 		if (portVarServices.length > 0) {
 			if (portVarServices.length > 1) log.warn(`Multiple services reference \${PORT} (${portVarServices.map((s) => s.name).join(", ")}); they cannot share a host port.`);
 			const externalPort = process.env["PORT"] ?? (defaults.envFile !== void 0 ? composeEnvFileValue(composeCwd, defaults.envFile, "PORT") : void 0);
-			let resolvedPort;
-			if (externalPort !== void 0) {
-				log.info(`PORT is already set (${externalPort}) — using the configured value.`);
-				const parsed = Number.parseInt(externalPort, 10);
-				resolvedPort = Number.isNaN(parsed) ? void 0 : parsed;
-			} else {
-				resolvedPort = await findFreePort();
+			if (externalPort !== void 0) log.info(`PORT is already set (${externalPort}) — using the configured value.`);
+			else {
+				const resolvedPort = await findFreePort();
 				composeEnv = { PORT: String(resolvedPort) };
 				log.info(`Allocated free host port ${String(resolvedPort)} for \${PORT}.`);
 			}
-			if (resolvedPort !== void 0 && toolingConfig?.dockerCheck?.healthChecks === void 0) {
-				const port = resolvedPort;
-				healthChecks = deriveHealthChecks(services, new Map(portVarServices.map((s) => [s.name, port])));
-			}
 		}
 		try {
 			const config = {
@@ -10554,7 +10735,7 @@ const dockerCheckCommand = defineCommand({
 				},
 				buildCommand: defaults.buildCommand,
 				buildCwd: defaults.buildCwd,
-				healthChecks: healthChecks ? toHttpHealthChecks(healthChecks) : [],
+				healthChecks: defaults.healthChecks ? toHttpHealthChecks(defaults.healthChecks) : [],
 				smoketest: defaults.smoketest,
 				smoketestCwd: defaults.smoketestCwd,
 				timeoutMs: args.timeout ? Number.parseInt(args.timeout, 10) : defaults.timeoutMs,
@@ -12934,7 +13115,9 @@ const healthStatusCommand = defineCommand({
 //#endregion
 //#region src/docs-check/discover.ts
 const DOCS_ROOT = "docs";
-const RETIRED_DIR = "completed";
+/** Canonical retirement dir name: encodes the binary (retired or not); the outcome lives in the doc's Status line. */
+const RETIRED_DIR = "retired";
+const RETIRED_DIR_NAMES = [RETIRED_DIR, "completed"];
 /** A directory with one of these names holds plan/spec docs. */
 const PLAN_DIR_NAMES = /* @__PURE__ */ new Set(["plans", "specs"]);
 /** `docs/` is a general folder: only the `plan-` prefix is a tracked doc there. */
@@ -12951,7 +13134,7 @@ function listDocs(exec, dir, pattern) {
 	if (!entries) return [];
 	return entries.filter((e) => !e.isDirectory && e.name.endsWith(".md")).filter((e) => pattern?.test(e.name) ?? true).map((e) => `${dir}/${e.name}`).toSorted();
 }
-/** Every `plans`/`specs` directory under docs/, depth-limited, skipping completed/ dirs. */
+/** Every `plans`/`specs` directory under docs/, depth-limited, skipping retired/completed dirs. */
 function conventionalActiveDirs(exec) {
 	const found = [];
 	const walk = (dir, depth) => {
@@ -12959,7 +13142,7 @@ function conventionalActiveDirs(exec) {
 		const entries = exec.readDir(dir);
 		if (!entries) return;
 		for (const entry of entries) {
-			if (!entry.isDirectory || entry.name === RETIRED_DIR) continue;
+			if (!entry.isDirectory || RETIRED_DIR_NAMES.includes(entry.name)) continue;
 			const child = `${dir}/${entry.name}`;
 			if (PLAN_DIR_NAMES.has(entry.name)) found.push(child);
 			walk(child, depth + 1);
@@ -12977,18 +13160,20 @@ function discoverPairs(exec, config) {
 	for (const active of [...conventionalActiveDirs(exec), ...config.extraDirs]) candidates.push({
 		active,
 		retired: `${active}/${RETIRED_DIR}`,
+		retiredDirs: RETIRED_DIR_NAMES.map((name) => `${active}/${name}`),
 		enforced: isEnforced(active, config.enforced)
 	});
 	candidates.push({
 		active: DOCS_ROOT,
 		retired: `${DOCS_ROOT}/${RETIRED_DIR}`,
+		retiredDirs: RETIRED_DIR_NAMES.map((name) => `${DOCS_ROOT}/${name}`),
 		activePattern: LEGACY_ACTIVE_PATTERN,
 		enforced: isEnforced(DOCS_ROOT, config.enforced)
 	});
 	const seen = /* @__PURE__ */ new Set();
 	return candidates.filter((pair) => {
 		if (seen.has(pair.active)) return false;
-		if (!(listDocs(exec, pair.active, pair.activePattern).length > 0 || listDocs(exec, pair.retired).length > 0)) return false;
+		if (!(listDocs(exec, pair.active, pair.activePattern).length > 0 || pair.retiredDirs.some((dir) => listDocs(exec, dir).length > 0))) return false;
 		seen.add(pair.active);
 		return true;
 	});
@@ -13141,8 +13326,8 @@ function relativeLinks(body, fileDir) {
 }
 //#endregion
 //#region src/docs-check/rules.ts
-/** Status keywords that mean "this work is over" — the doc belongs in completed/. */
-const TERMINAL_STATUS = /\b(completed|shipped|superseded|abandoned|cancelled|canceled)\b/i;
+/** Status keywords that mean "this work is over" — the doc belongs in retired/. */
+const TERMINAL_STATUS = /\b(completed|shipped|superseded|abandoned|cancelled|canceled|rejected)\b/i;
 /**
 * Qualifiers that mean the work is still open, and which WIN over a terminal
 * keyword in the same status. A partially-landed umbrella spec reads
@@ -13154,7 +13339,7 @@ const TERMINAL_STATUS = /\b(completed|shipped|superseded|abandoned|cancelled|can
 */
 const OPEN_STATUS = /\b(partial|partially|in[ -]progress|wip|draft|approved|proposed|blocked|planned|open)\b/i;
 /** A terminal status must carry the date it landed, so history stays legible. */
-const TERMINAL_STATUS_DATED = /\b(completed|shipped|superseded|abandoned|cancelled|canceled)\b[^\n]*?\d{4}-\d{2}-\d{2}/i;
+const TERMINAL_STATUS_DATED = /\b(completed|shipped|superseded|abandoned|cancelled|canceled|rejected)\b[^\n]*?\d{4}-\d{2}-\d{2}/i;
 /**
 * The paragraph a retired doc owes its reader: where the truth lives now.
 * Deliberately loose at both ends — NOT anchored to line-start (docs run it
@@ -13163,7 +13348,7 @@ const TERMINAL_STATUS_DATED = /\b(completed|shipped|superseded|abandoned|cancell
 * only.**`). The rule is that a retired doc SAYS where the truth went; policing
 * its punctuation would only teach people to route around the check.
 */
-const RETIRE_PARAGRAPH = /(?:\*\*)?\b(?:Shipped|Superseded|Abandoned)\b\s*(?:[:—–]|--?\s)/i;
+const RETIRE_PARAGRAPH = /(?:\*\*)?\b(?:Shipped|Superseded|Abandoned|Rejected)\b\s*(?:[:—–]|--?\s)/i;
 /** `Status:` must appear in the doc's header, not buried in a code sample. */
 const STATUS_LINE = /^\s*(?:>\s*)?(?:\*\*)?Status(?:\*\*)?:\s*(.+)$/im;
 const STATUS_SCAN_LINES = 30;
@@ -13195,8 +13380,8 @@ function checkStatus(input, status) {
 	if (!terminal && isRetired) violations.push({
 		file,
 		rule: "R2 retired-but-not-done",
-		message: `Doc lives in \`completed/\` but its status ("${status}") doesn't say completed/shipped/superseded.`,
-		fix: "Set `Status: **completed YYYY-MM-DD**` (or superseded/abandoned) — or move it back to the active dir if it isn't actually done."
+		message: `Doc lives in \`${retiredDir}/\` but its status ("${status}") doesn't say completed/shipped/superseded/rejected.`,
+		fix: "Set `Status: **completed YYYY-MM-DD**` (or superseded/abandoned/rejected) — or move it back to the active dir if it isn't actually done."
 	});
 	if (isRetired && terminal && !TERMINAL_STATUS_DATED.test(status)) violations.push({
 		file,
@@ -13207,7 +13392,7 @@ function checkStatus(input, status) {
 	if (isRetired && terminal && !RETIRE_PARAGRAPH.test(body)) violations.push({
 		file,
 		rule: "R3 missing-retire-paragraph",
-		message: "Retired doc has no `Shipped:` / `Superseded:` / `Abandoned:` paragraph.",
+		message: "Retired doc has no `Shipped:` / `Superseded:` / `Abandoned:` / `Rejected:` paragraph.",
 		fix: "Add one after the Status line naming what landed and where the post-implementation truth now lives (CLAUDE.md, the source files, …)."
 	});
 	return violations;
@@ -13218,7 +13403,7 @@ function checkLinks(input) {
 		file: input.file,
 		rule: "R4 broken-link",
 		message: `Relative link \`${link.raw}\` doesn't resolve (looked for ${link.target}).`,
-		fix: "Fix the path — a doc moved into `completed/` sits one level deeper, so each `../` needs one more `../`. If the link points at something the work deleted, it can never be re-pathed: de-link it (plain code span)."
+		fix: "Fix the path — a doc moved into `retired/` sits one level deeper, so each `../` needs one more `../`. If the link points at something the work deleted, it can never be re-pathed: de-link it (plain code span)."
 	}));
 }
 /**
@@ -13266,7 +13451,7 @@ function checkPair(exec, pair, config, opts) {
 	const linkExists = (target) => exec.exists(target);
 	const violations = [];
 	const activeFiles = listDocs(exec, pair.active, pair.activePattern);
-	const retiredFiles = listDocs(exec, pair.retired);
+	const retiredFiles = pair.retiredDirs.flatMap((dir) => listDocs(exec, dir));
 	for (const [files, isRetired] of [[activeFiles, false], [retiredFiles, true]]) for (const file of files) {
 		const body = exec.readFile(file);
 		if (body === void 0) continue;
@@ -14474,7 +14659,7 @@ const issueDownloadCommand = defineCommand({
 * `local <sha>[-dirty]` otherwise — so an artifact built from the working tree
 * can't pass itself off as the published release whose version it carries.
 */
-const displayVersion = "0.67.0";
+const displayVersion = "0.68.0";
 const main = defineCommand({
 	meta: {
 		name: "bst",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bensandee/tooling",
-  "version": "0.67.0",
+  "version": "0.68.0",
   "description": "CLI tool to bootstrap and maintain standardized TypeScript project tooling",
   "license": "MIT",
   "repository": {

package/tooling.schema.json

@@ -344,7 +344,7 @@
               ]
             },
             "dirs": {
-              "description": "Extra active doc dirs beyond convention (e.g. [\"docs/rfcs\"]). Each retires into its own completed/ subdir.",
+              "description": "Extra active doc dirs beyond convention (e.g. [\"docs/rfcs\"]). Each retires into its own retired/ subdir.",
               "type": "array",
               "items": {
                 "type": "string"