@warlock.js/core 5.30.0 → 5.32.0

package/esm/cli/commands/routes/format-routes-table.mjs

@@ -125,5 +125,5 @@ function printRoutesTable(rows) {
 }
 
 //#endregion
-export { printRoutesTable };
+export { printRoutesTable, routesSummary };
 //# sourceMappingURL=format-routes-table.mjs.map

package/esm/cli/commands/routes/route-row.mjs

@@ -88,5 +88,5 @@ function sortRouteRows(rows) {
 }
 
 //#endregion
-export { filterRouteRows, methodRank, sortRouteRows, toRouteRow };
+export { METHOD_ORDER, filterRouteRows, methodRank, sortRouteRows, toRouteRow };
 //# sourceMappingURL=route-row.mjs.map

package/esm/cli/commands/routes/routes-diff.action.mjs

@@ -1,9 +1,9 @@
 import { router } from "../../../router/router.mjs";
-import { resolveBuildConfig } from "../../../production/resolve-build-config.mjs";
 import { bootForDiagnostics } from "../doctor/boot-for-diagnostics.mjs";
+import { resolveBuildConfig } from "../../../production/resolve-build-config.mjs";
 import { comparePageRoutes, diffPageRoutes } from "./diff-page-routes.mjs";
 import path from "node:path";
-import fs from "node:fs";
+import fsSync from "node:fs";
 
 //#region ../../packages/core/src/cli/commands/routes/routes-diff.action.ts
 const SNAPSHOT_FILE = "page-routes.manifest.json";
