@warlock.js/core 5.30.0 → 5.31.0

package/esm/cli/commands/upgrade.command.mjs

@@ -0,0 +1,46 @@
+import { command } from "../../commands/cli-command.mjs";
+
+//#region ../../packages/core/src/cli/commands/upgrade.command.ts
+/**
+* `warlock upgrade --to <version>` — apply the mechanical edits for every
+* breaking change between the installed release and the target, and list the
+* places that need a decision (`file:line` plus the reason). `--dry-run`
+* prints a diff and writes nothing; `--json` prints the result as JSON.
+*
+* Needs no app boot: it reads source files, `package.json` and Node version
+* files only. `ts-morph` (an optional peer) is loaded when the command runs.
+*/
+const upgradeCommand = command({
+	name: "upgrade",
+	description: "Apply the code changes a Warlock upgrade needs (--to <version>), and list what to review by hand; --dry-run shows a diff, --json prints JSON",
+	action: async (data) => {
+		const { runUpgradeCommand } = await import("../../upgrade/upgrade-command.action.mjs");
+		await runUpgradeCommand(data.options);
+	},
+	options: [
+		{
+			text: "--to",
+			description: "Version to upgrade to, e.g. 5.31 or 5.31.0 (required)",
+			type: "string"
+		},
+		{
+			text: "--from",
+			description: "Version to upgrade from (default: the installed @warlock.js/core, so pass it once the new release is installed)",
+			type: "string"
+		},
+		{
+			text: "--dry-run",
+			description: "Show the diff and the review list without writing any file",
+			type: "boolean"
+		},
+		{
+			text: "--json, -j",
+			description: "Print the result as JSON",
+			type: "boolean"
+		}
+	]
+});
+
+//#endregion
+export { upgradeCommand };
+//# sourceMappingURL=upgrade.command.mjs.map

package/esm/cli/commands/upgrade.command.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.command.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/cli/commands/upgrade.command.ts"],"sourcesContent":["import { command } from \"../../commands/cli-command\";\n\n/**\n * `warlock upgrade --to <version>` — apply the mechanical edits for every\n * breaking change between the installed release and the target, and list the\n * places that need a decision (`file:line` plus the reason). `--dry-run`\n * prints a diff and writes nothing; `--json` prints the result as JSON.\n *\n * Needs no app boot: it reads source files, `package.json` and Node version\n * files only. `ts-morph` (an optional peer) is loaded when the command runs.\n */\nexport const upgradeCommand = command({\n  name: \"upgrade\",\n  description:\n    \"Apply the code changes a Warlock upgrade needs (--to <version>), and list what to review by hand; --dry-run shows a diff, --json prints JSON\",\n  action: async (data) => {\n    // Loaded here so ts-morph and the codemods never join another command's graph.\n    const { runUpgradeCommand } = await import(\"../../upgrade/upgrade-command.action\");\n    await runUpgradeCommand(data.options);\n  },\n  options: [\n    {\n      text: \"--to\",\n      description: \"Version to upgrade to, e.g. 5.31 or 5.31.0 (required)\",\n      type: \"string\",\n    },\n    {\n      text: \"--from\",\n      description:\n        \"Version to upgrade from (default: the installed @warlock.js/core, so pass it once the new release is installed)\",\n      type: \"string\",\n    },\n    {\n      text: \"--dry-run\",\n      description: \"Show the diff and the review list without writing any file\",\n      type: \"boolean\",\n    },\n    {\n      text: \"--json, -j\",\n      description: \"Print the result as JSON\",\n      type: \"boolean\",\n    },\n  ],\n});\n"],"mappings":";;;;;;;;;;;;AAWA,MAAa,iBAAiB,QAAQ;CACpC,MAAM;CACN,aACE;CACF,QAAQ,OAAO,SAAS;EAEtB,MAAM,EAAE,sBAAsB,MAAM,OAAO;EAC3C,MAAM,kBAAkB,KAAK,OAAO;CACtC;CACA,SAAS;EACP;GACE,MAAM;GACN,aAAa;GACb,MAAM;EACR;EACA;GACE,MAAM;GACN,aACE;GACF,MAAM;EACR;EACA;GACE,MAAM;GACN,aAAa;GACb,MAAM;EACR;EACA;GACE,MAAM;GACN,aAAa;GACb,MAAM;EACR;CACF;AACF,CAAC"}

package/esm/cli/flush-and-exit.mjs

@@ -0,0 +1,34 @@
+//#region ../../packages/core/src/cli/flush-and-exit.ts
+/** How long to wait for stdout/stderr to drain before exiting anyway. */
+const FLUSH_BUDGET_MS = 500;
+function drain(stream) {
+	return new Promise((resolve) => {
+		stream.write("", () => resolve());
+	});
+}
+/**
+* Exit with `code` once everything already written to stdout and stderr has
+* been flushed.
+*
+* For commands whose exit code carries meaning (`warlock check` exits 1 for
+* problems in the code and 2 for problems with the machine): a bare
+* `process.exit()` right after printing a large JSON report to a pipe can cut
+* the report short. Awaited inside the action, so the CLI never goes on to
+* print its success banner or exit 0.
+*
+* @param code The process exit code.
+*/
+async function flushAndExit(code) {
+	process.exitCode = code;
+	let timer;
+	await Promise.race([Promise.all([drain(process.stdout), drain(process.stderr)]), new Promise((resolve) => {
+		timer = setTimeout(resolve, FLUSH_BUDGET_MS);
+		timer.unref?.();
+	})]);
+	if (timer) clearTimeout(timer);
+	return process.exit(code);
+}
+
+//#endregion
+export { flushAndExit };
+//# sourceMappingURL=flush-and-exit.mjs.map

package/esm/cli/flush-and-exit.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"flush-and-exit.mjs","names":[],"sources":["../../../../../../../../packages/core/src/cli/flush-and-exit.ts"],"sourcesContent":["/** How long to wait for stdout/stderr to drain before exiting anyway. */\nconst FLUSH_BUDGET_MS = 500;\n\nfunction drain(stream: NodeJS.WriteStream): Promise<void> {\n  return new Promise((resolve) => {\n    // A zero-length write's callback fires once everything queued ahead of it\n    // has been handed to the OS.\n    stream.write(\"\", () => resolve());\n  });\n}\n\n/**\n * Exit with `code` once everything already written to stdout and stderr has\n * been flushed.\n *\n * For commands whose exit code carries meaning (`warlock check` exits 1 for\n * problems in the code and 2 for problems with the machine): a bare\n * `process.exit()` right after printing a large JSON report to a pipe can cut\n * the report short. Awaited inside the action, so the CLI never goes on to\n * print its success banner or exit 0.\n *\n * @param code The process exit code.\n */\nexport async function flushAndExit(code: number): Promise<never> {\n  process.exitCode = code;\n\n  let timer: NodeJS.Timeout | undefined;\n\n  await Promise.race([\n    Promise.all([drain(process.stdout), drain(process.stderr)]),\n    new Promise<void>((resolve) => {\n      timer = setTimeout(resolve, FLUSH_BUDGET_MS);\n      timer.unref?.();\n    }),\n  ]);\n\n  if (timer) clearTimeout(timer);\n\n  return process.exit(code);\n}\n"],"mappings":";;AACA,MAAM,kBAAkB;AAExB,SAAS,MAAM,QAA2C;CACxD,OAAO,IAAI,SAAS,YAAY;EAG9B,OAAO,MAAM,UAAU,QAAQ,CAAC;CAClC,CAAC;AACH;;;;;;;;;;;;;AAcA,eAAsB,aAAa,MAA8B;CAC/D,QAAQ,WAAW;CAEnB,IAAI;CAEJ,MAAM,QAAQ,KAAK,CACjB,QAAQ,IAAI,CAAC,MAAM,QAAQ,MAAM,GAAG,MAAM,QAAQ,MAAM,CAAC,CAAC,GAC1D,IAAI,SAAe,YAAY;EAC7B,QAAQ,WAAW,SAAS,eAAe;EAC3C,MAAM,QAAQ;CAChB,CAAC,CACH,CAAC;CAED,IAAI,OAAO,aAAa,KAAK;CAE7B,OAAO,QAAQ,KAAK,IAAI;AAC1B"}

package/esm/cli/framework-cli-commands.mjs

@@ -1,19 +1,29 @@
 import { addCommand } from "./commands/add.command.mjs";
+import { agentsMdCommand } from "./commands/agents-md.command.mjs";
+import { boardCommand } from "./commands/board.command.mjs";
 import { buildCommand } from "./commands/build.command.mjs";
+import { checkCommand } from "./commands/check.command.mjs";
 import { createDatabaseCommand } from "./commands/create-database.command.mjs";
 import { devServerCommand } from "./commands/dev-server.command.mjs";
 import { doctorCommand } from "./commands/doctor.command.mjs";
 import { dropTablesCommand } from "./commands/drop-tables.command.mjs";
-import { generateCommand, generateControllerCommand, generateMigrationCommand, generateModelCommand, generateModuleCommand, generateRepositoryCommand, generateResourceCommand, generateServiceCommand, generateUseCaseCommand } from "./commands/generate/generate.command.mjs";
+import { explainCommand } from "./commands/explain.command.mjs";
+import { generateCommand, generateControllerCommand, generateEndpointCommand, generateMigrationCommand, generateModelCommand, generateModuleCommand, generateRepositoryCommand, generateResourceCommand, generateServiceCommand, generateUseCaseCommand, makeCommand } from "./commands/generate/generate.command.mjs";
+import { inspectCommand } from "./commands/inspect.command.mjs";
+import { mcpCommand } from "./commands/mcp.command.mjs";
 import { migrateCommand } from "./commands/migrate.command.mjs";
 import { openApiGeneratorCommand } from "./commands/openapi-generator.command.mjs";
 import { postmanGeneratorCommand } from "./commands/postman-generator.command.mjs";
 import { routesCommand, routesDiffCommand } from "./commands/routes.command.mjs";
 import { seedCommand } from "./commands/seed.command.mjs";
 import { startProductionCommand } from "./commands/start-production.command.mjs";
+import { traceCommand } from "./commands/trace.command.mjs";
 import { storagePutCommand } from "./commands/storage-put.command.mjs";
