@bensandee/tooling 0.66.0 → 0.68.0

package/dist/project-name-CNaAmafB.mjs

@@ -1,612 +0,0 @@
-import path from "node:path";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { execFileSync, spawnSync } from "node:child_process";
-import { z } from "zod";
-import { parse } from "yaml";
-//#region src/utils/debug.ts
-const REDACT_PATTERNS = [/x-access-token:[^\s@]+/g, /Authorization:\s*(?:token|Bearer)\s+\S+/gi];
-const debugOut = (msg) => console.error(msg);
-/** Redact secrets (tokens, credentials) from text before logging. */
-function redact(text) {
-	let result = text;
-	for (const pattern of REDACT_PATTERNS) result = result.replace(pattern, "[REDACTED]");
-	return result;
-}
-/** Check if verbose/debug mode is enabled via environment variables. */
-function isEnvVerbose() {
-	return process.env["TOOLING_DEBUG"] === "true";
-}
-/** Log a debug message when verbose mode is enabled. */
-function debug(config, message) {
-	if (config.verbose) debugOut(`[debug] ${message}`);
-}
-/** Log the result of an exec call when verbose mode is enabled. */
-function debugExec(config, label, result) {
-	if (!config.verbose) return;
-	const lines = [`[debug] ${redact(label)} (exit code ${String(result.exitCode)})`];
-	if (result.stdout.trim()) lines.push(`  stdout: ${redact(result.stdout.trim())}`);
-	if (result.stderr.trim()) lines.push(`  stderr: ${redact(result.stderr.trim())}`);
-	debugOut(lines.join("\n"));
-}
-//#endregion
-//#region src/docker-check/compose-yaml.ts
-/**
-* Parse a Docker Compose file as plain data.
-*
-* Compose defines its own merge tags — `!reset` and `!override` — which control how
-* values combine across layered `-f` files, and they may tag a scalar, a map or a
-* sequence (`ipam: !reset null`, `ports: !override [...]`). `yaml` doesn't know them,
-* and for an unknown tag it does not throw: it calls `process.emitWarning()` with code
-* `TAG_RESOLVE_FAILED` and then falls back to the default schema. That warning reached
-* every `bst repo:sync --check` and `bst docker:check` run in any repo whose overlay
-* used a merge tag — noise in every CI log, from a file bst went looking for itself.
-*
-* `logLevel: "silent"` suppresses those non-fatal warnings. It does not weaken parsing:
-* genuine syntax errors still throw, and a tagged value still resolves to its underlying
-* data. Callers here only read compose as data (service names, images, ports,
-* healthchecks, the top-level `name:`) and never re-serialize it, so the tag semantics
-* are irrelevant to them — which is why silencing beats registering the tags, whose
-* scalar/map/seq forms would need a six-entry matrix to model correctly.
-*
-* Do not drop the option; `test/docker-check/detect.test.ts` and `compose-lint.test.ts`
-* pin it by asserting no process warning is emitted.
-*/
-function parseComposeYaml(content) {
-	return parse(content, { logLevel: "silent" });
-}
-//#endregion
-//#region src/docker-check/compose-lint.ts
-const ComposeFileShape = z.looseObject({ name: z.unknown().optional() });
-/**
-* Compose files live by convention in `./` or `docker/`. The lint walks those
-* by default; if `.tooling.json#dockerCheck.composeFiles` overrides the
-* location, each listed file (and its parent dir) is also linted.
-*/
-const COMPOSE_DIR_CANDIDATES = [".", "docker"];
-/** Base compose file names whose project namespace defaults to dir basename. */
-const BASE_COMPOSE_FILES = /* @__PURE__ */ new Set([
-	"docker-compose.yml",
-	"docker-compose.yaml",
-	"compose.yml",
-	"compose.yaml"
-]);
-const COMPOSE_FILENAME_PATTERN = /^(?:docker-compose|compose).*\.(?:yml|yaml)$/;
-/**
-* Walk compose files in `targetDir` and report lint violations:
-*
-* - Rule A (`missing-name`): every override compose file must declare a
-*   top-level `name:` directive. Base files (docker-compose.yml etc.) are
-*   exempt — their default of dir-basename is fine — but overrides without
-*   `name:` silently inherit the base's project namespace, which is how a
-*   `compose down -v` against the check overlay wiped the prod-volume project.
-* - Rule B (`duplicate-name`): no two compose files in a single dir may
-*   declare the same `name:`. Base files participate in collision detection.
-*/
-function lintComposeFiles(targetDir, config) {
-	const issues = [];
-	const visitedDirs = /* @__PURE__ */ new Set();
-	const standaloneFiles = [];
-	const dockerCheck = config?.dockerCheck;
-	const isObjectConfig = dockerCheck !== void 0 && dockerCheck !== false;
-	for (const candidate of COMPOSE_DIR_CANDIDATES) {
-		const absDir = path.resolve(targetDir, candidate);
-		if (existsSync(absDir)) visitDir(targetDir, absDir, visitedDirs, issues);
-	}
-	if (isObjectConfig && dockerCheck.composeFiles) for (const rel of dockerCheck.composeFiles) {
-		const absFile = path.resolve(targetDir, rel);
-		if (!existsSync(absFile)) continue;
-		const dir = path.dirname(absFile);
-		if (visitedDirs.has(dir)) continue;
-		const basename = path.basename(absFile);
-		standaloneFiles.push({
-			absPath: absFile,
-			relPath: path.relative(targetDir, absFile),
-			basename
-		});
-	}
-	const standaloneByDir = /* @__PURE__ */ new Map();
-	for (const file of standaloneFiles) {
-		const dir = path.dirname(file.absPath);
-		const list = standaloneByDir.get(dir) ?? [];
-		list.push(file);
-		standaloneByDir.set(dir, list);
-	}
-	for (const files of standaloneByDir.values()) {
-		files.sort((a, b) => a.relPath.localeCompare(b.relPath));
-		lintDirFiles(files, issues);
-	}
-	return issues;
-}
-function visitDir(targetDir, absDir, visitedDirs, issues) {
-	if (visitedDirs.has(absDir)) return;
-	visitedDirs.add(absDir);
-	let entries;
-	try {
-		entries = readdirSync(absDir);
-	} catch (_error) {
-		return;
-	}
-	const files = entries.filter((name) => COMPOSE_FILENAME_PATTERN.test(name)).toSorted().map((name) => {
-		const absPath = path.join(absDir, name);
-		return {
-			absPath,
-			relPath: path.relative(targetDir, absPath),
-			basename: name
-		};
-	});
-	if (files.length === 0) return;
-	lintDirFiles(files, issues);
-}
-function lintDirFiles(files, issues) {
-	const namesByFile = /* @__PURE__ */ new Map();
-	for (const file of files) {
-		const declaredName = readTopLevelName(file.absPath);
-		namesByFile.set(file.relPath, declaredName);
-		if (!BASE_COMPOSE_FILES.has(file.basename) && (declaredName === void 0 || declaredName === "")) {
-			const suggested = suggestProjectName(file);
-			issues.push({
-				kind: "missing-name",
-				files: [file.relPath],
-				message: `${file.relPath}: override compose file is missing required top-level 'name:' directive.\n  Add: name: ${suggested}\n  Why: without an explicit name, this override inherits the base file's project namespace.\n  A 'docker compose down -v' against this override would target the base project's volumes\n  — which has caused production volume loss in the past.`
-			});
-		}
-	}
-	const filesByName = /* @__PURE__ */ new Map();
-	for (const [relPath, declaredName] of namesByFile) {
-		if (declaredName === void 0 || declaredName === "") continue;
-		const list = filesByName.get(declaredName) ?? [];
-		list.push(relPath);
-		filesByName.set(declaredName, list);
-	}
-	for (const [declaredName, dupFiles] of filesByName) {
-		if (dupFiles.length < 2) continue;
-		dupFiles.sort();
-		const [first, second, ...rest] = dupFiles;
-		const ext = rest.length > 0 ? `, ${rest.join(", ")}` : "";
-		issues.push({
-			kind: "duplicate-name",
-			files: dupFiles,
-			message: `${String(first)} and ${String(second)}${ext} both declare 'name: ${declaredName}'.\n  Each compose file in the same directory must declare a unique 'name:'.\n  Suggested fix: rename one (e.g. 'name: ${declaredName}-test' in one of them).`
-		});
-	}
-}
-/** Suggest a default name for an override file by stripping the variant from the filename. */
-function suggestProjectName(file) {
-	const parts = file.basename.replace(/\.(yml|yaml)$/, "").split(".");
-	const variant = parts[parts.length - 1];
-	if (parts.length > 1 && variant) return `<project>-${variant}`;
-	return "<project>-check";
-}
-function readTopLevelName(absPath) {
-	let raw;
-	try {
-		raw = readFileSync(absPath, "utf-8");
-	} catch (_error) {
-		return;
-	}
-	let yamlValue;
-	try {
-		yamlValue = parseComposeYaml(raw);
-	} catch (_error) {
-		return;
-	}
-	const parsed = ComposeFileShape.safeParse(yamlValue);
-	if (!parsed.success) return void 0;
-	const value = parsed.data.name;
-	if (typeof value !== "string") return void 0;
-	return value;
-}
-//#endregion
-//#region src/docker-check/executor.ts
-/** Create an executor that runs real commands, fetches, and manages process signals. */
-function createRealExecutor() {
-	return {
-		exec(file, args, options) {
-			const result = spawnSync(file, args, {
-				cwd: options?.cwd,
-				env: options?.env ? {
-					...process.env,
-					...options.env
-				} : void 0,
-				encoding: "utf-8",
-				stdio: [
-					"pipe",
-					"pipe",
-					"pipe"
-				]
-			});
-			return {
-				stdout: result.stdout ?? "",
-				stderr: result.stderr ?? "",
-				exitCode: result.status ?? 1
-			};
-		},
-		execInherit(file, args, options) {
-			execFileSync(file, args, {
-				cwd: options?.cwd,
-				env: options?.env ? {
-					...process.env,
-					...options.env
-				} : void 0,
-				stdio: "inherit"
-			});
-		},
-		fetch: globalThis.fetch,
-		now: () => Date.now(),
-		sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
-		onSignal(signal, handler) {
-			process.on(signal, handler);
-			return () => {
-				process.removeListener(signal, handler);
-			};
-		},
-		log: (msg) => console.log(msg),
-		logError: (msg) => console.error(msg)
-	};
-}
-//#endregion
-//#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(),
-	Health: z.string()
-});
-/** Build the `docker compose` base args from config. */
-function composeArgs(config) {
-	const args = [
-		"compose",
-		"--project-name",
-		config.projectName
-	];
-	for (const f of config.composeFiles) args.push("-f", f);
-	if (config.envFile) args.push("--env-file", config.envFile);
-	return args;
-}
-/**
-* Compose's unset-interpolation warning. The variable name is quoted, and the
-* quotes arrive backslash-escaped when stderr is a pipe (which it always is
-* here) but bare when it is a TTY — so both forms are accepted.
-*/
-const UNSET_VARIABLE_WARNING = /The\s+\\?"([^"\\]+)\\?"\s+variable is not set/g;
-/** Names of the interpolation variables compose warned were unset, in order, de-duplicated. */
-function parseUnsetVariables(stderr) {
-	const names = /* @__PURE__ */ new Set();
-	for (const match of stderr.matchAll(UNSET_VARIABLE_WARNING)) {
-		const name = match[1];
-		if (name) names.add(name);
-	}
-	return [...names];
-}
-/**
-* Ask compose which interpolation variables are unset, and map each to an empty
-* string so it can be injected into the child env of every later compose call.
-*
-* Compose warns `The "FOO" variable is not set` once per file per invocation —
-* including on `down` — for a `${FOO}` with no default. Nothing expressible in
-* the check overlay silences that: interpolation happens per-file, before the
-* merge. Setting the variable does silence it, and setting it to the *empty
-* string* is what compose already substitutes, so the value each container sees
-* is unchanged. A non-empty placeholder would not be: a service that dials
-* `${LYRION_HOST}` would start resolving a hostname where today it gets "".
-*
-* Detection is delegated to compose rather than re-implementing its grammar:
-* `config` has already consulted `--env-file` and the process env, so it reports
-* exactly the variables that still need filling, in every position (`image:`,
-* `ports:`, `volumes:`, …) and every form, with `$$` escapes and `${FOO:-def}`
-* defaults already accounted for. If the wording ever changes we fill nothing
-* and the warnings simply come back — a `${FOO:?required}` error is never masked.
-*
-* Variables already present in `config.env` are left alone: the free-port logic
-* owns PORT, and an empty string there would unbind the published port.
-*/
-function fillUnsetVariables(executor, config) {
-	const result = executor.exec("docker", [...composeArgs(config), "config"], {
-		cwd: config.cwd,
-		env: config.env
-	});
-	const filled = {};
-	for (const name of parseUnsetVariables(result.stderr)) {
-		if (config.env && name in config.env) continue;
-		filled[name] = "";
-	}
-	return filled;
-}
-/** Run the build command if configured. */
-function buildImages(executor, config) {
-	if (!config.buildCommand) return;
-	const [file, ...args] = config.buildCommand;
-	if (!file) return;
-	executor.execInherit(file, args, { cwd: config.buildCwd ?? config.compose.cwd });
-}
-/** Run the smoketest command against the running stack. */
-function runSmoketest(executor, config) {
-	if (!config.smoketest) return;
-	const [file, ...args] = config.smoketest;
-	if (!file) return;
-	executor.execInherit(file, args, {
-		cwd: config.smoketestCwd ?? config.compose.cwd,
-		env: config.compose.env
-	});
-}
-/** Start the compose stack in detached mode. */
-function composeUp(executor, config) {
-	executor.execInherit("docker", [
-		...composeArgs(config),
-		"up",
-		"-d"
-	], {
-		cwd: config.cwd,
-		env: config.env
-	});
-}
-/** Tear down the compose stack, removing volumes and orphans. Swallows errors. */
-function composeDown(executor, config) {
-	try {
-		executor.execInherit("docker", [
-			...composeArgs(config),
-			"down",
-			"-v",
-			"--remove-orphans"
-		], {
-			cwd: config.cwd,
-			env: config.env
-		});
-	} catch (_error) {}
-}
-/** Show logs for a specific service (or all services if not specified). Swallows errors. */
-function composeLogs(executor, config, service) {
-	try {
-		const args = [...composeArgs(config), "logs"];
-		if (service) args.push(service);
-		executor.execInherit("docker", args, {
-			cwd: config.cwd,
-			env: config.env
-		});
-	} catch (_error) {}
-}
-/**
-* Query container status via `docker compose ps --format json`.
-* Handles both JSON array and newline-delimited JSON (varies by docker compose version).
-*/
-function composePs(executor, config) {
-	const output = executor.exec("docker", [
-		...composeArgs(config),
-		"ps",
-		"--format",
-		"json"
-	], {
-		cwd: config.cwd,
-		env: config.env
-	}).stdout.trim();
-	if (!output) return [];
-	const ArraySchema = z.array(ContainerInfoSchema);
-	try {
-		const direct = ArraySchema.safeParse(JSON.parse(output));
-		if (direct.success) return direct.data;
-		const single = ContainerInfoSchema.safeParse(JSON.parse(output));
-		if (single.success) return [single.data];
-	} catch (_error) {}
-	try {
-		const joined = `[${output.split("\n").join(",")}]`;
-		const delimited = ArraySchema.safeParse(JSON.parse(joined));
-		return delimited.success ? delimited.data : [];
-	} catch (_error) {
-		return [];
-	}
-}
-//#endregion
-//#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";
-}
-/** Run a single HTTP health check, returning true if the validator passes. */
-async function checkHttpHealth(executor, check) {
-	try {
-		const response = await executor.fetch(check.url);
-		return await check.validate(response);
-	} catch (_error) {
-		return false;
-	}
-}
-//#endregion
-//#region src/docker-check/check.ts
-const DEFAULT_TIMEOUT_MS = 12e4;
-const DEFAULT_POLL_INTERVAL_MS = 5e3;
-/**
-* Fill any compose interpolation variable that is still unset with an empty
-* string, so `${FOO}` with no default stops warning on every compose call —
-* `up` and, after the check has already passed, teardown. See
-* `fillUnsetVariables` for why empty (not a placeholder) and why compose itself
-* decides which variables need it.
-*
-* This runs here rather than in the `docker:check` command so the env reaches
-* every compose invocation *and* the smoketest through one `CheckConfig`, and so
-* programmatic consumers of the `docker-check` export get it too.
-*/
-function withFilledVariables(executor, config) {
-	const filled = fillUnsetVariables(executor, config.compose);
-	const names = Object.keys(filled);
-	if (names.length === 0) return config;
-	executor.log(`Unset compose variables set to an empty string: ${names.join(", ")}. To supply real values, put them in ${config.compose.envFile ?? "docker-compose.check.env"} beside the compose file.`);
-	return {
-		...config,
-		compose: {
-			...config.compose,
-			env: {
-				...config.compose.env,
-				...filled
-			}
-		}
-	};
-}
-/** Probe any not-yet-healthy HTTP endpoints, flipping them to healthy in `healthStatus`. */
-async function updateHttpHealth(executor, healthChecks, healthStatus) {
-	for (const check of healthChecks) {
-		if (healthStatus.get(check.name)) continue;
-		if (await checkHttpHealth(executor, check)) {
-			healthStatus.set(check.name, true);
-			executor.log(`${check.name} is healthy!`);
-		}
-	}
-}
-/**
-* Run the configured smoketest (if any). Returns a failure `CheckResult` when
-* the smoketest fails (after dumping logs and cleaning up), or `null` on success
-* or when no smoketest is configured.
-*/
-function runSmoketestStep(executor, config, cleanup, startTime) {
-	if (!config.smoketest) return null;
-	const { compose } = config;
-	executor.log(`Running smoketest: ${config.smoketest.join(" ")}`);
-	try {
-		runSmoketest(executor, config);
-		executor.log("Smoketest passed!");
-		return null;
-	} catch (error) {
-		const message = error instanceof Error ? error.message : String(error);
-		executor.logError(`Smoketest failed: ${message}`);
-		for (const service of compose.services) composeLogs(executor, compose, service);
-		cleanup();
-		return {
-			success: false,
-			reason: "smoketest-failed",
-			message,
-			elapsedMs: executor.now() - startTime
-		};
-	}
-}
-/** Run the full Docker check lifecycle. */
-async function runDockerCheck(executor, rawConfig) {
-	const config = withFilledVariables(executor, rawConfig);
-	const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-	const pollIntervalMs = config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-	const { compose } = config;
-	const vc = { verbose: config.verbose ?? false };
-	debug(vc, `Compose files: ${compose.composeFiles.join(", ")}`);
-	debug(vc, `Services: ${compose.services.join(", ")}`);
-	debug(vc, `Health checks: ${config.healthChecks.map((c) => c.name).join(", ") || "(none)"}`);
-	debug(vc, `Timeout: ${String(timeoutMs)}ms, poll interval: ${String(pollIntervalMs)}ms`);
-	const cleanup = () => composeDown(executor, compose);
-	let cleaningUp = false;
-	const gracefulShutdown = () => {
-		if (cleaningUp) {
-			executor.log("Cleanup in progress, please wait...");
-			return;
-		}
-		cleaningUp = true;
-		executor.log("Interrupted — shutting down compose stack...");
-		cleanup();
-		process.exit(1);
-	};
-	const disposeInt = executor.onSignal("SIGINT", gracefulShutdown);
-	const disposeTerm = executor.onSignal("SIGTERM", gracefulShutdown);
-	try {
-		if (config.buildCommand) {
-			executor.log("Building images...");
-			buildImages(executor, config);
-		}
-		executor.log("Starting compose stack...");
-		const startTime = executor.now();
-		try {
-			composeUp(executor, compose);
-		} catch (error) {
-			const message = error instanceof Error ? error.message : String(error);
-			executor.logError(`Compose stack failed to start — dumping logs`);
-			for (const service of compose.services) composeLogs(executor, compose, service);
-			cleanup();
-			return {
-				success: false,
-				reason: "startup-failed",
-				message,
-				elapsedMs: executor.now() - startTime
-			};
-		}
-		executor.log(`Waiting for stack to be healthy (max ${timeoutMs / 1e3}s)...`);
-		let lastStatusLogTime = startTime;
-		const healthStatus = new Map(config.healthChecks.map((c) => [c.name, false]));
-		while (executor.now() - startTime < timeoutMs) {
-			const containers = composePs(executor, compose);
-			debug(vc, `compose ps: ${containers.length} container(s)`);
-			let allContainersHealthy = true;
-			for (const service of compose.services) {
-				const status = getContainerHealth(containers, service);
-				debug(vc, `Container ${service}: ${status || "(no healthcheck)"}`);
-				if (status === "unhealthy") {
-					executor.logError(`Container ${service} is unhealthy`);
-					composeLogs(executor, compose, service);
-					cleanup();
-					return {
-						success: false,
-						reason: "unhealthy-container",
-						message: service,
-						elapsedMs: executor.now() - startTime
-					};
-				}
-				if (status === "starting") allContainersHealthy = false;
-			}
-			await updateHttpHealth(executor, config.healthChecks, healthStatus);
-			if (allContainersHealthy && [...healthStatus.values()].every(Boolean)) {
-				const smoketestFailure = runSmoketestStep(executor, config, cleanup, startTime);
-				if (smoketestFailure) return smoketestFailure;
-				executor.log("Check successful! All systems operational.");
-				cleanup();
-				return {
-					success: true,
-					elapsedMs: executor.now() - startTime
-				};
-			}
-			const now = executor.now();
-			if (now - lastStatusLogTime >= 5e3) {
-				lastStatusLogTime = now;
-				const elapsed = Math.floor((now - startTime) / 1e3);
-				const parts = [compose.services.map((s) => `${s}=${getContainerHealth(containers, s)}`).join(", "), [...healthStatus.entries()].map(([name, ok]) => `${name}=${ok ? "OK" : "Pending"}`).join(", ")].filter(Boolean).join(" | ");
-				executor.log(`Waiting... (${elapsed}s elapsed). ${parts}`);
-			}
-			await executor.sleep(pollIntervalMs);
-		}
-		executor.logError("Timeout waiting for stack to become healthy");
-		for (const service of compose.services) composeLogs(executor, compose, service);
-		cleanup();
-		return {
-			success: false,
-			reason: "timeout",
-			message: "Exceeded timeout",
-			elapsedMs: executor.now() - startTime
-		};
-	} catch (error) {
-		cleanup();
-		return {
-			success: false,
-			reason: "error",
-			message: error instanceof Error ? error.message : String(error),
-			elapsedMs: 0
-		};
-	} finally {
-		disposeInt();
-		disposeTerm();
-	}
-}
-//#endregion
-//#region src/docker-check/project-name.ts
-/**
-* Derive the `docker compose --project-name` value for a check run.
-*
-* Always returns a unique, non-colliding namespace so a stray `compose down -v`
-* during the check cannot target volumes belonging to a long-running stack
-* sharing the same docker daemon (the failure mode that wiped prod volumes
-* when a CI runner bind-mounted /var/run/docker.sock and the check overlay
-* inherited the base file's `name:`).
-*
-* Format: `<sanitized-repo>-check-<suffix>` where suffix prefers a CI run id
-* for traceability and falls back to `process.pid` locally so two concurrent
-* `bst docker:check` invocations on the same machine don't collide.
-*/
-function deriveProjectName(repoName, env = process.env) {
-	return `${sanitize(repoName)}-check-${sanitize(env["GITHUB_RUN_ID"] ?? env["CI_RUN_ID"] ?? String(process.pid))}`;
-}
-function sanitize(name) {
-	return name.replace(/^@[^/]+\//, "").toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "repo";
-}
-//#endregion
-export { composeArgs as a, composePs as c, lintComposeFiles as d, parseComposeYaml as f, redact as g, isEnvVerbose as h, getContainerHealth as i, composeUp as l, debugExec as m, runDockerCheck as n, composeDown as o, debug as p, checkHttpHealth as r, composeLogs as s, deriveProjectName as t, createRealExecutor as u };