@warlock.js/core 5.31.0 → 5.33.0

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

@@ -68,20 +68,21 @@ async function mcpCommandAction({ options }) {
 	if (transport.type === "stdio") routeConsoleToStderr();
 	const allowWrites = options.allowWrites === true;
 	const inspectOptions = lazyInspectOptions();
-	const server = await startWarlockMcpServer({
-		context: createMcpContext({
-			allowWrites,
-			inspect: async (sections) => inspectApp({
-				...await inspectOptions(),
-				sections
-			}),
-			...process.argv[1] ? { cliEntry: process.argv[1] } : {},
-			devtools: {
-				...stringOption(options.url) ? { url: stringOption(options.url) } : {},
-				...stringOption(options.devtoolsPath) ? { devtoolsPath: stringOption(options.devtoolsPath) } : {}
-			},
-			features: Object.keys(featuresMap)
+	const context = createMcpContext({
+		allowWrites,
+		inspect: async (sections) => inspectApp({
+			...await inspectOptions(),
+			sections
 		}),
+		...process.argv[1] ? { cliEntry: process.argv[1] } : {},
+		devtools: {
+			...stringOption(options.url) ? { url: stringOption(options.url) } : {},
+			...stringOption(options.devtoolsPath) ? { devtoolsPath: stringOption(options.devtoolsPath) } : {}
+		},
+		features: Object.keys(featuresMap)
+	});
+	const server = await startWarlockMcpServer({
+		context,
 		transport,
 		version: await getWarlockVersion()
 	});
@@ -99,5 +100,5 @@ async function mcpCommandAction({ options }) {
 }
 
 //#endregion
-export { mcpCommandAction, routeConsoleToStderr };
+export { mcpCommandAction, mcpTransportFromOptions, routeConsoleToStderr };
 //# sourceMappingURL=mcp-command.action.mjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"mcp-command.action.mjs","names":[],"sources":["../../../../../../../../../../packages/core/src/cli/commands/mcp/mcp-command.action.ts"],"sourcesContent":["import type { CommandActionData } from \"../../../commands/types\";\nimport { featuresMap } from \"../../../generations/features\";\nimport { bootForInspect, inspectOptionsFromBoot } from \"../../../tooling/inspect/boot-for-inspect\";\nimport { inspectApp, type InspectOptions } from \"../../../tooling/inspect/inspect-app\";\nimport { createMcpContext } from \"../../../tooling/mcp/create-mcp-context\";\nimport {\n  resolveMcpTransport,\n  startWarlockMcpServer,\n  type WarlockMcpTransport,\n} from \"../../../tooling/mcp/start-mcp-server\";\nimport { getWarlockVersion } from \"../../../utils/framework-vesion\";\nimport { flushAndExit } from \"../../flush-and-exit\";\n\nfunction stringOption(value: string | number | boolean | undefined): string | undefined {\n  if (typeof value === \"number\") return String(value);\n\n  return typeof value === \"string\" && value.trim().length > 0 ? value.trim() : undefined;\n}\n\n/**\n * The transport `warlock mcp` options describe: stdio by default, HTTP with\n * `--http` (and `--host`, `--port`, `--path`, `--token` / `WARLOCK_MCP_TOKEN`).\n * Throws on a port that is not a number.\n */\nexport function mcpTransportFromOptions(\n  options: CommandActionData[\"options\"],\n  env: NodeJS.ProcessEnv = process.env,\n): WarlockMcpTransport {\n  const http =\n    options.http === true || stringOption(options.host) !== undefined || options.port !== undefined;\n\n  if (!http) return { type: \"stdio\" };\n\n  const portText = stringOption(options.port);\n  const port = portText === undefined ? 0 : Number(portText);\n\n  if (!Number.isInteger(port) || port < 0 || port > 65_535) {\n    throw new Error(`--port must be a number from 0 to 65535, got ${JSON.stringify(portText)}.`);\n  }\n\n  return {\n    type: \"http\",\n    host: stringOption(options.host) ?? \"127.0.0.1\",\n    port,\n    path: stringOption(options.path) ?? \"/mcp\",\n    token: stringOption(options.token) ?? stringOption(env.WARLOCK_MCP_TOKEN),\n  };\n}\n\n/**\n * Send `console.log` / `console.info` / `console.debug` to stderr for the rest\n * of the process: over stdio, stdout carries only JSON-RPC, so a stray log\n * line from the app (or the framework's logger) would corrupt the stream.\n */\nexport function routeConsoleToStderr(): () => void {\n  const { log, info, debug } = console;\n  const toStderr = (...args: unknown[]) => console.error(...args);\n\n  console.log = toStderr;\n  console.info = toStderr;\n  console.debug = toStderr;\n\n  return () => {\n    console.log = log;\n    console.info = info;\n    console.debug = debug;\n  };\n}\n\n/** The read-only boot, run once on the first tool call that needs the app. */\nfunction lazyInspectOptions(): () => Promise<InspectOptions> {\n  let boot: Promise<InspectOptions> | undefined;\n\n  return () => {\n    boot ??= bootForInspect().then(inspectOptionsFromBoot);\n\n    return boot;\n  };\n}\n\n/**\n * Action behind `warlock mcp`.\n *\n * Serves the app's tools over MCP. The app is booted the `warlock inspect`\n * way — connectors booted, none started, no connection, no port — on the\n * first call that needs it, so the server answers `initialize` at once.\n * Runs until stdin closes (stdio) or SIGINT/SIGTERM.\n */\nexport async function mcpCommandAction({ options }: CommandActionData): Promise<void> {\n  const transport = mcpTransportFromOptions(options);\n\n  // Refuse an unsafe bind before anything boots.\n  resolveMcpTransport(transport);\n\n  if (transport.type === \"stdio\") routeConsoleToStderr();\n\n  const allowWrites = options.allowWrites === true;\n  const inspectOptions = lazyInspectOptions();\n  const context = createMcpContext({\n    allowWrites,\n    inspect: async (sections) => inspectApp({ ...(await inspectOptions()), sections }),\n    ...(process.argv[1] ? { cliEntry: process.argv[1] } : {}),\n    devtools: {\n      ...(stringOption(options.url) ? { url: stringOption(options.url) } : {}),\n      ...(stringOption(options.devtoolsPath)\n        ? { devtoolsPath: stringOption(options.devtoolsPath) }\n        : {}),\n    },\n    features: Object.keys(featuresMap),\n  });\n\n  const server = await startWarlockMcpServer({\n    context,\n    transport,\n    version: await getWarlockVersion(),\n  });\n\n  console.error(\n    `warlock mcp: ${server.tools.length} tools on ${server.url ?? \"stdio\"} (${allowWrites ? \"writes allowed\" : \"read-only\"})`,\n  );\n\n  let closing = false;\n\n  const stop = async () => {\n    if (closing) return;\n    closing = true;\n    await server.close();\n    await flushAndExit(0);\n  };\n\n  process.once(\"SIGINT\", () => void stop());\n  process.once(\"SIGTERM\", () => void stop());\n\n  if (transport.type === \"stdio\") {\n    process.stdin.once(\"end\", () => void stop());\n  }\n}\n"],"mappings":";;;;;;;;;AAaA,SAAS,aAAa,OAAkE;CACtF,IAAI,OAAO,UAAU,UAAU,OAAO,OAAO,KAAK;CAElD,OAAO,OAAO,UAAU,YAAY,MAAM,KAAK,CAAC,CAAC,SAAS,IAAI,MAAM,KAAK,IAAI;AAC/E;;;;;;AAOA,SAAgB,wBACd,SACA,MAAyB,QAAQ,KACZ;CAIrB,IAAI,EAFF,QAAQ,SAAS,QAAQ,aAAa,QAAQ,IAAI,MAAM,UAAa,QAAQ,SAAS,SAE7E,OAAO,EAAE,MAAM,QAAQ;CAElC,MAAM,WAAW,aAAa,QAAQ,IAAI;CAC1C,MAAM,OAAO,aAAa,SAAY,IAAI,OAAO,QAAQ;CAEzD,IAAI,CAAC,OAAO,UAAU,IAAI,KAAK,OAAO,KAAK,OAAO,OAChD,MAAM,IAAI,MAAM,gDAAgD,KAAK,UAAU,QAAQ,EAAE,EAAE;CAG7F,OAAO;EACL,MAAM;EACN,MAAM,aAAa,QAAQ,IAAI,KAAK;EACpC;EACA,MAAM,aAAa,QAAQ,IAAI,KAAK;EACpC,OAAO,aAAa,QAAQ,KAAK,KAAK,aAAa,IAAI,iBAAiB;CAC1E;AACF;;;;;;AAOA,SAAgB,uBAAmC;CACjD,MAAM,EAAE,KAAK,MAAM,UAAU;CAC7B,MAAM,YAAY,GAAG,SAAoB,QAAQ,MAAM,GAAG,IAAI;CAE9D,QAAQ,MAAM;CACd,QAAQ,OAAO;CACf,QAAQ,QAAQ;CAEhB,aAAa;EACX,QAAQ,MAAM;EACd,QAAQ,OAAO;EACf,QAAQ,QAAQ;CAClB;AACF;;AAGA,SAAS,qBAAoD;CAC3D,IAAI;CAEJ,aAAa;EACX,SAAS,eAAe,CAAC,CAAC,KAAK,sBAAsB;EAErD,OAAO;CACT;AACF;;;;;;;;;AAUA,eAAsB,iBAAiB,EAAE,WAA6C;CACpF,MAAM,YAAY,wBAAwB,OAAO;CAGjD,oBAAoB,SAAS;CAE7B,IAAI,UAAU,SAAS,SAAS,qBAAqB;CAErD,MAAM,cAAc,QAAQ,gBAAgB;CAC5C,MAAM,iBAAiB,mBAAmB;CAc1C,MAAM,SAAS,MAAM,sBAAsB;EACzC,SAdc,iBAAiB;GAC/B;GACA,SAAS,OAAO,aAAa,WAAW;IAAE,GAAI,MAAM,eAAe;IAAI;GAAS,CAAC;GACjF,GAAI,QAAQ,KAAK,KAAK,EAAE,UAAU,QAAQ,KAAK,GAAG,IAAI,CAAC;GACvD,UAAU;IACR,GAAI,aAAa,QAAQ,GAAG,IAAI,EAAE,KAAK,aAAa,QAAQ,GAAG,EAAE,IAAI,CAAC;IACtE,GAAI,aAAa,QAAQ,YAAY,IACjC,EAAE,cAAc,aAAa,QAAQ,YAAY,EAAE,IACnD,CAAC;GACP;GACA,UAAU,OAAO,KAAK,WAAW;EACnC,CAGQ;EACN;EACA,SAAS,MAAM,kBAAkB;CACnC,CAAC;CAED,QAAQ,MACN,gBAAgB,OAAO,MAAM,OAAO,YAAY,OAAO,OAAO,QAAQ,IAAI,cAAc,mBAAmB,YAAY,EACzH;CAEA,IAAI,UAAU;CAEd,MAAM,OAAO,YAAY;EACvB,IAAI,SAAS;EACb,UAAU;EACV,MAAM,OAAO,MAAM;EACnB,MAAM,aAAa,CAAC;CACtB;CAEA,QAAQ,KAAK,gBAAgB,KAAK,KAAK,CAAC;CACxC,QAAQ,KAAK,iBAAiB,KAAK,KAAK,CAAC;CAEzC,IAAI,UAAU,SAAS,SACrB,QAAQ,MAAM,KAAK,aAAa,KAAK,KAAK,CAAC;AAE/C"}
+{"version":3,"file":"mcp-command.action.mjs","names":[],"sources":["../../../../../../../../../../packages/core/src/cli/commands/mcp/mcp-command.action.ts"],"sourcesContent":["import type { CommandActionData } from \"../../../commands/types\";\nimport { featuresMap } from \"../../../generations/features\";\nimport { bootForInspect, inspectOptionsFromBoot } from \"../../../tooling/inspect/boot-for-inspect\";\nimport { inspectApp, type InspectOptions } from \"../../../tooling/inspect/inspect-app\";\nimport { createMcpContext } from \"../../../tooling/mcp/create-mcp-context\";\nimport {\n  resolveMcpTransport,\n  startWarlockMcpServer,\n  type WarlockMcpTransport,\n} from \"../../../tooling/mcp/start-mcp-server\";\nimport { getWarlockVersion } from \"../../../utils/framework-vesion\";\nimport { flushAndExit } from \"../../flush-and-exit\";\n\nfunction stringOption(value: string | number | boolean | undefined): string | undefined {\n  if (typeof value === \"number\") return String(value);\n\n  return typeof value === \"string\" && value.trim().length > 0 ? value.trim() : undefined;\n}\n\n/**\n * The transport `warlock mcp` options describe: stdio by default, HTTP with\n * `--http` (and `--host`, `--port`, `--path`, `--token` / `WARLOCK_MCP_TOKEN`).\n * Throws on a port that is not a number.\n */\nexport function mcpTransportFromOptions(\n  options: CommandActionData[\"options\"],\n  env: NodeJS.ProcessEnv = process.env,\n): WarlockMcpTransport {\n  const http =\n    options.http === true || stringOption(options.host) !== undefined || options.port !== undefined;\n\n  if (!http) return { type: \"stdio\" };\n\n  const portText = stringOption(options.port);\n  const port = portText === undefined ? 0 : Number(portText);\n\n  if (!Number.isInteger(port) || port < 0 || port > 65_535) {\n    throw new Error(`--port must be a number from 0 to 65535, got ${JSON.stringify(portText)}.`);\n  }\n\n  return {\n    type: \"http\",\n    host: stringOption(options.host) ?? \"127.0.0.1\",\n    port,\n    path: stringOption(options.path) ?? \"/mcp\",\n    token: stringOption(options.token) ?? stringOption(env.WARLOCK_MCP_TOKEN),\n  };\n}\n\n/**\n * Send `console.log` / `console.info` / `console.debug` to stderr for the rest\n * of the process: over stdio, stdout carries only JSON-RPC, so a stray log\n * line from the app (or the framework's logger) would corrupt the stream.\n */\nexport function routeConsoleToStderr(): () => void {\n  const { log, info, debug } = console;\n  const toStderr = (...args: unknown[]) => console.error(...args);\n\n  console.log = toStderr;\n  console.info = toStderr;\n  console.debug = toStderr;\n\n  return () => {\n    console.log = log;\n    console.info = info;\n    console.debug = debug;\n  };\n}\n\n/** The read-only boot, run once on the first tool call that needs the app. */\nfunction lazyInspectOptions(): () => Promise<InspectOptions> {\n  let boot: Promise<InspectOptions> | undefined;\n\n  return () => {\n    boot ??= bootForInspect().then(inspectOptionsFromBoot);\n\n    return boot;\n  };\n}\n\n/**\n * Action behind `warlock mcp`.\n *\n * Serves the app's tools over MCP. The app is booted the `warlock inspect`\n * way — connectors booted, none started, no connection, no port — on the\n * first call that needs it, so the server answers `initialize` at once.\n * Runs until stdin closes (stdio) or SIGINT/SIGTERM.\n */\nexport async function mcpCommandAction({ options }: CommandActionData): Promise<void> {\n  const transport = mcpTransportFromOptions(options);\n\n  // Refuse an unsafe bind before anything boots.\n  resolveMcpTransport(transport);\n\n  if (transport.type === \"stdio\") routeConsoleToStderr();\n\n  const allowWrites = options.allowWrites === true;\n  const inspectOptions = lazyInspectOptions();\n  const context = createMcpContext({\n    allowWrites,\n    inspect: async (sections) => inspectApp({ ...(await inspectOptions()), sections }),\n    ...(process.argv[1] ? { cliEntry: process.argv[1] } : {}),\n    devtools: {\n      ...(stringOption(options.url) ? { url: stringOption(options.url) } : {}),\n      ...(stringOption(options.devtoolsPath)\n        ? { devtoolsPath: stringOption(options.devtoolsPath) }\n        : {}),\n    },\n    features: Object.keys(featuresMap),\n  });\n\n  const server = await startWarlockMcpServer({\n    context,\n    transport,\n    version: await getWarlockVersion(),\n  });\n\n  console.error(\n    `warlock mcp: ${server.tools.length} tools on ${server.url ?? \"stdio\"} (${allowWrites ? \"writes allowed\" : \"read-only\"})`,\n  );\n\n  let closing = false;\n\n  const stop = async () => {\n    if (closing) return;\n    closing = true;\n    await server.close();\n    await flushAndExit(0);\n  };\n\n  process.once(\"SIGINT\", () => void stop());\n  process.once(\"SIGTERM\", () => void stop());\n\n  if (transport.type === \"stdio\") {\n    process.stdin.once(\"end\", () => void stop());\n  }\n}\n"],"mappings":";;;;;;;;;AAaA,SAAS,aAAa,OAAkE;CACtF,IAAI,OAAO,UAAU,UAAU,OAAO,OAAO,KAAK;CAElD,OAAO,OAAO,UAAU,YAAY,MAAM,KAAK,CAAC,CAAC,SAAS,IAAI,MAAM,KAAK,IAAI;AAC/E;;;;;;AAOA,SAAgB,wBACd,SACA,MAAyB,QAAQ,KACZ;CAIrB,IAAI,EAFF,QAAQ,SAAS,QAAQ,aAAa,QAAQ,IAAI,MAAM,UAAa,QAAQ,SAAS,SAE7E,OAAO,EAAE,MAAM,QAAQ;CAElC,MAAM,WAAW,aAAa,QAAQ,IAAI;CAC1C,MAAM,OAAO,aAAa,SAAY,IAAI,OAAO,QAAQ;CAEzD,IAAI,CAAC,OAAO,UAAU,IAAI,KAAK,OAAO,KAAK,OAAO,OAChD,MAAM,IAAI,MAAM,gDAAgD,KAAK,UAAU,QAAQ,EAAE,EAAE;CAG7F,OAAO;EACL,MAAM;EACN,MAAM,aAAa,QAAQ,IAAI,KAAK;EACpC;EACA,MAAM,aAAa,QAAQ,IAAI,KAAK;EACpC,OAAO,aAAa,QAAQ,KAAK,KAAK,aAAa,IAAI,iBAAiB;CAC1E;AACF;;;;;;AAOA,SAAgB,uBAAmC;CACjD,MAAM,EAAE,KAAK,MAAM,UAAU;CAC7B,MAAM,YAAY,GAAG,SAAoB,QAAQ,MAAM,GAAG,IAAI;CAE9D,QAAQ,MAAM;CACd,QAAQ,OAAO;CACf,QAAQ,QAAQ;CAEhB,aAAa;EACX,QAAQ,MAAM;EACd,QAAQ,OAAO;EACf,QAAQ,QAAQ;CAClB;AACF;;AAGA,SAAS,qBAAoD;CAC3D,IAAI;CAEJ,aAAa;EACX,SAAS,eAAe,CAAC,CAAC,KAAK,sBAAsB;EAErD,OAAO;CACT;AACF;;;;;;;;;AAUA,eAAsB,iBAAiB,EAAE,WAA6C;CACpF,MAAM,YAAY,wBAAwB,OAAO;CAGjD,oBAAoB,SAAS;CAE7B,IAAI,UAAU,SAAS,SAAS,qBAAqB;CAErD,MAAM,cAAc,QAAQ,gBAAgB;CAC5C,MAAM,iBAAiB,mBAAmB;CAC1C,MAAM,UAAU,iBAAiB;EAC/B;EACA,SAAS,OAAO,aAAa,WAAW;GAAE,GAAI,MAAM,eAAe;GAAI;EAAS,CAAC;EACjF,GAAI,QAAQ,KAAK,KAAK,EAAE,UAAU,QAAQ,KAAK,GAAG,IAAI,CAAC;EACvD,UAAU;GACR,GAAI,aAAa,QAAQ,GAAG,IAAI,EAAE,KAAK,aAAa,QAAQ,GAAG,EAAE,IAAI,CAAC;GACtE,GAAI,aAAa,QAAQ,YAAY,IACjC,EAAE,cAAc,aAAa,QAAQ,YAAY,EAAE,IACnD,CAAC;EACP;EACA,UAAU,OAAO,KAAK,WAAW;CACnC,CAAC;CAED,MAAM,SAAS,MAAM,sBAAsB;EACzC;EACA;EACA,SAAS,MAAM,kBAAkB;CACnC,CAAC;CAED,QAAQ,MACN,gBAAgB,OAAO,MAAM,OAAO,YAAY,OAAO,OAAO,QAAQ,IAAI,cAAc,mBAAmB,YAAY,EACzH;CAEA,IAAI,UAAU;CAEd,MAAM,OAAO,YAAY;EACvB,IAAI,SAAS;EACb,UAAU;EACV,MAAM,OAAO,MAAM;EACnB,MAAM,aAAa,CAAC;CACtB;CAEA,QAAQ,KAAK,gBAAgB,KAAK,KAAK,CAAC;CACxC,QAAQ,KAAK,iBAAiB,KAAK,KAAK,CAAC;CAEzC,IAAI,UAAU,SAAS,SACrB,QAAQ,MAAM,KAAK,aAAa,KAAK,KAAK,CAAC;AAE/C"}

package/esm/cli/commands/openapi-generator.action.mjs

@@ -39,5 +39,5 @@ async function generateOpenApiAction({ options }) {
 }
 
 //#endregion
-export { generateOpenApiAction, stringOption };
+export { DEFAULT_OPENAPI_OUTPUT, generateOpenApiAction, stringOption };
 //# sourceMappingURL=openapi-generator.action.mjs.map

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

@@ -0,0 +1,91 @@
+import { config } from "../../../config/config-getter.mjs";
+import { resolveBuildConfig } from "../../../production/resolve-build-config.mjs";
+import { checkDistReadyToStartAsync } from "../../../production/assert-dist-ready-to-start.mjs";
+import { createPm2Config, selectPm2Targets, writePm2Config } from "./pm2-config.mjs";
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { execFile } from "node:child_process";
+
+//#region ../../packages/core/src/cli/commands/pm2/pm2-command.action.ts
+/** No shell, no patterns, no import of PM2 or dependency on its daemon for init. */
+function runPm2(args, cwd) {
+	return new Promise((resolve, reject) => {
+		const child = execFile("pm2", args, {
+			cwd,
+			encoding: "utf8",
+			maxBuffer: 8388608
+		}, (error, stdout) => {
+			if (error) reject(/* @__PURE__ */ new Error(`PM2 command failed (CLI pid ${child.pid ?? "unavailable"}). Install PM2 separately and ensure it is on PATH. ${error.message}`));
+			else resolve(stdout);
+		});
+	});
+}
+function stringOption(data, name) {
+	const value = data.options[name];
+	if (value === void 0) return void 0;
+	if (typeof value !== "string" || value.length === 0) throw new Error(`--${name} requires a value.`);
+	return value;
+}
+async function pm2CommandAction(data) {
+	const [action, ...extra] = data.args;
+	if (action !== "init" && action !== "reload" || extra.length > 0) throw new Error("Usage: warlock pm2 init | warlock pm2 reload [--id <pm2-id>]");
+	const allowed = new Set(action === "init" ? [
+		"project",
+		"app",
+		"cluster",
+		"instances",
+		"listenTimeout"
+	] : [
+		"project",
+		"app",
+		"id"
+	]);
+	for (const key of Object.keys(data.options)) if (!allowed.has(key)) throw new Error(`Unsupported option for pm2 ${action}: ${key}`);
+	if (data.options.cluster !== void 0 && typeof data.options.cluster !== "boolean") throw new Error("--cluster must be a boolean.");
+	const root = process.cwd();
+	const packageJson = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+	const packageName = typeof packageJson === "object" && packageJson !== null && "name" in packageJson && typeof packageJson.name === "string" ? packageJson.name : void 0;
+	const project = stringOption(data, "project") ?? packageName;
+	if (!project) throw new Error("Set package.json name or pass --project to identify this project.");
+	const app = config.get("app") ?? {};
+	const appOverride = stringOption(data, "app");
+	const build = resolveBuildConfig();
+	const input = {
+		root,
+		project,
+		app: appOverride === void 0 ? app : {
+			...app,
+			appName: appOverride
+		},
+		environment: process.env.NODE_ENV ?? "development",
+		entryPath: build.entryPath,
+		sourcemap: build.sourcemap,
+		http: config.get("http"),
+		socket: config.get("socket")
+	};
+	if (action === "init") {
+		const generated = createPm2Config(input, {
+			cluster: data.options.cluster === true,
+			instances: stringOption(data, "instances"),
+			listenTimeout: stringOption(data, "listenTimeout")
+		});
+		const target = await writePm2Config(root, generated.content);
+		console.log(`Created ${target} for ${generated.app.name}.`);
+		console.log(`Readiness URL: ${generated.readinessUrl ?? "unavailable (HTTP/health disabled or ephemeral port)"}`);
+		console.log(generated.app.exec_mode === "cluster" ? "Cluster reload replaces workers in sequence; a PM2 readiness timeout can still cause downtime." : "Fork mode uses a restart on reload; use --cluster for rolling HTTP reloads.");
+		return;
+	}
+	const readiness = await checkDistReadyToStartAsync(build.outdir);
+	if (!readiness.ready) throw new Error(readiness.reason);
+	const list = JSON.parse(await runPm2(["jlist"], root));
+	const targets = selectPm2Targets(list, input, stringOption(data, "id"));
+	if (targets.some((target) => !target.cluster)) console.warn("Fork mode reload falls back to restart; expect a brief interruption.");
+	for (const target of targets) {
+		const output = await runPm2(["reload", String(target.id)], root);
+		if (output) process.stdout.write(output);
+	}
+}
+
+//#endregion
+export { pm2CommandAction, runPm2 };
+//# sourceMappingURL=pm2-command.action.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pm2-command.action.mjs","names":[],"sources":["../../../../../../../../../../packages/core/src/cli/commands/pm2/pm2-command.action.ts"],"sourcesContent":["import { execFile } from \"node:child_process\";\nimport { readFile } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport type { AppConfigurations } from \"../../../application/application-config-types\";\nimport type { CommandActionData } from \"../../../commands/types\";\nimport { config } from \"../../../config/config-getter\";\nimport type { HttpConfigurations } from \"../../../http/types\";\nimport { checkDistReadyToStartAsync } from \"../../../production/assert-dist-ready-to-start\";\nimport { resolveBuildConfig } from \"../../../production/resolve-build-config\";\nimport type { SocketOptions } from \"../../../socket/types\";\nimport { createPm2Config, selectPm2Targets, writePm2Config } from \"./pm2-config\";\n\n/** No shell, no patterns, no import of PM2 or dependency on its daemon for init. */\nexport function runPm2(args: string[], cwd: string): Promise<string> {\n  return new Promise((resolve, reject) => {\n    const child = execFile(\n      \"pm2\",\n      args,\n      { cwd, encoding: \"utf8\", maxBuffer: 8 * 1024 * 1024 },\n      (error, stdout) => {\n        if (error) {\n          reject(\n            new Error(\n              `PM2 command failed (CLI pid ${child.pid ?? \"unavailable\"}). Install PM2 separately and ensure it is on PATH. ${error.message}`,\n            ),\n          );\n        } else {\n          resolve(stdout);\n        }\n      },\n    );\n    // Retain the child and its PID; this function never stops a daemon or any\n    // application process. PM2 reload is invoked only with validated ids.\n  });\n}\n\nfunction stringOption(data: CommandActionData, name: string): string | undefined {\n  const value = data.options[name];\n  if (value === undefined) return undefined;\n  if (typeof value !== \"string\" || value.length === 0)\n    throw new Error(`--${name} requires a value.`);\n  return value;\n}\n\nexport async function pm2CommandAction(data: CommandActionData): Promise<void> {\n  const [action, ...extra] = data.args;\n  if ((action !== \"init\" && action !== \"reload\") || extra.length > 0) {\n    throw new Error(\"Usage: warlock pm2 init | warlock pm2 reload [--id <pm2-id>]\");\n  }\n  const allowed = new Set(\n    action === \"init\"\n      ? [\"project\", \"app\", \"cluster\", \"instances\", \"listenTimeout\"]\n      : [\"project\", \"app\", \"id\"],\n  );\n  for (const key of Object.keys(data.options)) {\n    if (!allowed.has(key)) throw new Error(`Unsupported option for pm2 ${action}: ${key}`);\n  }\n  if (data.options.cluster !== undefined && typeof data.options.cluster !== \"boolean\") {\n    throw new Error(\"--cluster must be a boolean.\");\n  }\n\n  const root = process.cwd();\n  const packageJson: unknown = JSON.parse(await readFile(path.join(root, \"package.json\"), \"utf8\"));\n  const packageName =\n    typeof packageJson === \"object\" &&\n    packageJson !== null &&\n    \"name\" in packageJson &&\n    typeof packageJson.name === \"string\"\n      ? packageJson.name\n      : undefined;\n  const project = stringOption(data, \"project\") ?? packageName;\n  if (!project)\n    throw new Error(\"Set package.json name or pass --project to identify this project.\");\n  const app = config.get<AppConfigurations | undefined>(\"app\") ?? {};\n  const appOverride = stringOption(data, \"app\");\n  const build = resolveBuildConfig();\n  const input = {\n    root,\n    project,\n    app: appOverride === undefined ? app : { ...app, appName: appOverride },\n    environment: process.env.NODE_ENV ?? \"development\",\n    entryPath: build.entryPath,\n    sourcemap: build.sourcemap,\n    http: config.get<HttpConfigurations | undefined>(\"http\"),\n    socket: config.get<SocketOptions | undefined>(\"socket\"),\n  };\n\n  if (action === \"init\") {\n    const generated = createPm2Config(input, {\n      cluster: data.options.cluster === true,\n      instances: stringOption(data, \"instances\"),\n      listenTimeout: stringOption(data, \"listenTimeout\"),\n    });\n    const target = await writePm2Config(root, generated.content);\n    console.log(`Created ${target} for ${generated.app.name}.`);\n    console.log(\n      `Readiness URL: ${generated.readinessUrl ?? \"unavailable (HTTP/health disabled or ephemeral port)\"}`,\n    );\n    console.log(\n      generated.app.exec_mode === \"cluster\"\n        ? \"Cluster reload replaces workers in sequence; a PM2 readiness timeout can still cause downtime.\"\n        : \"Fork mode uses a restart on reload; use --cluster for rolling HTTP reloads.\",\n    );\n    return;\n  }\n\n  const readiness = await checkDistReadyToStartAsync(build.outdir);\n  if (!readiness.ready) throw new Error(readiness.reason);\n  // jlist is JSON per PM2's API.js. Match exact identity locally, then reload\n  // numeric ids only; a name collision never broadens the operation.\n  // https://github.com/Unitech/pm2/blob/master/lib/API.js\n  const list: unknown = JSON.parse(await runPm2([\"jlist\"], root));\n  const targets = selectPm2Targets(list, input, stringOption(data, \"id\"));\n  if (targets.some((target) => !target.cluster)) {\n    console.warn(\"Fork mode reload falls back to restart; expect a brief interruption.\");\n  }\n  for (const target of targets) {\n    const output = await runPm2([\"reload\", String(target.id)], root);\n    if (output) process.stdout.write(output);\n  }\n}\n"],"mappings":"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"}

package/esm/cli/commands/pm2/pm2-config.mjs

@@ -0,0 +1,115 @@
+import { resolveBindPort } from "../../../http/resolve-bind-port.mjs";
+import { DEFAULT_SHUTDOWN_TIMEOUT } from "../../../connectors/shutdown-timeout.mjs";
+import path from "node:path";
+import { writeFile } from "node:fs/promises";
+
+//#region ../../packages/core/src/cli/commands/pm2/pm2-config.ts
+/** Refuse selectors PM2 could interpret as patterns, file names or options. */
+function nameComponent(value, label) {
+	if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(value)) throw new Error(`${label} must contain only letters, digits, underscores and hyphens, starting with a letter or digit.`);
+	return value;
+}
+function pm2AppName(input) {
+	return [
+		nameComponent(input.project.replace(/^@([^/]+)\/([^/]+)$/, "$1-$2"), "Project name (--project)"),
+		nameComponent(input.app.appName ?? "app", "App name (--app or app.appName)"),
+		nameComponent(input.environment, "NODE_ENV")
+	].join("-");
+}
+function positiveInteger(value, label) {
+	const number = typeof value === "number" ? value : /^\d+$/.test(value) ? Number(value) : NaN;
+	if (!Number.isSafeInteger(number) || number <= 0 || number > 2147483647) throw new Error(`${label} must be a positive integer no greater than 2147483647.`);
+	return number;
+}
+function assertClusterSockets(socket) {
+	if (!socket) return;
+	if (typeof socket.adapter !== "function") throw new Error("PM2 cluster mode with sockets requires socket.adapter for broadcasts between workers. Configure an adapter such as @socket.io/redis-adapter, or use fork mode.");
+	if (socket.options?.transports?.length !== 1 || socket.options.transports[0] !== "websocket") throw new Error("PM2 cluster sockets require socket.options.transports: [\"websocket\"] and WebSocket-only clients. Polling needs sticky routing to individual workers; use separate fork listeners behind a sticky proxy for polling.");
+}
+function readinessUrl(http) {
+	if (!http || http.health?.enabled === false) return void 0;
+	const port = resolveBindPort(http.port);
+	if (port === 0) return void 0;
+	const bindHost = http.host ?? "localhost";
+	const host = bindHost === "0.0.0.0" ? "127.0.0.1" : bindHost === "::" ? "::1" : bindHost;
+	const authority = host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+	const probePath = http.health?.readinessPath ?? "/ready";
+	if (!probePath.startsWith("/") || probePath.startsWith("//") || /[\r\n]/.test(probePath)) throw new Error("http.health.readinessPath must be a local absolute URL path.");
+	return `${http.serverOptions?.https ? "https" : "http"}://${authority}:${port}${probePath}`;
+}
+function createPm2Config(input, options = {}) {
+	const cluster = options.cluster === true;
+	if (!cluster && options.instances !== void 0) throw new Error("--instances requires --cluster; fork mode runs exactly one process.");
+	if (cluster) assertClusterSockets(input.socket);
+	const instances = cluster ? options.instances === "max" ? "max" : positiveInteger(options.instances ?? "2", "--instances") : 1;
+	const app = {
+		name: pm2AppName(input),
+		cwd: path.resolve(input.root),
+		script: path.resolve(input.root, input.entryPath),
+		interpreter: process.execPath,
+		node_args: input.sourcemap === false ? [] : ["--enable-source-maps"],
+		exec_mode: cluster ? "cluster" : "fork",
+		instances,
+		wait_ready: true,
+		listen_timeout: positiveInteger(options.listenTimeout ?? "30000", "--listen-timeout"),
+		kill_timeout: positiveInteger(input.app.shutdownTimeout ?? 1e4, "app.shutdownTimeout"),
+		time: false,
+		merge_logs: false,
+		env: { NODE_ENV: input.environment }
+	};
+	const url = readinessUrl(input.http);
+	return {
+		app,
+		content: [
+			"// Generated by warlock pm2 init. Rebuild the app before starting PM2.",
+			"// PM2 timeouts: https://pm2.keymetrics.io/docs/usage/signals-clean-restart/",
+			`// Readiness URL (external probe; PM2 does not poll it): ${JSON.stringify(url ?? "unavailable: HTTP/health disabled or ephemeral port").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029")}`,
+			`module.exports = ${JSON.stringify({ apps: [app] }, null, 2)};`,
+			""
+		].join("\n"),
+		readinessUrl: url
+	};
+}
+async function writePm2Config(root, content) {
+	const target = path.resolve(root, "ecosystem.config.cjs");
+	await writeFile(target, content, {
+		encoding: "utf8",
+		flag: "wx"
+	});
+	return target;
+}
+function record(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+/** Validate the entire target set before issuing any mutating PM2 command. */
+function selectPm2Targets(list, input, id) {
+	if (!Array.isArray(list)) throw new Error("PM2 jlist did not return a process array.");
+	if (id !== void 0 && (!/^\d+$/.test(id) || !Number.isSafeInteger(Number(id)))) throw new Error("--id must be a numeric PM2 id.");
+	const name = pm2AppName(input);
+	const targets = [];
+	for (const item of list) {
+		const process = record(item);
+		if (!process) throw new Error("Invalid PM2 process entry.");
+		if (id !== void 0 ? process.pm_id !== Number(id) : process.name !== name) continue;
+		const env = record(process.pm2_env);
+		if (process.name !== name || !env || env.pm_cwd !== path.resolve(input.root) || env.pm_exec_path !== path.resolve(input.root, input.entryPath)) throw new Error(`Refusing to reload PM2 id ${String(process.pm_id)}: name, working directory or bundle does not belong to this app.`);
+		if (typeof process.pm_id !== "number" || !Number.isSafeInteger(process.pm_id) || process.pm_id < 0) throw new Error("Invalid PM2 id in process list.");
+		if (env.exec_mode !== "fork_mode" && env.exec_mode !== "cluster_mode") throw new Error("Unrecognized PM2 execution mode.");
+		const cluster = env.exec_mode === "cluster_mode";
+		if (cluster) {
+			assertClusterSockets(input.socket);
+			if (env.wait_ready !== true || env.status !== "online") throw new Error("Rolling reload requires an online cluster worker with wait_ready: true. Check its PM2 configuration and status.");
+		}
+		targets.push({
+			id: process.pm_id,
+			cluster
+		});
+	}
+	if (targets.length === 0) throw new Error(`No PM2 process belonging to ${name} was found. Start its ecosystem file first.`);
+	if (new Set(targets.map((target) => target.id)).size !== targets.length) throw new Error("Duplicate PM2 ids in process list.");
+	return targets;
+}
+
+//#endregion
+export { assertClusterSockets, createPm2Config, pm2AppName, selectPm2Targets, writePm2Config };
+//# sourceMappingURL=pm2-config.mjs.map

package/esm/cli/commands/pm2/pm2-config.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pm2-config.mjs","names":[],"sources":["../../../../../../../../../../packages/core/src/cli/commands/pm2/pm2-config.ts"],"sourcesContent":["import path from \"node:path\";\nimport { writeFile } from \"node:fs/promises\";\nimport type { AppConfigurations } from \"../../../application/application-config-types\";\nimport { DEFAULT_SHUTDOWN_TIMEOUT } from \"../../../connectors/shutdown-timeout\";\nimport { resolveBindPort } from \"../../../http/resolve-bind-port\";\nimport type { HttpConfigurations } from \"../../../http/types\";\nimport type { SocketOptions } from \"../../../socket/types\";\nimport type { ResolvedBuildConfig } from \"../../../production/resolve-build-config\";\n\nexport type Pm2AppInput = {\n  root: string;\n  project: string;\n  app: AppConfigurations;\n  environment: string;\n  entryPath: string;\n  sourcemap: ResolvedBuildConfig[\"sourcemap\"];\n  http?: HttpConfigurations;\n  socket?: SocketOptions;\n};\n\nexport type Pm2InitOptions = {\n  cluster?: boolean;\n  instances?: string;\n  listenTimeout?: string;\n};\n\n/** Refuse selectors PM2 could interpret as patterns, file names or options. */\nfunction nameComponent(value: string, label: string): string {\n  if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(value)) {\n    throw new Error(\n      `${label} must contain only letters, digits, underscores and hyphens, starting with a letter or digit.`,\n    );\n  }\n  return value;\n}\n\nexport function pm2AppName(input: Pick<Pm2AppInput, \"project\" | \"app\" | \"environment\">): string {\n  // Preserve the npm scope in the project identity instead of dropping it.\n  const project = input.project.replace(/^@([^/]+)\\/([^/]+)$/, \"$1-$2\");\n  return [\n    nameComponent(project, \"Project name (--project)\"),\n    nameComponent(input.app.appName ?? \"app\", \"App name (--app or app.appName)\"),\n    nameComponent(input.environment, \"NODE_ENV\"),\n  ].join(\"-\");\n}\n\nfunction positiveInteger(value: number | string, label: string): number {\n  const number = typeof value === \"number\" ? value : /^\\d+$/.test(value) ? Number(value) : NaN;\n  if (!Number.isSafeInteger(number) || number <= 0 || number > 2_147_483_647) {\n    throw new Error(`${label} must be a positive integer no greater than 2147483647.`);\n  }\n  return number;\n}\n\nexport function assertClusterSockets(socket?: SocketOptions): void {\n  if (!socket) return;\n  if (typeof socket.adapter !== \"function\") {\n    throw new Error(\n      \"PM2 cluster mode with sockets requires socket.adapter for broadcasts between workers. Configure an adapter such as @socket.io/redis-adapter, or use fork mode.\",\n    );\n  }\n  // A proxy sticky to a shared PM2 port is not sticky to its workers. We do\n  // not install primary-process routing. Fail closed for long-polling.\n  // https://socket.io/docs/v4/using-multiple-nodes/\n  if (socket.options?.transports?.length !== 1 || socket.options.transports[0] !== \"websocket\") {\n    throw new Error(\n      'PM2 cluster sockets require socket.options.transports: [\"websocket\"] and WebSocket-only clients. Polling needs sticky routing to individual workers; use separate fork listeners behind a sticky proxy for polling.',\n    );\n  }\n}\n\nfunction readinessUrl(http?: HttpConfigurations): string | undefined {\n  if (!http || http.health?.enabled === false) return undefined;\n  const port = resolveBindPort(http.port);\n  if (port === 0) return undefined;\n  const bindHost = http.host ?? \"localhost\";\n  const host = bindHost === \"0.0.0.0\" ? \"127.0.0.1\" : bindHost === \"::\" ? \"::1\" : bindHost;\n  const authority = host.includes(\":\") && !host.startsWith(\"[\") ? `[${host}]` : host;\n  const probePath = http.health?.readinessPath ?? \"/ready\";\n  if (!probePath.startsWith(\"/\") || probePath.startsWith(\"//\") || /[\\r\\n]/.test(probePath)) {\n    throw new Error(\"http.health.readinessPath must be a local absolute URL path.\");\n  }\n  return `${http.serverOptions?.https ? \"https\" : \"http\"}://${authority}:${port}${probePath}`;\n}\n\nexport function createPm2Config(input: Pm2AppInput, options: Pm2InitOptions = {}) {\n  const cluster = options.cluster === true;\n  if (!cluster && options.instances !== undefined) {\n    throw new Error(\"--instances requires --cluster; fork mode runs exactly one process.\");\n  }\n  if (cluster) assertClusterSockets(input.socket);\n  const instances = cluster\n    ? options.instances === \"max\"\n      ? \"max\"\n      : positiveInteger(options.instances ?? \"2\", \"--instances\")\n    : 1;\n  const app = {\n    name: pm2AppName(input),\n    cwd: path.resolve(input.root),\n    // Run the bundle itself, not the `warlock start` child supervisor: PM2\n    // must own the process that listens and sends its readiness message.\n    script: path.resolve(input.root, input.entryPath),\n    interpreter: process.execPath,\n    node_args: input.sourcemap === false ? [] : [\"--enable-source-maps\"],\n    exec_mode: cluster ? \"cluster\" : \"fork\",\n    instances,\n    wait_ready: true,\n    listen_timeout: positiveInteger(options.listenTimeout ?? \"30000\", \"--listen-timeout\"),\n    kill_timeout: positiveInteger(\n      input.app.shutdownTimeout ?? DEFAULT_SHUTDOWN_TIMEOUT,\n      \"app.shutdownTimeout\",\n    ),\n    // Keep @warlock.js/logger messages intact; leave per-worker log suffixes.\n    time: false,\n    merge_logs: false,\n    env: { NODE_ENV: input.environment },\n  };\n  const url = readinessUrl(input.http);\n  // JSON encoding keeps project/config strings from becoming executable code\n  // or escaping a comment in this CommonJS file.\n  const content = [\n    \"// Generated by warlock pm2 init. Rebuild the app before starting PM2.\",\n    \"// PM2 timeouts: https://pm2.keymetrics.io/docs/usage/signals-clean-restart/\",\n    `// Readiness URL (external probe; PM2 does not poll it): ${JSON.stringify(\n      url ?? \"unavailable: HTTP/health disabled or ephemeral port\",\n    )\n      .replace(/\\u2028/g, \"\\\\u2028\")\n      .replace(/\\u2029/g, \"\\\\u2029\")}`,\n    `module.exports = ${JSON.stringify({ apps: [app] }, null, 2)};`,\n    \"\",\n  ].join(\"\\n\");\n  return { app, content, readinessUrl: url };\n}\n\nexport async function writePm2Config(root: string, content: string): Promise<string> {\n  const target = path.resolve(root, \"ecosystem.config.cjs\");\n  // Atomic create: an existing/customized ecosystem is never overwritten.\n  await writeFile(target, content, { encoding: \"utf8\", flag: \"wx\" });\n  return target;\n}\n\nexport type Pm2Target = { id: number; cluster: boolean };\n\nfunction record(value: unknown): Record<string, unknown> | undefined {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : undefined;\n}\n\n/** Validate the entire target set before issuing any mutating PM2 command. */\nexport function selectPm2Targets(list: unknown, input: Pm2AppInput, id?: string): Pm2Target[] {\n  if (!Array.isArray(list)) throw new Error(\"PM2 jlist did not return a process array.\");\n  if (id !== undefined && (!/^\\d+$/.test(id) || !Number.isSafeInteger(Number(id)))) {\n    throw new Error(\"--id must be a numeric PM2 id.\");\n  }\n  const name = pm2AppName(input);\n  const targets: Pm2Target[] = [];\n  for (const item of list) {\n    const process = record(item);\n    if (!process) throw new Error(\"Invalid PM2 process entry.\");\n    if (id !== undefined ? process.pm_id !== Number(id) : process.name !== name) continue;\n    const env = record(process.pm2_env);\n    if (\n      process.name !== name ||\n      !env ||\n      env.pm_cwd !== path.resolve(input.root) ||\n      env.pm_exec_path !== path.resolve(input.root, input.entryPath)\n    ) {\n      throw new Error(\n        `Refusing to reload PM2 id ${String(process.pm_id)}: name, working directory or bundle does not belong to this app.`,\n      );\n    }\n    if (\n      typeof process.pm_id !== \"number\" ||\n      !Number.isSafeInteger(process.pm_id) ||\n      process.pm_id < 0\n    ) {\n      throw new Error(\"Invalid PM2 id in process list.\");\n    }\n    if (env.exec_mode !== \"fork_mode\" && env.exec_mode !== \"cluster_mode\") {\n      throw new Error(\"Unrecognized PM2 execution mode.\");\n    }\n    const cluster = env.exec_mode === \"cluster_mode\";\n    if (cluster) {\n      assertClusterSockets(input.socket);\n      if (env.wait_ready !== true || env.status !== \"online\") {\n        throw new Error(\n          \"Rolling reload requires an online cluster worker with wait_ready: true. Check its PM2 configuration and status.\",\n        );\n      }\n    }\n    targets.push({ id: process.pm_id, cluster });\n  }\n  if (targets.length === 0)\n    throw new Error(\n      `No PM2 process belonging to ${name} was found. Start its ecosystem file first.`,\n    );\n  if (new Set(targets.map((target) => target.id)).size !== targets.length) {\n    throw new Error(\"Duplicate PM2 ids in process list.\");\n  }\n  return targets;\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,53 @@
+import { command } from "../../commands/cli-command.mjs";
+import { pm2CommandAction } from "./pm2/pm2-command.action.mjs";
+
+//#region ../../packages/core/src/cli/commands/pm2.command.ts
+const pm2Command = command({
+	name: "pm2 <action>",
+	description: "Optional PM2 tooling: init an ecosystem file or reload only this app",
+	preload: {
+		warlockConfig: true,
+		config: [
+			"app",
+			"http",
+			"socket"
+		]
+	},
+	action: pm2CommandAction,
+	options: [
+		{
+			text: "--project",
+			type: "string",
+			description: "Project name (default: package.json name)"
+		},
+		{
+			text: "--app",
+			type: "string",
+			description: "App name (default: app.appName or app)"
+		},
+		{
+			text: "--cluster",
+			type: "boolean",
+			description: "init: use cluster mode (default: fork)"
+		},
+		{
+			text: "--instances",
+			type: "string",
+			description: "init with --cluster: worker count or max (default: 2)"
+		},
+		{
+			text: "--listen-timeout",
+			type: "string",
+			description: "init: readiness timeout in ms (default: 30000)"
+		},
+		{
+			text: "--id",
+			type: "string",
+			description: "reload: one PM2 id, verified to belong to this app"
+		}
+	]
+});
+
+//#endregion
+export { pm2Command };
+//# sourceMappingURL=pm2.command.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pm2.command.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/cli/commands/pm2.command.ts"],"sourcesContent":["import { command } from \"../../commands/cli-command\";\nimport { pm2CommandAction } from \"./pm2/pm2-command.action\";\n\nexport const pm2Command = command({\n  name: \"pm2 <action>\",\n  description: \"Optional PM2 tooling: init an ecosystem file or reload only this app\",\n  // Read config without running bootstrap, prestart or any connector.\n  preload: { warlockConfig: true, config: [\"app\", \"http\", \"socket\"] },\n  action: pm2CommandAction,\n  options: [\n    { text: \"--project\", type: \"string\", description: \"Project name (default: package.json name)\" },\n    { text: \"--app\", type: \"string\", description: \"App name (default: app.appName or app)\" },\n    { text: \"--cluster\", type: \"boolean\", description: \"init: use cluster mode (default: fork)\" },\n    {\n      text: \"--instances\",\n      type: \"string\",\n      description: \"init with --cluster: worker count or max (default: 2)\",\n    },\n    {\n      text: \"--listen-timeout\",\n      type: \"string\",\n      description: \"init: readiness timeout in ms (default: 30000)\",\n    },\n    {\n      text: \"--id\",\n      type: \"string\",\n      description: \"reload: one PM2 id, verified to belong to this app\",\n    },\n  ],\n});\n"],"mappings":";;;;AAGA,MAAa,aAAa,QAAQ;CAChC,MAAM;CACN,aAAa;CAEb,SAAS;EAAE,eAAe;EAAM,QAAQ;GAAC;GAAO;GAAQ;EAAQ;CAAE;CAClE,QAAQ;CACR,SAAS;EACP;GAAE,MAAM;GAAa,MAAM;GAAU,aAAa;EAA4C;EAC9F;GAAE,MAAM;GAAS,MAAM;GAAU,aAAa;EAAyC;EACvF;GAAE,MAAM;GAAa,MAAM;GAAW,aAAa;EAAyC;EAC5F;GACE,MAAM;GACN,MAAM;GACN,aAAa;EACf;EACA;GACE,MAAM;GACN,MAAM;GACN,aAAa;EACf;EACA;GACE,MAAM;GACN,MAAM;GACN,aAAa;EACf;CACF;AACF,CAAC"}

package/esm/cli/commands/postman-generator.action.mjs

@@ -43,5 +43,5 @@ async function generatePostmanAction({ options }) {
 }
 
 //#endregion
-export { generatePostmanAction };
+export { DEFAULT_POSTMAN_OUTPUT, generatePostmanAction };
 //# sourceMappingURL=postman-generator.action.mjs.map

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

@@ -3,7 +3,7 @@ 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

@@ -127,5 +127,5 @@ const testCommand = command({
 });
 
 //#endregion
-export { testCommand };
+export { buildVitestArguments, readTestCommandOptions, resolveProjectVitest, testCommand };
 //# sourceMappingURL=test.command.mjs.map

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

@@ -141,5 +141,5 @@ async function traceCommandAction({ args, options }) {
 }
 
 //#endregion
-export { traceCommandAction };
+export { collectHeaderValues, formatTraceSummary, parseHeaderValues, parseTraceBody, traceCommandAction, traceFailureExitCode };
 //# sourceMappingURL=trace-command.action.mjs.map

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

@@ -1,3 +1,4 @@
+import { aiCommand } from "./commands/ai.command.mjs";
 import { addCommand } from "./commands/add.command.mjs";
 import { agentsMdCommand } from "./commands/agents-md.command.mjs";
 import { boardCommand } from "./commands/board.command.mjs";
@@ -10,10 +11,12 @@ import { dropTablesCommand } from "./commands/drop-tables.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 { issueCommand } from "./commands/issue.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 { pm2Command } from "./commands/pm2.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";
@@ -32,11 +35,13 @@ const frameworkCommands = [
 	openApiGeneratorCommand,
 	postmanGeneratorCommand,
 	testCommand,
+	aiCommand,
 	doctorCommand,
 	routesCommand,
 	routesDiffCommand,
 	inspectCommand,
 	explainCommand,
+	issueCommand,
 	checkCommand,
 	typecheckCommand,
 	mcpCommand,
@@ -45,6 +50,7 @@ const frameworkCommands = [
 	boardCommand,
 	buildCommand,
 	startProductionCommand,
+	pm2Command,
 	migrateCommand,
 	seedCommand,
 	createDatabaseCommand,

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 { 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"}
+{"version":3,"file":"framework-cli-commands.mjs","names":[],"sources":["../../../../../../../../packages/core/src/cli/framework-cli-commands.ts"],"sourcesContent":["import { aiCommand } from \"./commands/ai.command\";\nimport { 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 { issueCommand } from \"./commands/issue.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 { pm2Command } from \"./commands/pm2.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  aiCommand,\n  doctorCommand,\n  routesCommand,\n  routesDiffCommand,\n  inspectCommand,\n  explainCommand,\n  issueCommand,\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  pm2Command,\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,MAAa,oBAAoB;CAE/B;CACA;CACA;CACA;CAGA;CAGA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CAGA;CACA;CACA;CACA;CAGA;CACA;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

@@ -18,12 +18,12 @@ var CliOptionValueError = class extends Error {
 		this.name = "CliOptionValueError";
 	}
 };
-const TRUE_VALUES = new Set([
+const TRUE_VALUES = /* @__PURE__ */ new Set([
 	"true",
 	"1",
 	"yes"
 ]);
-const FALSE_VALUES = new Set([
+const FALSE_VALUES = /* @__PURE__ */ new Set([
 	"false",
 	"0",
 	"no"