+import { typecheckCommand } from "./commands/typecheck.command.mjs";
+import { testCommand } from "./commands/test.command.mjs";
 import { typingsGeneratorCommand } from "./commands/typings-generator.command.mjs";
 import { updateCommand } from "./commands/update.command.mjs";
+import { upgradeCommand } from "./commands/upgrade.command.mjs";
 
 //#region ../../packages/core/src/cli/framework-cli-commands.ts
 const frameworkCommands = [
@@ -21,9 +31,18 @@ const frameworkCommands = [
 	typingsGeneratorCommand,
 	openApiGeneratorCommand,
 	postmanGeneratorCommand,
+	testCommand,
 	doctorCommand,
 	routesCommand,
 	routesDiffCommand,
+	inspectCommand,
+	explainCommand,
+	checkCommand,
+	typecheckCommand,
+	mcpCommand,
+	traceCommand,
+	agentsMdCommand,
+	boardCommand,
 	buildCommand,
 	startProductionCommand,
 	migrateCommand,
@@ -32,7 +51,10 @@ const frameworkCommands = [
 	dropTablesCommand,
 	addCommand,
 	updateCommand,
+	upgradeCommand,
 	generateCommand,
+	makeCommand,
+	generateEndpointCommand,
 	generateModuleCommand,
 	generateControllerCommand,
 	generateServiceCommand,

package/esm/cli/framework-cli-commands.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"framework-cli-commands.mjs","names":[],"sources":["../../../../../../../../packages/core/src/cli/framework-cli-commands.ts"],"sourcesContent":["import { addCommand } from \"./commands/add.command\";\nimport { buildCommand } from \"./commands/build.command\";\nimport { createDatabaseCommand } from \"./commands/create-database.command\";\nimport { devServerCommand } from \"./commands/dev-server.command\";\nimport { doctorCommand } from \"./commands/doctor.command\";\nimport { dropTablesCommand } from \"./commands/drop-tables.command\";\nimport {\n  generateCommand,\n  generateControllerCommand,\n  generateMigrationCommand,\n  generateModelCommand,\n  generateModuleCommand,\n  generateRepositoryCommand,\n  generateResourceCommand,\n  generateServiceCommand,\n  generateUseCaseCommand,\n} from \"./commands/generate/generate.command\";\nimport { migrateCommand } from \"./commands/migrate.command\";\nimport { openApiGeneratorCommand } from \"./commands/openapi-generator.command\";\nimport { postmanGeneratorCommand } from \"./commands/postman-generator.command\";\nimport { routesCommand, routesDiffCommand } from \"./commands/routes.command\";\nimport { seedCommand } from \"./commands/seed.command\";\nimport { startProductionCommand } from \"./commands/start-production.command\";\nimport { storagePutCommand } from \"./commands/storage-put.command\";\nimport { typingsGeneratorCommand } from \"./commands/typings-generator.command\";\nimport { updateCommand } from \"./commands/update.command\";\n\nexport const frameworkCommands = [\n  // development commands\n  devServerCommand,\n  typingsGeneratorCommand,\n  openApiGeneratorCommand,\n  postmanGeneratorCommand,\n\n  // diagnostics commands\n  doctorCommand,\n  routesCommand,\n  routesDiffCommand,\n\n  // production commands\n  buildCommand,\n  startProductionCommand,\n\n  // database commands\n  migrateCommand,\n  seedCommand,\n  createDatabaseCommand,\n  dropTablesCommand,\n\n  // generation/installation commands\n  addCommand,\n  updateCommand,\n\n  // scaffolding commands\n  generateCommand,\n  generateModuleCommand,\n  generateControllerCommand,\n  generateServiceCommand,\n  generateUseCaseCommand,\n  generateModelCommand,\n  generateRepositoryCommand,\n  generateResourceCommand,\n  generateMigrationCommand,\n\n  // storage commands\n  storagePutCommand,\n];\n"],"mappings":";;;;;;;;;;;;;;;;;;AA2BA,MAAa,oBAAoB;CAE/B;CACA;CACA;CACA;CAGA;CACA;CACA;CAGA;CACA;CAGA;CACA;CACA;CACA;CAGA;CACA;CAGA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CAGA;AACF"}
+{"version":3,"file":"framework-cli-commands.mjs","names":[],"sources":["../../../../../../../../packages/core/src/cli/framework-cli-commands.ts"],"sourcesContent":["import { addCommand } from \"./commands/add.command\";\nimport { agentsMdCommand } from \"./commands/agents-md.command\";\nimport { boardCommand } from \"./commands/board.command\";\nimport { buildCommand } from \"./commands/build.command\";\nimport { checkCommand } from \"./commands/check.command\";\nimport { createDatabaseCommand } from \"./commands/create-database.command\";\nimport { devServerCommand } from \"./commands/dev-server.command\";\nimport { doctorCommand } from \"./commands/doctor.command\";\nimport { dropTablesCommand } from \"./commands/drop-tables.command\";\nimport { explainCommand } from \"./commands/explain.command\";\nimport {\n  generateCommand,\n  generateControllerCommand,\n  generateEndpointCommand,\n  generateMigrationCommand,\n  generateModelCommand,\n  generateModuleCommand,\n  generateRepositoryCommand,\n  generateResourceCommand,\n  generateServiceCommand,\n  generateUseCaseCommand,\n  makeCommand,\n} from \"./commands/generate/generate.command\";\nimport { inspectCommand } from \"./commands/inspect.command\";\nimport { mcpCommand } from \"./commands/mcp.command\";\nimport { migrateCommand } from \"./commands/migrate.command\";\nimport { openApiGeneratorCommand } from \"./commands/openapi-generator.command\";\nimport { postmanGeneratorCommand } from \"./commands/postman-generator.command\";\nimport { routesCommand, routesDiffCommand } from \"./commands/routes.command\";\nimport { seedCommand } from \"./commands/seed.command\";\nimport { startProductionCommand } from \"./commands/start-production.command\";\nimport { traceCommand } from \"./commands/trace.command\";\nimport { storagePutCommand } from \"./commands/storage-put.command\";\nimport { typecheckCommand } from \"./commands/typecheck.command\";\nimport { testCommand } from \"./commands/test.command\";\nimport { typingsGeneratorCommand } from \"./commands/typings-generator.command\";\nimport { updateCommand } from \"./commands/update.command\";\nimport { upgradeCommand } from \"./commands/upgrade.command\";\n\nexport const frameworkCommands = [\n  // development commands\n  devServerCommand,\n  typingsGeneratorCommand,\n  openApiGeneratorCommand,\n  postmanGeneratorCommand,\n\n  // testing commands\n  testCommand,\n\n  // diagnostics commands\n  doctorCommand,\n  routesCommand,\n  routesDiffCommand,\n  inspectCommand,\n  explainCommand,\n  checkCommand,\n  typecheckCommand,\n\n  // agent tooling commands\n  mcpCommand,\n  traceCommand,\n  agentsMdCommand,\n  boardCommand,\n\n  // production commands\n  buildCommand,\n  startProductionCommand,\n\n  // database commands\n  migrateCommand,\n  seedCommand,\n  createDatabaseCommand,\n  dropTablesCommand,\n\n  // generation/installation commands\n  addCommand,\n  updateCommand,\n  upgradeCommand,\n\n  // scaffolding commands\n  generateCommand,\n  makeCommand,\n  generateEndpointCommand,\n  generateModuleCommand,\n  generateControllerCommand,\n  generateServiceCommand,\n  generateUseCaseCommand,\n  generateModelCommand,\n  generateRepositoryCommand,\n  generateResourceCommand,\n  generateMigrationCommand,\n\n  // storage commands\n  storagePutCommand,\n];\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,MAAa,oBAAoB;CAE/B;CACA;CACA;CACA;CAGA;CAGA;CACA;CACA;CACA;CACA;CACA;CACA;CAGA;CACA;CACA;CACA;CAGA;CACA;CAGA;CACA;CACA;CACA;CAGA;CACA;CACA;CAGA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CAGA;AACF"}

package/esm/cli/parse-cli-args.mjs

@@ -14,6 +14,7 @@ var CliOptionValueError = class extends Error {
 		super(`Invalid value ${JSON.stringify(value)} for boolean option ${optionToken}. Expected one of: true, false, 1, 0, yes, no — or pass ${optionToken} on its own for true.`);
 		this.optionToken = optionToken;
 		this.value = value;
+		this.code = "WL7001";
 		this.name = "CliOptionValueError";
 	}
 };

package/esm/cli/parse-cli-args.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"parse-cli-args.mjs","names":[],"sources":["../../../../../../../../packages/core/src/cli/parse-cli-args.ts"],"sourcesContent":["import { toCamelCase } from \"@mongez/reinforcements\";\n\nexport type ParsedCliArgs = {\n  name: string;\n  args: string[];\n  options: Record<string, string | boolean>;\n};\n\n/**\n * The slice of a declared command option this parser needs.\n *\n * `CLICommand.commandOptions` (`ResolvedCLICommandOption[]`) satisfies it, but\n * the parser stays independent of the command classes so it can be unit-tested\n * and reused with a hand-written schema.\n */\nexport type CliOptionSchema = {\n  name?: string;\n  alias?: string;\n  type?: \"string\" | \"boolean\" | \"number\";\n};\n\n/**\n * Thrown when a declared boolean option is given a value that is neither\n * true-ish nor false-ish.\n *\n * We refuse to guess. Guessing is exactly what produced #21: `--rollback=false`\n * was kept as the truthy string `\"false\"` and dropped every table. An option\n * that gates a destructive action must fail loudly on input it cannot read.\n */\nexport class CliOptionValueError extends Error {\n  public constructor(\n    public readonly optionToken: string,\n    public readonly value: string,\n  ) {\n    super(\n      `Invalid value ${JSON.stringify(value)} for boolean option ${optionToken}. ` +\n        `Expected one of: true, false, 1, 0, yes, no — or pass ${optionToken} on its own for true.`,\n    );\n\n    this.name = \"CliOptionValueError\";\n  }\n}\n\nconst TRUE_VALUES = new Set([\"true\", \"1\", \"yes\"]);\nconst FALSE_VALUES = new Set([\"false\", \"0\", \"no\"]);\n\n/**\n * Collect the camelCased keys (names AND aliases) of every option the command\n * declared as `type: \"boolean\"`.\n *\n * Both sides are camelCased because declared names keep their raw kebab form\n * (`\"pending-only\"`) while the parser emits camelCase keys (`pendingOnly`).\n */\nfunction collectBooleanKeys(schema: CliOptionSchema[]): Set<string> {\n  const keys = new Set<string>();\n\n  for (const option of schema) {\n    if (option.type !== \"boolean\") continue;\n\n    if (option.name) {\n      keys.add(toCamelCase(option.name));\n    }\n\n    if (option.alias) {\n      keys.add(toCamelCase(option.alias));\n    }\n  }\n\n  return keys;\n}\n\n/**\n * Collect the declared aliases longer than one character (`-st`, `-rs`, `-pm`).\n *\n * A cluster equal to one of these is that alias, not a bundle of single-letter\n * flags, so it has to be matched before the bundle split.\n */\nfunction collectMultiCharAliases(schema: CliOptionSchema[]): Set<string> {\n  const aliases = new Set<string>();\n\n  for (const option of schema) {\n    if (option.alias && option.alias.length > 1) {\n      aliases.add(option.alias);\n    }\n  }\n\n  return aliases;\n}\n\n/**\n * Turn the value written after `=` into a real boolean, or throw.\n */\nfunction toBoolean(optionToken: string, value: string): boolean {\n  const normalized = value.toLowerCase();\n\n  if (TRUE_VALUES.has(normalized)) return true;\n  if (FALSE_VALUES.has(normalized)) return false;\n\n  throw new CliOptionValueError(optionToken, value);\n}\n\n/**\n * Parse CLI arguments from process.argv\n *\n * Called with a `schema` (the resolved command's declared options), every\n * option declared `type: \"boolean\"` is resolved as a boolean:\n * `--flag` → true, `--flag=false|0|no` → false, `--flag=true|1|yes` → true,\n * and `--flag <token>` leaves `<token>` as a POSITIONAL instead of swallowing\n * it as the flag's value. Anything else throws {@link CliOptionValueError}.\n *\n * Called without a schema — which is how the command name is discovered,\n * before any command object exists — behaviour is unchanged: every value stays\n * a raw string and a bare `--flag` still consumes the following non-dash token.\n * Nothing is blanket-coerced here on purpose: `--name=false` on a string-typed\n * option must survive as the string `\"false\"`.\n *\n * Options the schema does not declare keep the schema-less behaviour.\n *\n * @example\n * parseCliArgs([\"node\", \"warlock\", \"migrate\", \"--rollback\", \"file.ts\"])\n * // Returns: { name: \"migrate\", args: [], options: { rollback: \"file.ts\" } }\n *\n * @example\n * // `rollback` declared as type: \"boolean\" — the file stays a positional\n * parseCliArgs([\"node\", \"warlock\", \"migrate\", \"--rollback\", \"file.ts\"], migrateOptions)\n * // Returns: { name: \"migrate\", args: [\"file.ts\"], options: { rollback: true } }\n *\n * @example\n * parseCliArgs([\"node\", \"warlock\", \"dev\", \"--port=3000\", \"--fresh\"])\n * // Returns: { name: \"dev\", args: [], options: { port: \"3000\", fresh: true } }\n */\nexport function parseCliArgs(argv: string[], schema: CliOptionSchema[] = []): ParsedCliArgs {\n  // Command is at index 2 (after \"node\" and script path)\n  // But if index 2 starts with \"-\", it's an option, not a command\n  const potentialCommand = argv[2] || \"\";\n  const isFirstArgOption = potentialCommand.startsWith(\"-\");\n  const command = isFirstArgOption ? \"\" : potentialCommand;\n  const args: string[] = [];\n  const options: Record<string, string | boolean> = {};\n  const booleanKeys = collectBooleanKeys(schema);\n  const multiCharAliases = collectMultiCharAliases(schema);\n\n  // Parse arguments starting from index 3 (or 2 if first arg was an option)\n  const startIndex = isFirstArgOption ? 2 : 3;\n  for (let i = startIndex; i < argv.length; i++) {\n    const arg = argv[i];\n\n    // `i < argv.length` bounds this, but the compiler does not narrow an index\n    // read from a loop condition. Skipping rather than coercing: this file\n    // already refuses to guess about an operator's input (see\n    // `CliOptionValueError` above), and an `?? \"\"` here would silently push an\n    // empty POSITIONAL onto `args` — which for a command that takes a file or\n    // a table name is a scope the operator never typed.\n    if (arg === undefined) continue;\n\n    if (arg.startsWith(\"--\")) {\n      // Long option: --key or --key=value\n      const withoutDashes = arg.slice(2);\n      const equalIndex = withoutDashes.indexOf(\"=\");\n\n      if (equalIndex !== -1) {\n        // --key=value format\n        const key = toCamelCase(withoutDashes.slice(0, equalIndex));\n        const value = withoutDashes.slice(equalIndex + 1);\n        options[key] = booleanKeys.has(key)\n          ? toBoolean(`--${withoutDashes.slice(0, equalIndex)}`, value)\n          : value;\n      } else {\n        // --key format (check if next arg is a value)\n        const key = toCamelCase(withoutDashes);\n        const nextArg = argv[i + 1];\n\n        // A declared boolean NEVER consumes the next token: `--rollback\n        // users.ts` means \"rollback, and here is a positional\", not \"rollback\n        // the file users.ts\". Swallowing it silently discarded the operator's\n        // only stated scope and rolled back everything.\n        if (booleanKeys.has(key)) {\n          options[key] = true;\n        } else if (nextArg && !nextArg.startsWith(\"-\")) {\n          // If next arg exists and doesn't start with -, treat it as value\n          options[key] = nextArg;\n          i++; // Skip next arg\n        } else {\n          options[key] = true;\n        }\n      }\n    } else if (arg.startsWith(\"-\") && arg.length > 1) {\n      // Short option: -f, -t=value, or -abc (multiple flags)\n      const flags = arg.slice(1);\n      const equalIndex = flags.indexOf(\"=\");\n\n      if (equalIndex !== -1) {\n        // -t=value format\n        const rawKey = flags.slice(0, equalIndex);\n        const key = toCamelCase(rawKey);\n        const value = flags.slice(equalIndex + 1);\n        options[key] = booleanKeys.has(key) ? toBoolean(`-${rawKey}`, value) : value;\n      } else if (flags.length === 1 || multiCharAliases.has(flags)) {\n        // Single flag: -f, or a declared multi-character alias: -st\n        const key = toCamelCase(flags);\n        const nextArg = argv[i + 1];\n\n        if (booleanKeys.has(key)) {\n          options[key] = true;\n        } else if (nextArg && !nextArg.startsWith(\"-\")) {\n          options[key] = nextArg;\n          i++; // Skip next arg\n        } else {\n          options[key] = true;\n        }\n      } else {\n        // Multiple flags: -abc becomes { a: true, b: true, c: true }\n        // A bundle carries no value and never consumes the next token, so a\n        // declared boolean already resolves to `true` here.\n        for (const flag of flags) {\n          options[toCamelCase(flag)] = true;\n        }\n      }\n    } else {\n      // Positional argument\n      args.push(arg);\n    }\n  }\n\n  return { name: command, args, options };\n}\n"],"mappings":"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"}
+{"version":3,"file":"parse-cli-args.mjs","names":[],"sources":["../../../../../../../../packages/core/src/cli/parse-cli-args.ts"],"sourcesContent":["import { toCamelCase } from \"@mongez/reinforcements\";\n\nexport type ParsedCliArgs = {\n  name: string;\n  args: string[];\n  options: Record<string, string | boolean>;\n};\n\n/**\n * The slice of a declared command option this parser needs.\n *\n * `CLICommand.commandOptions` (`ResolvedCLICommandOption[]`) satisfies it, but\n * the parser stays independent of the command classes so it can be unit-tested\n * and reused with a hand-written schema.\n */\nexport type CliOptionSchema = {\n  name?: string;\n  alias?: string;\n  type?: \"string\" | \"boolean\" | \"number\";\n};\n\n/**\n * Thrown when a declared boolean option is given a value that is neither\n * true-ish nor false-ish.\n *\n * We refuse to guess. Guessing is exactly what produced #21: `--rollback=false`\n * was kept as the truthy string `\"false\"` and dropped every table. An option\n * that gates a destructive action must fail loudly on input it cannot read.\n */\nexport class CliOptionValueError extends Error {\n  /** Stable Warlock error code; `warlock explain WL7001` prints the fix. */\n  public readonly code = \"WL7001\";\n\n  public constructor(\n    public readonly optionToken: string,\n    public readonly value: string,\n  ) {\n    super(\n      `Invalid value ${JSON.stringify(value)} for boolean option ${optionToken}. ` +\n        `Expected one of: true, false, 1, 0, yes, no — or pass ${optionToken} on its own for true.`,\n    );\n\n    this.name = \"CliOptionValueError\";\n  }\n}\n\nconst TRUE_VALUES = new Set([\"true\", \"1\", \"yes\"]);\nconst FALSE_VALUES = new Set([\"false\", \"0\", \"no\"]);\n\n/**\n * Collect the camelCased keys (names AND aliases) of every option the command\n * declared as `type: \"boolean\"`.\n *\n * Both sides are camelCased because declared names keep their raw kebab form\n * (`\"pending-only\"`) while the parser emits camelCase keys (`pendingOnly`).\n */\nfunction collectBooleanKeys(schema: CliOptionSchema[]): Set<string> {\n  const keys = new Set<string>();\n\n  for (const option of schema) {\n    if (option.type !== \"boolean\") continue;\n\n    if (option.name) {\n      keys.add(toCamelCase(option.name));\n    }\n\n    if (option.alias) {\n      keys.add(toCamelCase(option.alias));\n    }\n  }\n\n  return keys;\n}\n\n/**\n * Collect the declared aliases longer than one character (`-st`, `-rs`, `-pm`).\n *\n * A cluster equal to one of these is that alias, not a bundle of single-letter\n * flags, so it has to be matched before the bundle split.\n */\nfunction collectMultiCharAliases(schema: CliOptionSchema[]): Set<string> {\n  const aliases = new Set<string>();\n\n  for (const option of schema) {\n    if (option.alias && option.alias.length > 1) {\n      aliases.add(option.alias);\n    }\n  }\n\n  return aliases;\n}\n\n/**\n * Turn the value written after `=` into a real boolean, or throw.\n */\nfunction toBoolean(optionToken: string, value: string): boolean {\n  const normalized = value.toLowerCase();\n\n  if (TRUE_VALUES.has(normalized)) return true;\n  if (FALSE_VALUES.has(normalized)) return false;\n\n  throw new CliOptionValueError(optionToken, value);\n}\n\n/**\n * Parse CLI arguments from process.argv\n *\n * Called with a `schema` (the resolved command's declared options), every\n * option declared `type: \"boolean\"` is resolved as a boolean:\n * `--flag` → true, `--flag=false|0|no` → false, `--flag=true|1|yes` → true,\n * and `--flag <token>` leaves `<token>` as a POSITIONAL instead of swallowing\n * it as the flag's value. Anything else throws {@link CliOptionValueError}.\n *\n * Called without a schema — which is how the command name is discovered,\n * before any command object exists — behaviour is unchanged: every value stays\n * a raw string and a bare `--flag` still consumes the following non-dash token.\n * Nothing is blanket-coerced here on purpose: `--name=false` on a string-typed\n * option must survive as the string `\"false\"`.\n *\n * Options the schema does not declare keep the schema-less behaviour.\n *\n * @example\n * parseCliArgs([\"node\", \"warlock\", \"migrate\", \"--rollback\", \"file.ts\"])\n * // Returns: { name: \"migrate\", args: [], options: { rollback: \"file.ts\" } }\n *\n * @example\n * // `rollback` declared as type: \"boolean\" — the file stays a positional\n * parseCliArgs([\"node\", \"warlock\", \"migrate\", \"--rollback\", \"file.ts\"], migrateOptions)\n * // Returns: { name: \"migrate\", args: [\"file.ts\"], options: { rollback: true } }\n *\n * @example\n * parseCliArgs([\"node\", \"warlock\", \"dev\", \"--port=3000\", \"--fresh\"])\n * // Returns: { name: \"dev\", args: [], options: { port: \"3000\", fresh: true } }\n */\nexport function parseCliArgs(argv: string[], schema: CliOptionSchema[] = []): ParsedCliArgs {\n  // Command is at index 2 (after \"node\" and script path)\n  // But if index 2 starts with \"-\", it's an option, not a command\n  const potentialCommand = argv[2] || \"\";\n  const isFirstArgOption = potentialCommand.startsWith(\"-\");\n  const command = isFirstArgOption ? \"\" : potentialCommand;\n  const args: string[] = [];\n  const options: Record<string, string | boolean> = {};\n  const booleanKeys = collectBooleanKeys(schema);\n  const multiCharAliases = collectMultiCharAliases(schema);\n\n  // Parse arguments starting from index 3 (or 2 if first arg was an option)\n  const startIndex = isFirstArgOption ? 2 : 3;\n  for (let i = startIndex; i < argv.length; i++) {\n    const arg = argv[i];\n\n    // `i < argv.length` bounds this, but the compiler does not narrow an index\n    // read from a loop condition. Skipping rather than coercing: this file\n    // already refuses to guess about an operator's input (see\n    // `CliOptionValueError` above), and an `?? \"\"` here would silently push an\n    // empty POSITIONAL onto `args` — which for a command that takes a file or\n    // a table name is a scope the operator never typed.\n    if (arg === undefined) continue;\n\n    if (arg.startsWith(\"--\")) {\n      // Long option: --key or --key=value\n      const withoutDashes = arg.slice(2);\n      const equalIndex = withoutDashes.indexOf(\"=\");\n\n      if (equalIndex !== -1) {\n        // --key=value format\n        const key = toCamelCase(withoutDashes.slice(0, equalIndex));\n        const value = withoutDashes.slice(equalIndex + 1);\n        options[key] = booleanKeys.has(key)\n          ? toBoolean(`--${withoutDashes.slice(0, equalIndex)}`, value)\n          : value;\n      } else {\n        // --key format (check if next arg is a value)\n        const key = toCamelCase(withoutDashes);\n        const nextArg = argv[i + 1];\n\n        // A declared boolean NEVER consumes the next token: `--rollback\n        // users.ts` means \"rollback, and here is a positional\", not \"rollback\n        // the file users.ts\". Swallowing it silently discarded the operator's\n        // only stated scope and rolled back everything.\n        if (booleanKeys.has(key)) {\n          options[key] = true;\n        } else if (nextArg && !nextArg.startsWith(\"-\")) {\n          // If next arg exists and doesn't start with -, treat it as value\n          options[key] = nextArg;\n          i++; // Skip next arg\n        } else {\n          options[key] = true;\n        }\n      }\n    } else if (arg.startsWith(\"-\") && arg.length > 1) {\n      // Short option: -f, -t=value, or -abc (multiple flags)\n      const flags = arg.slice(1);\n      const equalIndex = flags.indexOf(\"=\");\n\n      if (equalIndex !== -1) {\n        // -t=value format\n        const rawKey = flags.slice(0, equalIndex);\n        const key = toCamelCase(rawKey);\n        const value = flags.slice(equalIndex + 1);\n        options[key] = booleanKeys.has(key) ? toBoolean(`-${rawKey}`, value) : value;\n      } else if (flags.length === 1 || multiCharAliases.has(flags)) {\n        // Single flag: -f, or a declared multi-character alias: -st\n        const key = toCamelCase(flags);\n        const nextArg = argv[i + 1];\n\n        if (booleanKeys.has(key)) {\n          options[key] = true;\n        } else if (nextArg && !nextArg.startsWith(\"-\")) {\n          options[key] = nextArg;\n          i++; // Skip next arg\n        } else {\n          options[key] = true;\n        }\n      } else {\n        // Multiple flags: -abc becomes { a: true, b: true, c: true }\n        // A bundle carries no value and never consumes the next token, so a\n        // declared boolean already resolves to `true` here.\n        for (const flag of flags) {\n          options[toCamelCase(flag)] = true;\n        }\n      }\n    } else {\n      // Positional argument\n      args.push(arg);\n    }\n  }\n\n  return { name: command, args, options };\n}\n"],"mappings":"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"}

package/esm/config/config-loader.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"config-loader.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/config/config-loader.ts"],"mappings":";AAgBA;;;;AAAA,KAAY,oBAAA,IAAwB,WAAA,oBAA+B,OAAO"}
+{"version":3,"file":"config-loader.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/config/config-loader.ts"],"mappings":";AAiBA;;;;AAAA,KAAY,oBAAA,IAAwB,WAAA,oBAA+B,OAAO"}

