@bensandee/tooling 0.33.0 → 0.34.0

package/README.md

@@ -32,7 +32,7 @@ The tool auto-detects project structure, CI platform, project type, and Docker p
 | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `tooling repo:sync [dir]`         | Detect, generate, and sync project tooling (idempotent). First run prompts for release strategy, CI platform (if not detected), and formatter (if Prettier found). Subsequent runs are non-interactive. |
 | `tooling repo:sync --check [dir]` | Dry-run drift detection. Exits 1 if files would change. CI-friendly.                                                                                                                                    |
-| `tooling checks:run`              | Run project checks (build, docker:build, typecheck, lint, test, format, knip, tooling:check, docker:check). Flags: `--skip`, `--add`, `--fail-fast`.                                                    |
+| `tooling checks:run`              | Run project checks (build, docker:build, typecheck, lint, test, format, knip, tooling:check, docker:check). Flags: `--skip`, `--add`, `--fail-fast`, `--verbose`.                                       |
 
 **Flags:** `--yes` (accept all defaults), `--no-ci`, `--no-prompt`, `--eslint-plugin`
 
@@ -60,13 +60,13 @@ The generated `ci:check` script defaults to `pnpm check --skip 'docker:*'` since
 
 ### Release management
 
-| Command                          | Description                                                                                                                     |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `tooling release:changesets`     | Changesets version/publish for Forgejo CI. Flag: `--dry-run`. Env: `FORGEJO_SERVER_URL`, `FORGEJO_REPOSITORY`, `RELEASE_TOKEN`. |
-| `tooling release:simple`         | Streamlined release using commit-and-tag-version. Flags: `--release-as`, `--first-release`, `--prerelease`.                     |
-| `tooling release:trigger`        | Trigger a release workflow.                                                                                                     |
-| `tooling forgejo:create-release` | Create a Forgejo release from a tag.                                                                                            |
-| `tooling changesets:merge`       | Merge a changesets version PR.                                                                                                  |
+| Command                          | Description                                                                                                                                   |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tooling release:changesets`     | Changesets version/publish for Forgejo CI. Flags: `--dry-run`, `--verbose`. Env: `FORGEJO_SERVER_URL`, `FORGEJO_REPOSITORY`, `RELEASE_TOKEN`. |
+| `tooling release:simple`         | Streamlined release using commit-and-tag-version. Flags: `--release-as`, `--first-release`, `--prerelease`, `--verbose`.                      |
+| `tooling release:trigger`        | Trigger a release workflow.                                                                                                                   |
+| `tooling forgejo:create-release` | Create a Forgejo release from a tag.                                                                                                          |
+| `tooling changesets:merge`       | Merge a changesets version PR.                                                                                                                |
 
 #### `release:simple`
 
@@ -147,7 +147,7 @@ To give individual packages a standalone `image:build` script for local testing:
 }
 ```
 
-**Flags:** `--package <dir>` (build a single package)
+**Flags:** `--package <dir>` (build a single package), `--verbose`
 
 #### `docker:publish`
 
@@ -157,7 +157,7 @@ Tags generated per package: `latest`, `vX.Y.Z`, `vX.Y`, `vX`
 
 Each package is tagged independently using its own version, so packages in a monorepo can have different release cadences. Packages without a `version` field are rejected at publish time.
 
-**Flags:** `--dry-run` (build and tag only, skip login/push/logout)
+**Flags:** `--dry-run` (build and tag only, skip login/push/logout), `--verbose`
 
 **Required CI variables:**
 
@@ -188,6 +188,17 @@ Available override fields:
 | `projectType`        | string  | Auto-detected from `package.json` deps                                           |
 | `detectPackageTypes` | boolean | `true`                                                                           |
 
+## Debug logging
+
+All CLI commands support a `--verbose` flag for detailed debug output. Alternatively, set `TOOLING_DEBUG=true` as an environment variable — useful in CI workflows:
+
+```yaml
+env:
+  TOOLING_DEBUG: "true"
+```
+
+Debug output is prefixed with `[debug]` and includes exec results (exit codes, stdout/stderr), compose configuration details, container health statuses, and retry attempts.
+
 ## Library API
 
 The `"."` export provides type-only exports for programmatic use:

package/dist/bin.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { l as createRealExecutor$1, t as runDockerCheck, u as isExecSyncError } from "./check-B2AAPCBO.mjs";
+import { d as debug, f as debugExec, h as note, l as createRealExecutor$1, m as log, p as isEnvVerbose, t as runDockerCheck, u as isExecSyncError } from "./check-Ceom_OgJ.mjs";
 import { defineCommand, runMain } from "citty";
-import * as clack from "@clack/prompts";
+import * as p from "@clack/prompts";
 import { isCancel, select } from "@clack/prompts";
 import path from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
@@ -13,22 +13,6 @@ import { FatalError, TransientError, UnexpectedError } from "@bensandee/common";
 import { isMap, isScalar, isSeq, parse as parse$1, parseDocument, stringify } from "yaml";
 import picomatch from "picomatch";
 import { tmpdir } from "node:os";
