@bensandee/tooling 0.17.0 → 0.19.0

package/README.md

@@ -162,17 +162,17 @@ import type {
 | `DetectedProjectState` | Detected existing project state (package manager, CI, etc.)                                     |
 | `LegacyConfig`         | Legacy config detection for migration                                                           |
 
-## Docker verification
+## Docker check
 
-The `@bensandee/tooling/docker-verify` export provides utilities for verifying Docker Compose stacks via health checks.
+The `@bensandee/tooling/docker-check` export provides utilities for checking Docker Compose stacks via health checks.
 
 ### Quick start
 
 ```ts
-import { createRealExecutor, runVerification } from "@bensandee/tooling/docker-verify";
-import type { VerifyConfig } from "@bensandee/tooling/docker-verify";
+import { createRealExecutor, runDockerCheck } from "@bensandee/tooling/docker-check";
+import type { CheckConfig } from "@bensandee/tooling/docker-check";
 
-const config: VerifyConfig = {
+const config: CheckConfig = {
   compose: {
     cwd: "./deploy",
     composeFiles: ["docker-compose.yaml"],
@@ -190,7 +190,7 @@ const config: VerifyConfig = {
   pollIntervalMs: 5_000,
 };
 
-const result = await runVerification(createRealExecutor(), config);
+const result = await runDockerCheck(createRealExecutor(), config);
 if (!result.success) {
   console.error(result.reason, result.message);
 }
@@ -200,7 +200,7 @@ if (!result.success) {
 
 | Export                                 | Description                                                       |
 | -------------------------------------- | ----------------------------------------------------------------- |
-| `runVerification(executor, config)`    | Full lifecycle: build, compose up, health check polling, teardown |
+| `runDockerCheck(executor, config)`     | Full lifecycle: build, compose up, health check polling, teardown |
 | `createRealExecutor()`                 | Production executor (real shell, fetch, timers)                   |
 | `composeUp(executor, config)`          | Start compose services                                            |
 | `composeDown(executor, config)`        | Stop and remove compose services                                  |
@@ -211,11 +211,11 @@ if (!result.success) {
 
 ### Types
 
-| Type                   | Description                                                                                |
-| ---------------------- | ------------------------------------------------------------------------------------------ |
-| `VerifyConfig`         | Full verification config (compose settings, build command, health checks, timeouts)        |
-| `ComposeConfig`        | Docker Compose settings (cwd, compose files, env file, services)                           |
-| `HttpHealthCheck`      | Health check definition (name, URL, validate function)                                     |
-| `VerifyResult`         | Result: `{ success: true, elapsedMs }` or `{ success: false, reason, message, elapsedMs }` |
-| `DockerVerifyExecutor` | Side-effect abstraction (exec, fetch, timers) for testability                              |
-| `ContainerInfo`        | Container status info from `composePs`                                                     |
+| Type                  | Description                                                                                |
+| --------------------- | ------------------------------------------------------------------------------------------ |
+| `CheckConfig`         | Full check config (compose settings, build command, health checks, timeouts)               |
+| `ComposeConfig`       | Docker Compose settings (cwd, compose files, env file, services)                           |
+| `HttpHealthCheck`     | Health check definition (name, URL, validate function)                                     |
+| `CheckResult`         | Result: `{ success: true, elapsedMs }` or `{ success: false, reason, message, elapsedMs }` |
+| `DockerCheckExecutor` | Side-effect abstraction (exec, fetch, timers) for testability                              |
+| `ContainerInfo`       | Container status info from `composePs`                                                     |

package/dist/bin.mjs

@@ -1,15 +1,16 @@
 #!/usr/bin/env node
-import { t as isExecSyncError } from "./exec-CC49vrkM.mjs";
+import { l as createRealExecutor$1, t as runDockerCheck, u as isExecSyncError } from "./check-VAgrEX2D.mjs";
 import { defineCommand, runMain } from "citty";
 import * as p from "@clack/prompts";
 import path from "node:path";
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import JSON5 from "json5";
 import { parse } from "jsonc-parser";
 import { z } from "zod";
-import { isMap, isSeq, parseDocument } from "yaml";
+import { isMap, isSeq, parse as parse$1, parseDocument, stringify } from "yaml";
 import { execSync } from "node:child_process";
 import { FatalError, TransientError, UnexpectedError } from "@bensandee/common";
+import { tmpdir } from "node:os";
 //#region src/types.ts
 const LEGACY_TOOLS = [
 	"eslint",
@@ -41,7 +42,7 @@ const TsconfigSchema = z.object({
 	include: z.array(z.string()).optional(),
 	exclude: z.array(z.string()).optional(),
 	files: z.array(z.string()).optional(),
-	references: z.array(z.object({ path: z.string() }).passthrough()).optional(),
+	references: z.array(z.object({ path: z.string() }).loose()).optional(),
 	compilerOptions: z.record(z.string(), z.unknown()).optional()
 }).loose();
 const RenovateSchema = z.object({
@@ -456,7 +457,7 @@ const DeclarativeHealthCheckSchema = z.object({
 	url: z.string(),
 	status: z.number().int().optional()
 });
-const DockerVerifyConfigSchema = z.object({
+const DockerCheckConfigSchema = z.object({
 	composeFiles: z.array(z.string()).optional(),
 	envFile: z.string().optional(),
 	services: z.array(z.string()).optional(),
@@ -495,7 +496,7 @@ const ToolingConfigSchema = z.object({
 		dockerfile: z.string(),
 		context: z.string().default(".")
 	})).optional(),
-	dockerVerify: DockerVerifyConfigSchema.optional()
+	dockerCheck: z.union([z.literal(false), DockerCheckConfigSchema]).optional()
 });
 /** Load saved tooling config from the target directory. Returns undefined if missing or invalid. */
 function loadToolingConfig(targetDir) {
@@ -656,7 +657,7 @@ function getAddedDevDepNames(config) {
 	const deps = { ...ROOT_DEV_DEPS };
 	if (config.structure !== "monorepo") Object.assign(deps, PER_PACKAGE_DEV_DEPS);
 	deps["@bensandee/config"] = "0.8.2";
-	deps["@bensandee/tooling"] = "0.17.0";
+	deps["@bensandee/tooling"] = "0.19.0";
 	if (config.formatter === "oxfmt") deps["oxfmt"] = "0.35.0";
 	if (config.formatter === "prettier") deps["prettier"] = "3.8.1";
 	addReleaseDeps(deps, config);
@@ -677,7 +678,7 @@ async function generatePackageJson(ctx) {
 	const devDeps = { ...ROOT_DEV_DEPS };
 	if (!isMonorepo) Object.assign(devDeps, PER_PACKAGE_DEV_DEPS);
 	devDeps["@bensandee/config"] = isWorkspacePackage(ctx, "@bensandee/config") ? "workspace:*" : "0.8.2";
-	devDeps["@bensandee/tooling"] = isWorkspacePackage(ctx, "@bensandee/tooling") ? "workspace:*" : "0.17.0";
+	devDeps["@bensandee/tooling"] = isWorkspacePackage(ctx, "@bensandee/tooling") ? "workspace:*" : "0.19.0";
 	if (ctx.config.useEslintPlugin) devDeps["@bensandee/eslint-plugin"] = isWorkspacePackage(ctx, "@bensandee/eslint-plugin") ? "workspace:*" : "0.9.2";
 	if (ctx.config.formatter === "oxfmt") devDeps["oxfmt"] = "0.35.0";
 	if (ctx.config.formatter === "prettier") devDeps["prettier"] = "3.8.1";
@@ -1266,6 +1267,34 @@ function mergeWorkflowSteps(existing, jobName, requiredSteps) {
 * Returns unchanged content if the job already exists, the file has an opt-out comment,
 * or the document can't be parsed.
 */
+/**
+* Ensure a `concurrency` block exists at the workflow top level.
+* Adds it if missing — never modifies an existing one.
+* Returns unchanged content if the file has an opt-out comment or can't be parsed.
+*/
+function ensureWorkflowConcurrency(existing, concurrency) {
+	if (isToolingIgnored(existing)) return {
+		content: existing,
+		changed: false
+	};
+	try {
+		const doc = parseDocument(existing);
+		if (doc.has("concurrency")) return {
+			content: existing,
+			changed: false
+		};
+		doc.set("concurrency", doc.createNode(concurrency));
+		return {
+			content: doc.toString(),
+			changed: true
+		};
+	} catch {
+		return {
+			content: existing,
+			changed: false
+		};
+	}
+}
 function addWorkflowJob(existing, jobName, jobConfig) {
 	if (isToolingIgnored(existing)) return {
 		content: existing,
@@ -1296,6 +1325,14 @@ function addWorkflowJob(existing, jobName, jobConfig) {
 }
 //#endregion
 //#region src/generators/ci.ts
+/** Build a GitHub Actions expression like `${{ expr }}` without triggering no-template-curly-in-string. */
+function actionsExpr$2(expr) {
+	return `\${{ ${expr} }}`;
+}
+const CI_CONCURRENCY = {
+	group: `ci-${actionsExpr$2("github.ref")}`,
+	"cancel-in-progress": actionsExpr$2("github.ref != 'refs/heads/main'")
+};
 function hasEnginesNode$2(ctx) {
 	const raw = ctx.read("package.json");
 	if (!raw) return false;
@@ -1309,6 +1346,10 @@ ${emailNotifications}on:
     branches: [main]
   pull_request:
 
+concurrency:
+  group: ci-${actionsExpr$2("github.ref")}
+  cancel-in-progress: ${actionsExpr$2("github.ref != 'refs/heads/main'")}
+
 jobs:
   check:
     runs-on: ubuntu-latest
@@ -1371,8 +1412,9 @@ async function generateCi(ctx) {
 		const existing = ctx.read(filePath);
 		if (existing) {
 			const merged = mergeWorkflowSteps(existing, "check", requiredCheckSteps(nodeVersionYaml));
-			const withComment = ensureSchemaComment(merged.content, isGitHub ? "github" : "forgejo");
-			if (merged.changed || withComment !== merged.content) {
+			const withConcurrency = ensureWorkflowConcurrency(merged.content, CI_CONCURRENCY);
+			const withComment = ensureSchemaComment(withConcurrency.content, isGitHub ? "github" : "forgejo");
+			if (merged.changed || withConcurrency.changed || withComment !== withConcurrency.content) {
 				ctx.write(filePath, withComment);
 				return {
 					filePath,
@@ -2312,7 +2354,7 @@ const SCHEMA_NPM_PATH = "@bensandee/config/schemas/forgejo-workflow.schema.json"
 const SCHEMA_LOCAL_PATH = ".vscode/forgejo-workflow.schema.json";
 const SETTINGS_PATH = ".vscode/settings.json";
 const SCHEMA_GLOB = ".forgejo/workflows/*.{yml,yaml}";
-const VscodeSettingsSchema = z.object({ "yaml.schemas": z.record(z.string(), z.unknown()).default({}) }).passthrough();
+const VscodeSettingsSchema = z.object({ "yaml.schemas": z.record(z.string(), z.unknown()).default({}) }).loose();
 function readSchemaFromNodeModules(targetDir) {
 	const candidate = path.join(targetDir, "node_modules", SCHEMA_NPM_PATH);
 	if (!existsSync(candidate)) return void 0;
@@ -4073,7 +4115,7 @@ function generateTags(version) {
 function imageRef(namespace, imageName, tag) {
 	return `${namespace}/${imageName}:${tag}`;
 }
-function log(message) {
+function log$1(message) {
 	console.log(message);
 }
 function debug(verbose, message) {
@@ -4114,22 +4156,22 @@ function runDockerBuild(executor, config) {
 	const repoName = readRepoName(executor, config.cwd);
 	if (config.packageDir) {
 		const pkg = readSinglePackageDocker(executor, config.cwd, config.packageDir, repoName);
-		log(`Building image for ${pkg.dir} (${pkg.imageName}:latest)...`);
+		log$1(`Building image for ${pkg.dir} (${pkg.imageName}:latest)...`);
 		buildImage(executor, pkg, config.cwd, config.verbose, config.extraArgs);
-		log(`Built ${pkg.imageName}:latest`);
+		log$1(`Built ${pkg.imageName}:latest`);
 		return { packages: [pkg] };
 	}
 	const packages = detectDockerPackages(executor, config.cwd, repoName);
 	if (packages.length === 0) {
-		log("No packages with docker config found");
+		log$1("No packages with docker config found");
 		return { packages: [] };
 	}
-	log(`Found ${packages.length} Docker package(s): ${packages.map((p) => p.dir).join(", ")}`);
+	log$1(`Found ${packages.length} Docker package(s): ${packages.map((p) => p.dir).join(", ")}`);
 	for (const pkg of packages) {
-		log(`Building image for ${pkg.dir} (${pkg.imageName}:latest)...`);
+		log$1(`Building image for ${pkg.dir} (${pkg.imageName}:latest)...`);
 		buildImage(executor, pkg, config.cwd, config.verbose, config.extraArgs);
 	}
-	log(`Built ${packages.length} image(s)`);
+	log$1(`Built ${packages.length} image(s)`);
 	return { packages };
 }
 /**
@@ -4153,35 +4195,35 @@ function runDockerPublish(executor, config) {
 	};
 	for (const pkg of packages) if (!pkg.version) throw new FatalError(`Package ${pkg.dir} has docker config but no version in package.json`);
 	if (!config.dryRun) {
-		log(`Logging in to ${config.registryHost}...`);
+		log$1(`Logging in to ${config.registryHost}...`);
 		const loginResult = executor.exec(`echo "${config.password}" | docker login ${config.registryHost} -u ${config.username} --password-stdin`);
 		if (loginResult.exitCode !== 0) throw new FatalError(`Docker login failed: ${loginResult.stderr}`);
-	} else log("[dry-run] Skipping docker login");
+	} else log$1("[dry-run] Skipping docker login");
 	const allTags = [];
 	try {
 		for (const pkg of packages) {
 			const tags = generateTags(pkg.version ?? "");
-			log(`${pkg.dir} v${pkg.version} → tags: ${tags.join(", ")}`);
+			log$1(`${pkg.dir} v${pkg.version} → tags: ${tags.join(", ")}`);
 			for (const tag of tags) {
 				const ref = imageRef(config.registryNamespace, pkg.imageName, tag);
 				allTags.push(ref);
-				log(`Tagging ${pkg.imageName} → ${ref}`);
+				log$1(`Tagging ${pkg.imageName} → ${ref}`);
 				const tagResult = executor.exec(`docker tag ${pkg.imageName} ${ref}`);
 				if (tagResult.exitCode !== 0) throw new FatalError(`docker tag failed: ${tagResult.stderr}`);
 				if (!config.dryRun) {
-					log(`Pushing ${ref}...`);
+					log$1(`Pushing ${ref}...`);
 					const pushResult = executor.exec(`docker push ${ref}`);
 					if (pushResult.exitCode !== 0) throw new FatalError(`docker push failed: ${pushResult.stderr}`);
-				} else log(`[dry-run] Skipping push for ${ref}`);
+				} else log$1(`[dry-run] Skipping push for ${ref}`);
 			}
 		}
 	} finally {
 		if (!config.dryRun) {
-			log(`Logging out from ${config.registryHost}...`);
+			log$1(`Logging out from ${config.registryHost}...`);
 			executor.exec(`docker logout ${config.registryHost}`);
 		}
 	}
-	log(`Published ${allTags.length} image tag(s)`);
+	log$1(`Published ${allTags.length} image tag(s)`);
 	return {
 		packages,
 		tags: allTags
@@ -4257,11 +4299,251 @@ const dockerBuildCommand = defineCommand({
 	}
 });
 //#endregion
+//#region src/docker-check/detect.ts
+/** Compose file names to scan, in priority order. */
+const COMPOSE_FILE_CANDIDATES = [
+	"docker-compose.yaml",
+	"docker-compose.yml",
+	"compose.yaml",
+	"compose.yml"
+];
+/** Zod schema for the subset of compose YAML we care about. */
+const ComposePortSchema = z.union([z.string(), z.object({
+	published: z.union([z.string(), z.number()]),
+	target: z.union([z.string(), z.number()]).optional()
+}).loose()]);
+const ComposeServiceSchema = z.object({
+	ports: z.array(ComposePortSchema).optional(),
+	healthcheck: z.unknown().optional()
+}).loose();
+const ComposeFileSchema = z.object({ services: z.record(z.string(), ComposeServiceSchema).optional() }).loose();
+/** Directories to scan for compose files, in priority order. */
+const COMPOSE_DIR_CANDIDATES = [".", "docker"];
+/** Detect which compose files exist at conventional paths.
+*  Returns the resolved directory and the matching file names. */
+function detectComposeFiles(cwd) {
+	for (const dir of COMPOSE_DIR_CANDIDATES) {
+		const absDir = path.resolve(cwd, dir);
+		const files = COMPOSE_FILE_CANDIDATES.filter((name) => existsSync(path.join(absDir, name)));
+		if (files.length > 0) return {
+			dir: absDir,
+			files
+		};
+	}
+	return {
+		dir: cwd,
+		files: []
+	};
+}
+/** Parse a single port mapping string and extract the host port. */
+function parsePortString(port) {
+	const withoutProtocol = port.split("/")[0];
+	if (!withoutProtocol) return void 0;
+	const parts = withoutProtocol.split(":");
+	if (parts.length === 2) {
+		const host = parts[0];
+		if (!host) return void 0;
+		const parsed = Number.parseInt(host, 10);
+		return Number.isNaN(parsed) ? void 0 : parsed;
+	}
+	if (parts.length === 3) {
+		const host = parts[1];
+		if (!host) return void 0;
+		const parsed = Number.parseInt(host, 10);
+		return Number.isNaN(parsed) ? void 0 : parsed;
+	}
+}
+/** Extract the host port from a compose port definition. */
+function extractHostPort(port) {
+	if (typeof port === "string") return parsePortString(port);
+	const published = port.published;
+	if (typeof published === "number") return published;
+	if (typeof published === "string") {
+		const parsed = Number.parseInt(published, 10);
+		return Number.isNaN(parsed) ? void 0 : parsed;
+	}
+}
+/** Parse compose files and return service info (names, ports, healthcheck presence). */
+function parseComposeServices(cwd, composeFiles) {
+	const serviceMap = /* @__PURE__ */ new Map();
+	for (const file of composeFiles) {
+		let parsed;
+		try {
+			const content = readFileSync(path.join(cwd, file), "utf-8");
+			parsed = ComposeFileSchema.safeParse(parse$1(content));
+		} catch (_error) {
+			continue;
+		}
+		if (!parsed.success || !parsed.data.services) continue;
+		for (const [name, service] of Object.entries(parsed.data.services)) {
+			const existing = serviceMap.get(name);
+			let hostPort = existing?.hostPort;
+			if (hostPort === void 0 && service.ports) for (const port of service.ports) {
+				const extracted = extractHostPort(port);
+				if (extracted !== void 0) {
+					hostPort = extracted;
+					break;
+				}
+			}
+			serviceMap.set(name, {
+				name,
+				hostPort,
+				hasHealthcheck: existing?.hasHealthcheck ?? service.healthcheck !== void 0
+			});
+		}
+	}
+	return [...serviceMap.values()];
+}
+/** Generate health checks from parsed services: services with exposed ports get HTTP checks, unless they define a compose-level healthcheck. */
+function deriveHealthChecks(services) {
+	return services.filter((s) => s.hostPort !== void 0 && !s.hasHealthcheck).map((s) => ({
+		name: s.name,
+		url: `http://localhost:${String(s.hostPort)}/`
+	}));
+}
+/** Check overlay file name patterns, matched against the base compose file name. */
+const CHECK_OVERLAY_PATTERNS = [(base) => base.replace(/\.(yaml|yml)$/, `.check.$1`)];
+/** Detect a user-provided check overlay file alongside the base compose file. */
+function detectCheckOverlay(dir, baseFile) {
+	for (const pattern of CHECK_OVERLAY_PATTERNS) {
+		const candidate = pattern(baseFile);
+		if (existsSync(path.join(dir, candidate))) return candidate;
+	}
+}
+/** Detect a check env file in the compose directory. */
+function detectCheckEnvFile(dir) {
+	if (existsSync(path.join(dir, "docker-compose.check.env"))) return "docker-compose.check.env";
+}
+/** Fast healthcheck intervals for the generated check overlay. */
+const CHECK_HEALTHCHECK = {
+	interval: "5s",
+	timeout: "5s",
+	retries: 12,
+	start_period: "10s",
+	start_interval: "5s"
+};
+/**
+* Generate a check overlay YAML string from parsed services.
+* Sets `restart: "no"` on all services, and overrides healthcheck intervals
+* for services that define a healthcheck in the base compose file.
+*/
+function generateCheckOverlay(services) {
+	const serviceOverrides = {};
+	for (const service of services) {
+		const override = { restart: "no" };
+		if (service.hasHealthcheck) override["healthcheck"] = { ...CHECK_HEALTHCHECK };
+		serviceOverrides[service.name] = override;
+	}
+	return stringify({ services: serviceOverrides });
+}
+/** Auto-detect compose config from conventional file locations. */
+function computeCheckDefaults(cwd) {
+	const { dir, files } = detectComposeFiles(cwd);
+	if (files.length === 0) return {};
+	const baseFile = files[0];
+	const checkOverlay = baseFile ? detectCheckOverlay(dir, baseFile) : void 0;
+	const envFile = detectCheckEnvFile(dir);
+	const services = parseComposeServices(dir, files);
+	const healthChecks = deriveHealthChecks(services);
+	return {
+		composeCwd: dir !== cwd ? dir : void 0,
+		composeFiles: files,
+		checkOverlay,
+		envFile,
+		services: services.map((s) => s.name),
+		healthChecks: healthChecks.length > 0 ? healthChecks : void 0
+	};
+}
+//#endregion
+//#region src/commands/docker-check.ts
+/** Convert declarative health checks to functional ones. */
+function toHttpHealthChecks(checks) {
+	return checks.map((check) => ({
+		name: check.name,
+		url: check.url,
+		validate: async (res) => check.status ? res.status === check.status : res.ok
+	}));
+}
+/** Write the generated check overlay to a temp file. Returns the absolute path. */
+function writeTempOverlay(content) {
+	const name = `tooling-check-overlay-${process.pid}.yaml`;
+	const filePath = path.join(tmpdir(), name);
+	writeFileSync(filePath, content, "utf-8");
+	return filePath;
+}
+function log(message) {
+	console.log(message);
+}
+function warn(message) {
+	console.warn(message);
+}
+const dockerCheckCommand = defineCommand({
+	meta: {
+		name: "docker:check",
+		description: "Check Docker Compose stack health by auto-detecting services from compose files"
+	},
+	args: {
+		timeout: {
+			type: "string",
+			description: "Maximum time to wait for health checks, in ms (default: 120000)"
+		},
+		"poll-interval": {
+			type: "string",
+			description: "Interval between polling attempts, in ms (default: 5000)"
+		}
+	},
+	async run({ args }) {
+		const cwd = process.cwd();
+		if (loadToolingConfig(cwd)?.dockerCheck === false) {
+			log("Docker check is disabled in .tooling.json");
+			return;
+		}
+		const defaults = computeCheckDefaults(cwd);
+		if (!defaults.composeFiles || defaults.composeFiles.length === 0) throw new FatalError("No compose files found. Expected docker-compose.yaml or compose.yaml in ./ or docker/.");
+		if (!defaults.checkOverlay) {
+			const composeCwd = defaults.composeCwd ?? cwd;
+			const expectedOverlay = (defaults.composeFiles[0] ?? "docker-compose.yaml").replace(/\.(yaml|yml)$/, ".check.$1");
+			warn(`Compose files found but no check overlay. Create ${path.relative(cwd, path.join(composeCwd, expectedOverlay))} to enable docker:check.`);
+			warn("To suppress this warning, set \"dockerCheck\": false in .tooling.json.");
+			return;
+		}
+		if (!defaults.services || defaults.services.length === 0) throw new FatalError("No services found in compose files.");
+		const composeCwd = defaults.composeCwd ?? cwd;
+		const tempOverlayPath = writeTempOverlay(generateCheckOverlay(parseComposeServices(composeCwd, defaults.composeFiles)));
+		const composeFiles = [
+			...defaults.composeFiles,
+			tempOverlayPath,
+			defaults.checkOverlay
+		];
+		try {
+			const config = {
+				compose: {
+					cwd: composeCwd,
+					composeFiles,
+					envFile: defaults.envFile,
+					services: defaults.services
+				},
+				buildCommand: defaults.buildCommand,
+				buildCwd: defaults.buildCwd,
+				healthChecks: defaults.healthChecks ? toHttpHealthChecks(defaults.healthChecks) : [],
+				timeoutMs: args.timeout ? Number.parseInt(args.timeout, 10) : defaults.timeoutMs,
+				pollIntervalMs: args["poll-interval"] ? Number.parseInt(args["poll-interval"], 10) : defaults.pollIntervalMs
+			};
+			const result = await runDockerCheck(createRealExecutor$1(), config);
+			if (!result.success) throw new FatalError(`Check failed (${result.reason}): ${result.message}`);
+		} finally {
+			try {
+				unlinkSync(tempOverlayPath);
+			} catch (_error) {}
+		}
+	}
+});
+//#endregion
 //#region src/bin.ts
 const main = defineCommand({
 	meta: {
 		name: "tooling",
-		version: "0.17.0",
+		version: "0.19.0",
 		description: "Bootstrap and maintain standardized TypeScript project tooling"
 	},
 	subCommands: {
@@ -4273,10 +4555,11 @@ const main = defineCommand({
 		"changesets:merge": releaseMergeCommand,
 		"release:simple": releaseSimpleCommand,
 		"docker:publish": publishDockerCommand,
-		"docker:build": dockerBuildCommand
+		"docker:build": dockerBuildCommand,
+		"docker:check": dockerCheckCommand
 	}
 });
-console.log(`@bensandee/tooling v0.17.0`);
+console.log(`@bensandee/tooling v0.19.0`);
 runMain(main);
 //#endregion
 export {};

package/dist/{docker-verify/index.mjs → check-VAgrEX2D.mjs}

@@ -1,7 +1,12 @@
-import { t as isExecSyncError } from "../exec-CC49vrkM.mjs";
 import { z } from "zod";
 import { execSync } from "node:child_process";
-//#region src/docker-verify/executor.ts
+//#region src/utils/exec.ts
+/** Type guard for `execSync` errors that carry stdout/stderr/status. */
+function isExecSyncError(err) {
+	return err instanceof Error && "stdout" in err && typeof err.stdout === "string" && "stderr" in err && typeof err.stderr === "string" && "status" in err && typeof err.status === "number";
+}
+//#endregion
+//#region src/docker-check/executor.ts
 /** Create an executor that runs real commands, fetches, and manages process signals. */
 function createRealExecutor() {
 	return {
@@ -61,7 +66,7 @@ function createRealExecutor() {
 	};
 }
 //#endregion
-//#region src/docker-verify/compose.ts
+//#region src/docker-check/compose.ts
 /** Zod schema for a single container entry from `docker compose ps --format json`. */
 const ContainerInfoSchema = z.object({
 	Service: z.string(),
@@ -116,7 +121,7 @@ function composePs(executor, config) {
 	}
 }
 //#endregion
-//#region src/docker-verify/health.ts
+//#region src/docker-check/health.ts
 /** 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";
@@ -131,11 +136,11 @@ async function checkHttpHealth(executor, check) {
 	}
 }
 //#endregion
-//#region src/docker-verify/verify.ts
+//#region src/docker-check/check.ts
 const DEFAULT_TIMEOUT_MS = 12e4;
 const DEFAULT_POLL_INTERVAL_MS = 5e3;
-/** Run the full Docker image verification lifecycle. */
-async function runVerification(executor, config) {
+/** Run the full Docker check lifecycle. */
+async function runDockerCheck(executor, config) {
 	const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
 	const pollIntervalMs = config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
 	const { compose } = config;
@@ -178,7 +183,7 @@ async function runVerification(executor, config) {
 				}
 			}
 			if ([...healthStatus.values()].every(Boolean)) {
-				executor.log("Verification successful! All systems operational.");
+				executor.log("Check successful! All systems operational.");
 				cleanup();
 				return {
 					success: true,
@@ -215,4 +220,4 @@ async function runVerification(executor, config) {
 	}
 }
 //#endregion
-export { checkHttpHealth, composeCommand, composeDown, composeLogs, composePs, composeUp, createRealExecutor, getContainerHealth, runVerification };
+export { composeDown as a, composeUp as c, composeCommand as i, createRealExecutor as l, checkHttpHealth as n, composeLogs as o, getContainerHealth as r, composePs as s, runDockerCheck as t, isExecSyncError as u };

package/dist/{docker-verify → docker-check}/index.d.mts

@@ -13,9 +13,9 @@ interface ExecOptions {
   env?: Record<string, string>;
 }
 //#endregion
-//#region src/docker-verify/types.d.ts
+//#region src/docker-check/types.d.ts
 /** Abstraction over side effects for testability. */
-interface DockerVerifyExecutor {
+interface DockerCheckExecutor {
   /** Run a shell command and return the result (stdout/stderr captured). */
   exec(command: string, options?: ExecOptions): ExecResult;
   /** Run a shell command, streaming stdout/stderr to the console. */
@@ -46,15 +46,15 @@ interface HttpHealthCheck {
 interface ComposeConfig {
   /** Working directory for docker compose commands. */
   cwd: string;
-  /** Compose files to use (e.g. ["docker-compose.yaml", "docker-compose.verify.yaml"]). */
+  /** Compose files to use (e.g. ["docker-compose.yaml", "docker-compose.check.yaml"]). */
   composeFiles: string[];
   /** Optional env file for compose. */
   envFile?: string;
   /** Service names to monitor for container-level health. */
   services: string[];
 }
-/** Full verification configuration. */
-interface VerifyConfig {
+/** Full docker check configuration. */
+interface CheckConfig {
   /** Docker compose settings. */
   compose: ComposeConfig;
   /** Optional build command to run before starting compose (e.g. "pnpm image:build"). */
@@ -68,8 +68,8 @@ interface VerifyConfig {
   /** Interval between polling attempts, in ms. Default: 5000. */
   pollIntervalMs?: number;
 }
-/** Result of the verification run. */
-type VerifyResult = {
+/** Result of the docker check run. */
+type CheckResult = {
   success: true;
   elapsedMs: number;
 } | {
@@ -79,15 +79,15 @@ type VerifyResult = {
   elapsedMs: number;
 };
 //#endregion
-//#region src/docker-verify/executor.d.ts
+//#region src/docker-check/executor.d.ts
 /** Create an executor that runs real commands, fetches, and manages process signals. */
-declare function createRealExecutor(): DockerVerifyExecutor;
+declare function createRealExecutor(): DockerCheckExecutor;
 //#endregion
-//#region src/docker-verify/verify.d.ts
-/** Run the full Docker image verification lifecycle. */
-declare function runVerification(executor: DockerVerifyExecutor, config: VerifyConfig): Promise<VerifyResult>;
+//#region src/docker-check/check.d.ts
+/** Run the full Docker check lifecycle. */
+declare function runDockerCheck(executor: DockerCheckExecutor, config: CheckConfig): Promise<CheckResult>;
 //#endregion
-//#region src/docker-verify/compose.d.ts
+//#region src/docker-check/compose.d.ts
 /** Zod schema for a single container entry from `docker compose ps --format json`. */
 declare const ContainerInfoSchema: z.ZodObject<{
   Service: z.ZodString;
@@ -97,21 +97,21 @@ type ContainerInfo = z.infer<typeof ContainerInfoSchema>;
 /** Build the `docker compose` base command string from config. */
 declare function composeCommand(config: ComposeConfig): string;
 /** Start the compose stack in detached mode. */
-declare function composeUp(executor: DockerVerifyExecutor, config: ComposeConfig): void;
+declare function composeUp(executor: DockerCheckExecutor, config: ComposeConfig): void;
 /** Tear down the compose stack, removing volumes and orphans. Swallows errors. */
-declare function composeDown(executor: DockerVerifyExecutor, config: ComposeConfig): void;
+declare function composeDown(executor: DockerCheckExecutor, config: ComposeConfig): void;
 /** Show logs for a specific service (or all services if not specified). Swallows errors. */
-declare function composeLogs(executor: DockerVerifyExecutor, config: ComposeConfig, service?: string): void;
+declare function composeLogs(executor: DockerCheckExecutor, config: ComposeConfig, service?: string): void;
 /**
  * Query container status via `docker compose ps --format json`.
  * Handles both JSON array and newline-delimited JSON (varies by docker compose version).
  */
-declare function composePs(executor: DockerVerifyExecutor, config: ComposeConfig): ContainerInfo[];
+declare function composePs(executor: DockerCheckExecutor, config: ComposeConfig): ContainerInfo[];
 //#endregion
-//#region src/docker-verify/health.d.ts
+//#region src/docker-check/health.d.ts
 /** Look up the health status of a specific service from container info. */
 declare function getContainerHealth(containers: ContainerInfo[], serviceName: string): string;
 /** Run a single HTTP health check, returning true if the validator passes. */
-declare function checkHttpHealth(executor: DockerVerifyExecutor, check: HttpHealthCheck): Promise<boolean>;
+declare function checkHttpHealth(executor: DockerCheckExecutor, check: HttpHealthCheck): Promise<boolean>;
 //#endregion
-export { type ComposeConfig, type ContainerInfo, type DockerVerifyExecutor, type HttpHealthCheck, type VerifyConfig, type VerifyResult, checkHttpHealth, composeCommand, composeDown, composeLogs, composePs, composeUp, createRealExecutor, getContainerHealth, runVerification };
+export { type CheckConfig, type CheckResult, type ComposeConfig, type ContainerInfo, type DockerCheckExecutor, type HttpHealthCheck, checkHttpHealth, composeCommand, composeDown, composeLogs, composePs, composeUp, createRealExecutor, getContainerHealth, runDockerCheck };

package/dist/docker-check/index.mjs

@@ -0,0 +1,2 @@
+import { a as composeDown, c as composeUp, i as composeCommand, l as createRealExecutor, n as checkHttpHealth, o as composeLogs, r as getContainerHealth, s as composePs, t as runDockerCheck } from "../check-VAgrEX2D.mjs";
+export { checkHttpHealth, composeCommand, composeDown, composeLogs, composePs, composeUp, createRealExecutor, getContainerHealth, runDockerCheck };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bensandee/tooling",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "CLI tool to bootstrap and maintain standardized TypeScript project tooling",
   "bin": {
     "tooling": "./dist/bin.mjs"
@@ -18,9 +18,9 @@
       "default": "./dist/index.mjs"
     },
     "./bin": "./dist/bin.mjs",
-    "./docker-verify": {
-      "types": "./dist/docker-verify/index.d.mts",
-      "default": "./dist/docker-verify/index.mjs"
+    "./docker-check": {
+      "types": "./dist/docker-check/index.d.mts",
+      "default": "./dist/docker-check/index.mjs"
     },
     "./package.json": "./package.json"
   },

package/dist/exec-CC49vrkM.mjs

@@ -1,7 +0,0 @@
-//#region src/utils/exec.ts
-/** Type guard for `execSync` errors that carry stdout/stderr/status. */
-function isExecSyncError(err) {
-	return err instanceof Error && "stdout" in err && typeof err.stdout === "string" && "stderr" in err && typeof err.stderr === "string" && "status" in err && typeof err.status === "number";
-}
-//#endregion
-export { isExecSyncError as t };