@bensandee/tooling 0.64.1 → 0.65.0

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

@@ -109,7 +109,7 @@ declare function createRealExecutor(): DockerCheckExecutor;
 //#endregion
 //#region src/docker-check/check.d.ts
 /** Run the full Docker check lifecycle. */
-declare function runDockerCheck(executor: DockerCheckExecutor, config: CheckConfig): Promise<CheckResult>;
+declare function runDockerCheck(executor: DockerCheckExecutor, rawConfig: CheckConfig): Promise<CheckResult>;
 //#endregion
 //#region src/docker-check/compose.d.ts
 /** Zod schema for a single container entry from `docker compose ps --format json`. */
@@ -242,6 +242,12 @@ declare const ToolingConfigSchema: z.ZodObject<{
     historyBranch: z.ZodOptional<z.ZodString>;
     tolerance: z.ZodOptional<z.ZodNumber>;
   }, z.core.$strip>>;
+  docs: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+    enforced: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
+    dirs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    staleDays: z.ZodOptional<z.ZodNumber>;
+    staleEnforced: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strict>]>>;
   deploy: z.ZodOptional<z.ZodObject<{
     dispatchRepo: z.ZodString;
     stack: z.ZodOptional<z.ZodString>;
@@ -250,6 +256,22 @@ declare const ToolingConfigSchema: z.ZodObject<{
   }, z.core.$strict>>;
   pnpmWorkspace: z.ZodOptional<z.ZodLiteral<false>>;
   defaultBranch: z.ZodOptional<z.ZodString>;
+  unmanagedDevDependencies: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  stack: z.ZodOptional<z.ZodEnum<{
+    none: "none";
+    typescript: "typescript";
+    javascript: "javascript";
+  }>>;
+  builder: z.ZodOptional<z.ZodEnum<{
+    none: "none";
+    custom: "custom";
+    tsdown: "tsdown";
+    vite: "vite";
+  }>>;
+  checks: z.ZodOptional<z.ZodObject<{
+    add: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    skip: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  }, z.core.$strict>>;
 }, z.core.$strict>;
 type ToolingConfig = z.infer<typeof ToolingConfigSchema>;
 //#endregion

package/dist/docker-check/index.mjs

@@ -1,2 +1,2 @@
-import { a as composeArgs, c as composePs, f as lintComposeFiles, i as getContainerHealth, l as composeUp, n as runDockerCheck, o as composeDown, r as checkHttpHealth, s as composeLogs, t as deriveProjectName, u as createRealExecutor } from "../project-name-CHPvgMTP.mjs";
+import { a as composeArgs, c as composePs, d as lintComposeFiles, i as getContainerHealth, l as composeUp, n as runDockerCheck, o as composeDown, r as checkHttpHealth, s as composeLogs, t as deriveProjectName, u as createRealExecutor } from "../project-name-CnyTIy5a.mjs";
 export { checkHttpHealth, composeArgs, composeDown, composeLogs, composePs, composeUp, createRealExecutor, deriveProjectName, getContainerHealth, lintComposeFiles, runDockerCheck };

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-import { a as LegacyConfig, i as GeneratorResult, n as Generator, o as ProjectConfig, r as GeneratorContext, t as DetectedProjectState } from "./types-CMKT2loB.mjs";
+import { a as LegacyConfig, i as GeneratorResult, n as Generator, o as ProjectConfig, r as GeneratorContext, t as DetectedProjectState } from "./types-C6cLSf_a.mjs";
 export type { DetectedProjectState, Generator, GeneratorContext, GeneratorResult, LegacyConfig, ProjectConfig };

package/dist/{project-name-CHPvgMTP.mjs → project-name-CnyTIy5a.mjs}

@@ -1,27 +1,11 @@
-import * as clack from "@clack/prompts";
 import path from "node:path";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { z } from "zod";
 import { parse } from "yaml";
-//#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
 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;
