@bensandee/tooling 0.60.0 → 0.60.1

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`, `--verbose`.                                       |
+| `tooling checks:run`              | Run project checks (build, docker:build, typecheck, lint, test, format, knip, tooling:check, docker:check). Flags: `--skip`, `--add`, `--fail-fast`, `--verbose`, `--with-coverage`.                    |
 
 **Flags:** `--yes` (accept all defaults), `--no-ci`, `--no-prompt`, `--eslint-plugin`
 
@@ -56,6 +56,20 @@ The `--add` flag appends extra checks (must be defined in `package.json`):
 tooling checks:run --add e2e
 ```
 
+The `--with-coverage` flag runs the `test` step via `pnpm run test:coverage` (when that script is defined), producing `coverage/coverage-summary.json` for the `coverage:*` commands.
+
+**Extend the `check` script with `--add`, never a shell chain.** `repo:sync` generates `check` as a single rooted command (`bst checks:run`) and `ci:check` as `pnpm check --skip 'docker:*'`. When CI runs `pnpm ci:check --with-coverage`, pnpm appends the forwarded flag to the _end_ of the resolved script — so it reaches `bst checks:run` only if that is the last command. Adding extra checks via an `&&` chain silently drops `--with-coverage` and `--skip 'docker:*'`:
+
+```jsonc
+// ✓ forwarded flags reach bst checks:run
+"check": "bst checks:run --add check:env-drift,check:custom"
+
+// ✗ --with-coverage / --skip land on check:custom instead
+"check": "bst checks:run && pnpm check:env-drift && pnpm check:custom"
+```
+
+`repo:sync` warns when it detects the broken shape, and `coverage:summary` / `coverage:check` name it as the likely cause if the summary file is missing.
+
 The generated `ci:check` script defaults to `pnpm check --skip 'docker:*'` since CI environments typically lack Docker support.
 
 ### Custom blocks in workflows

package/dist/bin.mjs

@@ -1564,6 +1564,72 @@ async function generateDeployCi(ctx) {
 	};
 }
 //#endregion