package/esm/config/config-loader.mjs

@@ -1,9 +1,10 @@
 import { configSpecialHandlers } from "./config-special-handlers.mjs";
+import { InvalidConfigError, validateConfigValue } from "./config-schema.mjs";
 import { importAppModule } from "../loader/app-module-importer.mjs";
 import { configKeyFromPath } from "./config-key-from-path.mjs";
 import config from "@mongez/config";
-import { colors } from "@mongez/copper";
 import { pathToFileURL } from "node:url";
+import { colors } from "@mongez/copper";
 
 //#region ../../packages/core/src/config/config-loader.ts
 /**
@@ -12,8 +13,16 @@ import { pathToFileURL } from "node:url";
 * Supports special handlers for configs that require additional processing
 */
 var ConfigLoader = class {
+	/**
+	* Load every config file, then throw one {@link InvalidConfigError} listing
+	* every value that fails its file's `configSchema`. An invalid config is
+	* still registered (later files may read it while loading) but its special
+	* handler does not run, so nothing connects with a broken configuration.
+	*/
 	async loadAll(configFiles) {
-		for (const file of configFiles) await this.loadConfig(file);
+		const issues = [];
+		for (const file of configFiles) issues.push(...await this.loadConfigFile(file, "register-invalid"));
+		if (issues.length > 0) throw new InvalidConfigError(issues);
 	}
 	/**
 	* Load a single configuration file.
@@ -22,19 +31,31 @@ var ConfigLoader = class {
 	* cycle gets a fresh module — no manual cache-busting needed here.
 	*/
 	async loadConfig(file) {
+		const issues = await this.loadConfigFile(file, "keep-previous");
+		if (issues.length > 0) throw new InvalidConfigError(issues);
+	}
+	/**
+	* Import, validate and register one config file. Returns the schema issues.
+	* On a hot reload (`keep-previous`) an invalid value is not registered, so
+	* the running app keeps its last valid configuration.
+	*/
+	async loadConfigFile(file, whenInvalid) {
 		const configName = this.getConfigName(file.relativePath);
-		try {
-			const fileUrl = pathToFileURL(file.absolutePath).href;
-			const configValue = (await importAppModule(fileUrl)).default;
-			if (configValue === void 0) {
-				console.log(colors.red(`config error: `), `Config file ${colors.yellow(file.relativePath)} does not have a default export`);
-				return;
-			}
-			config.set(configName, configValue);
-			await configSpecialHandlers.execute(configName, configValue);
-		} catch (error) {
-			throw error;
+		const fileUrl = pathToFileURL(file.absolutePath).href;
+		const configModule = await importAppModule(fileUrl);
+		const configValue = configModule.default;
+		if (configValue === void 0) {
+			console.log(colors.red(`config error: `), `Config file ${colors.yellow(file.relativePath)} does not have a default export`);
+			return [];
+		}
+		const issues = await validateConfigValue(configName, configValue, configModule.configSchema);
+		if (issues.length > 0) {
+			if (whenInvalid === "register-invalid") config.set(configName, configValue);
+			return issues;
 		}
+		config.set(configName, configValue);
+		await configSpecialHandlers.execute(configName, configValue);
+		return [];
 	}
 	async reloadConfig(file) {
 		await this.loadConfig(file);

package/esm/config/config-loader.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"config-loader.mjs","names":[],"sources":["../../../../../../../../packages/core/src/config/config-loader.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport { colors } from \"@mongez/copper\";\nimport { pathToFileURL } from \"node:url\";\nimport type { FileManager } from \"../dev-server/file-manager\";\nimport { importAppModule } from \"../loader/app-module-importer\";\nimport { configKeyFromPath } from \"./config-key-from-path\";\nimport { configSpecialHandlers } from \"./config-special-handlers\";\n\n/**\n * Special Config Handler\n * A function that handles special configuration loading\n */\n// Returns unknown, not void: ConfigSpecialHandlers.execute() RETURNS handler(config)\n// rather than discarding it, and a test pins that (\"returns the handler's resolved\n// value\"). The implementation and the test agreed; only this type said handlers\n// produce nothing, which made any value-returning handler fail to typecheck.\nexport type SpecialConfigHandler = (configValue: any) => unknown | Promise<unknown>;\n\n/**\n * Config Loader\n * Dynamically loads all configuration files and registers them with @mongez/config\n * Supports special handlers for configs that require additional processing\n */\nexport class ConfigLoader {\n  public async loadAll(configFiles: FileManager[]): Promise<void> {\n    for (const file of configFiles) {\n      await this.loadConfig(file);\n    }\n  }\n\n  /**\n   * Load a single configuration file.\n   *\n   * The ESM loader hook stamps a version token onto the URL so that each HMR\n   * cycle gets a fresh module — no manual cache-busting needed here.\n   */\n  public async loadConfig(file: FileManager): Promise<void> {\n    const configName = this.getConfigName(file.relativePath);\n\n    try {\n      const fileUrl = pathToFileURL(file.absolutePath).href;\n      const configModule = await importAppModule(fileUrl);\n      const configValue = configModule.default;\n\n      if (configValue === undefined) {\n        console.log(\n          colors.red(`config error: `),\n          `Config file ${colors.yellow(file.relativePath)} does not have a default export`,\n        );\n        return;\n      }\n\n      config.set(configName, configValue);\n      await configSpecialHandlers.execute(configName, configValue);\n    } catch (error) {\n      throw error;\n    }\n  }\n\n  public async reloadConfig(file: FileManager): Promise<void> {\n    await this.loadConfig(file);\n  }\n\n  private getConfigName(relativePath: string): string {\n    const configName = configKeyFromPath(relativePath);\n\n    if (!configName) {\n      throw new Error(`Invalid config file path: ${relativePath}`);\n    }\n\n    return configName;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AAuBA,IAAa,eAAb,MAA0B;CACxB,MAAa,QAAQ,aAA2C;EAC9D,KAAK,MAAM,QAAQ,aACjB,MAAM,KAAK,WAAW,IAAI;CAE9B;;;;;;;CAQA,MAAa,WAAW,MAAkC;EACxD,MAAM,aAAa,KAAK,cAAc,KAAK,YAAY;EAEvD,IAAI;GACF,MAAM,UAAU,cAAc,KAAK,YAAY,CAAC,CAAC;GAEjD,MAAM,eAAc,MADO,gBAAgB,OAAO,EAClB,CAAC;GAEjC,IAAI,gBAAgB,QAAW;IAC7B,QAAQ,IACN,OAAO,IAAI,gBAAgB,GAC3B,eAAe,OAAO,OAAO,KAAK,YAAY,EAAE,gCAClD;IACA;GACF;GAEA,OAAO,IAAI,YAAY,WAAW;GAClC,MAAM,sBAAsB,QAAQ,YAAY,WAAW;EAC7D,SAAS,OAAO;GACd,MAAM;EACR;CACF;CAEA,MAAa,aAAa,MAAkC;EAC1D,MAAM,KAAK,WAAW,IAAI;CAC5B;CAEA,AAAQ,cAAc,cAA8B;EAClD,MAAM,aAAa,kBAAkB,YAAY;EAEjD,IAAI,CAAC,YACH,MAAM,IAAI,MAAM,6BAA6B,cAAc;EAG7D,OAAO;CACT;AACF"}
+{"version":3,"file":"config-loader.mjs","names":[],"sources":["../../../../../../../../packages/core/src/config/config-loader.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport { colors } from \"@mongez/copper\";\nimport { pathToFileURL } from \"node:url\";\nimport type { FileManager } from \"../dev-server/file-manager\";\nimport { importAppModule } from \"../loader/app-module-importer\";\nimport { configKeyFromPath } from \"./config-key-from-path\";\nimport { type ConfigIssue, InvalidConfigError, validateConfigValue } from \"./config-schema\";\nimport { configSpecialHandlers } from \"./config-special-handlers\";\n\n/**\n * Special Config Handler\n * A function that handles special configuration loading\n */\n// Returns unknown, not void: ConfigSpecialHandlers.execute() RETURNS handler(config)\n// rather than discarding it, and a test pins that (\"returns the handler's resolved\n// value\"). The implementation and the test agreed; only this type said handlers\n// produce nothing, which made any value-returning handler fail to typecheck.\nexport type SpecialConfigHandler = (configValue: any) => unknown | Promise<unknown>;\n\n/**\n * Config Loader\n * Dynamically loads all configuration files and registers them with @mongez/config\n * Supports special handlers for configs that require additional processing\n */\nexport class ConfigLoader {\n  /**\n   * Load every config file, then throw one {@link InvalidConfigError} listing\n   * every value that fails its file's `configSchema`. An invalid config is\n   * still registered (later files may read it while loading) but its special\n   * handler does not run, so nothing connects with a broken configuration.\n   */\n  public async loadAll(configFiles: FileManager[]): Promise<void> {\n    const issues: ConfigIssue[] = [];\n\n    for (const file of configFiles) {\n      issues.push(...(await this.loadConfigFile(file, \"register-invalid\")));\n    }\n\n    if (issues.length > 0) throw new InvalidConfigError(issues);\n  }\n\n  /**\n   * Load a single configuration file.\n   *\n   * The ESM loader hook stamps a version token onto the URL so that each HMR\n   * cycle gets a fresh module — no manual cache-busting needed here.\n   */\n  public async loadConfig(file: FileManager): Promise<void> {\n    const issues = await this.loadConfigFile(file, \"keep-previous\");\n\n    if (issues.length > 0) throw new InvalidConfigError(issues);\n  }\n\n  /**\n   * Import, validate and register one config file. Returns the schema issues.\n   * On a hot reload (`keep-previous`) an invalid value is not registered, so\n   * the running app keeps its last valid configuration.\n   */\n  private async loadConfigFile(\n    file: FileManager,\n    whenInvalid: \"register-invalid\" | \"keep-previous\",\n  ): Promise<ConfigIssue[]> {\n    const configName = this.getConfigName(file.relativePath);\n\n    const fileUrl = pathToFileURL(file.absolutePath).href;\n    const configModule = await importAppModule(fileUrl);\n    const configValue = configModule.default;\n\n    if (configValue === undefined) {\n      console.log(\n        colors.red(`config error: `),\n        `Config file ${colors.yellow(file.relativePath)} does not have a default export`,\n      );\n      return [];\n    }\n\n    const issues = await validateConfigValue(configName, configValue, configModule.configSchema);\n\n    if (issues.length > 0) {\n      if (whenInvalid === \"register-invalid\") config.set(configName, configValue);\n      return issues;\n    }\n\n    config.set(configName, configValue);\n    await configSpecialHandlers.execute(configName, configValue);\n\n    return [];\n  }\n\n  public async reloadConfig(file: FileManager): Promise<void> {\n    await this.loadConfig(file);\n  }\n\n  private getConfigName(relativePath: string): string {\n    const configName = configKeyFromPath(relativePath);\n\n    if (!configName) {\n      throw new Error(`Invalid config file path: ${relativePath}`);\n    }\n\n    return configName;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;AAwBA,IAAa,eAAb,MAA0B;;;;;;;CAOxB,MAAa,QAAQ,aAA2C;EAC9D,MAAM,SAAwB,CAAC;EAE/B,KAAK,MAAM,QAAQ,aACjB,OAAO,KAAK,GAAI,MAAM,KAAK,eAAe,MAAM,kBAAkB,CAAE;EAGtE,IAAI,OAAO,SAAS,GAAG,MAAM,IAAI,mBAAmB,MAAM;CAC5D;;;;;;;CAQA,MAAa,WAAW,MAAkC;EACxD,MAAM,SAAS,MAAM,KAAK,eAAe,MAAM,eAAe;EAE9D,IAAI,OAAO,SAAS,GAAG,MAAM,IAAI,mBAAmB,MAAM;CAC5D;;;;;;CAOA,MAAc,eACZ,MACA,aACwB;EACxB,MAAM,aAAa,KAAK,cAAc,KAAK,YAAY;EAEvD,MAAM,UAAU,cAAc,KAAK,YAAY,CAAC,CAAC;EACjD,MAAM,eAAe,MAAM,gBAAgB,OAAO;EAClD,MAAM,cAAc,aAAa;EAEjC,IAAI,gBAAgB,QAAW;GAC7B,QAAQ,IACN,OAAO,IAAI,gBAAgB,GAC3B,eAAe,OAAO,OAAO,KAAK,YAAY,EAAE,gCAClD;GACA,OAAO,CAAC;EACV;EAEA,MAAM,SAAS,MAAM,oBAAoB,YAAY,aAAa,aAAa,YAAY;EAE3F,IAAI,OAAO,SAAS,GAAG;GACrB,IAAI,gBAAgB,oBAAoB,OAAO,IAAI,YAAY,WAAW;GAC1E,OAAO;EACT;EAEA,OAAO,IAAI,YAAY,WAAW;EAClC,MAAM,sBAAsB,QAAQ,YAAY,WAAW;EAE3D,OAAO,CAAC;CACV;CAEA,MAAa,aAAa,MAAkC;EAC1D,MAAM,KAAK,WAAW,IAAI;CAC5B;CAEA,AAAQ,cAAc,cAA8B;EAClD,MAAM,aAAa,kBAAkB,YAAY;EAEjD,IAAI,CAAC,YACH,MAAM,IAAI,MAAM,6BAA6B,cAAc;EAG7D,OAAO;CACT;AACF"}

package/esm/config/config-schema.d.mts

@@ -0,0 +1,67 @@
+import { BaseValidator, Infer } from "@warlock.js/seal";
+
+//#region ../../packages/core/src/config/config-schema.d.ts
+declare const CONFIG_SCHEMA_MARKER: unique symbol;
+type ConfigSchemaOptions = {
+  /**
+   * The environment variable each key is read from, by key path
+   * (`{ host: "MAIL_HOST", "smtp.password": "SMTP_PASSWORD" }`). Named in the
+   * boot error so the fix is obvious.
+   */
+  env?: Readonly<Record<string, string>>;
+};
+/** A config file's schema, as returned by {@link defineConfigSchema}. */
+type ConfigSchema<TValidator extends BaseValidator = BaseValidator> = {
+  readonly [CONFIG_SCHEMA_MARKER]: true;
+  readonly validator: TValidator;
+  readonly env: Readonly<Record<string, string>>;
+};
+/** The config value a schema describes, for typing the default export. */
+type ConfigOf<TSchema extends ConfigSchema> = TSchema extends ConfigSchema<infer TValidator> ? Infer.Input<TValidator> : never;
+/** One problem found while validating configuration. */
+type ConfigIssue = {
+  /** Config name (the file's key, e.g. `mail`). */config: string; /** Key path inside it (`smtp.host`); empty for the config value as a whole. */
+  key: string; /** What is wrong, from the schema's rule. */
+  message: string; /** The environment variable that feeds this key, when the schema names it. */
+  env?: string;
+};
+/**
+ * Declare the schema a config file's default export must satisfy. Export the
+ * result as `configSchema` from the same file.
+ */
+declare function defineConfigSchema<TValidator extends BaseValidator>(validator: TValidator, options?: ConfigSchemaOptions): ConfigSchema<TValidator>;
+/** Whether a value is a {@link ConfigSchema}. */
+declare function isConfigSchema(value: unknown): value is ConfigSchema;
+/**
+ * Thrown at boot when one or more config files do not satisfy their
+ * `configSchema`. `issues` lists every problem; the message is ready to print.
+ */
+declare class InvalidConfigError extends Error {
+  readonly issues: readonly ConfigIssue[];
+  readonly name = "InvalidConfigError";
+  constructor(issues: readonly ConfigIssue[]);
+}
+/** Render issues as the boot error message. */
+declare function formatConfigIssues(issues: readonly ConfigIssue[]): string;
+/**
+ * Validate one config value against its schema. Returns the issues found (an
+ * empty list when it is valid, or when `schema` is not a config schema).
+ */
+declare function validateConfigValue(configName: string, value: unknown, schema: unknown): Promise<ConfigIssue[]>;
+/** A loaded config module: its default export and, optionally, its `configSchema`. */
+type ConfigModuleEntry = {
+  name: string;
+  module: {
+    default?: unknown;
+    configSchema?: unknown;
+  };
+};
+/**
+ * Validate every config module that exports a `configSchema` and throw one
+ * {@link InvalidConfigError} listing all problems. Used by the production
+ * config loader `warlock build` generates.
+ */
+declare function assertValidConfigModules(entries: readonly ConfigModuleEntry[]): Promise<void>;
+//#endregion
+export { ConfigIssue, ConfigModuleEntry, ConfigOf, ConfigSchema, ConfigSchemaOptions, InvalidConfigError, assertValidConfigModules, defineConfigSchema, formatConfigIssues, isConfigSchema, validateConfigValue };
+//# sourceMappingURL=config-schema.d.mts.map

package/esm/config/config-schema.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-schema.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/config/config-schema.ts"],"mappings":";;;cAmCM,oBAAA;AAAA,KAEM,mBAAA;EAaD;;;;AAAoB;EAP7B,GAAA,GAAM,QAAQ,CAAC,MAAA;AAAA;;KAIL,YAAA,oBAAgC,aAAA,GAAgB,aAAA;EAAA,UAChD,oBAAA;EAAA,SACD,SAAA,EAAW,UAAA;EAAA,SACX,GAAA,EAAK,QAAA,CAAS,MAAA;AAAA;;KAIb,QAAA,iBAAyB,YAAA,IACnC,OAAA,SAAgB,YAAA,qBAAiC,KAAA,CAAM,KAAA,CAAM,UAAA;;KAGnD,WAAA;EAHV,iDAKA,MAAA,UALmC;EAOnC,GAAA,UAPuD;EASvD,OAAA,UATuE;EAWvE,GAAA;AAAA;;;;;iBAOc,kBAAA,oBAAsC,aAAA,EACpD,SAAA,EAAW,UAAA,EACX,OAAA,GAAS,mBAAA,GACR,YAAA,CAAa,UAAA;;iBAKA,cAAA,CAAe,KAAA,YAAiB,KAAA,IAAS,YAAY;;AAfhE;AAOL;;cAoBa,kBAAA,SAA2B,KAAA;EAAA,SAGH,MAAA,WAAiB,WAAA;EAAA,SAF3B,IAAA;cAEU,MAAA,WAAiB,WAAA;AAAA;;iBAMtC,kBAAA,CAAmB,MAA8B,WAAb,WAAW;;;;;iBAgBzC,mBAAA,CACpB,UAAA,UACA,KAAA,WACA,MAAA,YACC,OAAO,CAAC,WAAA;;KAuBC,iBAAA;EACV,IAAA;EACA,MAAA;IAAU,OAAA;IAAmB,YAAA;EAAA;AAAA;;;;;;iBAQT,wBAAA,CACpB,OAAA,WAAkB,iBAAA,KACjB,OAAO"}

package/esm/config/config-schema.mjs

@@ -0,0 +1,77 @@
+import { validate } from "@warlock.js/seal";
+
+//#region ../../packages/core/src/config/config-schema.ts
+const CONFIG_SCHEMA_MARKER = Symbol.for("warlock.js.configSchema");
+/**
+* Declare the schema a config file's default export must satisfy. Export the
+* result as `configSchema` from the same file.
+*/
+function defineConfigSchema(validator, options = {}) {
+	return {
+		[CONFIG_SCHEMA_MARKER]: true,
+		validator,
+		env: { ...options.env }
+	};
+}
+/** Whether a value is a {@link ConfigSchema}. */
+function isConfigSchema(value) {
+	return typeof value === "object" && value !== null && value[CONFIG_SCHEMA_MARKER] === true;
+}
+/**
+* Thrown at boot when one or more config files do not satisfy their
+* `configSchema`. `issues` lists every problem; the message is ready to print.
+*/
+var InvalidConfigError = class extends Error {
+	constructor(issues) {
+		super(formatConfigIssues(issues));
+		this.issues = issues;
+		this.name = "InvalidConfigError";
+	}
+};
+/** Render issues as the boot error message. */
+function formatConfigIssues(issues) {
+	const lines = issues.map((issue) => {
+		const path = issue.key ? `${issue.config}.${issue.key}` : issue.config;
+		const hint = issue.env ? ` (set ${issue.env} in your environment or .env)` : "";
+		return `  - ${path}: ${issue.message}${hint}`;
+	});
+	return `Invalid configuration (${issues.length === 1 ? "1 problem" : `${issues.length} problems`}); the app cannot start until it is fixed:\n${lines.join("\n")}`;
+}
+/**
+* Validate one config value against its schema. Returns the issues found (an
+* empty list when it is valid, or when `schema` is not a config schema).
+*/
+async function validateConfigValue(configName, value, schema) {
+	if (!isConfigSchema(schema)) return [];
+	const result = await validate(schema.validator, value);
+	if (result.isValid) return [];
+	if (result.errors.length === 0) return [{
+		config: configName,
+		key: "",
+		message: "does not match its config schema"
+	}];
+	return result.errors.map((error) => {
+		const key = error.input ?? "";
+		const env = schema.env[key];
+		return {
+			config: configName,
+			key,
+			message: error.error,
+			...env !== void 0 && { env }
+		};
+	});
+}
+/**
+* Validate every config module that exports a `configSchema` and throw one
+* {@link InvalidConfigError} listing all problems. Used by the production
+* config loader `warlock build` generates.
+*/
+async function assertValidConfigModules(entries) {
+	const issues = [];
+	for (const entry of entries) issues.push(...await validateConfigValue(entry.name, entry.module.default, entry.module.configSchema));
+	if (issues.length > 0) throw new InvalidConfigError(issues);
+}
+
+//#endregion
+export { InvalidConfigError, assertValidConfigModules, defineConfigSchema, formatConfigIssues, isConfigSchema, validateConfigValue };
+//# sourceMappingURL=config-schema.mjs.map

package/esm/config/config-schema.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-schema.mjs","names":[],"sources":["../../../../../../../../packages/core/src/config/config-schema.ts"],"sourcesContent":["/**\n * Typed, validated configuration.\n *\n * A config file (`src/config/<name>.ts`) may export a `configSchema` next to\n * its default export. Before the config is registered, at `warlock dev` boot,\n * on every config hot reload, and at production start, its value is validated\n * against that schema. Every problem across every config file is collected and\n * the app refuses to start with ONE error that lists them all — key path, what\n * is wrong, and the environment variable to set when the schema names one.\n * Values are never printed, so a secret cannot end up in the boot log.\n *\n * Config files without a `configSchema` load exactly as before.\n *\n * @example\n * // src/config/mail.ts\n * import { defineConfigSchema, env, type ConfigOf } from \"@warlock.js/core\";\n * import { v } from \"@warlock.js/seal\";\n *\n * export const configSchema = defineConfigSchema(\n *   v.object({ host: v.string(), port: v.int(), from: v.email() }),\n *   { env: { host: \"MAIL_HOST\", port: \"MAIL_PORT\", from: \"MAIL_FROM\" } },\n * );\n *\n * const mailConfig: ConfigOf<typeof configSchema> = {\n *   host: env(\"MAIL_HOST\"),\n *   port: Number(env(\"MAIL_PORT\", 587)),\n *   from: env(\"MAIL_FROM\"),\n * };\n *\n * export default mailConfig;\n */\n\nimport type { BaseValidator, Infer } from \"@warlock.js/seal\";\nimport { validate } from \"@warlock.js/seal\";\n\nconst CONFIG_SCHEMA_MARKER: unique symbol = Symbol.for(\"warlock.js.configSchema\");\n\nexport type ConfigSchemaOptions = {\n  /**\n   * The environment variable each key is read from, by key path\n   * (`{ host: \"MAIL_HOST\", \"smtp.password\": \"SMTP_PASSWORD\" }`). Named in the\n   * boot error so the fix is obvious.\n   */\n  env?: Readonly<Record<string, string>>;\n};\n\n/** A config file's schema, as returned by {@link defineConfigSchema}. */\nexport type ConfigSchema<TValidator extends BaseValidator = BaseValidator> = {\n  readonly [CONFIG_SCHEMA_MARKER]: true;\n  readonly validator: TValidator;\n  readonly env: Readonly<Record<string, string>>;\n};\n\n/** The config value a schema describes, for typing the default export. */\nexport type ConfigOf<TSchema extends ConfigSchema> =\n  TSchema extends ConfigSchema<infer TValidator> ? Infer.Input<TValidator> : never;\n\n/** One problem found while validating configuration. */\nexport type ConfigIssue = {\n  /** Config name (the file's key, e.g. `mail`). */\n  config: string;\n  /** Key path inside it (`smtp.host`); empty for the config value as a whole. */\n  key: string;\n  /** What is wrong, from the schema's rule. */\n  message: string;\n  /** The environment variable that feeds this key, when the schema names it. */\n  env?: string;\n};\n\n/**\n * Declare the schema a config file's default export must satisfy. Export the\n * result as `configSchema` from the same file.\n */\nexport function defineConfigSchema<TValidator extends BaseValidator>(\n  validator: TValidator,\n  options: ConfigSchemaOptions = {},\n): ConfigSchema<TValidator> {\n  return { [CONFIG_SCHEMA_MARKER]: true, validator, env: { ...options.env } };\n}\n\n/** Whether a value is a {@link ConfigSchema}. */\nexport function isConfigSchema(value: unknown): value is ConfigSchema {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    (value as Record<PropertyKey, unknown>)[CONFIG_SCHEMA_MARKER] === true\n  );\n}\n\n/**\n * Thrown at boot when one or more config files do not satisfy their\n * `configSchema`. `issues` lists every problem; the message is ready to print.\n */\nexport class InvalidConfigError extends Error {\n  public override readonly name = \"InvalidConfigError\";\n\n  public constructor(public readonly issues: readonly ConfigIssue[]) {\n    super(formatConfigIssues(issues));\n  }\n}\n\n/** Render issues as the boot error message. */\nexport function formatConfigIssues(issues: readonly ConfigIssue[]): string {\n  const lines = issues.map((issue) => {\n    const path = issue.key ? `${issue.config}.${issue.key}` : issue.config;\n    const hint = issue.env ? ` (set ${issue.env} in your environment or .env)` : \"\";\n    return `  - ${path}: ${issue.message}${hint}`;\n  });\n\n  const count = issues.length === 1 ? \"1 problem\" : `${issues.length} problems`;\n\n  return `Invalid configuration (${count}); the app cannot start until it is fixed:\\n${lines.join(\"\\n\")}`;\n}\n\n/**\n * Validate one config value against its schema. Returns the issues found (an\n * empty list when it is valid, or when `schema` is not a config schema).\n */\nexport async function validateConfigValue(\n  configName: string,\n  value: unknown,\n  schema: unknown,\n): Promise<ConfigIssue[]> {\n  if (!isConfigSchema(schema)) return [];\n\n  const result = await validate(schema.validator, value);\n  if (result.isValid) return [];\n\n  if (result.errors.length === 0) {\n    return [{ config: configName, key: \"\", message: \"does not match its config schema\" }];\n  }\n\n  return result.errors.map((error) => {\n    const key = error.input ?? \"\";\n    const env = schema.env[key];\n    return {\n      config: configName,\n      key,\n      message: error.error,\n      ...(env !== undefined && { env }),\n    };\n  });\n}\n\n/** A loaded config module: its default export and, optionally, its `configSchema`. */\nexport type ConfigModuleEntry = {\n  name: string;\n  module: { default?: unknown; configSchema?: unknown };\n};\n\n/**\n * Validate every config module that exports a `configSchema` and throw one\n * {@link InvalidConfigError} listing all problems. Used by the production\n * config loader `warlock build` generates.\n */\nexport async function assertValidConfigModules(\n  entries: readonly ConfigModuleEntry[],\n): Promise<void> {\n  const issues: ConfigIssue[] = [];\n\n  for (const entry of entries) {\n    issues.push(\n      ...(await validateConfigValue(entry.name, entry.module.default, entry.module.configSchema)),\n    );\n  }\n\n  if (issues.length > 0) throw new InvalidConfigError(issues);\n}\n"],"mappings":";;;AAmCA,MAAM,uBAAsC,OAAO,IAAI,yBAAyB;;;;;AAsChF,SAAgB,mBACd,WACA,UAA+B,CAAC,GACN;CAC1B,OAAO;GAAG,uBAAuB;EAAM;EAAW,KAAK,EAAE,GAAG,QAAQ,IAAI;CAAE;AAC5E;;AAGA,SAAgB,eAAe,OAAuC;CACpE,OACE,OAAO,UAAU,YACjB,UAAU,QACT,MAAuC,0BAA0B;AAEtE;;;;;AAMA,IAAa,qBAAb,cAAwC,MAAM;CAG5C,AAAO,YAAY,AAAgB,QAAgC;EACjE,MAAM,mBAAmB,MAAM,CAAC;EADC;cAFH;CAIhC;AACF;;AAGA,SAAgB,mBAAmB,QAAwC;CACzE,MAAM,QAAQ,OAAO,KAAK,UAAU;EAClC,MAAM,OAAO,MAAM,MAAM,GAAG,MAAM,OAAO,GAAG,MAAM,QAAQ,MAAM;EAChE,MAAM,OAAO,MAAM,MAAM,SAAS,MAAM,IAAI,iCAAiC;EAC7E,OAAO,OAAO,KAAK,IAAI,MAAM,UAAU;CACzC,CAAC;CAID,OAAO,0BAFO,OAAO,WAAW,IAAI,cAAc,GAAG,OAAO,OAAO,WAE5B,8CAA8C,MAAM,KAAK,IAAI;AACtG;;;;;AAMA,eAAsB,oBACpB,YACA,OACA,QACwB;CACxB,IAAI,CAAC,eAAe,MAAM,GAAG,OAAO,CAAC;CAErC,MAAM,SAAS,MAAM,SAAS,OAAO,WAAW,KAAK;CACrD,IAAI,OAAO,SAAS,OAAO,CAAC;CAE5B,IAAI,OAAO,OAAO,WAAW,GAC3B,OAAO,CAAC;EAAE,QAAQ;EAAY,KAAK;EAAI,SAAS;CAAmC,CAAC;CAGtF,OAAO,OAAO,OAAO,KAAK,UAAU;EAClC,MAAM,MAAM,MAAM,SAAS;EAC3B,MAAM,MAAM,OAAO,IAAI;EACvB,OAAO;GACL,QAAQ;GACR;GACA,SAAS,MAAM;GACf,GAAI,QAAQ,UAAa,EAAE,IAAI;EACjC;CACF,CAAC;AACH;;;;;;AAaA,eAAsB,yBACpB,SACe;CACf,MAAM,SAAwB,CAAC;CAE/B,KAAK,MAAM,SAAS,SAClB,OAAO,KACL,GAAI,MAAM,oBAAoB,MAAM,MAAM,MAAM,OAAO,SAAS,MAAM,OAAO,YAAY,CAC3F;CAGF,IAAI,OAAO,SAAS,GAAG,MAAM,IAAI,mBAAmB,MAAM;AAC5D"}

package/esm/config/index.d.mts

@@ -0,0 +1,6 @@
+import { ConfigKey, ConfigKeyRegistry, ConfigName, ConfigRegistry } from "./types.mjs";
+import { config } from "./config-getter.mjs";
+import { registerAppConfig } from "./config-handlers.mjs";
+import { ConfigIssue, ConfigModuleEntry, ConfigOf, ConfigSchema, ConfigSchemaOptions, InvalidConfigError, assertValidConfigModules, defineConfigSchema, formatConfigIssues, isConfigSchema, validateConfigValue } from "./config-schema.mjs";
+import { setConfig } from "./config-setter.mjs";
+import { ConfigSpecialHandlers, configSpecialHandlers } from "./config-special-handlers.mjs";

package/esm/config/index.mjs

@@ -1,6 +1,7 @@
 import { config } from "./config-getter.mjs";
 import { ConfigSpecialHandlers, configSpecialHandlers } from "./config-special-handlers.mjs";
 import { registerAppConfig } from "./config-handlers.mjs";
+import { InvalidConfigError, assertValidConfigModules, defineConfigSchema, formatConfigIssues, isConfigSchema, validateConfigValue } from "./config-schema.mjs";
 import { setConfig } from "./config-setter.mjs";
 
 export {  };

package/esm/connectors/assert-no-reserved-connector-names.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"assert-no-reserved-connector-names.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/connectors/assert-no-reserved-connector-names.ts"],"mappings":";;;iBA+BgB,8BAAA,CAA+B,UAAuB,EAAX,SAAS"}
+{"version":3,"file":"assert-no-reserved-connector-names.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/connectors/assert-no-reserved-connector-names.ts"],"mappings":";;;iBAgCgB,8BAAA,CAA+B,UAAuB,EAAX,SAAS"}