-//#region src/utils/log.ts
-const out = (msg) => console.log(msg);
-const isCI = Boolean(process.env["CI"]);
-const log$2 = isCI ? {
-	info: out,
-	warn: (msg) => out(`[warn] ${msg}`),
-	error: (msg) => out(`[error] ${msg}`),
-	success: (msg) => out(`✓ ${msg}`)
-} : clack.log;
-function note(body, title) {
-	if (isCI) {
-		if (title) out(`--- ${title} ---`);
-		out(body);
-	} else clack.note(body, title);
-}
-//#endregion
 //#region src/types.ts
 const LEGACY_TOOLS = [
 	"eslint",
@@ -312,7 +296,7 @@ function getMonorepoPackages(targetDir) {
 //#endregion
 //#region src/prompts/init-prompts.ts
 function isCancelled(value) {
-	return clack.isCancel(value);
+	return p.isCancel(value);
 }
 function detectProjectInfo(targetDir) {
 	const existingPkg = readPackageJson(targetDir);
@@ -323,7 +307,7 @@ function detectProjectInfo(targetDir) {
 	};
 }
 async function runInitPrompts(targetDir, saved) {
-	clack.intro("@bensandee/tooling repo:sync");
+	p.intro("@bensandee/tooling repo:sync");
 	const { detected, defaults, name } = detectProjectInfo(targetDir);
 	const isFirstInit = !saved;
 	const structure = saved?.structure ?? defaults.structure;
@@ -336,7 +320,7 @@ async function runInitPrompts(targetDir, saved) {
 	const projectType = saved?.projectType ?? defaults.projectType;
 	const detectPackageTypes = saved?.detectPackageTypes ?? defaults.detectPackageTypes;
 	if (detected.legacyConfigs.some((l) => l.tool === "prettier") && isFirstInit) {
-		const formatterAnswer = await clack.select({
+		const formatterAnswer = await p.select({
 			message: "Existing Prettier config found. Keep Prettier or migrate to oxfmt?",
 			initialValue: "prettier",
 			options: [{
@@ -349,14 +333,14 @@ async function runInitPrompts(targetDir, saved) {
 			}]
 		});
 		if (isCancelled(formatterAnswer)) {
-			clack.cancel("Cancelled.");
+			p.cancel("Cancelled.");
 			process.exit(0);
 		}
 		formatter = formatterAnswer;
 	}
 	const detectedCi = detectCiPlatform(targetDir);
 	if (isFirstInit && detectedCi === "none") {
-		const ciAnswer = await clack.select({
+		const ciAnswer = await p.select({
 			message: "CI workflow",
 			initialValue: "forgejo",
 			options: [
@@ -375,14 +359,14 @@ async function runInitPrompts(targetDir, saved) {
 			]
 		});
 		if (isCancelled(ciAnswer)) {
-			clack.cancel("Cancelled.");
+			p.cancel("Cancelled.");
 			process.exit(0);
 		}
 		ci = ciAnswer;
 	}
 	const hasExistingRelease = detected.hasReleaseItConfig || detected.hasSimpleReleaseConfig || detected.hasChangesetsConfig;
 	if (isFirstInit && !hasExistingRelease) {
-		const releaseAnswer = await clack.select({
+		const releaseAnswer = await p.select({
 			message: "Release management",
 			initialValue: defaults.releaseStrategy,
 			options: [
@@ -408,7 +392,7 @@ async function runInitPrompts(targetDir, saved) {
 			]
 		});
 		if (isCancelled(releaseAnswer)) {
-			clack.cancel("Cancelled.");
+			p.cancel("Cancelled.");
 			process.exit(0);
 		}
 		releaseStrategy = releaseAnswer;
@@ -416,12 +400,12 @@ async function runInitPrompts(targetDir, saved) {
 	let publishNpm = saved?.publishNpm ?? false;
 	if (isFirstInit && releaseStrategy !== "none") {
 		if (getPublishablePackages(targetDir, structure).length > 0) {
-			const answer = await clack.confirm({
+			const answer = await p.confirm({
 				message: "Publish packages to npm?",
 				initialValue: false
 			});
 			if (isCancelled(answer)) {
-				clack.cancel("Cancelled.");
+				p.cancel("Cancelled.");
 				process.exit(0);
 			}
 			publishNpm = answer;
@@ -430,18 +414,18 @@ async function runInitPrompts(targetDir, saved) {
 	let publishDocker = saved?.publishDocker ?? false;
 	if (isFirstInit) {
 		if (existsSync(path.join(targetDir, "Dockerfile")) || existsSync(path.join(targetDir, "docker/Dockerfile"))) {
-			const answer = await clack.confirm({
+			const answer = await p.confirm({
 				message: "Publish Docker images to a registry?",
 				initialValue: false
 			});
 			if (isCancelled(answer)) {
-				clack.cancel("Cancelled.");
+				p.cancel("Cancelled.");
 				process.exit(0);
 			}
 			publishDocker = answer;
 		}
 	}
-	clack.outro("Configuration complete!");
+	p.outro("Configuration complete!");
 	return {
 		name,
 		structure,
@@ -859,9 +843,6 @@ function generateTags(version) {
 function imageRef(namespace, imageName, tag) {
 	return `${namespace}/${imageName}:${tag}`;
 }
-function log$1(message) {
-	console.log(message);
-}
 /** Read the repo name from root package.json. */
 function readRepoName(executor, cwd) {
 	const rootPkgRaw = executor.readFile(path.join(cwd, "package.json"));
@@ -894,22 +875,24 @@ function runDockerBuild(executor, config) {
 	const repoName = readRepoName(executor, config.cwd);
 	if (config.packageDir) {
 		const pkg = readSinglePackageDocker(executor, config.cwd, config.packageDir, repoName);
-		log$1(`Building image for ${pkg.dir} (${pkg.imageName}:latest)...`);
+		log.info(`Building image for ${pkg.dir} (${pkg.imageName}:latest)...`);
+		debug(config, `Dockerfile: ${pkg.docker.dockerfile}, context: ${pkg.docker.context}`);
 		buildImage(executor, pkg, config.cwd, config.extraArgs);
-		log$1(`Built ${pkg.imageName}:latest`);
+		log.info(`Built ${pkg.imageName}:latest`);
 		return { packages: [pkg] };
 	}
 	const packages = detectDockerPackages(executor, config.cwd, repoName);
 	if (packages.length === 0) {
-		log$1("No packages with docker config found");
+		log.info("No packages with docker config found");
 		return { packages: [] };
 	}
-	log$1(`Found ${packages.length} Docker package(s): ${packages.map((p) => p.dir).join(", ")}`);
+	log.info(`Found ${String(packages.length)} Docker package(s): ${packages.map((p) => p.dir).join(", ")}`);
 	for (const pkg of packages) {
-		log$1(`Building image for ${pkg.dir} (${pkg.imageName}:latest)...`);
+		log.info(`Building image for ${pkg.dir} (${pkg.imageName}:latest)...`);
+		debug(config, `Dockerfile: ${pkg.docker.dockerfile}, context: ${pkg.docker.context}`);
 		buildImage(executor, pkg, config.cwd, config.extraArgs);
 	}
-	log$1(`Built ${packages.length} image(s)`);
+	log.info(`Built ${String(packages.length)} image(s)`);
 	return { packages };
 }
 /**
@@ -924,7 +907,8 @@ function runDockerPublish(executor, config) {
 	const { packages } = runDockerBuild(executor, {
 		cwd: config.cwd,
 		packageDir: void 0,
-		extraArgs: []
+		extraArgs: [],
+		verbose: config.verbose
 	});
 	if (packages.length === 0) return {
 		packages: [],
@@ -932,35 +916,38 @@ 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$1(`Logging in to ${config.registryHost}...`);
+		log.info(`Logging in to ${config.registryHost}...`);
 		const loginResult = executor.exec(`echo "${config.password}" | docker login ${config.registryHost} -u ${config.username} --password-stdin`);
+		debugExec(config, "docker login", loginResult);
 		if (loginResult.exitCode !== 0) throw new FatalError(`Docker login failed: ${loginResult.stderr}`);
-	} else log$1("[dry-run] Skipping docker login");
+	} else log.info("[dry-run] Skipping docker login");
 	const allTags = [];
 	try {
 		for (const pkg of packages) {
 			const tags = generateTags(pkg.version ?? "");
-			log$1(`${pkg.dir} v${pkg.version} → tags: ${tags.join(", ")}`);
+			log.info(`${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$1(`Tagging ${pkg.imageName} → ${ref}`);
+				log.info(`Tagging ${pkg.imageName} → ${ref}`);
 				const tagResult = executor.exec(`docker tag ${pkg.imageName} ${ref}`);
+				debugExec(config, `docker tag ${pkg.imageName} ${ref}`, tagResult);
 				if (tagResult.exitCode !== 0) throw new FatalError(`docker tag failed: ${tagResult.stderr}`);
 				if (!config.dryRun) {
-					log$1(`Pushing ${ref}...`);
+					log.info(`Pushing ${ref}...`);
 					const pushResult = executor.exec(`docker push ${ref}`);
+					debugExec(config, `docker push ${ref}`, pushResult);
 					if (pushResult.exitCode !== 0) throw new FatalError(`docker push failed: ${pushResult.stderr}`);
-				} else log$1(`[dry-run] Skipping push for ${ref}`);
+				} else log.info(`[dry-run] Skipping push for ${ref}`);
 			}
 		}
 	} finally {
 		if (!config.dryRun) {
-			log$1(`Logging out from ${config.registryHost}...`);
+			log.info(`Logging out from ${config.registryHost}...`);
 			executor.exec(`docker logout ${config.registryHost}`);
 		}
 	}
-	log$1(`Published ${allTags.length} image tag(s)`);
+	log.info(`Published ${String(allTags.length)} image tag(s)`);
 	return {
 		packages,
 		tags: allTags
@@ -1590,7 +1577,7 @@ function getAddedDevDepNames(config) {
 	const deps = { ...ROOT_DEV_DEPS };
 	if (config.structure !== "monorepo") Object.assign(deps, PER_PACKAGE_DEV_DEPS);
 	deps["@bensandee/config"] = "0.9.1";
-	deps["@bensandee/tooling"] = "0.33.0";
+	deps["@bensandee/tooling"] = "0.34.0";
 	if (config.formatter === "oxfmt") deps["oxfmt"] = {
 		"@changesets/cli": "2.30.0",
 		"@release-it/bumper": "7.0.5",
@@ -1645,7 +1632,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.9.1";
-	devDeps["@bensandee/tooling"] = isWorkspacePackage(ctx, "@bensandee/tooling") ? "workspace:*" : "0.33.0";
+	devDeps["@bensandee/tooling"] = isWorkspacePackage(ctx, "@bensandee/tooling") ? "workspace:*" : "0.34.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"] = {
 		"@changesets/cli": "2.30.0",
@@ -3321,7 +3308,7 @@ function generateMigratePrompt(results, config, detected) {
 	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
 	sections.push("# Migration Prompt");
 	sections.push("");
-	sections.push(`_Generated by \`@bensandee/tooling@0.33.0 repo:sync\` on ${timestamp}_`);
+	sections.push(`_Generated by \`@bensandee/tooling@0.34.0 repo:sync\` on ${timestamp}_`);
 	sections.push("");
 	sections.push("The following prompt was generated by `@bensandee/tooling repo:sync`. Paste it into Claude Code or another AI assistant to finish migrating this repository.");
 	sections.push("");
@@ -3505,11 +3492,11 @@ function contextAsDockerReader(ctx) {
 function logDetectionSummary(ctx) {
 	if (ctx.config.publishDocker) {
 		const dockerPackages = detectDockerPackages(contextAsDockerReader(ctx), ctx.targetDir, ctx.config.name);
-		if (dockerPackages.length > 0) log$2.info(`Docker images: ${dockerPackages.map((pkg) => pkg.imageName).join(", ")}`);
+		if (dockerPackages.length > 0) log.info(`Docker images: ${dockerPackages.map((pkg) => pkg.imageName).join(", ")}`);
 	}
 	if (ctx.config.publishNpm) {
 		const publishable = getPublishablePackages(ctx.targetDir, ctx.config.structure, ctx.packageJson);
-		if (publishable.length > 0) log$2.info(`npm packages: ${publishable.map((pkg) => pkg.name).join(", ")}`);
+		if (publishable.length > 0) log.info(`npm packages: ${publishable.map((pkg) => pkg.name).join(", ")}`);
 	}
 }
 async function runInit(config, options = {}) {
@@ -3543,7 +3530,7 @@ async function runInit(config, options = {}) {
 	const promptPath = ".tooling-migrate.md";
 	ctx.write(promptPath, prompt);
 	if (!hasChanges && options.noPrompt) {
-		log$2.success("Repository is up to date.");
+		log.success("Repository is up to date.");
 		return results;
 	}
 	if (results.some((r) => r.action === "archived" && r.filePath.startsWith(".husky/"))) try {
@@ -3558,13 +3545,13 @@ async function runInit(config, options = {}) {
 	if (updated.length > 0) summaryLines.push(`Updated: ${updated.map((r) => r.filePath).join(", ")}`);
 	note(summaryLines.join("\n"), "Summary");
 	if (!options.noPrompt) {
-		log$2.info(`Migration prompt written to ${promptPath}`);
-		log$2.info("In Claude Code, run: \"Execute the steps in .tooling-migrate.md\"");
+		log.info(`Migration prompt written to ${promptPath}`);
+		log.info("In Claude Code, run: \"Execute the steps in .tooling-migrate.md\"");
 	}
 	const bensandeeDeps = getAddedDevDepNames(config).filter((name) => name.startsWith("@bensandee/"));
 	const hasLockfile = ctx.exists("pnpm-lock.yaml");
 	if (bensandeeDeps.length > 0 && hasLockfile) {
-		log$2.info("Updating @bensandee/* packages...");
+		log.info("Updating @bensandee/* packages...");
 		try {
 			execSync(`pnpm update --latest ${bensandeeDeps.join(" ")}`, {
 				cwd: config.targetDir,
@@ -3572,7 +3559,7 @@ async function runInit(config, options = {}) {
 				timeout: 6e4
 			});
 		} catch (_error) {
-			log$2.warn("Could not update @bensandee/* packages — run pnpm install manually");
+			log.warn("Could not update @bensandee/* packages — run pnpm install manually");
 		}
 	}
 	if (hasChanges && ctx.exists("package.json")) try {
@@ -3664,22 +3651,22 @@ async function runCheck(targetDir) {
 		return true;
 	});
 	if (actionable.length === 0) {
-		log$2.success("Repository is up to date.");
+		log.success("Repository is up to date.");
 		return 0;
 	}
-	log$2.warn(`${actionable.length} file(s) would be changed by repo:sync`);
+	log.warn(`${actionable.length} file(s) would be changed by repo:sync`);
 	for (const r of actionable) {
-		log$2.info(`  ${r.action}: ${r.filePath} — ${r.description}`);
+		log.info(`  ${r.action}: ${r.filePath} — ${r.description}`);
 		const newContent = pendingWrites.get(r.filePath);
 		if (!newContent) continue;
 		const existingPath = path.join(targetDir, r.filePath);
 		const existing = existsSync(existingPath) ? readFileSync(existingPath, "utf-8") : void 0;
 		if (!existing) {
 			const lineCount = newContent.split("\n").length - 1;
-			log$2.info(`    + ${lineCount} new lines`);
+			log.info(`    + ${lineCount} new lines`);
 		} else {
 			const diff = lineDiff(existing, newContent);
-			for (const line of diff) log$2.info(`    ${line}`);
+			for (const line of diff) log.info(`    ${line}`);
 		}
 	}
 	return 1;
@@ -3827,6 +3814,17 @@ function reconcileTags(expectedTags, remoteTags, stdoutTags) {
 }
 //#endregion
 //#region src/release/forgejo.ts
+const RETRY_ATTEMPTS = 3;
+const RETRY_BASE_DELAY_MS = 1e3;
+/** Safely read response body text for inclusion in error messages. */
+async function responseBodyText(res) {
+	try {
+		const text = await res.text();
+		return text.length > 500 ? text.slice(0, 500) + "…" : text;
+	} catch {
+		return "(could not read response body)";
+	}
+}
 const PullRequestSchema = z.array(z.object({
 	number: z.number(),
 	head: z.object({ ref: z.string() })
@@ -3840,7 +3838,10 @@ const PullRequestSchema = z.array(z.object({
 async function findOpenPr(executor, conn, head) {
 	const url = `${conn.serverUrl}/api/v1/repos/${conn.repository}/pulls?state=open`;
 	const res = await executor.fetch(url, { headers: { Authorization: `token ${conn.token}` } });
-	if (!res.ok) throw new TransientError(`Failed to list PRs: ${res.status} ${res.statusText}`);
+	if (!res.ok) {
+		const body = await responseBodyText(res);
+		throw new TransientError(`Failed to list PRs: ${res.status} ${res.statusText}\n${body}`);
+	}
 	const parsed = PullRequestSchema.safeParse(await res.json());
 	if (!parsed.success) throw new UnexpectedError(`Unexpected PR list response: ${parsed.error.message}`);
 	return parsed.data.find((pr) => pr.head.ref === head)?.number ?? null;
@@ -3862,7 +3863,10 @@ async function createPr(executor, conn, options) {
 		},
 		body: JSON.stringify(payload)
 	});
-	if (!res.ok) throw new TransientError(`Failed to create PR: ${res.status} ${res.statusText}`);
+	if (!res.ok) {
+		const body = await responseBodyText(res);
+		throw new TransientError(`Failed to create PR: ${res.status} ${res.statusText}\n${body}`);
+	}
 }
 /** Update an existing pull request's title and body. */
 async function updatePr(executor, conn, prNumber, options) {
@@ -3878,7 +3882,10 @@ async function updatePr(executor, conn, prNumber, options) {
 			body: options.body
 		})
 	});
-	if (!res.ok) throw new TransientError(`Failed to update PR #${String(prNumber)}: ${res.status} ${res.statusText}`);
+	if (!res.ok) {
+		const body = await responseBodyText(res);
+		throw new TransientError(`Failed to update PR #${String(prNumber)}: ${res.status} ${res.statusText}\n${body}`);
+	}
 }
 /** Merge a pull request by number. */
 async function mergePr(executor, conn, prNumber, options) {
@@ -3894,7 +3901,10 @@ async function mergePr(executor, conn, prNumber, options) {
 			delete_branch_after_merge: options?.deleteBranch ?? true
 		})
 	});
-	if (!res.ok) throw new TransientError(`Failed to merge PR #${String(prNumber)}: ${res.status} ${res.statusText}`);
+	if (!res.ok) {
+		const body = await responseBodyText(res);
+		throw new TransientError(`Failed to merge PR #${String(prNumber)}: ${res.status} ${res.statusText}\n${body}`);
+	}
 }
 /** Check whether a Forgejo release already exists for a given tag. */
 async function findRelease(executor, conn, tag) {
@@ -3903,7 +3913,8 @@ async function findRelease(executor, conn, tag) {
 	const res = await executor.fetch(url, { headers: { Authorization: `token ${conn.token}` } });
 	if (res.status === 200) return true;
 	if (res.status === 404) return false;
-	throw new TransientError(`Failed to check release for ${tag}: ${res.status} ${res.statusText}`);
+	const body = await responseBodyText(res);
+	throw new TransientError(`Failed to check release for ${tag}: ${res.status} ${res.statusText}\n${body}`);
 }
 /** Create a Forgejo release for a given tag. */
 async function createRelease(executor, conn, tag) {
@@ -3920,21 +3931,35 @@ async function createRelease(executor, conn, tag) {
 			body: `Published ${tag}`
 		})
 	});
-	if (!res.ok) throw new TransientError(`Failed to create release for ${tag}: ${res.status} ${res.statusText}`);
+	if (!res.ok) {
+		const body = await responseBodyText(res);
+		throw new TransientError(`Failed to create release for ${tag}: ${res.status} ${res.statusText}\n${body}`);
+	}
 }
-//#endregion
-//#region src/release/log.ts
-/** Log a debug message when verbose mode is enabled. */
-function debug(config, message) {
-	if (config.verbose) log$2.info(`[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] ${label} (exit code ${String(result.exitCode)})`];
-	if (result.stdout.trim()) lines.push(`  stdout: ${result.stdout.trim()}`);
-	if (result.stderr.trim()) lines.push(`  stderr: ${result.stderr.trim()}`);
-	log$2.info(lines.join("\n"));
+/**
+* Ensure a Forgejo release exists for a tag, creating it if necessary.
+*
+* Handles two edge cases:
+* - The release already exists before we try (skips creation)
+* - Forgejo auto-creates a release when a tag is pushed, causing a 500 race
+*   condition (detected by re-checking after failure)
+*
+* Retries on transient errors with exponential backoff.
+* Returns "created" | "exists" | "race" indicating what happened.
+*/
+async function ensureRelease(executor, conn, tag) {
+	if (await findRelease(executor, conn, tag)) return "exists";
+	for (let attempt = 1; attempt <= RETRY_ATTEMPTS; attempt++) try {
+		await createRelease(executor, conn, tag);
+		return "created";
+	} catch (error) {
+		if (await findRelease(executor, conn, tag)) return "race";
+		if (attempt >= RETRY_ATTEMPTS) throw error;
+		log.warn(`Release creation attempt ${String(attempt)}/${String(RETRY_ATTEMPTS)} failed: ${error instanceof Error ? error.message : String(error)}`);
+		const delay = RETRY_BASE_DELAY_MS * 2 ** (attempt - 1);
+		await new Promise((resolve) => setTimeout(resolve, delay));
+	}
+	throw new TransientError(`Failed to create release for ${tag} after ${String(RETRY_ATTEMPTS)} attempts`);
 }
 //#endregion
 //#region src/release/version.ts
@@ -4006,7 +4031,7 @@ function buildPrContent(executor, cwd, packagesBefore) {
 }
 /** Mode 1: version packages and create/update a PR. */
 async function runVersionMode(executor, config) {
-	log$2.info("Changesets detected — versioning packages");
+	log.info("Changesets detected — versioning packages");
 	const packagesBefore = executor.listWorkspacePackages(config.cwd);
 	debug(config, `Packages before versioning: ${packagesBefore.map((pkg) => `${pkg.name}@${pkg.version}`).join(", ") || "(none)"}`);
 	const changesetConfigPath = path.join(config.cwd, ".changeset", "config.json");
@@ -4032,19 +4057,19 @@ async function runVersionMode(executor, config) {
 	const addResult = executor.exec("git add -A", { cwd: config.cwd });
 	if (addResult.exitCode !== 0) throw new FatalError(`git add failed: ${addResult.stderr || addResult.stdout}`);
 	const remainingChangesets = executor.listChangesetFiles(config.cwd);
-	if (remainingChangesets.length > 0) log$2.warn(`Changeset files still present after versioning: ${remainingChangesets.join(", ")}`);
+	if (remainingChangesets.length > 0) log.warn(`Changeset files still present after versioning: ${remainingChangesets.join(", ")}`);
 	debug(config, `Changeset files after versioning: ${remainingChangesets.length > 0 ? remainingChangesets.join(", ") : "(none — all consumed)"}`);
 	const commitResult = executor.exec("git commit -m \"chore: version packages\"", { cwd: config.cwd });
 	debugExec(config, "git commit", commitResult);
 	if (commitResult.exitCode !== 0) {
-		log$2.info("Nothing to commit after versioning");
+		log.info("Nothing to commit after versioning");
 		return {
 			mode: "version",
 			pr: "none"
 		};
 	}
 	if (config.dryRun) {
-		log$2.info("[dry-run] Would push and create/update PR");
+		log.info("[dry-run] Would push and create/update PR");
 		return {
 			mode: "version",
 			pr: "none"
@@ -4067,7 +4092,7 @@ async function runVersionMode(executor, config) {
 			base: "main",
 			body
 		});
-		log$2.info("Created version PR");
+		log.info("Created version PR");
 		return {
 			mode: "version",
 			pr: "created"
@@ -4077,7 +4102,7 @@ async function runVersionMode(executor, config) {
 		title,
 		body
 	});
-	log$2.info(`Updated version PR #${String(existingPr)}`);
+	log.info(`Updated version PR #${String(existingPr)}`);
 	return {
 		mode: "version",
 		pr: "updated"
@@ -4085,24 +4110,9 @@ async function runVersionMode(executor, config) {
 }
 //#endregion
 //#region src/release/publish.ts
-const RETRY_ATTEMPTS = 3;
-const RETRY_BASE_DELAY_MS = 1e3;
-async function retryAsync(fn) {
-	let lastError;
-	for (let attempt = 0; attempt <= RETRY_ATTEMPTS; attempt++) try {
-		return await fn();
-	} catch (error) {
-		lastError = error;
-		if (attempt < RETRY_ATTEMPTS) {
-			const delay = RETRY_BASE_DELAY_MS * 2 ** attempt;
-			await new Promise((resolve) => setTimeout(resolve, delay));
-		}
-	}
-	throw lastError;
-}
 /** Mode 2: publish to npm, push tags, and create Forgejo releases. */
 async function runPublishMode(executor, config) {
-	log$2.info("No changesets — publishing packages");
+	log.info("No changesets — publishing packages");
 	const publishResult = executor.exec("pnpm changeset publish", { cwd: config.cwd });
 	debugExec(config, "pnpm changeset publish", publishResult);
 	if (publishResult.exitCode !== 0) throw new FatalError(`pnpm changeset publish failed (exit code ${String(publishResult.exitCode)}):\n${publishResult.stderr}`);
@@ -4117,11 +4127,11 @@ async function runPublishMode(executor, config) {
 	debug(config, `Reconciled tags to push: ${tagsToPush.length > 0 ? tagsToPush.join(", ") : "(none)"}`);
 	if (config.dryRun) {
 		if (tagsToPush.length === 0) {
-			log$2.info("No packages were published");
+			log.info("No packages were published");
 			return { mode: "none" };
 		}
-		log$2.info(`Tags to process: ${tagsToPush.join(", ")}`);
-		log$2.info("[dry-run] Would push tags and create releases");
+		log.info(`Tags to process: ${tagsToPush.join(", ")}`);
+		log.info("[dry-run] Would push tags and create releases");
 		return {
 			mode: "publish",
 			tags: tagsToPush
@@ -4137,10 +4147,10 @@ async function runPublishMode(executor, config) {
 	for (const tag of remoteExpectedTags) if (!await findRelease(executor, conn, tag)) tagsWithMissingReleases.push(tag);
 	const allTags = [...tagsToPush, ...tagsWithMissingReleases];
 	if (allTags.length === 0) {
-		log$2.info("No packages were published");
+		log.info("No packages were published");
 		return { mode: "none" };
 	}
-	log$2.info(`Tags to process: ${allTags.join(", ")}`);
+	log.info(`Tags to process: ${allTags.join(", ")}`);
 	const errors = [];
 	for (const tag of allTags) try {
 		if (!remoteSet.has(tag)) {
@@ -4151,24 +4161,14 @@ async function runPublishMode(executor, config) {
 			const pushTagResult = executor.exec(`git push origin refs/tags/${tag}`, { cwd: config.cwd });
 			if (pushTagResult.exitCode !== 0) throw new FatalError(`Failed to push tag ${tag}: ${pushTagResult.stderr || pushTagResult.stdout}`);
 		}
-		if (await findRelease(executor, conn, tag)) log$2.warn(`Release for ${tag} already exists — skipping`);
-		else {
-			await retryAsync(async () => {
-				try {
-					await createRelease(executor, conn, tag);
-				} catch (error) {
-					if (await findRelease(executor, conn, tag)) return;
-					throw error;
-				}
-			});
-			log$2.info(`Created release for ${tag}`);
-		}
+		if (await ensureRelease(executor, conn, tag) === "exists") log.warn(`Release for ${tag} already exists — skipping`);
+		else log.info(`Created release for ${tag}`);
 	} catch (error) {
 		errors.push({
 			tag,
 			error
 		});
-		log$2.warn(`Failed to process ${tag}: ${error instanceof Error ? error.message : String(error)}`);
+		log.warn(`Failed to process ${tag}: ${error instanceof Error ? error.message : String(error)}`);
 	}
 	if (errors.length > 0) throw new TransientError(`Failed to create releases for: ${errors.map((e) => e.tag).join(", ")}`);
 	return {
@@ -4262,6 +4262,14 @@ function configureGitAuth(executor, conn, cwd) {
 	const authUrl = `https://x-access-token:${conn.token}@${host}/${conn.repository}`;
 	executor.exec(`git remote set-url origin ${authUrl}`, { cwd });
 }
+/** Configure git user.name and user.email for CI bot commits. */
+function configureGitIdentity(executor, platform, cwd) {
+	const isGitHub = platform === "github";
+	const name = isGitHub ? "github-actions[bot]" : "forgejo-actions[bot]";
+	const email = isGitHub ? "github-actions[bot]@users.noreply.github.com" : "forgejo-actions[bot]@noreply.localhost";
+	executor.exec(`git config user.name "${name}"`, { cwd });
+	executor.exec(`git config user.email "${email}"`, { cwd });
+}
 //#endregion
 //#region src/commands/release-changesets.ts
 const releaseForgejoCommand = defineCommand({
@@ -4276,13 +4284,13 @@ const releaseForgejoCommand = defineCommand({
 		},
 		verbose: {
 			type: "boolean",
-			description: "Enable detailed debug logging (also enabled by RELEASE_DEBUG env var)"
+			description: "Enable detailed debug logging (also enabled by TOOLING_DEBUG env var)"
 		}
 	},
 	async run({ args }) {
 		if ((await runRelease(buildReleaseConfig({
 			dryRun: args["dry-run"] === true,
-			verbose: args.verbose === true || process.env["RELEASE_DEBUG"] === "true"
+			verbose: args.verbose === true || isEnvVerbose()
 		}), createRealExecutor())).mode === "none") process.exitCode = 0;
 	}
 });
@@ -4310,8 +4318,7 @@ async function runRelease(config, executor) {
 		debug(config, `Skipping release on non-main branch: ${branch}`);
 		return { mode: "none" };
 	}
-	executor.exec("git config user.name \"forgejo-actions[bot]\"", { cwd: config.cwd });
-	executor.exec("git config user.email \"forgejo-actions[bot]@noreply.localhost\"", { cwd: config.cwd });
+	configureGitIdentity(executor, "forgejo", config.cwd);
 	configureGitAuth(executor, config, config.cwd);
 	const changesetFiles = executor.listChangesetFiles(config.cwd);
 	debug(config, `Changeset files found: ${changesetFiles.length > 0 ? changesetFiles.join(", ") : "(none)"}`);
@@ -4369,7 +4376,7 @@ async function triggerForgejo(conn, ref, inputs) {
 		body: JSON.stringify(body)
 	});
 	if (!res.ok) throw new FatalError(`Failed to trigger Forgejo workflow: ${res.status} ${res.statusText}`);
-	log$2.info(`Triggered release workflow on Forgejo (ref: ${ref})`);
+	log.info(`Triggered release workflow on Forgejo (ref: ${ref})`);
 }
 function triggerGitHub(ref, inputs) {
 	const executor = createRealExecutor();
@@ -4377,7 +4384,7 @@ function triggerGitHub(ref, inputs) {
 	const cmd = `gh workflow run release.yml --ref ${ref}${inputFlags ? ` ${inputFlags}` : ""}`;
 	const result = executor.exec(cmd, { cwd: process.cwd() });
 	if (result.exitCode !== 0) throw new FatalError(`Failed to trigger GitHub workflow: ${result.stderr || result.stdout || "unknown error"}`);
-	log$2.info(`Triggered release workflow on GitHub (ref: ${ref})`);
+	log.info(`Triggered release workflow on GitHub (ref: ${ref})`);
 }
 //#endregion
 //#region src/commands/forgejo-create-release.ts
@@ -4397,11 +4404,11 @@ const createForgejoReleaseCommand = defineCommand({
 		const executor = createRealExecutor();
 		const conn = resolved.conn;
 		if (await findRelease(executor, conn, args.tag)) {
-			log$2.info(`Release for ${args.tag} already exists — skipping`);
+			log.info(`Release for ${args.tag} already exists — skipping`);
 			return;
 		}
 		await createRelease(executor, conn, args.tag);
-		log$2.info(`Created Forgejo release for ${args.tag}`);
+		log.info(`Created Forgejo release for ${args.tag}`);
 	}
 });
 //#endregion
@@ -4428,26 +4435,26 @@ async function mergeForgejo(conn, dryRun) {
 	const prNumber = await findOpenPr(executor, conn, HEAD_BRANCH);
 	if (prNumber === null) throw new FatalError(`No open PR found for branch ${HEAD_BRANCH}`);
 	if (dryRun) {
-		log$2.info(`[dry-run] Would merge PR #${String(prNumber)} and delete branch ${HEAD_BRANCH}`);
+		log.info(`[dry-run] Would merge PR #${String(prNumber)} and delete branch ${HEAD_BRANCH}`);
 		return;
 	}
 	await mergePr(executor, conn, prNumber, {
 		method: "merge",
 		deleteBranch: true
 	});
-	log$2.info(`Merged PR #${String(prNumber)} and deleted branch ${HEAD_BRANCH}`);
+	log.info(`Merged PR #${String(prNumber)} and deleted branch ${HEAD_BRANCH}`);
 }
 function mergeGitHub(dryRun) {
 	const executor = createRealExecutor();
 	if (dryRun) {
 		const prNum = executor.exec(`gh pr view ${HEAD_BRANCH} --json number --jq .number`, { cwd: process.cwd() }).stdout.trim();
 		if (!prNum) throw new FatalError(`No open PR found for branch ${HEAD_BRANCH}`);
-		log$2.info(`[dry-run] Would merge PR #${prNum} and delete branch ${HEAD_BRANCH}`);
+		log.info(`[dry-run] Would merge PR #${prNum} and delete branch ${HEAD_BRANCH}`);
 		return;
 	}
 	const result = executor.exec(`gh pr merge ${HEAD_BRANCH} --merge --delete-branch`, { cwd: process.cwd() });
 	if (result.exitCode !== 0) throw new FatalError(`Failed to merge PR: ${result.stderr || result.stdout || "unknown error"}`);
-	log$2.info(`Merged changesets PR and deleted branch ${HEAD_BRANCH}`);
+	log.info(`Merged changesets PR and deleted branch ${HEAD_BRANCH}`);
 }
 //#endregion
 //#region src/release/simple.ts
@@ -4477,20 +4484,15 @@ function readVersion(executor, cwd) {
 	if (!pkg?.version) throw new FatalError("No version field found in package.json");
 	return pkg.version;
 }
-/** Configure git identity for CI bot commits. */
-function configureGitIdentity(executor, config) {
-	const isGitHub = config.platform?.type === "github";
-	const name = isGitHub ? "github-actions[bot]" : "forgejo-actions[bot]";
-	const email = isGitHub ? "github-actions[bot]@users.noreply.github.com" : "forgejo-actions[bot]@noreply.localhost";
-	executor.exec(`git config user.name "${name}"`, { cwd: config.cwd });
-	executor.exec(`git config user.email "${email}"`, { cwd: config.cwd });
-	debug(config, `Configured git identity: ${name} <${email}>`);
+/** Resolve the platform type string for git identity configuration. */
+function platformType(config) {
+	return config.platform?.type === "github" ? "github" : "forgejo";
 }
 /** Run the full commit-and-tag-version release flow. */
 async function runSimpleRelease(executor, config) {
-	configureGitIdentity(executor, config);
+	configureGitIdentity(executor, platformType(config), config.cwd);
 	const command = buildCommand(config);
-	log$2.info(`Running: ${command}`);
+	log.info(`Running: ${command}`);
 	const versionResult = executor.exec(command, { cwd: config.cwd });
 	debugExec(config, "commit-and-tag-version", versionResult);
 	if (versionResult.exitCode !== 0) throw new FatalError(`commit-and-tag-version failed (exit code ${String(versionResult.exitCode)}):\n${versionResult.stderr || versionResult.stdout}`);
@@ -4500,12 +4502,12 @@ async function runSimpleRelease(executor, config) {
 	debugExec(config, "git describe", tagResult);
 	const tag = tagResult.stdout.trim();
 	if (!tag) throw new FatalError("Could not determine the new tag from git describe");
-	log$2.info(`Version ${version} tagged as ${tag}`);
+	log.info(`Version ${version} tagged as ${tag}`);
 	if (config.dryRun) {
 		const slidingTags = config.noSlidingTags ? [] : computeSlidingTags(version);
-		log$2.info(`[dry-run] Would push to origin with --follow-tags`);
-		if (slidingTags.length > 0) log$2.info(`[dry-run] Would create sliding tags: ${slidingTags.join(", ")}`);
-		if (!config.noRelease && config.platform) log$2.info(`[dry-run] Would create ${config.platform.type} release for ${tag}`);
+		log.info(`[dry-run] Would push to origin with --follow-tags`);
+		if (slidingTags.length > 0) log.info(`[dry-run] Would create sliding tags: ${slidingTags.join(", ")}`);
+		if (!config.noRelease && config.platform) log.info(`[dry-run] Would create ${config.platform.type} release for ${tag}`);
 		return {
 			version,
 			tag,
@@ -4526,7 +4528,7 @@ async function runSimpleRelease(executor, config) {
 		debugExec(config, "git push", pushResult);
 		if (pushResult.exitCode !== 0) throw new FatalError(`git push failed (exit code ${String(pushResult.exitCode)}):\n${pushResult.stderr || pushResult.stdout}`);
 		pushed = true;
-		log$2.info("Pushed to origin");
+		log.info("Pushed to origin");
 	}
 	let slidingTags = [];
 	if (!config.noSlidingTags && pushed) {
@@ -4537,8 +4539,8 @@ async function runSimpleRelease(executor, config) {
 		}
 		const forcePushResult = executor.exec(`git push origin ${slidingTags.join(" ")} --force`, { cwd: config.cwd });
 		debugExec(config, "force-push sliding tags", forcePushResult);
-		if (forcePushResult.exitCode !== 0) log$2.warn(`Warning: Failed to push sliding tags: ${forcePushResult.stderr || forcePushResult.stdout}`);
-		else log$2.info(`Created sliding tags: ${slidingTags.join(", ")}`);
+		if (forcePushResult.exitCode !== 0) log.warn(`Warning: Failed to push sliding tags: ${forcePushResult.stderr || forcePushResult.stdout}`);
+		else log.info(`Created sliding tags: ${slidingTags.join(", ")}`);
 	}
 	let releaseCreated = false;
 	if (!config.noRelease && config.platform) releaseCreated = await createPlatformRelease(executor, config, tag);
@@ -4553,21 +4555,20 @@ async function runSimpleRelease(executor, config) {
 async function createPlatformRelease(executor, config, tag) {
 	if (!config.platform) return false;
 	if (config.platform.type === "forgejo") {
-		if (await findRelease(executor, config.platform.conn, tag)) {
+		if (await ensureRelease(executor, config.platform.conn, tag) === "exists") {
 			debug(config, `Release for ${tag} already exists, skipping`);
 			return false;
 		}
-		await createRelease(executor, config.platform.conn, tag);
-		log$2.info(`Created Forgejo release for ${tag}`);
+		log.info(`Created Forgejo release for ${tag}`);
 		return true;
 	}
 	const ghResult = executor.exec(`gh release create ${tag} --generate-notes`, { cwd: config.cwd });
 	debugExec(config, "gh release create", ghResult);
 	if (ghResult.exitCode !== 0) {
-		log$2.warn(`Warning: Failed to create GitHub release: ${ghResult.stderr || ghResult.stdout}`);
+		log.warn(`Warning: Failed to create GitHub release: ${ghResult.stderr || ghResult.stdout}`);
 		return false;
 	}
-	log$2.info(`Created GitHub release for ${tag}`);
+	log.info(`Created GitHub release for ${tag}`);
 	return true;
 }
 //#endregion
@@ -4584,7 +4585,7 @@ const releaseSimpleCommand = defineCommand({
 		},
 		verbose: {
 			type: "boolean",
-			description: "Enable detailed debug logging (also enabled by RELEASE_DEBUG env var)"
+			description: "Enable detailed debug logging (also enabled by TOOLING_DEBUG env var)"
 		},
 		"no-push": {
 			type: "boolean",
@@ -4613,7 +4614,7 @@ const releaseSimpleCommand = defineCommand({
 	},
 	async run({ args }) {
 		const cwd = process.cwd();
-		const verbose = args.verbose === true || process.env["RELEASE_DEBUG"] === "true";
+		const verbose = args.verbose === true || isEnvVerbose();
 		const noRelease = args["no-release"] === true;
 		let platform;
 		if (!noRelease) {
@@ -4697,12 +4698,12 @@ const ciReporter = {
 const localReporter = {
 	groupStart: (_name) => {},
 	groupEnd: () => {},
-	passed: (name) => log$2.success(name),
-	failed: (name) => log$2.error(`${name} failed`),
-	undefinedCheck: (name) => log$2.error(`${name} not defined in package.json`),
-	skippedNotDefined: (names) => log$2.info(`Skipped (not defined): ${names.join(", ")}`),
-	allPassed: () => log$2.success("All checks passed"),
-	anyFailed: (names) => log$2.error(`Failed checks: ${names.join(", ")}`)
+	passed: (name) => log.success(name),
+	failed: (name) => log.error(`${name} failed`),
+	undefinedCheck: (name) => log.error(`${name} not defined in package.json`),
+	skippedNotDefined: (names) => log.info(`Skipped (not defined): ${names.join(", ")}`),
+	allPassed: () => log.success("All checks passed"),
+	anyFailed: (names) => log.error(`Failed checks: ${names.join(", ")}`)
 };
 function runRunChecks(targetDir, options = {}) {
 	const exec = options.execCommand ?? defaultExecCommand;
@@ -4712,6 +4713,7 @@ function runRunChecks(targetDir, options = {}) {
 	const isCI = Boolean(process.env["CI"]);
 	const failFast = options.failFast ?? !isCI;
 	const reporter = isCI ? ciReporter : localReporter;
+	const vc = { verbose: options.verbose ?? false };
 	const definedScripts = getScripts(targetDir);
 	const addedNames = new Set(add);
 	const allChecks = [...CHECKS, ...add.map((name) => ({ name }))];
@@ -4727,11 +4729,13 @@ function runRunChecks(targetDir, options = {}) {
 			continue;
 		}
 		const cmd = check.args ? `pnpm run ${check.name} ${check.args}` : `pnpm run ${check.name}`;
+		debug(vc, `Running: ${cmd} (in ${targetDir})`);
 		reporter.groupStart(check.name);
 		const start = Date.now();
 		const exitCode = exec(cmd, targetDir);
 		const elapsed = ((Date.now() - start) / 1e3).toFixed(1);
 		reporter.groupEnd();
+		debug(vc, `${check.name}: exit code ${String(exitCode)}, ${elapsed}s`);
 		if (exitCode === 0) reporter.passed(check.name, elapsed);
 		else {
 			reporter.failed(check.name, elapsed);
@@ -4772,13 +4776,19 @@ const runChecksCommand = defineCommand({
 			type: "boolean",
 			description: "Stop on first failure (default: true in dev, false in CI)",
 			required: false
+		},
+		verbose: {
+			type: "boolean",
+			description: "Emit detailed debug logging",
+			required: false
 		}
 	},
 	run({ args }) {
 		const exitCode = runRunChecks(path.resolve(args.dir ?? "."), {
 			skip: args.skip ? new Set(args.skip.split(",").map((s) => s.trim())) : void 0,
 			add: args.add ? args.add.split(",").map((s) => s.trim()) : void 0,
-			failFast: args["fail-fast"] ? true : void 0
+			failFast: args["fail-fast"] ? true : void 0,
+			verbose: args.verbose === true || isEnvVerbose()
 		});
 		process.exitCode = exitCode;
 	}
@@ -4795,10 +4805,16 @@ const publishDockerCommand = defineCommand({
 		name: "docker:publish",
 		description: "Build, tag, and push Docker images for packages with an image:build script"
 	},
-	args: { "dry-run": {
-		type: "boolean",
-		description: "Build and tag images but skip login, push, and logout"
-	} },
+	args: {
+		"dry-run": {
+			type: "boolean",
+			description: "Build and tag images but skip login, push, and logout"
+		},
+		verbose: {
+			type: "boolean",
+			description: "Emit detailed debug logging"
+		}
+	},
 	async run({ args }) {
 		const config = {
 			cwd: process.cwd(),
@@ -4806,7 +4822,8 @@ const publishDockerCommand = defineCommand({
 			registryNamespace: requireEnv("DOCKER_REGISTRY_NAMESPACE"),
 			username: requireEnv("DOCKER_USERNAME"),
 			password: requireEnv("DOCKER_PASSWORD"),
-			dryRun: args["dry-run"] === true
+			dryRun: args["dry-run"] === true,
+			verbose: args.verbose === true || isEnvVerbose()
 		};
 		runDockerPublish(createRealExecutor(), config);
 	}
@@ -4839,6 +4856,10 @@ const dockerBuildCommand = defineCommand({
 			type: "string",
 			description: "Build a single package by directory path (e.g. packages/server). Useful as an image:build script."
 		},
+		verbose: {
+			type: "boolean",
+			description: "Emit detailed debug logging"
+		},
 		_: {
 			type: "positional",
 			required: false,
@@ -4849,6 +4870,7 @@ const dockerBuildCommand = defineCommand({
 		const executor = createRealExecutor();
 		const rawExtra = args._ ?? [];
 		const extraArgs = Array.isArray(rawExtra) ? rawExtra.map(String) : [String(rawExtra)];
+		const verbose = args.verbose === true || isEnvVerbose();
 		let cwd = process.cwd();
 		let packageDir = args.package;
 		if (!packageDir) {
@@ -4859,7 +4881,8 @@ const dockerBuildCommand = defineCommand({
 		runDockerBuild(executor, {
 			cwd,
 			packageDir,
-			extraArgs: extraArgs.filter((a) => a.length > 0)
+			extraArgs: extraArgs.filter((a) => a.length > 0),
+			verbose
 		});
 	}
 });
@@ -5076,12 +5099,6 @@ function writeTempOverlay(content) {
 	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",
@@ -5095,12 +5112,16 @@ const dockerCheckCommand = defineCommand({
 		"poll-interval": {
 			type: "string",
 			description: "Interval between polling attempts, in ms (default: 5000)"
+		},
+		verbose: {
+			type: "boolean",
+			description: "Emit detailed debug logging"
 		}
 	},
 	async run({ args }) {
 		const cwd = process.cwd();
 		if (loadToolingConfig(cwd)?.dockerCheck === false) {
-			log("Docker check is disabled in .tooling.json");
+			log.info("Docker check is disabled in .tooling.json");
 			return;
 		}
 		const defaults = computeCheckDefaults(cwd);
@@ -5108,8 +5129,8 @@ const dockerCheckCommand = defineCommand({
 		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.");
+			log.warn(`Compose files found but no check overlay. Create ${path.relative(cwd, path.join(composeCwd, expectedOverlay))} to enable docker:check.`);
+			log.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.");
@@ -5122,7 +5143,7 @@ const dockerCheckCommand = defineCommand({
 			if (rootPkg?.name) {
 				const dockerPackages = detectDockerPackages(fileReader, cwd, rootPkg.name);
 				const composeImages = extractComposeImageNames(services);
-				for (const pkg of dockerPackages) if (!composeImages.some((img) => img === pkg.imageName || img.endsWith(`/${pkg.imageName}`))) warn(`Docker package "${pkg.dir}" (image: ${pkg.imageName}) is not referenced in any compose service.`);
+				for (const pkg of dockerPackages) if (!composeImages.some((img) => img === pkg.imageName || img.endsWith(`/${pkg.imageName}`))) log.warn(`Docker package "${pkg.dir}" (image: ${pkg.imageName}) is not referenced in any compose service.`);
 			}
 		}
 		const tempOverlayPath = writeTempOverlay(generateCheckOverlay(services));
@@ -5143,7 +5164,8 @@ const dockerCheckCommand = defineCommand({
 				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
+				pollIntervalMs: args["poll-interval"] ? Number.parseInt(args["poll-interval"], 10) : defaults.pollIntervalMs,
+				verbose: args.verbose === true || isEnvVerbose()
 			};
 			const result = await runDockerCheck(createRealExecutor$1(), config);
 			if (!result.success) throw new FatalError(`Check failed (${result.reason}): ${result.message}`);
@@ -5159,7 +5181,7 @@ const dockerCheckCommand = defineCommand({
 const main = defineCommand({
 	meta: {
 		name: "bst",
-		version: "0.33.0",
+		version: "0.34.0",
 		description: "Bootstrap and maintain standardized TypeScript project tooling"
 	},
 	subCommands: {
@@ -5175,7 +5197,7 @@ const main = defineCommand({
 		"docker:check": dockerCheckCommand
 	}
 });
-console.log(`@bensandee/tooling v0.33.0`);
+console.log(`@bensandee/tooling v0.34.0`);
 async function run() {
 	await runMain(main);
 	process.exit(process.exitCode ?? 0);

package/dist/{check-B2AAPCBO.mjs → check-Ceom_OgJ.mjs}

@@ -1,5 +1,40 @@
+import * as clack from "@clack/prompts";
 import { execSync } from "node:child_process";
 import { z } from "zod";
+//#region src/utils/log.ts
+const out = (msg) => console.log(msg);
+const isCI = Boolean(process.env["CI"]);
+const log = isCI ? {
+	info: out,
+	warn: (msg) => out(`[warn] ${msg}`),
+	error: (msg) => out(`[error] ${msg}`),
+	success: (msg) => out(`✓ ${msg}`)
+} : clack.log;
+function note(body, title) {
+	if (isCI) {
+		if (title) out(`--- ${title} ---`);
+		out(body);
+	} else clack.note(body, title);
+}
+//#endregion
+//#region src/utils/debug.ts
+/** 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) log.info(`[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] ${label} (exit code ${String(result.exitCode)})`];
+	if (result.stdout.trim()) lines.push(`  stdout: ${result.stdout.trim()}`);
+	if (result.stderr.trim()) lines.push(`  stderr: ${result.stderr.trim()}`);
+	log.info(lines.join("\n"));
+}
+//#endregion
 //#region src/utils/exec.ts
 /** Type guard for `execSync` errors that carry stdout/stderr/status. */
 function isExecSyncError(err) {
@@ -144,6 +179,11 @@ async function runDockerCheck(executor, config) {
 	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 = () => {
@@ -171,9 +211,11 @@ async function runDockerCheck(executor, config) {
 		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);
@@ -233,4 +275,4 @@ async function runDockerCheck(executor, config) {
 	}
 }
 //#endregion
-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 };
+export { composeDown as a, composeUp as c, debug as d, debugExec as f, note as h, composeCommand as i, createRealExecutor as l, log as m, checkHttpHealth as n, composeLogs as o, isEnvVerbose as p, getContainerHealth as r, composePs as s, runDockerCheck as t, isExecSyncError as u };

package/dist/docker-check/index.d.mts

@@ -67,6 +67,8 @@ interface CheckConfig {
   timeoutMs?: number;
   /** Interval between polling attempts, in ms. Default: 5000. */
   pollIntervalMs?: number;
+  /** If true, emit detailed debug logging. */
+  verbose?: boolean;
 }
 /** Result of the docker check run. */
 type CheckResult = {

package/dist/docker-check/index.mjs

@@ -1,2 +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-B2AAPCBO.mjs";
+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-Ceom_OgJ.mjs";
 export { checkHttpHealth, composeCommand, composeDown, composeLogs, composePs, composeUp, createRealExecutor, getContainerHealth, runDockerCheck };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bensandee/tooling",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "CLI tool to bootstrap and maintain standardized TypeScript project tooling",
   "bin": {
     "bst": "./dist/bin.mjs"