@@ -26,7 +26,7 @@ function snapshotPath() {
 function readSnapshot(file) {
 	let raw;
 	try {
-		raw = fs.readFileSync(file, "utf-8");
+		raw = fsSync.readFileSync(file, "utf-8");
 	} catch {
 		throw new Error(`Cannot compare page routes: no build snapshot exists at "${file}". Run \`warlock build\` successfully, then run \`warlock routes:diff\` again.`);
 	}

package/esm/cli/commands/routes/routes-diff.action.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"routes-diff.action.mjs","names":[],"sources":["../../../../../../../../../../packages/core/src/cli/commands/routes/routes-diff.action.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { resolveBuildConfig } from \"../../../production/resolve-build-config\";\nimport { router } from \"../../../router/router\";\nimport type { Route } from \"../../../router/types\";\nimport { bootForDiagnostics } from \"../doctor/boot-for-diagnostics\";\nimport { comparePageRoutes, diffPageRoutes, type PageRoute } from \"./diff-page-routes\";\n\ntype PageRoutesSnapshot = {\n  version: 1;\n  routes: PageRoute[];\n};\n\nconst SNAPSHOT_FILE = \"page-routes.manifest.json\";\n\n/**\n * What a clean `warlock routes:diff` does and does NOT prove, printed on a\n * clean run so the guarantee is stated where it is relied on.\n */\nconst CLEAN_RUN_LIMIT =\n  \"Note: page names are compared as DERIVED by the build, so a clean diff does not prove \" +\n  \"that no route name collided at registration (the router appends `.<method>` to a name \" +\n  \"already claimed by another method). Run `warlock routes` to see the registered names.\";\n\nfunction routeFromLive(route: Route): PageRoute {\n  return {\n    method: route.method.toUpperCase() as \"GET\",\n    path: route.path,\n    name: route.name ?? \"\",\n    source: route.sourceFile ?? \"\",\n  };\n}\n\nfunction snapshotPath(): string {\n  return path.join(resolveBuildConfig().outdir, SNAPSHOT_FILE);\n}\n\nfunction readSnapshot(file: string): PageRoutesSnapshot {\n  let raw: string;\n\n  try {\n    raw = fs.readFileSync(file, \"utf-8\");\n  } catch {\n    throw new Error(\n      `Cannot compare page routes: no build snapshot exists at \"${file}\". Run \\`warlock build\\` successfully, then run \\`warlock routes:diff\\` again.`,\n    );\n  }\n\n  try {\n    const parsed: unknown = JSON.parse(raw);\n\n    if (\n      typeof parsed !== \"object\" ||\n      parsed === null ||\n      (parsed as { version?: unknown }).version !== 1 ||\n      !Array.isArray((parsed as { routes?: unknown }).routes) ||\n      !(parsed as { routes: unknown[] }).routes.every(\n        (route) =>\n          typeof route === \"object\" &&\n          route !== null &&\n          (route as PageRoute).method === \"GET\" &&\n          typeof (route as PageRoute).path === \"string\" &&\n          typeof (route as PageRoute).name === \"string\" &&\n          typeof (route as PageRoute).source === \"string\",\n      )\n    ) {\n      throw new Error(\"invalid shape\");\n    }\n\n    return parsed as PageRoutesSnapshot;\n  } catch {\n    throw new Error(\n      `Cannot compare page routes: build snapshot \"${file}\" is malformed. Run \\`warlock build\\` successfully to replace it, then retry.`,\n    );\n  }\n}\n\nfunction printRoute(prefix: string, route: PageRoute): void {\n  const source = route.source ? ` (${route.source})` : \"\";\n  console.log(`${prefix} GET ${route.path}  ${route.name}${source}`);\n}\n\n/**\n * Compare the last successful production page surface with the live dev\n * surface.\n *\n * The comparison itself lives in `diff-page-routes.ts`, which also documents\n * why the route-name method suffix is the one registration-time difference the\n * build-time manifest cannot record — and therefore what a clean run of this\n * command does not prove.\n */\nexport async function routesDiffCommandAction(): Promise<void> {\n  const snapshot = readSnapshot(snapshotPath());\n  const context = await bootForDiagnostics();\n\n  if (\n    !context.booted ||\n    context.moduleFailures.length > 0 ||\n    context.connectors.failures.length > 0 ||\n    context.connectors.registrationError !== undefined\n  ) {\n    const details = [\n      ...context.moduleFailures.map(({ file, message }) => `${file}: ${message}`),\n      ...context.connectors.failures.map(({ name, message }) => `${name}: ${message}`),\n      ...(context.connectors.registrationError ? [context.connectors.registrationError] : []),\n    ];\n    throw new Error(\n      `Cannot compare page routes because diagnostic boot failed.${details.length ? `\\n${details.join(\"\\n\")}` : \"\"}`,\n    );\n  }\n\n  const live = router\n    .list()\n    .filter((route) => route.isPage)\n    .map(routeFromLive)\n    .sort(comparePageRoutes);\n  const expected = [...snapshot.routes].sort(comparePageRoutes);\n  const { changes, removed, added } = diffPageRoutes(expected, live);\n\n  if (changes.length === 0 && removed.length === 0 && added.length === 0) {\n    console.log(`Page routes match (${expected.length} routes).`);\n    console.log(CLEAN_RUN_LIMIT);\n    return;\n  }\n\n  for (const { before, after } of changes) {\n    printRoute(\"changed -\", before);\n    printRoute(\"        +\", after);\n  }\n  for (const route of removed) printRoute(\"removed -\", route);\n  for (const route of added) printRoute(\"added   +\", route);\n\n  throw new Error(\n    `Page route drift: ${changes.length} changed, ${removed.length} removed, ${added.length} added. Run \\`warlock build\\` after reviewing these changes.`,\n  );\n}\n"],"mappings":";;;;;;;;AAaA,MAAM,gBAAgB;;;;;AAMtB,MAAM,kBACJ;AAIF,SAAS,cAAc,OAAyB;CAC9C,OAAO;EACL,QAAQ,MAAM,OAAO,YAAY;EACjC,MAAM,MAAM;EACZ,MAAM,MAAM,QAAQ;EACpB,QAAQ,MAAM,cAAc;CAC9B;AACF;AAEA,SAAS,eAAuB;CAC9B,OAAO,KAAK,KAAK,mBAAmB,CAAC,CAAC,QAAQ,aAAa;AAC7D;AAEA,SAAS,aAAa,MAAkC;CACtD,IAAI;CAEJ,IAAI;EACF,MAAM,GAAG,aAAa,MAAM,OAAO;CACrC,QAAQ;EACN,MAAM,IAAI,MACR,4DAA4D,KAAK,+EACnE;CACF;CAEA,IAAI;EACF,MAAM,SAAkB,KAAK,MAAM,GAAG;EAEtC,IACE,OAAO,WAAW,YAClB,WAAW,QACV,OAAiC,YAAY,KAC9C,CAAC,MAAM,QAAS,OAAgC,MAAM,KACtD,CAAE,OAAiC,OAAO,OACvC,UACC,OAAO,UAAU,YACjB,UAAU,QACT,MAAoB,WAAW,SAChC,OAAQ,MAAoB,SAAS,YACrC,OAAQ,MAAoB,SAAS,YACrC,OAAQ,MAAoB,WAAW,QAC3C,GAEA,MAAM,IAAI,MAAM,eAAe;EAGjC,OAAO;CACT,QAAQ;EACN,MAAM,IAAI,MACR,+CAA+C,KAAK,8EACtD;CACF;AACF;AAEA,SAAS,WAAW,QAAgB,OAAwB;CAC1D,MAAM,SAAS,MAAM,SAAS,KAAK,MAAM,OAAO,KAAK;CACrD,QAAQ,IAAI,GAAG,OAAO,OAAO,MAAM,KAAK,IAAI,MAAM,OAAO,QAAQ;AACnE;;;;;;;;;;AAWA,eAAsB,0BAAyC;CAC7D,MAAM,WAAW,aAAa,aAAa,CAAC;CAC5C,MAAM,UAAU,MAAM,mBAAmB;CAEzC,IACE,CAAC,QAAQ,UACT,QAAQ,eAAe,SAAS,KAChC,QAAQ,WAAW,SAAS,SAAS,KACrC,QAAQ,WAAW,sBAAsB,QACzC;EACA,MAAM,UAAU;GACd,GAAG,QAAQ,eAAe,KAAK,EAAE,MAAM,cAAc,GAAG,KAAK,IAAI,SAAS;GAC1E,GAAG,QAAQ,WAAW,SAAS,KAAK,EAAE,MAAM,cAAc,GAAG,KAAK,IAAI,SAAS;GAC/E,GAAI,QAAQ,WAAW,oBAAoB,CAAC,QAAQ,WAAW,iBAAiB,IAAI,CAAC;EACvF;EACA,MAAM,IAAI,MACR,6DAA6D,QAAQ,SAAS,KAAK,QAAQ,KAAK,IAAI,MAAM,IAC5G;CACF;CAEA,MAAM,OAAO,OACV,KAAK,CAAC,CACN,QAAQ,UAAU,MAAM,MAAM,CAAC,CAC/B,IAAI,aAAa,CAAC,CAClB,KAAK,iBAAiB;CACzB,MAAM,WAAW,CAAC,GAAG,SAAS,MAAM,CAAC,CAAC,KAAK,iBAAiB;CAC5D,MAAM,EAAE,SAAS,SAAS,UAAU,eAAe,UAAU,IAAI;CAEjE,IAAI,QAAQ,WAAW,KAAK,QAAQ,WAAW,KAAK,MAAM,WAAW,GAAG;EACtE,QAAQ,IAAI,sBAAsB,SAAS,OAAO,UAAU;EAC5D,QAAQ,IAAI,eAAe;EAC3B;CACF;CAEA,KAAK,MAAM,EAAE,QAAQ,WAAW,SAAS;EACvC,WAAW,aAAa,MAAM;EAC9B,WAAW,aAAa,KAAK;CAC/B;CACA,KAAK,MAAM,SAAS,SAAS,WAAW,aAAa,KAAK;CAC1D,KAAK,MAAM,SAAS,OAAO,WAAW,aAAa,KAAK;CAExD,MAAM,IAAI,MACR,qBAAqB,QAAQ,OAAO,YAAY,QAAQ,OAAO,YAAY,MAAM,OAAO,6DAC1F;AACF"}
+{"version":3,"file":"routes-diff.action.mjs","names":["fs"],"sources":["../../../../../../../../../../packages/core/src/cli/commands/routes/routes-diff.action.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { resolveBuildConfig } from \"../../../production/resolve-build-config\";\nimport { router } from \"../../../router/router\";\nimport type { Route } from \"../../../router/types\";\nimport { bootForDiagnostics } from \"../doctor/boot-for-diagnostics\";\nimport { comparePageRoutes, diffPageRoutes, type PageRoute } from \"./diff-page-routes\";\n\ntype PageRoutesSnapshot = {\n  version: 1;\n  routes: PageRoute[];\n};\n\nconst SNAPSHOT_FILE = \"page-routes.manifest.json\";\n\n/**\n * What a clean `warlock routes:diff` does and does NOT prove, printed on a\n * clean run so the guarantee is stated where it is relied on.\n */\nconst CLEAN_RUN_LIMIT =\n  \"Note: page names are compared as DERIVED by the build, so a clean diff does not prove \" +\n  \"that no route name collided at registration (the router appends `.<method>` to a name \" +\n  \"already claimed by another method). Run `warlock routes` to see the registered names.\";\n\nfunction routeFromLive(route: Route): PageRoute {\n  return {\n    method: route.method.toUpperCase() as \"GET\",\n    path: route.path,\n    name: route.name ?? \"\",\n    source: route.sourceFile ?? \"\",\n  };\n}\n\nfunction snapshotPath(): string {\n  return path.join(resolveBuildConfig().outdir, SNAPSHOT_FILE);\n}\n\nfunction readSnapshot(file: string): PageRoutesSnapshot {\n  let raw: string;\n\n  try {\n    raw = fs.readFileSync(file, \"utf-8\");\n  } catch {\n    throw new Error(\n      `Cannot compare page routes: no build snapshot exists at \"${file}\". Run \\`warlock build\\` successfully, then run \\`warlock routes:diff\\` again.`,\n    );\n  }\n\n  try {\n    const parsed: unknown = JSON.parse(raw);\n\n    if (\n      typeof parsed !== \"object\" ||\n      parsed === null ||\n      (parsed as { version?: unknown }).version !== 1 ||\n      !Array.isArray((parsed as { routes?: unknown }).routes) ||\n      !(parsed as { routes: unknown[] }).routes.every(\n        (route) =>\n          typeof route === \"object\" &&\n          route !== null &&\n          (route as PageRoute).method === \"GET\" &&\n          typeof (route as PageRoute).path === \"string\" &&\n          typeof (route as PageRoute).name === \"string\" &&\n          typeof (route as PageRoute).source === \"string\",\n      )\n    ) {\n      throw new Error(\"invalid shape\");\n    }\n\n    return parsed as PageRoutesSnapshot;\n  } catch {\n    throw new Error(\n      `Cannot compare page routes: build snapshot \"${file}\" is malformed. Run \\`warlock build\\` successfully to replace it, then retry.`,\n    );\n  }\n}\n\nfunction printRoute(prefix: string, route: PageRoute): void {\n  const source = route.source ? ` (${route.source})` : \"\";\n  console.log(`${prefix} GET ${route.path}  ${route.name}${source}`);\n}\n\n/**\n * Compare the last successful production page surface with the live dev\n * surface.\n *\n * The comparison itself lives in `diff-page-routes.ts`, which also documents\n * why the route-name method suffix is the one registration-time difference the\n * build-time manifest cannot record — and therefore what a clean run of this\n * command does not prove.\n */\nexport async function routesDiffCommandAction(): Promise<void> {\n  const snapshot = readSnapshot(snapshotPath());\n  const context = await bootForDiagnostics();\n\n  if (\n    !context.booted ||\n    context.moduleFailures.length > 0 ||\n    context.connectors.failures.length > 0 ||\n    context.connectors.registrationError !== undefined\n  ) {\n    const details = [\n      ...context.moduleFailures.map(({ file, message }) => `${file}: ${message}`),\n      ...context.connectors.failures.map(({ name, message }) => `${name}: ${message}`),\n      ...(context.connectors.registrationError ? [context.connectors.registrationError] : []),\n    ];\n    throw new Error(\n      `Cannot compare page routes because diagnostic boot failed.${details.length ? `\\n${details.join(\"\\n\")}` : \"\"}`,\n    );\n  }\n\n  const live = router\n    .list()\n    .filter((route) => route.isPage)\n    .map(routeFromLive)\n    .sort(comparePageRoutes);\n  const expected = [...snapshot.routes].sort(comparePageRoutes);\n  const { changes, removed, added } = diffPageRoutes(expected, live);\n\n  if (changes.length === 0 && removed.length === 0 && added.length === 0) {\n    console.log(`Page routes match (${expected.length} routes).`);\n    console.log(CLEAN_RUN_LIMIT);\n    return;\n  }\n\n  for (const { before, after } of changes) {\n    printRoute(\"changed -\", before);\n    printRoute(\"        +\", after);\n  }\n  for (const route of removed) printRoute(\"removed -\", route);\n  for (const route of added) printRoute(\"added   +\", route);\n\n  throw new Error(\n    `Page route drift: ${changes.length} changed, ${removed.length} removed, ${added.length} added. Run \\`warlock build\\` after reviewing these changes.`,\n  );\n}\n"],"mappings":";;;;;;;;AAaA,MAAM,gBAAgB;;;;;AAMtB,MAAM,kBACJ;AAIF,SAAS,cAAc,OAAyB;CAC9C,OAAO;EACL,QAAQ,MAAM,OAAO,YAAY;EACjC,MAAM,MAAM;EACZ,MAAM,MAAM,QAAQ;EACpB,QAAQ,MAAM,cAAc;CAC9B;AACF;AAEA,SAAS,eAAuB;CAC9B,OAAO,KAAK,KAAK,mBAAmB,CAAC,CAAC,QAAQ,aAAa;AAC7D;AAEA,SAAS,aAAa,MAAkC;CACtD,IAAI;CAEJ,IAAI;EACF,MAAMA,OAAG,aAAa,MAAM,OAAO;CACrC,QAAQ;EACN,MAAM,IAAI,MACR,4DAA4D,KAAK,+EACnE;CACF;CAEA,IAAI;EACF,MAAM,SAAkB,KAAK,MAAM,GAAG;EAEtC,IACE,OAAO,WAAW,YAClB,WAAW,QACV,OAAiC,YAAY,KAC9C,CAAC,MAAM,QAAS,OAAgC,MAAM,KACtD,CAAE,OAAiC,OAAO,OACvC,UACC,OAAO,UAAU,YACjB,UAAU,QACT,MAAoB,WAAW,SAChC,OAAQ,MAAoB,SAAS,YACrC,OAAQ,MAAoB,SAAS,YACrC,OAAQ,MAAoB,WAAW,QAC3C,GAEA,MAAM,IAAI,MAAM,eAAe;EAGjC,OAAO;CACT,QAAQ;EACN,MAAM,IAAI,MACR,+CAA+C,KAAK,8EACtD;CACF;AACF;AAEA,SAAS,WAAW,QAAgB,OAAwB;CAC1D,MAAM,SAAS,MAAM,SAAS,KAAK,MAAM,OAAO,KAAK;CACrD,QAAQ,IAAI,GAAG,OAAO,OAAO,MAAM,KAAK,IAAI,MAAM,OAAO,QAAQ;AACnE;;;;;;;;;;AAWA,eAAsB,0BAAyC;CAC7D,MAAM,WAAW,aAAa,aAAa,CAAC;CAC5C,MAAM,UAAU,MAAM,mBAAmB;CAEzC,IACE,CAAC,QAAQ,UACT,QAAQ,eAAe,SAAS,KAChC,QAAQ,WAAW,SAAS,SAAS,KACrC,QAAQ,WAAW,sBAAsB,QACzC;EACA,MAAM,UAAU;GACd,GAAG,QAAQ,eAAe,KAAK,EAAE,MAAM,cAAc,GAAG,KAAK,IAAI,SAAS;GAC1E,GAAG,QAAQ,WAAW,SAAS,KAAK,EAAE,MAAM,cAAc,GAAG,KAAK,IAAI,SAAS;GAC/E,GAAI,QAAQ,WAAW,oBAAoB,CAAC,QAAQ,WAAW,iBAAiB,IAAI,CAAC;EACvF;EACA,MAAM,IAAI,MACR,6DAA6D,QAAQ,SAAS,KAAK,QAAQ,KAAK,IAAI,MAAM,IAC5G;CACF;CAEA,MAAM,OAAO,OACV,KAAK,CAAC,CACN,QAAQ,UAAU,MAAM,MAAM,CAAC,CAC/B,IAAI,aAAa,CAAC,CAClB,KAAK,iBAAiB;CACzB,MAAM,WAAW,CAAC,GAAG,SAAS,MAAM,CAAC,CAAC,KAAK,iBAAiB;CAC5D,MAAM,EAAE,SAAS,SAAS,UAAU,eAAe,UAAU,IAAI;CAEjE,IAAI,QAAQ,WAAW,KAAK,QAAQ,WAAW,KAAK,MAAM,WAAW,GAAG;EACtE,QAAQ,IAAI,sBAAsB,SAAS,OAAO,UAAU;EAC5D,QAAQ,IAAI,eAAe;EAC3B;CACF;CAEA,KAAK,MAAM,EAAE,QAAQ,WAAW,SAAS;EACvC,WAAW,aAAa,MAAM;EAC9B,WAAW,aAAa,KAAK;CAC/B;CACA,KAAK,MAAM,SAAS,SAAS,WAAW,aAAa,KAAK;CAC1D,KAAK,MAAM,SAAS,OAAO,WAAW,aAAa,KAAK;CAExD,MAAM,IAAI,MACR,qBAAqB,QAAQ,OAAO,YAAY,QAAQ,OAAO,YAAY,MAAM,OAAO,6DAC1F;AACF"}

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

@@ -0,0 +1,131 @@
+import { command } from "../../commands/cli-command.mjs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+
+//#region ../../packages/core/src/cli/commands/test.command.ts
+/**
+* Translate `warlock test` options into Vitest arguments. Pure, so the mapping
+* is pinned by a test rather than discovered in CI.
+*
+* Flags used (verified against `vitest --help`, Vitest 4.1):
+* `run`, `related [...filters]`, `--changed [since]`, `--passWithNoTests`,
+* `--reporter <name>`, `--testNamePattern <pattern>`.
+*/
+function buildVitestArguments(options) {
+	const related = options.related ?? [];
+	const args = [];
+	if (related.length > 0) {
+		args.push("related", ...related, ...options.filters);
+		if (!options.watch) args.push("--run");
+	} else {
+		if (!options.watch) args.push("run");
+		args.push(...options.filters);
+	}
+	if (options.changed || options.since) {
+		args.push("--changed");
+		if (options.since) args.push(options.since);
+	}
+	if (related.length > 0 || options.changed || options.since) args.push("--passWithNoTests");
+	if (options.testNamePattern) args.push("--testNamePattern", options.testNamePattern);
+	if (options.json) args.push("--reporter=json");
+	return args;
+}
+/** Read `warlock test`'s parsed CLI input into {@link TestCommandOptions}. */
+function readTestCommandOptions(data) {
+	const text = (value) => typeof value === "string" && value.trim() !== "" ? value.trim() : void 0;
+	const relatedOption = text(data.options.related);
+	return {
+		filters: data.args,
+		changed: data.options.changed === true,
+		since: text(data.options.since),
+		related: relatedOption ? relatedOption.split(",").map((file) => file.trim()).filter(Boolean) : void 0,
+		watch: data.options.watch === true,
+		json: data.options.json === true,
+		testNamePattern: text(data.options.testNamePattern) ?? text(data.options.t)
+	};
+}
+/**
+* The project's own Vitest entry (`vitest.mjs`), resolved from the project
+* root — never a global or an `npx` download.
+*/
+function resolveProjectVitest(projectRoot, resolve = createRequire(path.join(projectRoot, "package.json")).resolve) {
+	let manifestPath;
+	try {
+		manifestPath = resolve("vitest/package.json");
+	} catch {
+		throw new Error(`Vitest is not installed in ${projectRoot}. Run \`warlock add test\` (or install vitest as a dev dependency) first.`);
+	}
+	const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+	const bin = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.vitest;
+	const entry = path.join(path.dirname(manifestPath), bin ?? "vitest.mjs");
+	if (!existsSync(entry)) throw new Error(`Vitest's entry point was not found at ${entry}. Reinstall vitest.`);
+	return entry;
+}
+async function testCommandAction(data) {
+	const options = readTestCommandOptions(data);
+	const vitest = resolveProjectVitest(process.cwd());
+	const args = buildVitestArguments(options);
+	const exitCode = await new Promise((resolve, reject) => {
+		const child = spawn(process.execPath, [vitest, ...args], {
+			cwd: process.cwd(),
+			env: {
+				...process.env,
+				NODE_ENV: "test"
+			},
+			stdio: "inherit"
+		});
+		child.once("error", reject);
+		child.once("exit", (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+	});
+	if (exitCode !== 0) process.exit(exitCode);
+}
+/**
+* `warlock test` — run the project's tests through its own Vitest.
+*
+* @example
+* warlock test                                  # everything, once
+* warlock test --changed                        # tests affected by uncommitted changes
+* warlock test --changed --since main           # ... by changes since main
+* warlock test --related src/app/posts/services/create-post.service.ts
+* warlock test src/app/posts --json             # one folder, JSON report on stdout
+*/
+const testCommand = command({
+	name: "test [filters...]",
+	description: "Run the project's tests with Vitest; --changed / --related run only the tests your change affects",
+	action: testCommandAction,
+	options: [
+		{
+			text: "--changed",
+			description: "Only run tests affected by uncommitted changes (git)",
+			type: "boolean"
+		},
+		{
+			text: "--since <ref>",
+			description: "With --changed: tests affected by changes since this git ref (e.g. main)"
+		},
+		{
+			text: "--related <files>",
+			description: "Comma-separated source files: only run the tests that import them"
+		},
+		{
+			text: "--watch, -w",
+			description: "Re-run on change instead of running once",
+			type: "boolean"
+		},
+		{
+			text: "--test-name-pattern, -t",
+			description: "Only run tests whose name matches this pattern"
+		},
+		{
+			text: "--json",
+			description: "Print Vitest's JSON report on stdout",
+			type: "boolean"
+		}
+	]
+});
+
+//#endregion
+export { buildVitestArguments, readTestCommandOptions, resolveProjectVitest, testCommand };
+//# sourceMappingURL=test.command.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"test.command.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/cli/commands/test.command.ts"],"sourcesContent":["import { spawn } from \"node:child_process\";\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { createRequire } from \"node:module\";\nimport path from \"node:path\";\nimport { command } from \"../../commands/cli-command\";\nimport type { CommandActionData } from \"../../commands/types\";\n\n/** What `warlock test` was asked for. */\nexport type TestCommandOptions = {\n  /** Positional filters: file paths or name fragments, passed to Vitest. */\n  filters: string[];\n  /** Only the tests affected by uncommitted changes (or by changes since `since`). */\n  changed?: boolean;\n  /** A git ref for `changed`: tests affected by changes since this commit or branch. */\n  since?: string;\n  /** Only the tests that import these source files, directly or not. */\n  related?: string[];\n  /** Keep running and re-run on change instead of running once. */\n  watch?: boolean;\n  /** Print Vitest's JSON report on stdout. */\n  json?: boolean;\n  /** Only tests whose name matches this pattern. */\n  testNamePattern?: string;\n};\n\n/**\n * Translate `warlock test` options into Vitest arguments. Pure, so the mapping\n * is pinned by a test rather than discovered in CI.\n *\n * Flags used (verified against `vitest --help`, Vitest 4.1):\n * `run`, `related [...filters]`, `--changed [since]`, `--passWithNoTests`,\n * `--reporter <name>`, `--testNamePattern <pattern>`.\n */\nexport function buildVitestArguments(options: TestCommandOptions): string[] {\n  const related = options.related ?? [];\n  const args: string[] = [];\n\n  if (related.length > 0) {\n    // `vitest related` watches by default; `--run` makes it run once.\n    args.push(\"related\", ...related, ...options.filters);\n\n    if (!options.watch) args.push(\"--run\");\n  } else {\n    if (!options.watch) args.push(\"run\");\n\n    args.push(...options.filters);\n  }\n\n  if (options.changed || options.since) {\n    args.push(\"--changed\");\n\n    if (options.since) args.push(options.since);\n  }\n\n  // \"Run what my change affects\" finding nothing to run is a pass, not an error.\n  if (related.length > 0 || options.changed || options.since) args.push(\"--passWithNoTests\");\n\n  if (options.testNamePattern) args.push(\"--testNamePattern\", options.testNamePattern);\n\n  if (options.json) args.push(\"--reporter=json\");\n\n  return args;\n}\n\n/** Read `warlock test`'s parsed CLI input into {@link TestCommandOptions}. */\nexport function readTestCommandOptions(data: CommandActionData): TestCommandOptions {\n  const text = (value: unknown): string | undefined =>\n    typeof value === \"string\" && value.trim() !== \"\" ? value.trim() : undefined;\n  const relatedOption = text(data.options.related);\n\n  return {\n    filters: data.args,\n    changed: data.options.changed === true,\n    since: text(data.options.since),\n    related: relatedOption\n      ? relatedOption\n          .split(\",\")\n          .map((file) => file.trim())\n          .filter(Boolean)\n      : undefined,\n    watch: data.options.watch === true,\n    json: data.options.json === true,\n    testNamePattern: text(data.options.testNamePattern) ?? text(data.options.t),\n  };\n}\n\n/**\n * The project's own Vitest entry (`vitest.mjs`), resolved from the project\n * root — never a global or an `npx` download.\n */\nexport function resolveProjectVitest(\n  projectRoot: string,\n  resolve: (specifier: string) => string = createRequire(path.join(projectRoot, \"package.json\"))\n    .resolve,\n): string {\n  let manifestPath: string;\n\n  try {\n    manifestPath = resolve(\"vitest/package.json\");\n  } catch {\n    throw new Error(\n      `Vitest is not installed in ${projectRoot}. Run \\`warlock add test\\` (or install vitest as a dev dependency) first.`,\n    );\n  }\n\n  const manifest = JSON.parse(readFileSync(manifestPath, \"utf8\")) as {\n    bin?: string | Record<string, string>;\n  };\n  const bin = typeof manifest.bin === \"string\" ? manifest.bin : manifest.bin?.vitest;\n  const entry = path.join(path.dirname(manifestPath), bin ?? \"vitest.mjs\");\n\n  if (!existsSync(entry)) {\n    throw new Error(`Vitest's entry point was not found at ${entry}. Reinstall vitest.`);\n  }\n\n  return entry;\n}\n\nasync function testCommandAction(data: CommandActionData): Promise<void> {\n  const options = readTestCommandOptions(data);\n  const vitest = resolveProjectVitest(process.cwd());\n  const args = buildVitestArguments(options);\n\n  const exitCode = await new Promise<number>((resolve, reject) => {\n    const child = spawn(process.execPath, [vitest, ...args], {\n      cwd: process.cwd(),\n      // Vitest only defaults NODE_ENV to \"test\" when it is unset; an exported\n      // NODE_ENV=production would otherwise reach the test server and be refused.\n      env: { ...process.env, NODE_ENV: \"test\" },\n      stdio: \"inherit\",\n    });\n\n    child.once(\"error\", reject);\n    child.once(\"exit\", (code, signal) => resolve(code ?? (signal ? 1 : 0)));\n  });\n\n  if (exitCode !== 0) process.exit(exitCode);\n}\n\n/**\n * `warlock test` — run the project's tests through its own Vitest.\n *\n * @example\n * warlock test                                  # everything, once\n * warlock test --changed                        # tests affected by uncommitted changes\n * warlock test --changed --since main           # ... by changes since main\n * warlock test --related src/app/posts/services/create-post.service.ts\n * warlock test src/app/posts --json             # one folder, JSON report on stdout\n */\nexport const testCommand = command({\n  name: \"test [filters...]\",\n  description:\n    \"Run the project's tests with Vitest; --changed / --related run only the tests your change affects\",\n  action: testCommandAction,\n  options: [\n    {\n      text: \"--changed\",\n      description: \"Only run tests affected by uncommitted changes (git)\",\n      type: \"boolean\",\n    },\n    {\n      text: \"--since <ref>\",\n      description: \"With --changed: tests affected by changes since this git ref (e.g. main)\",\n    },\n    {\n      text: \"--related <files>\",\n      description: \"Comma-separated source files: only run the tests that import them\",\n    },\n    {\n      text: \"--watch, -w\",\n      description: \"Re-run on change instead of running once\",\n      type: \"boolean\",\n    },\n    {\n      text: \"--test-name-pattern, -t\",\n      description: \"Only run tests whose name matches this pattern\",\n    },\n    {\n      text: \"--json\",\n      description: \"Print Vitest's JSON report on stdout\",\n      type: \"boolean\",\n    },\n  ],\n});\n"],"mappings":"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"}

package/esm/cli/commands/trace/trace-command.action.mjs

@@ -0,0 +1,145 @@
+import { ERROR_CODES, errorCodeOf } from "../../../errors/error-codes.mjs";
+import { flushAndExit } from "../../flush-and-exit.mjs";
+import { traceRequest } from "../../../tooling/trace/trace-request.mjs";
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import { colors } from "@mongez/copper";
+
+//#region ../../packages/core/src/cli/commands/trace/trace-command.action.ts
+function stringOption(value) {
+	return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+/**
+* Every `--header` / `-H` value in `argv`, in order. The CLI parser keeps only
+* the last value of a repeated option, so headers are read from argv directly.
+* Accepts `--header k:v`, `--header=k:v`, `-H k:v` and `-H=k:v`.
+*/
+function collectHeaderValues(argv) {
+	const values = [];
+	for (let index = 0; index < argv.length; index++) {
+		const token = argv[index];
+		if (token === void 0) continue;
+		const inline = /^(?:--header|-H)=(.*)$/s.exec(token);
+		if (inline) {
+			values.push(inline[1] ?? "");
+			continue;
+		}
+		if (token === "--header" || token === "-H") {
+			const next = argv[index + 1];
+			if (next !== void 0) {
+				values.push(next);
+				index++;
+			}
+		}
+	}
+	return values;
+}
+/**
+* Turn `name:value` strings into a header object. The first colon splits; both
+* sides are trimmed. Throws on a value without a colon or with an empty name.
+*/
+function parseHeaderValues(values) {
+	const headers = {};
+	for (const value of values) {
+		const colon = value.indexOf(":");
+		const name = colon === -1 ? "" : value.slice(0, colon).trim();
+		if (name.length === 0) throw new Error(`Invalid --header ${JSON.stringify(value)}: expected name:value.`);
+		headers[name] = value.slice(colon + 1).trim();
+	}
+	return headers;
+}
+/**
+* The request body for `--body`: `@path` reads the file (relative to `cwd`);
+* text that parses as JSON becomes that value (sent as JSON); anything else is
+* sent as the text itself. `undefined` without `--body`.
+*/
+function parseTraceBody(value, cwd = process.cwd(), readFile = (file) => readFileSync(file, "utf8")) {
+	if (value === void 0) return void 0;
+	const text = value.startsWith("@") ? readFile(path.resolve(cwd, value.slice(1))) : value;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+function ms(value) {
+	return value === null ? "-" : `${value.toFixed(1)}ms`;
+}
+/** The human summary `warlock trace` prints without `--json`. Uncolored, so it is testable. */
+function formatTraceSummary(report) {
+	const { timeline } = report;
+	const lines = [`${report.request.method} ${report.request.url} → ${report.response.status}  (${report.route ?? "no route"}, id ${report.requestId})`, `  total ${ms(report.timings.totalMs)} server, ${ms(report.timings.clientMs)} round trip`];
+	if (timeline.routeMatch) lines.push(`  route.match  ${ms(timeline.routeMatch.durationMs)}`);
+	for (const middleware of timeline.middleware) lines.push(`  middleware   ${middleware.name ?? "(anonymous)"}  ${ms(middleware.durationMs)}`);
+	if (timeline.validation.ran) {
+		const verdict = timeline.validation.passed ? "passed" : "failed";
+		lines.push(`  validation   ${verdict}  ${ms(timeline.validation.durationMs)}`);
+	}
+	if (timeline.handler) lines.push(`  handler      ${ms(timeline.handler.durationMs)}`);
+	const nPlusOne = report.queries.filter((query) => query.nPlusOne).length;
+	lines.push(`  queries ${report.queries.length}${nPlusOne > 0 ? ` (${nPlusOne} N+1)` : ""} · logs ${report.logs.length} · cache ${report.cache.length} · mails ${report.mails.length}`);
+	for (const warning of report.warnings) if (typeof warning.message === "string") lines.push(`  ! ${warning.message}`);
+	if (report.error) lines.push(`  error: ${report.error}`);
+	lines.push("", "Run with --json for the full timeline.");
+	return lines;
+}
+/** The exit code for a failed trace: 2 for this machine (WL8xxx), 1 otherwise. */
+function traceFailureExitCode(error) {
+	const code = errorCodeOf(error);
+	return code !== void 0 && ERROR_CODES[code].category === "environment" ? 2 : 1;
+}
+/**
+* Action behind `warlock trace <method> <url>`.
+*
+* Sends the request to the running dev server and prints its devtools
+* timeline; with `--json`, stdout carries exactly the report. A failure
+* (no dev server, no devtools, no record) prints the coded error — as
+* `{ ok: false, code, message }` with `--json` — and exits 2 for this machine
+* or 1 otherwise.
+*
+* @param data Parsed CLI args: `[method, url]`, `body`, `url`, `devtoolsPath`, `idHeader`, `timeout`, `json`.
+*/
+async function traceCommandAction({ args, options }) {
+	const json = options.json === true;
+	const [method, url] = args;
+	try {
+		if (!method || !url) throw new Error("Usage: warlock trace <method> <url> [--body json|@file] [--header k:v]");
+		const timeout = stringOption(options.timeout);
+		const timeoutMs = timeout === void 0 ? void 0 : Number(timeout);
+		if (timeoutMs !== void 0 && (!Number.isFinite(timeoutMs) || timeoutMs < 0)) throw new Error(`Invalid --timeout ${JSON.stringify(timeout)}: expected milliseconds.`);
+		const report = await traceRequest({
+			method,
+			url,
+			body: parseTraceBody(stringOption(options.body)),
+			headers: parseHeaderValues(collectHeaderValues(process.argv)),
+			serverUrl: stringOption(options.url),
+			devtoolsPath: stringOption(options.devtoolsPath),
+			requestIdHeader: stringOption(options.idHeader),
+			timeoutMs
+		});
+		if (json) {
+			console.log(JSON.stringify(report, null, 2));
+			return;
+		}
+		const [heading, ...rest] = formatTraceSummary(report);
+		console.log(colors.bold(heading ?? ""));
+		for (const line of rest) console.log(line);
+	} catch (error) {
+		const code = errorCodeOf(error) ?? null;
+		const message = error instanceof Error ? error.message : String(error);
+		if (json) console.log(JSON.stringify({
+			ok: false,
+			code,
+			message
+		}, null, 2));
+		else {
+			console.error(colors.red(`${code ? `${code} ` : ""}${message}`));
+			if (code) console.error(`  → ${ERROR_CODES[code].fix}`);
+		}
+		await flushAndExit(traceFailureExitCode(error));
+	}
+}
+
+//#endregion
+export { collectHeaderValues, formatTraceSummary, parseHeaderValues, parseTraceBody, traceCommandAction, traceFailureExitCode };
+//# sourceMappingURL=trace-command.action.mjs.map

package/esm/cli/commands/trace/trace-command.action.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-command.action.mjs","names":[],"sources":["../../../../../../../../../../packages/core/src/cli/commands/trace/trace-command.action.ts"],"sourcesContent":["import { readFileSync } from \"node:fs\";\nimport path from \"node:path\";\nimport { colors } from \"@mongez/copper\";\nimport type { CommandActionData } from \"../../../commands/types\";\nimport { ERROR_CODES, errorCodeOf } from \"../../../errors/error-codes\";\nimport type { TraceReport } from \"../../../tooling/trace/trace-report.types\";\nimport { traceRequest } from \"../../../tooling/trace/trace-request\";\nimport { flushAndExit } from \"../../flush-and-exit\";\n\nfunction stringOption(value: string | number | boolean | undefined): string | undefined {\n  return typeof value === \"string\" && value.trim().length > 0 ? value.trim() : undefined;\n}\n\n/**\n * Every `--header` / `-H` value in `argv`, in order. The CLI parser keeps only\n * the last value of a repeated option, so headers are read from argv directly.\n * Accepts `--header k:v`, `--header=k:v`, `-H k:v` and `-H=k:v`.\n */\nexport function collectHeaderValues(argv: readonly string[]): string[] {\n  const values: string[] = [];\n\n  for (let index = 0; index < argv.length; index++) {\n    const token = argv[index];\n\n    if (token === undefined) continue;\n\n    const inline = /^(?:--header|-H)=(.*)$/s.exec(token);\n\n    if (inline) {\n      values.push(inline[1] ?? \"\");\n      continue;\n    }\n\n    if (token === \"--header\" || token === \"-H\") {\n      const next = argv[index + 1];\n\n      if (next !== undefined) {\n        values.push(next);\n        index++;\n      }\n    }\n  }\n\n  return values;\n}\n\n/**\n * Turn `name:value` strings into a header object. The first colon splits; both\n * sides are trimmed. Throws on a value without a colon or with an empty name.\n */\nexport function parseHeaderValues(values: readonly string[]): Record<string, string> {\n  const headers: Record<string, string> = {};\n\n  for (const value of values) {\n    const colon = value.indexOf(\":\");\n    const name = colon === -1 ? \"\" : value.slice(0, colon).trim();\n\n    if (name.length === 0) {\n      throw new Error(`Invalid --header ${JSON.stringify(value)}: expected name:value.`);\n    }\n\n    headers[name] = value.slice(colon + 1).trim();\n  }\n\n  return headers;\n}\n\n/**\n * The request body for `--body`: `@path` reads the file (relative to `cwd`);\n * text that parses as JSON becomes that value (sent as JSON); anything else is\n * sent as the text itself. `undefined` without `--body`.\n */\nexport function parseTraceBody(\n  value: string | undefined,\n  cwd = process.cwd(),\n  readFile: (file: string) => string = (file) => readFileSync(file, \"utf8\"),\n): unknown {\n  if (value === undefined) return undefined;\n\n  const text = value.startsWith(\"@\") ? readFile(path.resolve(cwd, value.slice(1))) : value;\n\n  try {\n    return JSON.parse(text);\n  } catch {\n    return text;\n  }\n}\n\nfunction ms(value: number | null): string {\n  return value === null ? \"-\" : `${value.toFixed(1)}ms`;\n}\n\n/** The human summary `warlock trace` prints without `--json`. Uncolored, so it is testable. */\nexport function formatTraceSummary(report: TraceReport): string[] {\n  const { timeline } = report;\n  const lines = [\n    `${report.request.method} ${report.request.url} → ${report.response.status}  (${report.route ?? \"no route\"}, id ${report.requestId})`,\n    `  total ${ms(report.timings.totalMs)} server, ${ms(report.timings.clientMs)} round trip`,\n  ];\n\n  if (timeline.routeMatch) lines.push(`  route.match  ${ms(timeline.routeMatch.durationMs)}`);\n\n  for (const middleware of timeline.middleware) {\n    lines.push(`  middleware   ${middleware.name ?? \"(anonymous)\"}  ${ms(middleware.durationMs)}`);\n  }\n\n  if (timeline.validation.ran) {\n    const verdict = timeline.validation.passed ? \"passed\" : \"failed\";\n\n    lines.push(`  validation   ${verdict}  ${ms(timeline.validation.durationMs)}`);\n  }\n\n  if (timeline.handler) lines.push(`  handler      ${ms(timeline.handler.durationMs)}`);\n\n  const nPlusOne = report.queries.filter((query) => query.nPlusOne).length;\n\n  lines.push(\n    `  queries ${report.queries.length}${nPlusOne > 0 ? ` (${nPlusOne} N+1)` : \"\"} · logs ${report.logs.length} · cache ${report.cache.length} · mails ${report.mails.length}`,\n  );\n\n  for (const warning of report.warnings) {\n    if (typeof warning.message === \"string\") lines.push(`  ! ${warning.message}`);\n  }\n\n  if (report.error) lines.push(`  error: ${report.error}`);\n\n  lines.push(\"\", \"Run with --json for the full timeline.\");\n\n  return lines;\n}\n\n/** The exit code for a failed trace: 2 for this machine (WL8xxx), 1 otherwise. */\nexport function traceFailureExitCode(error: unknown): 1 | 2 {\n  const code = errorCodeOf(error);\n\n  return code !== undefined && ERROR_CODES[code].category === \"environment\" ? 2 : 1;\n}\n\n/**\n * Action behind `warlock trace <method> <url>`.\n *\n * Sends the request to the running dev server and prints its devtools\n * timeline; with `--json`, stdout carries exactly the report. A failure\n * (no dev server, no devtools, no record) prints the coded error — as\n * `{ ok: false, code, message }` with `--json` — and exits 2 for this machine\n * or 1 otherwise.\n *\n * @param data Parsed CLI args: `[method, url]`, `body`, `url`, `devtoolsPath`, `idHeader`, `timeout`, `json`.\n */\nexport async function traceCommandAction({ args, options }: CommandActionData): Promise<void> {\n  const json = options.json === true;\n  const [method, url] = args;\n\n  try {\n    if (!method || !url) {\n      throw new Error(\"Usage: warlock trace <method> <url> [--body json|@file] [--header k:v]\");\n    }\n\n    const timeout = stringOption(options.timeout);\n    const timeoutMs = timeout === undefined ? undefined : Number(timeout);\n\n    if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs < 0)) {\n      throw new Error(`Invalid --timeout ${JSON.stringify(timeout)}: expected milliseconds.`);\n    }\n\n    const report = await traceRequest({\n      method,\n      url,\n      body: parseTraceBody(stringOption(options.body)),\n      headers: parseHeaderValues(collectHeaderValues(process.argv)),\n      serverUrl: stringOption(options.url),\n      devtoolsPath: stringOption(options.devtoolsPath),\n      requestIdHeader: stringOption(options.idHeader),\n      timeoutMs,\n    });\n\n    if (json) {\n      console.log(JSON.stringify(report, null, 2));\n      return;\n    }\n\n    const [heading, ...rest] = formatTraceSummary(report);\n\n    console.log(colors.bold(heading ?? \"\"));\n\n    for (const line of rest) {\n      console.log(line);\n    }\n  } catch (error) {\n    const code = errorCodeOf(error) ?? null;\n    const message = error instanceof Error ? error.message : String(error);\n\n    if (json) {\n      console.log(JSON.stringify({ ok: false, code, message }, null, 2));\n    } else {\n      console.error(colors.red(`${code ? `${code} ` : \"\"}${message}`));\n\n      if (code) console.error(`  → ${ERROR_CODES[code].fix}`);\n    }\n\n    await flushAndExit(traceFailureExitCode(error));\n  }\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,60 @@
+import { command } from "../../commands/cli-command.mjs";
+import { traceCommandAction } from "./trace/trace-command.action.mjs";
+
+//#region ../../packages/core/src/cli/commands/trace.command.ts
+/**
+* `warlock trace <method> <url>` — send one request to the running dev server
+* and print its devtools timeline: middleware, validation result, handler,
+* queries with N+1 flags, logs, cache operations, the response and timings.
+* `--json` prints the versioned report (`schemaVersion: 1`).
+*
+* No preload: nothing boots here. The dev server (`warlock dev` with
+* `@warlock.js/devtools` installed) does the work; this command finds it
+* through `.warlock/dev-server.json` or `--url`.
+*/
+const traceCommand = command({
+	name: "trace <method> <url>",
+	description: "Send a request to the running dev server and print its devtools timeline (middleware, validation, queries, logs, response, timings); --json for the report",
+	action: traceCommandAction,
+	options: [
+		{
+			text: "--body, -b",
+			description: "Request body: JSON text, plain text, or @file to read it from a file",
+			type: "string"
+		},
+		{
+			text: "--header, -H",
+			description: "A request header as name:value (repeatable)",
+			type: "string"
+		},
+		{
+			text: "--url, -u",
+			description: "Dev server origin (default: read from .warlock/dev-server.json)",
+			type: "string"
+		},
+		{
+			text: "--devtools-path",
+			description: "Devtools mount path (default /__warlock)",
+			type: "string"
+		},
+		{
+			text: "--id-header",
+			description: "The app's request id header (http.requestId.header; default x-request-id)",
+			type: "string"
+		},
+		{
+			text: "--timeout, -t",
+			description: "How long to wait for the devtools record, in ms (default 5000)",
+			type: "string"
+		},
+		{
+			text: "--json, -j",
+			description: "Print the trace report as JSON (schemaVersion 1)",
+			type: "boolean"
+		}
+	]
+});
+
+//#endregion
+export { traceCommand };
+//# sourceMappingURL=trace.command.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"trace.command.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/cli/commands/trace.command.ts"],"sourcesContent":["import { command } from \"../../commands/cli-command\";\nimport { traceCommandAction } from \"./trace/trace-command.action\";\n\n/**\n * `warlock trace <method> <url>` — send one request to the running dev server\n * and print its devtools timeline: middleware, validation result, handler,\n * queries with N+1 flags, logs, cache operations, the response and timings.\n * `--json` prints the versioned report (`schemaVersion: 1`).\n *\n * No preload: nothing boots here. The dev server (`warlock dev` with\n * `@warlock.js/devtools` installed) does the work; this command finds it\n * through `.warlock/dev-server.json` or `--url`.\n */\nexport const traceCommand = command({\n  name: \"trace <method> <url>\",\n  description:\n    \"Send a request to the running dev server and print its devtools timeline (middleware, validation, queries, logs, response, timings); --json for the report\",\n  action: traceCommandAction,\n  options: [\n    {\n      text: \"--body, -b\",\n      description: \"Request body: JSON text, plain text, or @file to read it from a file\",\n      type: \"string\",\n    },\n    {\n      text: \"--header, -H\",\n      description: \"A request header as name:value (repeatable)\",\n      type: \"string\",\n    },\n    {\n      text: \"--url, -u\",\n      description: \"Dev server origin (default: read from .warlock/dev-server.json)\",\n      type: \"string\",\n    },\n    {\n      text: \"--devtools-path\",\n      description: \"Devtools mount path (default /__warlock)\",\n      type: \"string\",\n    },\n    {\n      text: \"--id-header\",\n      description: \"The app's request id header (http.requestId.header; default x-request-id)\",\n      type: \"string\",\n    },\n    {\n      text: \"--timeout, -t\",\n      description: \"How long to wait for the devtools record, in ms (default 5000)\",\n      type: \"string\",\n    },\n    {\n      text: \"--json, -j\",\n      description: \"Print the trace report as JSON (schemaVersion 1)\",\n      type: \"boolean\",\n    },\n  ],\n});\n"],"mappings":";;;;;;;;;;;;;;AAaA,MAAa,eAAe,QAAQ;CAClC,MAAM;CACN,aACE;CACF,QAAQ;CACR,SAAS;EACP;GACE,MAAM;GACN,aAAa;GACb,MAAM;EACR;EACA;GACE,MAAM;GACN,aAAa;GACb,MAAM;EACR;EACA;GACE,MAAM;GACN,aAAa;GACb,MAAM;EACR;EACA;GACE,MAAM;GACN,aAAa;GACb,MAAM;EACR;EACA;GACE,MAAM;GACN,aAAa;GACb,MAAM;EACR;EACA;GACE,MAAM;GACN,aAAa;GACb,MAAM;EACR;EACA;GACE,MAAM;GACN,aAAa;GACb,MAAM;EACR;CACF;AACF,CAAC"}

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

@@ -0,0 +1,40 @@
+import { command } from "../../commands/cli-command.mjs";
+import { typecheckCommandAction } from "./check/typecheck-command.action.mjs";
+
+//#region ../../packages/core/src/cli/commands/typecheck.command.ts
+/**
+* `warlock typecheck` — incremental TypeScript check through the compiler
+* API, with `--changed` to limit it to the changed files and their importers.
+* The same problem shape and exit codes as `warlock check`. No preload.
+*/
+const typecheckCommand = command({
+	name: "typecheck",
+	description: "Typecheck the project incrementally; --changed limits it to changed files and the files importing them",
+	action: typecheckCommandAction,
+	options: [
+		{
+			text: "--changed, -c",
+			description: "Only the files changed against HEAD (plus untracked files) and their importers",
+			type: "boolean"
+		},
+		{
+			text: "--base, -b",
+			description: "Compare with the merge base of this ref instead of HEAD (implies --changed)",
+			type: "string"
+		},
+		{
+			text: "--project, -p",
+			description: "tsconfig path (default tsconfig.json)",
+			type: "string"
+		},
+		{
+			text: "--json, -j",
+			description: "Print the result as JSON",
+			type: "boolean"
+		}
+	]
+});
+
+//#endregion
+export { typecheckCommand };
+//# sourceMappingURL=typecheck.command.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"typecheck.command.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/cli/commands/typecheck.command.ts"],"sourcesContent":["import { command } from \"../../commands/cli-command\";\nimport { typecheckCommandAction } from \"./check/typecheck-command.action\";\n\n/**\n * `warlock typecheck` — incremental TypeScript check through the compiler\n * API, with `--changed` to limit it to the changed files and their importers.\n * The same problem shape and exit codes as `warlock check`. No preload.\n */\nexport const typecheckCommand = command({\n  name: \"typecheck\",\n  description:\n    \"Typecheck the project incrementally; --changed limits it to changed files and the files importing them\",\n  action: typecheckCommandAction,\n  options: [\n    {\n      text: \"--changed, -c\",\n      description: \"Only the files changed against HEAD (plus untracked files) and their importers\",\n      type: \"boolean\",\n    },\n    {\n      text: \"--base, -b\",\n      description: \"Compare with the merge base of this ref instead of HEAD (implies --changed)\",\n      type: \"string\",\n    },\n    {\n      text: \"--project, -p\",\n      description: \"tsconfig path (default tsconfig.json)\",\n      type: \"string\",\n    },\n    {\n      text: \"--json, -j\",\n      description: \"Print the result as JSON\",\n      type: \"boolean\",\n    },\n  ],\n});\n"],"mappings":";;;;;;;;;AAQA,MAAa,mBAAmB,QAAQ;CACtC,MAAM;CACN,aACE;CACF,QAAQ;CACR,SAAS;EACP;GACE,MAAM;GACN,aAAa;GACb,MAAM;EACR;EACA;GACE,MAAM;GACN,aAAa;GACb,MAAM;EACR;EACA;GACE,MAAM;GACN,aAAa;GACb,MAAM;EACR;EACA;GACE,MAAM;GACN,aAAa;GACb,MAAM;EACR;CACF;AACF,CAAC"}

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/commands-loader.mjs

@@ -46,5 +46,5 @@ var CLICommandsLoader = class {
 const cliCommandsLoader = new CLICommandsLoader();
 
 //#endregion
-export { cliCommandsLoader };
+export { CLICommandsLoader, cliCommandsLoader };
 //# sourceMappingURL=commands-loader.mjs.map

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"}