package/esm/connectors/assert-no-reserved-connector-names.mjs

@@ -1,3 +1,4 @@
+import { WarlockError } from "../errors/warlock-error.mjs";
 import { connectorsManager } from "./connectors-manager.mjs";
 
 //#region ../../packages/core/src/connectors/assert-no-reserved-connector-names.ts
@@ -36,7 +37,7 @@ function assertNoReservedConnectorNames(connectors) {
 	const names = unique.map((name) => JSON.stringify(name)).join(", ");
 	const subject = unique.length === 1 ? "name is" : "names are";
 	const object = unique.length === 1 ? "it" : "one of them";
-	throw new Error(`The following connector ${subject} reserved by a framework built-in connector: [${names}].\nEvery connector name must be unique, and the framework already registers a built-in connector under ${unique.length === 1 ? "that name" : "those names"}, so a custom connector carrying ${object} would be built for and then never booted. Rename the custom connector in \`warlock.config.ts > connectors\` to a name of your own.`);
+	throw new WarlockError("WL1009", `The following connector ${subject} reserved by a framework built-in connector: [${names}].\nEvery connector name must be unique, and the framework already registers a built-in connector under ${unique.length === 1 ? "that name" : "those names"}, so a custom connector carrying ${object} would be built for and then never booted. Rename the custom connector in \`warlock.config.ts > connectors\` to a name of your own.`);
 }
 
 //#endregion