@@ -34,7 +18,7 @@ function isEnvVerbose() {
 }
 /** Log a debug message when verbose mode is enabled. */
 function debug(config, message) {
-	if (config.verbose) log.info(`[debug] ${message}`);
+	if (config.verbose) debugOut(`[debug] ${message}`);
 }
 /** Log the result of an exec call when verbose mode is enabled. */
 function debugExec(config, label, result) {
@@ -42,7 +26,7 @@ function debugExec(config, label, result) {
 	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())}`);
-	log.info(lines.join("\n"));
+	debugOut(lines.join("\n"));
 }
 //#endregion
 //#region src/docker-check/compose-lint.ts
@@ -54,7 +38,7 @@ const ComposeFileShape = z.looseObject({ name: z.unknown().optional() });
 */
 const COMPOSE_DIR_CANDIDATES = [".", "docker"];
 /** Base compose file names whose project namespace defaults to dir basename. */
-const BASE_COMPOSE_FILES = new Set([
+const BASE_COMPOSE_FILES = /* @__PURE__ */ new Set([
 	"docker-compose.yml",
 	"docker-compose.yaml",
 	"compose.yml",
@@ -187,47 +171,29 @@ function readTopLevelName(absPath) {
 	return value;
 }
 //#endregion
-//#region src/utils/exec.ts
-/** Type guard for `execSync` errors that carry stdout/stderr/status. */
-function isExecSyncError(err) {
-	return err instanceof Error && "stdout" in err && typeof err.stdout === "string" && "stderr" in err && typeof err.stderr === "string" && "status" in err && typeof err.status === "number";
-}
-//#endregion
 //#region src/docker-check/executor.ts
 /** Create an executor that runs real commands, fetches, and manages process signals. */
 function createRealExecutor() {
 	return {
 		exec(file, args, options) {
-			try {
-				return {
-					stdout: execFileSync(file, args, {
-						cwd: options?.cwd,
-						env: options?.env ? {
-							...process.env,
-							...options.env
-						} : void 0,
-						encoding: "utf-8",
-						stdio: [
-							"pipe",
-							"pipe",
-							"pipe"
-						]
-					}),
-					stderr: "",
-					exitCode: 0
-				};
-			} catch (err) {
-				if (isExecSyncError(err)) return {
-					stdout: err.stdout,
-					stderr: err.stderr,
-					exitCode: err.status
-				};
-				return {
-					stdout: "",
-					stderr: "",
-					exitCode: 1
-				};
-			}
+			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, {
@@ -270,6 +236,55 @@ function composeArgs(config) {
 	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;
@@ -372,6 +387,33 @@ async function checkHttpHealth(executor, check) {
 //#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) {
@@ -409,7 +451,8 @@ function runSmoketestStep(executor, config, cleanup, startTime) {
 	}
 }
 /** Run the full Docker check lifecycle. */
-async function runDockerCheck(executor, config) {
+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;
@@ -540,4 +583,4 @@ function sanitize(name) {
 	return name.replace(/^@[^/]+\//, "").toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "repo";
 }
 //#endregion
-export { log as _, composeArgs as a, composePs as c, isExecSyncError as d, lintComposeFiles 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, note as v };
+export { composeArgs as a, composePs as c, lintComposeFiles as d, debug as f, redact as h, getContainerHealth as i, composeUp as l, isEnvVerbose as m, runDockerCheck as n, composeDown as o, debugExec as p, checkHttpHealth as r, composeLogs as s, deriveProjectName as t, createRealExecutor as u };

package/dist/{types-CMKT2loB.d.mts → types-C6cLSf_a.d.mts}

@@ -9,6 +9,7 @@ declare const PackageJsonSchema: z.ZodObject<{
   scripts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
   dependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
   devDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  peerDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
   bin: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
   exports: z.ZodOptional<z.ZodUnknown>;
   main: z.ZodOptional<z.ZodString>;
@@ -37,6 +38,10 @@ type PackageJson = z.infer<typeof PackageJsonSchema>;
 type CiPlatform = "github" | "forgejo" | "none";
 type ReleaseStrategy = "release-it" | "simple" | "changesets" | "none";
 type Formatter = "oxfmt" | "prettier";
+/** Whether the repo has TS/JS source at all. Never inferred from absence. */
+type Stack = "typescript" | "javascript" | "none";
+/** What compiles the project, if anything. */
+type Builder = "tsdown" | "vite" | "custom" | "none";
 /** User's answers from the interactive prompt or CLI flags. */
 interface ProjectConfig {
   /** Project name (from package.json name or user input) */
@@ -47,6 +52,10 @@ interface ProjectConfig {
   useEslintPlugin: boolean;
   /** Formatter choice */
   formatter: Formatter;
+  /** Whether the repo has TS/JS source at all */
+  stack: Stack;
+  /** What compiles the project */
+  builder: Builder;
   /** Set up vitest with a starter test */
   setupVitest: boolean;
   /** CI platform choice */
@@ -88,6 +97,13 @@ interface GeneratorContext {
   write: (relativePath: string, content: string) => void;
   /** Remove a file from the target directory (no-op if not found) */
   remove: (relativePath: string) => void;
+  /**
+   * Rewrite generated content the way the target repo's own formatter would — so a
+   * generated file is a fixed point of `pnpm format` and can't drift against
+   * `repo:sync --check`. Returns the content unchanged when the formatter isn't
+   * installed yet. See `utils/format.ts`.
+   */
+  format: (relativePath: string, content: string) => string;
   /** Prompt user for conflict resolution on non-mergeable files */
   confirmOverwrite: (relativePath: string) => Promise<"overwrite" | "skip">;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bensandee/tooling",
-  "version": "0.64.1",
+  "version": "0.65.0",
   "description": "CLI tool to bootstrap and maintain standardized TypeScript project tooling",
   "license": "MIT",
   "repository": {
@@ -47,16 +47,16 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@bensandee/config": "0.12.0",
+    "@bensandee/config": "0.13.1",
     "@changesets/cli": "2.31.0",
     "@release-it/bumper": "7.0.6",
-    "@types/node": "24.13.0",
+    "@types/node": "24.13.2",
     "@types/picomatch": "4.0.3",
     "commit-and-tag-version": "12.7.3",
-    "prettier": "3.8.3",
+    "prettier": "3.8.4",
     "release-it": "20.2.0",
-    "tsdown": "0.22.2",
-    "@bensandee/claude-hooks": "0.8.2"
+    "tsdown": "0.22.3",
+    "@bensandee/claude-hooks": "0.9.0"
   },
   "scripts": {
     "build": "tsdown",

package/tooling.schema.json

@@ -314,6 +314,52 @@
       },
       "additionalProperties": false
     },
+    "docs": {
+      "description": "Plan/spec lifecycle gate (`bst docs:check`). Overrides only — dirs are discovered by convention. Set to false to disable. Violations are advisory until a pair is named in `enforced`.",
+      "anyOf": [
+        {
+          "type": "boolean",
+          "const": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "enforced": {
+              "description": "Which discovered pairs fail the build. true = all; an array names active dirs (e.g. [\"docs/plans\"]); default false = every violation is advisory.",
+              "anyOf": [
+                {
+                  "type": "boolean"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              ]
+            },
+            "dirs": {
+              "description": "Extra active doc dirs beyond convention (e.g. [\"docs/rfcs\"]). Each retires into its own completed/ subdir.",
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "staleDays": {
+              "description": "Days before an untouched active doc is flagged (default 30; 0 disables the rule).",
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 9007199254740991
+            },
+            "staleEnforced": {
+              "description": "Make the staleness rule fatal inside an enforced pair (default false: staleness is always advisory).",
+              "type": "boolean"
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
     "deploy": {
       "description": "Generate a deploy-dispatch step in the release workflow that triggers a workflow_dispatch event in another repo after a successful release. The resolved release token must have rights on `dispatchRepo`.",
       "type": "object",
@@ -346,6 +392,44 @@
     "defaultBranch": {
       "description": "Repository default branch name. Used by `checks:run` to decide when to enable coverage automatically. Default: detected via git (origin/HEAD), falling back to 'main'.",
       "type": "string"
+    },
+    "unmanagedDevDependencies": {
+      "description": "devDependency names repo:sync must never add or re-pin. Escape hatch for holding a tooling-managed dep (oxlint, vitest, knip, ...) at a deliberately off-canonical version; without it, repo:sync raises any managed devDep whose version has drifted below the canonical pin.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "stack": {
+      "description": "Whether the repo has TS/JS source. Detected from source evidence; TypeScript is never inferred from absence.",
+      "type": "string",
+      "enum": ["typescript", "javascript", "none"]
+    },
+    "builder": {
+      "description": "What compiles the project. Detected from the package.json build script, then config-file presence.",
+      "type": "string",
+      "enum": ["tsdown", "vite", "custom", "none"]
+    },
+    "checks": {
+      "description": "Check-pipeline overrides: extra steps to add, and steps to skip (unioned with CI defaults).",
+      "type": "object",
+      "properties": {
+        "add": {
+          "description": "Extra package.json scripts to run as first-class check steps, appended to the built-in list (e.g. ['lint:php']). An added step with no matching script is a hard failure.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "skip": {
+          "description": "Check steps to skip, unioned with the built-in CI defaults (never replacing them). Supports glob patterns.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
     }
   },
   "additionalProperties": false