+//#region src/utils/script-forwarding.ts
+/**
+* pnpm appends args forwarded via `pnpm <script> <args>` to the END of the
+* resolved script string. A forwarded flag therefore only reaches its intended
+* command when that command is the LAST command in the script. The generated
+* CI workflow depends on this two-hop forwarding:
+*
+*   pnpm ci:check --with-coverage
+*   → pnpm check --skip 'docker:*' --with-coverage
+*   → bst checks:run --skip 'docker:*' --with-coverage
+*
+* If `check` or `ci:check` ends in a different command (e.g. an `&&` chain),
+* the forwarded flags silently land on the wrong command — tests run without
+* coverage and `--skip` becomes a no-op. This module detects that shape so
+* callers can surface a precise diagnosis instead of a confusing downstream
+* failure.
+*/
+/** The final command of a script, after splitting on `&&`, `||`, `|`, and `;`. */
+function lastCommandSegment(script) {
+	return (script.split(/&&|\|\|?|;/).at(-1) ?? "").trim();
+}
+/**
+* True when args forwarded to a `check` script would reach `bst checks:run`
+* — its last command must invoke `bst checks:run` (or the `bin.mjs checks:run`
+* variant used by the tooling repo itself). Trailing flags like `--add` are
+* fine; only the position of the invocation matters.
+*/
+function isCheckScriptForwardingSafe(script) {
+	return /(?:^|[\s/])(?:bst|bin\.mjs)\s+checks:run(?=\s|$)/.test(lastCommandSegment(script));
+}
+/**
+* True when args forwarded to a `ci:check` script would reach `pnpm check`
+* — its last command must invoke `pnpm check` (or `pnpm run check`).
+*/
+function isCiCheckScriptForwardingSafe(script) {
+	return /(?:^|\s)pnpm\s+(?:run\s+)?check(?=\s|$)/.test(lastCommandSegment(script));
+}
+/**
+* Inspect a package.json `scripts` record for `check` / `ci:check` definitions
+* whose shape would swallow pnpm-forwarded args. Returns a human-readable hint
+* naming the problem and the fix, or undefined when forwarding is sound.
+*/
+function diagnoseCheckScriptForwarding(scripts) {
+	if (!scripts) return void 0;
+	const problems = [];
+	const check = scripts["check"];
+	if (check !== void 0 && !isCheckScriptForwardingSafe(check)) problems.push(`the \`check\` script does not end with \`bst checks:run\` (its last command is \`${lastCommandSegment(check)}\`)`);
+	const ciCheck = scripts["ci:check"];
+	if (ciCheck !== void 0 && !isCiCheckScriptForwardingSafe(ciCheck)) problems.push(`the \`ci:check\` script does not end with \`pnpm check\` (its last command is \`${lastCommandSegment(ciCheck)}\`)`);
+	if (problems.length === 0) return void 0;
+	return `Likely cause: ${problems.join(", and ")}. pnpm appends forwarded args (e.g. \`--with-coverage\`, \`--skip 'docker:*'\`) to the end of the resolved script, so they never reach \`bst checks:run\`. Make \`bst checks:run\` the last command — move extra checks into \`bst checks:run --add <name,...>\`.`;
+}
+/**
+* Filesystem wrapper around {@link diagnoseCheckScriptForwarding}: reads
+* `package.json` from `targetDir` (best-effort) and diagnoses its scripts.
+*/
+function diagnoseCheckScriptForwardingAt(targetDir) {
+	let scripts;
+	try {
+		scripts = parsePackageJson(readFileSync(path.join(targetDir, "package.json"), "utf-8"))?.scripts;
+	} catch (_error) {
+		return;
+	}
+	return diagnoseCheckScriptForwarding(scripts);
+}
+//#endregion
 //#region src/generators/package-json.ts
 const STANDARD_SCRIPTS_SINGLE = {
 	build: "tsdown",
@@ -1841,7 +1907,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.11.2";
-	devDeps["@bensandee/tooling"] = isWorkspacePackage(ctx, "@bensandee/tooling") ? "workspace:*" : "0.60.0";
+	devDeps["@bensandee/tooling"] = isWorkspacePackage(ctx, "@bensandee/tooling") ? "workspace:*" : "0.60.1";
 	if (ctx.config.useEslintPlugin) devDeps["@bensandee/eslint-plugin"] = isWorkspacePackage(ctx, "@bensandee/eslint-plugin") ? "workspace:*" : "0.13.0";
 	if (ctx.config.formatter === "oxfmt") devDeps["oxfmt"] = {
 		"@changesets/cli": "2.31.0",
@@ -1901,6 +1967,8 @@ async function generatePackageJson(ctx) {
 			changes.push(`removed deprecated script: ${key}`);
 		}
 		pkg.scripts = existingScripts;
+		const forwardingHint = diagnoseCheckScriptForwarding(existingScripts);
+		if (forwardingHint) log.warn(`package.json: pnpm-forwarded check flags may be dropped. ${forwardingHint}`);
 		const existingDevDeps = pkg.devDependencies ?? {};
 		for (const [key, value] of Object.entries(devDeps)) if (!(key in existingDevDeps)) {
 			existingDevDeps[key] = value;
@@ -4903,7 +4971,7 @@ async function runGenerators(ctx) {
 function generateMigratePrompt(results, config, detected) {
 	const sections = [];
 	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
-	sections.push(`# Migration Prompt\n\n_Generated by \`@bensandee/tooling@0.60.0 repo:sync\` on ${timestamp}_\n`);
+	sections.push(`# Migration Prompt\n\n_Generated by \`@bensandee/tooling@0.60.1 repo:sync\` on ${timestamp}_\n`);
 	const changed = results.filter((r) => r.action === "created" || r.action === "updated" || r.action === "archived");
 	if (changed.length > 0) {
 		const items = changed.map((r) => {
@@ -5971,19 +6039,39 @@ async function runRelease(config, executor) {
 }
 //#endregion
 //#region src/release/dispatch.ts
+const INPUT_FLAG = "--input";
+const INPUT_FLAG_EQ = "--input=";
 /**
-* Parse repeatable `--input key=value` flags into an inputs object.
+* Collect every `--input` value from a command's raw CLI args.
 *
-* Citty types a repeatable string flag as `string`, but the underlying parser
-* collects repeats into an array — so the raw value may be a string, an array
-* of strings, or undefined. Throws {@link FatalError} on malformed input.
+* citty@0.2.2 keeps only the LAST occurrence of a repeated named flag, so a
+* declared `input` arg cannot capture `--input a=1 --input b=2` — it silently
+* yields just `b=2`. Scanning the raw argv directly recovers all occurrences.
+* Both `--input k=v` (two tokens) and `--input=k=v` (one token) forms are
+* supported. Throws {@link FatalError} when `--input` has no following value.
+*/
+function collectInputArgs(rawArgs) {
+	const values = [];
+	for (let i = 0; i < rawArgs.length; i += 1) {
+		const arg = rawArgs[i];
+		if (arg === void 0) continue;
+		if (arg === INPUT_FLAG) {
+			const next = rawArgs[i + 1];
+			if (next === void 0) throw new FatalError("Missing value for --input: expected `--input key=value`");
+			values.push(next);
+			i += 1;
+		} else if (arg.startsWith(INPUT_FLAG_EQ)) values.push(arg.slice(8));
+	}
+	return values;
+}
+/**
+* Parse `key=value` workflow-input strings (as collected by
+* {@link collectInputArgs}) into an inputs object. Throws {@link FatalError} on
+* a malformed entry — no `=`, or an empty key.
 */
 function parseInputs(raw) {
 	const inputs = {};
-	if (raw === void 0 || raw === null) return inputs;
-	const values = Array.isArray(raw) ? raw : [raw];
-	for (const value of values) {
-		if (typeof value !== "string") throw new FatalError(`Invalid --input value: expected key=value, got ${typeof value}`);
+	for (const value of raw) {
 		const eq = value.indexOf("=");
 		if (eq <= 0) throw new FatalError(`Invalid --input "${value}": expected key=value`);
 		inputs[value.slice(0, eq)] = value.slice(eq + 1);
@@ -6101,10 +6189,10 @@ const workflowDispatchCommand = defineCommand({
 			required: false
 		}
 	},
-	async run({ args }) {
+	async run({ args, rawArgs }) {
 		if (!args.workflow) throw new FatalError("--workflow is required");
 		const ref = args.ref ?? "main";
-		const inputs = parseInputs(args.input);
+		const inputs = parseInputs(collectInputArgs(rawArgs));
 		await dispatchWorkflow(resolveConnection(process.cwd()), {
 			repo: args.repo,
 			workflow: args.workflow,
@@ -8405,12 +8493,26 @@ function formatTimestamp(iso) {
 	return `${String(date.getUTCFullYear())}-${String(date.getUTCMonth() + 1).padStart(2, "0")}-${String(date.getUTCDate()).padStart(2, "0")}`;
 }
 //#endregion
+//#region src/commands/coverage-missing-summary.ts
+const COVERAGE_SUMMARY_FILE$3 = "coverage/coverage-summary.json";
+/**
+* Build the "coverage summary not found" error message. When the project's
+* `check` / `ci:check` scripts have a shape that drops pnpm-forwarded flags,
+* a precise diagnosis is appended — that mis-forwarding is the usual reason a
+* CI `--with-coverage` run produces no summary file.
+*/
+function missingSummaryMessage(targetDir) {
+	const base = `${COVERAGE_SUMMARY_FILE$3} not found. Run \`pnpm test:coverage\` first, or add "json-summary" to your vitest reporters.`;
+	const hint = diagnoseCheckScriptForwardingAt(targetDir);
+	return hint ? `${base}\n\n${hint}` : base;
+}
+//#endregion
 //#region src/commands/coverage-summary.ts
 const COVERAGE_SUMMARY_FILE$2 = "coverage/coverage-summary.json";
 const out$3 = (msg) => console.log(msg);
 function readSummary(targetDir) {
 	const summaryPath = path.join(targetDir, COVERAGE_SUMMARY_FILE$2);
-	if (!existsSync(summaryPath)) throw new FatalError(`${COVERAGE_SUMMARY_FILE$2} not found. Run \`pnpm test:coverage\` first, or add "json-summary" to your vitest reporters.`);
+	if (!existsSync(summaryPath)) throw new FatalError(missingSummaryMessage(targetDir));
 	return readFileSync(summaryPath, "utf-8");
 }
 function getHeadSha(targetDir) {
@@ -8493,7 +8595,7 @@ const coverageCheckCommand = defineCommand({
 		const targetDir = path.resolve(args.dir ?? ".");
 		const summaryPath = path.join(targetDir, COVERAGE_SUMMARY_FILE$1);
 		const baselinePath = path.join(targetDir, BASELINE_FILE);
-		if (!existsSync(summaryPath)) throw new FatalError(`${COVERAGE_SUMMARY_FILE$1} not found. Run \`pnpm test:coverage\` first, or add "json-summary" to your vitest reporters.`);
+		if (!existsSync(summaryPath)) throw new FatalError(missingSummaryMessage(targetDir));
 		const current = deriveBaseline(parseV8Summary(readFileSync(summaryPath, "utf-8")), { rootDir: targetDir });
 		if (!existsSync(baselinePath)) {
 			if (args["update-baseline"] === true) {
@@ -8580,7 +8682,7 @@ const out = (msg) => console.log(msg);
 const main = defineCommand({
 	meta: {
 		name: "bst",
-		version: "0.60.0",
+		version: "0.60.1",
 		description: "Bootstrap and maintain standardized TypeScript project tooling"
 	},
 	subCommands: {
@@ -8653,7 +8755,7 @@ const main = defineCommand({
 		})
 	}
 });
-console.log(`@bensandee/tooling v0.60.0`);
+console.log(`@bensandee/tooling v0.60.1`);
 async function run() {
 	await runMain(main);
 	process.exit(process.exitCode ?? 0);

package/package.json

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