package/esm/connectors/assert-no-reserved-connector-names.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"assert-no-reserved-connector-names.mjs","names":[],"sources":["../../../../../../../../packages/core/src/connectors/assert-no-reserved-connector-names.ts"],"sourcesContent":["/**\n * Refuses a `connectors` array that claims a name a framework built-in owns.\n *\n * The uniqueness check rejects a name repeated inside the array; this rejects\n * one already held by a BUILT-IN outside it. The manager registers its\n * built-ins in its own constructor, so those names are taken before any config\n * is read — and the two halves disagreed about what that meant. The build\n * drains per ENTRY and knows nothing of the manager, so it prepared the custom\n * connector's artifacts; the runtime registers per NAME and found the built-in\n * already there, so it skipped the entry. The result booted the built-in the\n * app did not ask for, never booted the connector it did, and reported success\n * from both halves.\n *\n * Refused rather than resolved in the app's favour: the built-ins are the\n * framework's own wiring — other framework code reaches for `http`, `cache`,\n * `database` by name — so letting a config replace one silently repoints\n * everything that looks it up. The name is the app's to change; the built-in's\n * is not.\n *\n * Scope, precisely: BUILT-IN names only. A name held by a PREVIOUSLY\n * CONFIGURED connector (an earlier call in the same process) is not this\n * check's business — that case is the registration skip's deliberate\n * idempotency, and stays out of both validators.\n *\n * Reads {@link ConnectorsManager.isBuiltInName}, which is the ONLY inventory of\n * built-in names, so this cannot fall out of step with what the manager\n * actually registered.\n */\nimport { connectorsManager } from \"./connectors-manager\";\nimport type { Connector } from \"./types\";\n\nexport function assertNoReservedConnectorNames(connectors: Connector[]): void {\n  const reserved = connectors\n    .map((connector) => connector.name)\n    .filter((name) => connectorsManager.isBuiltInName(name));\n\n  if (reserved.length === 0) return;\n\n  const unique = [...new Set(reserved)];\n  const names = unique.map((name) => JSON.stringify(name)).join(\", \");\n  const subject = unique.length === 1 ? \"name is\" : \"names are\";\n  const object = unique.length === 1 ? \"it\" : \"one of them\";\n\n  throw new Error(\n    `The following connector ${subject} reserved by a framework built-in connector: [${names}].\\n` +\n      \"Every connector name must be unique, and the framework already registers a built-in connector under \" +\n      `${unique.length === 1 ? \"that name\" : \"those names\"}, so a custom connector carrying ${object} ` +\n      \"would be built for and then never booted. \" +\n      \"Rename the custom connector in `warlock.config.ts > connectors` to a name of your own.\",\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,SAAgB,+BAA+B,YAA+B;CAC5E,MAAM,WAAW,WACd,KAAK,cAAc,UAAU,IAAI,CAAC,CAClC,QAAQ,SAAS,kBAAkB,cAAc,IAAI,CAAC;CAEzD,IAAI,SAAS,WAAW,GAAG;CAE3B,MAAM,SAAS,CAAC,GAAG,IAAI,IAAI,QAAQ,CAAC;CACpC,MAAM,QAAQ,OAAO,KAAK,SAAS,KAAK,UAAU,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI;CAClE,MAAM,UAAU,OAAO,WAAW,IAAI,YAAY;CAClD,MAAM,SAAS,OAAO,WAAW,IAAI,OAAO;CAE5C,MAAM,IAAI,MACR,2BAA2B,QAAQ,gDAAgD,MAAM,0GAEpF,OAAO,WAAW,IAAI,cAAc,cAAc,mCAAmC,OAAO,oIAGnG;AACF"}
+{"version":3,"file":"assert-no-reserved-connector-names.mjs","names":[],"sources":["../../../../../../../../packages/core/src/connectors/assert-no-reserved-connector-names.ts"],"sourcesContent":["/**\n * Refuses a `connectors` array that claims a name a framework built-in owns.\n *\n * The uniqueness check rejects a name repeated inside the array; this rejects\n * one already held by a BUILT-IN outside it. The manager registers its\n * built-ins in its own constructor, so those names are taken before any config\n * is read — and the two halves disagreed about what that meant. The build\n * drains per ENTRY and knows nothing of the manager, so it prepared the custom\n * connector's artifacts; the runtime registers per NAME and found the built-in\n * already there, so it skipped the entry. The result booted the built-in the\n * app did not ask for, never booted the connector it did, and reported success\n * from both halves.\n *\n * Refused rather than resolved in the app's favour: the built-ins are the\n * framework's own wiring — other framework code reaches for `http`, `cache`,\n * `database` by name — so letting a config replace one silently repoints\n * everything that looks it up. The name is the app's to change; the built-in's\n * is not.\n *\n * Scope, precisely: BUILT-IN names only. A name held by a PREVIOUSLY\n * CONFIGURED connector (an earlier call in the same process) is not this\n * check's business — that case is the registration skip's deliberate\n * idempotency, and stays out of both validators.\n *\n * Reads {@link ConnectorsManager.isBuiltInName}, which is the ONLY inventory of\n * built-in names, so this cannot fall out of step with what the manager\n * actually registered.\n */\nimport { WarlockError } from \"../errors/warlock-error\";\nimport { connectorsManager } from \"./connectors-manager\";\nimport type { Connector } from \"./types\";\n\nexport function assertNoReservedConnectorNames(connectors: Connector[]): void {\n  const reserved = connectors\n    .map((connector) => connector.name)\n    .filter((name) => connectorsManager.isBuiltInName(name));\n\n  if (reserved.length === 0) return;\n\n  const unique = [...new Set(reserved)];\n  const names = unique.map((name) => JSON.stringify(name)).join(\", \");\n  const subject = unique.length === 1 ? \"name is\" : \"names are\";\n  const object = unique.length === 1 ? \"it\" : \"one of them\";\n\n  throw new WarlockError(\n    \"WL1009\",\n    `The following connector ${subject} reserved by a framework built-in connector: [${names}].\\n` +\n      \"Every connector name must be unique, and the framework already registers a built-in connector under \" +\n      `${unique.length === 1 ? \"that name\" : \"those names\"}, so a custom connector carrying ${object} ` +\n      \"would be built for and then never booted. \" +\n      \"Rename the custom connector in `warlock.config.ts > connectors` to a name of your own.\",\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,SAAgB,+BAA+B,YAA+B;CAC5E,MAAM,WAAW,WACd,KAAK,cAAc,UAAU,IAAI,CAAC,CAClC,QAAQ,SAAS,kBAAkB,cAAc,IAAI,CAAC;CAEzD,IAAI,SAAS,WAAW,GAAG;CAE3B,MAAM,SAAS,CAAC,GAAG,IAAI,IAAI,QAAQ,CAAC;CACpC,MAAM,QAAQ,OAAO,KAAK,SAAS,KAAK,UAAU,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI;CAClE,MAAM,UAAU,OAAO,WAAW,IAAI,YAAY;CAClD,MAAM,SAAS,OAAO,WAAW,IAAI,OAAO;CAE5C,MAAM,IAAI,aACR,UACA,2BAA2B,QAAQ,gDAAgD,MAAM,0GAEpF,OAAO,WAAW,IAAI,cAAc,cAAc,mCAAmC,OAAO,oIAGnG;AACF"}

package/esm/connectors/assert-unique-connector-names.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"assert-unique-connector-names.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/connectors/assert-unique-connector-names.ts"],"mappings":";;;iBAyBgB,0BAAA,CAA2B,UAAuB,EAAX,SAAS"}
+{"version":3,"file":"assert-unique-connector-names.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/connectors/assert-unique-connector-names.ts"],"mappings":";;;iBA0BgB,0BAAA,CAA2B,UAAuB,EAAX,SAAS"}

package/esm/connectors/assert-unique-connector-names.mjs

@@ -1,4 +1,29 @@
+import { WarlockError } from "../errors/warlock-error.mjs";
+
 //#region ../../packages/core/src/connectors/assert-unique-connector-names.ts
+/**
+* Refuses a `connectors` array that lists the same name more than once.
+*
+* A name is a connector's identity across both halves of its life, and the two
+* halves treat a repeat differently. The build works per ARRAY ENTRY: it drains
+* the build contribution of every element, so a name listed twice contributes
+* twice — files written twice, esbuild patches merged twice. The runtime works
+* per NAME: the first entry registers and every later one with that name is
+* skipped, because registering it again would boot and shut down the same
+* connector twice.
+*
+* So a duplicate is half-applied: built for twice, booted once, with nothing
+* reported either way. The name-set the drift check compares is identical on
+* both sides, so it passes the array straight through — this asymmetry is
+* invisible to it, which is why it is caught here instead.
+*
+* Called by both halves (the build before it drains, the registration before it
+* registers) so neither can be reached with an array the other would refuse.
+* It rejects duplicates WITHIN the array it is handed. A name held OUTSIDE the
+* array is out of scope here: if a BUILT-IN holds it, the reserved-name check
+* refuses it; if an EARLIER CALL configured it, the registration skip treats it
+* as idempotency on purpose — neither validator claims that case.
+*/
 function assertUniqueConnectorNames(connectors) {
 	const seen = /* @__PURE__ */ new Set();
 	const duplicated = /* @__PURE__ */ new Set();
@@ -11,8 +36,7 @@ function assertUniqueConnectorNames(connectors) {
 	}
 	if (duplicated.size === 0) return;
 	const names = [...duplicated].map((name) => JSON.stringify(name)).join(", ");
-	const subject = duplicated.size === 1 ? "name is" : "names are";
-	throw new Error(`The same connector ${subject} listed more than once in \`connectors\`: [${names}].\nEvery connector in \`warlock.config.ts > connectors\` must have a unique name. The build prepares artifacts per ENTRY — it drains the build contribution of each one, so a repeated name contributes twice — while the runtime registers each NAME once and skips the rest. A duplicate is therefore half-applied, and neither half reports it. Remove the extra entry, or give the connectors distinct names.`);
+	throw new WarlockError("WL1009", `The same connector ${duplicated.size === 1 ? "name is" : "names are"} listed more than once in \`connectors\`: [${names}].\nEvery connector in \`warlock.config.ts > connectors\` must have a unique name. The build prepares artifacts per ENTRY — it drains the build contribution of each one, so a repeated name contributes twice — while the runtime registers each NAME once and skips the rest. A duplicate is therefore half-applied, and neither half reports it. Remove the extra entry, or give the connectors distinct names.`);
 }
 
 //#endregion