@warlock.js/core 5.30.0 → 5.31.0

package/bin/warlock.js

@@ -4,6 +4,41 @@ import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
+const [nodeMajor, nodeMinor] = process.versions.node.split(".").map(Number);
+if (nodeMajor < 22 || (nodeMajor === 22 && nodeMinor < 15)) {
+  console.error(`[warlock] requires Node 22.15 or newer (running ${process.versions.node}).`);
+  process.exit(1);
+}
+
+// Bun and Deno report the Node version they emulate in `process.versions.node`
+// and add their own entry, so the check above passes on both. `warlock dev` is
+// the one command that cannot run there (it is built on Node's module loader
+// hooks), and it is refused here, before anything loads, so the refusal reads
+// the same whether the CLI runs from published output or from source. The
+// `dev` command repeats this check for callers that bypass this file.
+const foreignRuntimeName = process.versions.bun
+  ? "Bun"
+  : process.versions.deno
+    ? "Deno"
+    : undefined;
+
+if (foreignRuntimeName && process.argv[2] === "dev") {
+  const foreignRuntime = `${foreignRuntimeName} ${process.versions.bun ?? process.versions.deno}`;
+  const start = process.versions.bun ? "bun dist/app.js" : "deno run -A dist/app.js";
+
+  console.error(
+    [
+      `✖ warlock dev runs on Node.js only — this process is ${foreignRuntime}.`,
+      "  The development server compiles TypeScript and hot-reloads modules through Node's module loader hooks.",
+      "  Run it with Node.js 22.15 or newer: npx warlock dev",
+      `  ${foreignRuntimeName} can run the production build: build it with Node (npx warlock build),`,
+      `  then start it with ${start}.`,
+      "  Supported runtimes: https://warlock.js.org/v/latest/core/digging-deeper/supported-runtimes/",
+    ].join("\n"),
+  );
+  process.exit(1);
+}
+
 const binDir = path.dirname(fileURLToPath(import.meta.url));
 
 /**
@@ -49,8 +84,19 @@ async function bootFromSource() {
   }
 
   const { registerHooks } = await import("node:module");
-  const { readFileSync } = await import("node:fs");
-  const { transformSync } = await import("esbuild");
+
+  // Bun has no `module.registerHooks`. Only a source checkout reaches this
+  // path (published packages ship compiled output), so say what is missing
+  // instead of failing on "registerHooks is not a function".
+  if (typeof registerHooks !== "function") {
+    console.error(
+      "[warlock] Running @warlock.js/core from TypeScript source needs Node's module.registerHooks " +
+        "(Node 22.15 or newer); this runtime does not provide it. Use Node, or install the published package.",
+    );
+    process.exit(1);
+  }
+
+  const { register } = await import("node:module");
   const { getTsconfig, resolvePathAlias } = await import("get-tsconfig");
 
   // Same target the dev loader and the production builder pin, so a file
@@ -58,8 +104,6 @@ async function bootFromSource() {
   // get anywhere else in the toolchain. Drifting from it would make the CLI a
   // third, subtly different dialect.
   const TRANSPILE_TARGET = "node22";
-  const TS_FILE = /\.(ts|tsx|mts|cts)$/;
-  const VERSION_QUERY = /\?v=\d+$/;
 
   // Read from cwd, not from core: `jsx`, `experimentalDecorators` and friends
   // are the *app's* call, and this is the same source of truth the dev
@@ -70,59 +114,44 @@ async function bootFromSource() {
   });
 
   /**
-   * Handover switch. Verified behaviour: in-thread hooks run *before*
-   * `register()` worker hooks and delegate down the chain. So once the dev
-   * server registers its own loader, these hooks would still intercept every
-   * `.ts` first and short-circuit — silently bypassing the dev loader's
-   * transpile cache and, worse, its `?v=N` HMR stamping.
+   * Handover switch for the in-thread `resolve` hook below. Verified
+   * behaviour: in-thread hooks run *before* `register()` worker hooks and
+   * delegate down the chain, so once the dev server registers its own loader
+   * this hook would still resolve every `.ts` first and short-circuit,
+   * bypassing the dev loader's `?v=N` HMR stamping.
    *
-   * Setting `active = false` makes both hooks pure pass-throughs, handing the
-   * TypeScript path over intact. `registerLoader()` should flip it just before
-   * it calls `register()`; until it does, these hooks stay in charge, which is
-   * the correct default for every non-dev command.
+   * Setting `active = false` makes it a pure pass-through. `registerLoader()`
+   * should flip it just before it calls `register()`; until it does, this
+   * hook stays in charge, which is the correct default for every non-dev
+   * command. (The `load` hook needs no switch: it is a worker hook, and the
+   * dev loader's worker hooks, registered later, run before it.)
    */
   const bootstrapLoader = { active: true };
   globalThis.__warlockBootstrapLoader = bootstrapLoader;
 
   /**
-   * `load` hook. In-thread (`registerHooks`) rather than the worker-thread
-   * `register()`, which is what lets stage 2 below exist at all: a worker hook
-   * could not hand a transpiled function back to this thread.
+   * `load` hook — transpiles TypeScript with esbuild. It runs on Node's
+   * loader worker thread (`register()`), NOT in this thread
+   * (`registerHooks()`): on Node 22.15 an in-thread `load` hook makes a
+   * CommonJS package that `require()`s a file which an ES module also imports
+   * receive that file's empty, not-yet-run `exports`, which crashed every
+   * booting command inside `dayjs.extend`. See `source-load-hook.mjs`.
    */
-  function load(url, context, nextLoad) {
-    const cleanUrl = url.replace(VERSION_QUERY, "");
-
-    // Not TypeScript → not ours. npm `.js`, `node:`, JSON all fall through.
-    if (!bootstrapLoader.active || !TS_FILE.test(cleanUrl)) return nextLoad(url, context);
-
-    const absolutePath = fileURLToPath(cleanUrl);
-    const { code } = transformSync(readFileSync(absolutePath, "utf8"), {
-      loader: absolutePath.endsWith(".tsx") ? "tsx" : "ts",
-      format: "esm",
-      target: TRANSPILE_TARGET,
-      sourcefile: absolutePath,
-      sourcemap: "inline",
-      tsconfigRaw,
-    });
-
-    return { format: "module", source: code, shortCircuit: true };
-  }
-
-  registerHooks({ load });
+  register(pathToFileURL(path.join(binDir, "source-load-hook.mjs")).href, {
+    data: { target: TRANSPILE_TARGET, tsconfigRaw },
+  });
 
   // Stage 2 — the reuse. With `load` live, core's own resolver can be pulled
   // in as TypeScript. It is imported by exact absolute path on purpose: it is
   // a leaf module whose only import is `node:url`, so it needs no extension
   // probing to load, which is precisely the thing we don't have yet.
-  const { ownResolve } = await import(
-    pathToFileURL(
-      path.join(binDir, "..", "src", "dev-server", "loader", "own-resolver.ts"),
-    ).href
+  const { ownResolve, probeFile } = await import(
+    pathToFileURL(path.join(binDir, "..", "src", "dev-server", "loader", "own-resolver.ts")).href
   );
 
   let pathsMatcher = null;
   if (tsconfig) {
-    pathsMatcher = specifier => resolvePathAlias(tsconfig, specifier);
+    pathsMatcher = (specifier) => resolvePathAlias(tsconfig, specifier);
   }
 
   /**
@@ -131,6 +160,14 @@ async function bootFromSource() {
    * `null` for (bare npm, `node:`, `file:`) falls through to Node's default,
    * which keeps `exports`/`node_modules` semantics intact.
    *
+   * One fallback on top: a bare subpath of a package consumed as source, such
+   * as `@warlock.js/core/net` (imported by `@warlock.js/ai`). Core declares no
+   * `exports` map in source form, so Node's default resolver lands on the
+   * `net/` directory and refuses it (`ERR_UNSUPPORTED_DIR_IMPORT`); the
+   * published package maps the subpath to its built entry instead. The
+   * directory's `index.ts` is what TypeScript and vitest resolve the same
+   * specifier to, so that is what this resolves it to as well.
+   *
    * The dev loader's version of this also stamps `?v=N` for HMR. That is
    * deliberately absent: the CLI process has no watcher, and the dev server
    * registers its own full loader when it boots.
@@ -143,7 +180,30 @@ async function bootFromSource() {
     // Producing the URL ourselves means `nextResolve` was never called, so the
     // chain has to be short-circuited explicitly or Node raises
     // ERR_LOADER_CHAIN_INCOMPLETE.
-    return owned ? { url: owned, shortCircuit: true } : nextResolve(specifier, context);
+    if (owned) return { url: owned, shortCircuit: true };
+
+    try {
+      return nextResolve(specifier, context);
+    } catch (error) {
+      const index = bootstrapLoader.active ? directoryIndexOf(error) : null;
+
+      if (index) return { url: index, shortCircuit: true };
+
+      throw error;
+    }
+  }
+
+  /**
+   * The `index.ts` (or `.tsx`/`.js`/`.jsx`) inside the directory Node refused
+   * to import, as a `file:` URL, or `null` when the error is anything else.
+   */
+  function directoryIndexOf(error) {
+    if (error?.code !== "ERR_UNSUPPORTED_DIR_IMPORT" || typeof error.url !== "string") return null;
+
+    const directory = fileURLToPath(error.url).replace(/\\/g, "/").replace(/\/$/, "");
+    const hit = probeFile(`${directory}/index`, existsSync);
+
+    return hit ? pathToFileURL(hit).href : null;
   }
 
   registerHooks({ resolve });

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

@@ -1,11 +1,12 @@
 import { command } from "../../commands/cli-command.mjs";
+import { generationOutputOptions, runGenerationCommand } from "../../generations/generation-run.mjs";
 import { addCommandAction } from "../../generations/add-command.action.mjs";
 
 //#region ../../packages/core/src/cli/commands/add.command.ts
 const addCommand = command({
 	name: "add <features...>",
 	description: "Add new feature(s) to the project",
-	action: addCommandAction,
+	action: (data) => runGenerationCommand("add", data, addCommandAction),
 	options: [
 		{
 			text: "--package-manager, -pm",
@@ -20,7 +21,8 @@ const addCommand = command({
 			text: "--no-install",
 			description: "Record dependencies in package.json without installing them — still ejects configs, adds scripts, and runs setup hooks. Used by scaffolders that run a single install afterwards.",
 			type: "boolean"
-		}
+		},
+		...generationOutputOptions
 	]
 });
 

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

@@ -1 +1 @@
-{"version":3,"file":"add.command.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/cli/commands/add.command.ts"],"sourcesContent":["import { addCommandAction } from \"../../generations/add-command.action\";\nimport { command } from \"../../commands/cli-command\";\n\nexport const addCommand = command({\n  name: \"add <features...>\",\n  description: \"Add new feature(s) to the project\",\n  action: addCommandAction,\n  options: [\n    {\n      text: \"--package-manager, -pm\",\n      description: \"Package manager to use, if not passed, it will be detected automatically\",\n    },\n    {\n      text: \"--list, -l\",\n      description: \"List available features\",\n      type: \"boolean\",\n    },\n    {\n      text: \"--no-install\",\n      description:\n        \"Record dependencies in package.json without installing them — still ejects configs, adds scripts, and runs setup hooks. Used by scaffolders that run a single install afterwards.\",\n      type: \"boolean\",\n    },\n  ],\n});\n"],"mappings":";;;;AAGA,MAAa,aAAa,QAAQ;CAChC,MAAM;CACN,aAAa;CACb,QAAQ;CACR,SAAS;EACP;GACE,MAAM;GACN,aAAa;EACf;EACA;GACE,MAAM;GACN,aAAa;GACb,MAAM;EACR;EACA;GACE,MAAM;GACN,aACE;GACF,MAAM;EACR;CACF;AACF,CAAC"}
+{"version":3,"file":"add.command.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/cli/commands/add.command.ts"],"sourcesContent":["import { addCommandAction } from \"../../generations/add-command.action\";\nimport { generationOutputOptions, runGenerationCommand } from \"../../generations/generation-run\";\nimport { command } from \"../../commands/cli-command\";\n\nexport const addCommand = command({\n  name: \"add <features...>\",\n  description: \"Add new feature(s) to the project\",\n  action: (data) => runGenerationCommand(\"add\", data, addCommandAction),\n  options: [\n    {\n      text: \"--package-manager, -pm\",\n      description: \"Package manager to use, if not passed, it will be detected automatically\",\n    },\n    {\n      text: \"--list, -l\",\n      description: \"List available features\",\n      type: \"boolean\",\n    },\n    {\n      text: \"--no-install\",\n      description:\n        \"Record dependencies in package.json without installing them — still ejects configs, adds scripts, and runs setup hooks. Used by scaffolders that run a single install afterwards.\",\n      type: \"boolean\",\n    },\n    ...generationOutputOptions,\n  ],\n});\n"],"mappings":";;;;;AAIA,MAAa,aAAa,QAAQ;CAChC,MAAM;CACN,aAAa;CACb,SAAS,SAAS,qBAAqB,OAAO,MAAM,gBAAgB;CACpE,SAAS;EACP;GACE,MAAM;GACN,aAAa;EACf;EACA;GACE,MAAM;GACN,aAAa;GACb,MAAM;EACR;EACA;GACE,MAAM;GACN,aACE;GACF,MAAM;EACR;EACA,GAAG;CACL;AACF,CAAC"}

package/esm/cli/commands/agents-md/agents-md-command.action.mjs

@@ -0,0 +1,69 @@
+import { AGENTS_MD_FILE } from "../../../tooling/agents-md/agents-md-markers.mjs";
+import { listInstalledSkills } from "../../../tooling/agents-md/installed-skills.mjs";
+import { listAppModules, renderAgentsMdSection } from "../../../tooling/agents-md/render-agents-md.mjs";
+import { writeAgentsMd } from "../../../tooling/agents-md/write-agents-md.mjs";
+import { bootForInspect, inspectOptionsFromBoot } from "../../../tooling/inspect/boot-for-inspect.mjs";
+import { inspectApp } from "../../../tooling/inspect/inspect-app.mjs";
+import { withConsoleOnStderr } from "../routes/with-console-on-stderr.mjs";
+import path from "node:path";
+
+//#region ../../packages/core/src/cli/commands/agents-md/agents-md-command.action.ts
+/** The inspect sections the generated section reads. */
+const AGENTS_MD_SECTIONS = [
+	"routes",
+	"models",
+	"packages"
+];
+/** The one line `warlock agents-md --write` prints. */
+function formatWriteStatus(result) {
+	const file = path.relative(process.cwd(), result.file) || "AGENTS.md";
+	switch (result.status) {
+		case "created": return `Created ${file} with the generated section.`;
+		case "updated": return `Updated the generated section of ${file}.`;
+		case "unchanged": return `${file} is up to date.`;
+		default: return `${file} does not exist; nothing written.`;
+	}
+}
+/**
+* Action behind `warlock agents-md`.
+*
+* Boots the app read-only (the inspect boot pass) with boot output on stderr,
+* then prints the section (no flag), writes it (`--write`) or prints
+* `{ file, status, section }` (`--json`; `status` is `"printed"` without
+* `--write`). Malformed markers throw `WL7501` and nothing is written.
+*
+* @param data Parsed CLI args: `options.write`, `options.json`.
+*/
+async function agentsMdCommandAction({ options }) {
+	const cwd = process.cwd();
+	const report = await inspectApp({
+		...inspectOptionsFromBoot(await withConsoleOnStderr(() => bootForInspect(cwd))),
+		cwd,
+		sections: AGENTS_MD_SECTIONS
+	});
+	if (options.write === true) {
+		const result = writeAgentsMd({
+			cwd,
+			report
+		});
+		console.log(options.json === true ? JSON.stringify(result, null, 2) : formatWriteStatus(result));
+		return;
+	}
+	const section = renderAgentsMdSection(report, {
+		skills: listInstalledSkills(cwd),
+		modules: listAppModules(cwd)
+	});
+	if (options.json === true) {
+		console.log(JSON.stringify({
+			file: path.join(cwd, AGENTS_MD_FILE),
+			status: "printed",
+			section
+		}, null, 2));
+		return;
+	}
+	process.stdout.write(section);
+}
+
+//#endregion
+export { agentsMdCommandAction };
+//# sourceMappingURL=agents-md-command.action.mjs.map

package/esm/cli/commands/agents-md/agents-md-command.action.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-md-command.action.mjs","names":[],"sources":["../../../../../../../../../../packages/core/src/cli/commands/agents-md/agents-md-command.action.ts"],"sourcesContent":["import path from \"node:path\";\nimport type { CommandActionData } from \"../../../commands/types\";\nimport { AGENTS_MD_FILE } from \"../../../tooling/agents-md/agents-md-markers\";\nimport { listInstalledSkills } from \"../../../tooling/agents-md/installed-skills\";\nimport { listAppModules, renderAgentsMdSection } from \"../../../tooling/agents-md/render-agents-md\";\nimport {\n  writeAgentsMd,\n  type WriteAgentsMdResult,\n} from \"../../../tooling/agents-md/write-agents-md\";\nimport { bootForInspect, inspectOptionsFromBoot } from \"../../../tooling/inspect/boot-for-inspect\";\nimport { inspectApp } from \"../../../tooling/inspect/inspect-app\";\nimport type { InspectSection } from \"../../../tooling/inspect/inspect-report.types\";\nimport { withConsoleOnStderr } from \"../routes/with-console-on-stderr\";\n\n/** The inspect sections the generated section reads. */\nexport const AGENTS_MD_SECTIONS: readonly InspectSection[] = [\"routes\", \"models\", \"packages\"];\n\n/** The one line `warlock agents-md --write` prints. */\nexport function formatWriteStatus(result: Pick<WriteAgentsMdResult, \"file\" | \"status\">): string {\n  const file = path.relative(process.cwd(), result.file) || AGENTS_MD_FILE;\n\n  switch (result.status) {\n    case \"created\":\n      return `Created ${file} with the generated section.`;\n    case \"updated\":\n      return `Updated the generated section of ${file}.`;\n    case \"unchanged\":\n      return `${file} is up to date.`;\n    default:\n      return `${file} does not exist; nothing written.`;\n  }\n}\n\n/**\n * Action behind `warlock agents-md`.\n *\n * Boots the app read-only (the inspect boot pass) with boot output on stderr,\n * then prints the section (no flag), writes it (`--write`) or prints\n * `{ file, status, section }` (`--json`; `status` is `\"printed\"` without\n * `--write`). Malformed markers throw `WL7501` and nothing is written.\n *\n * @param data Parsed CLI args: `options.write`, `options.json`.\n */\nexport async function agentsMdCommandAction({ options }: CommandActionData): Promise<void> {\n  const cwd = process.cwd();\n  const boot = await withConsoleOnStderr(() => bootForInspect(cwd));\n  const report = await inspectApp({\n    ...inspectOptionsFromBoot(boot),\n    cwd,\n    sections: AGENTS_MD_SECTIONS,\n  });\n\n  if (options.write === true) {\n    const result = writeAgentsMd({ cwd, report });\n\n    console.log(\n      options.json === true ? JSON.stringify(result, null, 2) : formatWriteStatus(result),\n    );\n    return;\n  }\n\n  const section = renderAgentsMdSection(report, {\n    skills: listInstalledSkills(cwd),\n    modules: listAppModules(cwd),\n  });\n\n  if (options.json === true) {\n    console.log(\n      JSON.stringify({ file: path.join(cwd, AGENTS_MD_FILE), status: \"printed\", section }, null, 2),\n    );\n    return;\n  }\n\n  process.stdout.write(section);\n}\n"],"mappings":";;;;;;;;;;;AAeA,MAAa,qBAAgD;CAAC;CAAU;CAAU;AAAU;;AAG5F,SAAgB,kBAAkB,QAA8D;CAC9F,MAAM,OAAO,KAAK,SAAS,QAAQ,IAAI,GAAG,OAAO,IAAI;CAErD,QAAQ,OAAO,QAAf;EACE,KAAK,WACH,OAAO,WAAW,KAAK;EACzB,KAAK,WACH,OAAO,oCAAoC,KAAK;EAClD,KAAK,aACH,OAAO,GAAG,KAAK;EACjB,SACE,OAAO,GAAG,KAAK;CACnB;AACF;;;;;;;;;;;AAYA,eAAsB,sBAAsB,EAAE,WAA6C;CACzF,MAAM,MAAM,QAAQ,IAAI;CAExB,MAAM,SAAS,MAAM,WAAW;EAC9B,GAAG,uBAAuB,MAFT,0BAA0B,eAAe,GAAG,CAAC,CAEhC;EAC9B;EACA,UAAU;CACZ,CAAC;CAED,IAAI,QAAQ,UAAU,MAAM;EAC1B,MAAM,SAAS,cAAc;GAAE;GAAK;EAAO,CAAC;EAE5C,QAAQ,IACN,QAAQ,SAAS,OAAO,KAAK,UAAU,QAAQ,MAAM,CAAC,IAAI,kBAAkB,MAAM,CACpF;EACA;CACF;CAEA,MAAM,UAAU,sBAAsB,QAAQ;EAC5C,QAAQ,oBAAoB,GAAG;EAC/B,SAAS,eAAe,GAAG;CAC7B,CAAC;CAED,IAAI,QAAQ,SAAS,MAAM;EACzB,QAAQ,IACN,KAAK,UAAU;GAAE,MAAM,KAAK,KAAK,KAAK,cAAc;GAAG,QAAQ;GAAW;EAAQ,GAAG,MAAM,CAAC,CAC9F;EACA;CACF;CAEA,QAAQ,OAAO,MAAM,OAAO;AAC9B"}

package/esm/cli/commands/agents-md.command.mjs

@@ -0,0 +1,38 @@
+import { command } from "../../commands/cli-command.mjs";
+import { agentsMdCommandAction } from "./agents-md/agents-md-command.action.mjs";
+
+//#region ../../packages/core/src/cli/commands/agents-md.command.ts
+/**
+* `warlock agents-md` — render the app-specific AGENTS.md section from the
+* booted app (modules, routes, models, conventions, installed skills, verify
+* commands). Prints it; `--write` puts it between the
+* `<!-- warlock:generated:start -->` / `end` markers of AGENTS.md, creating
+* the file when missing and never touching content outside the markers.
+*
+* Boots like `warlock inspect`: connectors boot but none starts, so no
+* connection opens and no port binds.
+*/
+const agentsMdCommand = command({
+	name: "agents-md",
+	description: "Generate the app-specific AGENTS.md section from the booted app; --write updates it between its markers",
+	action: agentsMdCommandAction,
+	preload: {
+		runtimeStrategy: "development",
+		config: true,
+		env: true,
+		bootstrap: true
+	},
+	options: [{
+		text: "--write, -w",
+		description: "Write the section into AGENTS.md between its markers (creates the file when missing)",
+		type: "boolean"
+	}, {
+		text: "--json, -j",
+		description: "Print { file, status, section } as JSON",
+		type: "boolean"
+	}]
+});
+
+//#endregion
+export { agentsMdCommand };
+//# sourceMappingURL=agents-md.command.mjs.map

package/esm/cli/commands/agents-md.command.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-md.command.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/cli/commands/agents-md.command.ts"],"sourcesContent":["import { command } from \"../../commands/cli-command\";\nimport { agentsMdCommandAction } from \"./agents-md/agents-md-command.action\";\n\n/**\n * `warlock agents-md` — render the app-specific AGENTS.md section from the\n * booted app (modules, routes, models, conventions, installed skills, verify\n * commands). Prints it; `--write` puts it between the\n * `<!-- warlock:generated:start -->` / `end` markers of AGENTS.md, creating\n * the file when missing and never touching content outside the markers.\n *\n * Boots like `warlock inspect`: connectors boot but none starts, so no\n * connection opens and no port binds.\n */\nexport const agentsMdCommand = command({\n  name: \"agents-md\",\n  description:\n    \"Generate the app-specific AGENTS.md section from the booted app; --write updates it between its markers\",\n  action: agentsMdCommandAction,\n  preload: {\n    runtimeStrategy: \"development\",\n    config: true,\n    env: true,\n    bootstrap: true,\n  },\n  options: [\n    {\n      text: \"--write, -w\",\n      description:\n        \"Write the section into AGENTS.md between its markers (creates the file when missing)\",\n      type: \"boolean\",\n    },\n    {\n      text: \"--json, -j\",\n      description: \"Print { file, status, section } as JSON\",\n      type: \"boolean\",\n    },\n  ],\n});\n"],"mappings":";;;;;;;;;;;;;;AAaA,MAAa,kBAAkB,QAAQ;CACrC,MAAM;CACN,aACE;CACF,QAAQ;CACR,SAAS;EACP,iBAAiB;EACjB,QAAQ;EACR,KAAK;EACL,WAAW;CACb;CACA,SAAS,CACP;EACE,MAAM;EACN,aACE;EACF,MAAM;CACR,GACA;EACE,MAAM;EACN,aAAa;EACb,MAAM;CACR,CACF;AACF,CAAC"}

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

@@ -0,0 +1,279 @@
+import { WarlockError } from "../../../errors/warlock-error.mjs";
+import { BOARD_STATES, BOARD_VERDICT_LINES, isBoardState, isBoardVerdict } from "../../../tooling/board/board.types.mjs";
+import { addBoardItem, initBoard, moveBoardItem, nextBoardStates, readBoardItem, readBoardStatus, sendBoardMessage, watchBoard } from "../../../tooling/board/board.mjs";
+import { flushAndExit } from "../../flush-and-exit.mjs";
+import path from "node:path";
+import { readFileSync } from "node:fs";
+
+//#region ../../packages/core/src/cli/commands/board/board-command.action.ts
+/** The exit code of `warlock board watch` when it times out. */
+const BOARD_WATCH_TIMEOUT_EXIT_CODE = 3;
+/** The sub-commands of `warlock board`. */
+const BOARD_ACTIONS = [
+	"init",
+	"add",
+	"status",
+	"send",
+	"watch"
+];
+function stringOption(options, key) {
+	const value = options[key];
+	if (typeof value === "number") return String(value);
+	return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+function parseId(value, label) {
+	const id = value === void 0 ? NaN : Number(value);
+	if (!Number.isInteger(id) || id < 1) throw new Error(`${label} must be a positive whole number, got ${JSON.stringify(value)}.`);
+	return id;
+}
+/** `--body text` as is; `--body @notes.md` reads the file (relative to `cwd`). */
+function readBodyOption(value, cwd) {
+	if (value === void 0) return "";
+	return value.startsWith("@") ? readFileSync(path.resolve(cwd, value.slice(1)), "utf8") : value;
+}
+/** The current agent: the explicit option, else `WARLOCK_AGENT`, else `null`. */
+function agentOf(options, key, environment) {
+	return stringOption(options, key) ?? environment.WARLOCK_AGENT ?? null;
+}
+/**
+* Turn `warlock board <action> [args...]` into a {@link BoardInvocation}.
+* Throws on an unknown action, a missing argument or an invalid value.
+*
+* @param args Positionals after `board`: the action first.
+* @param options Parsed flags.
+* @param cwd Where `--body @file` resolves.
+* @param environment Where `WARLOCK_AGENT` is read.
+*/
+function parseBoardInvocation(args, options, cwd = process.cwd(), environment = process.env) {
+	const [action, ...rest] = args;
+	switch (action) {
+		case "init": return { type: "init" };
+		case "add": {
+			const title = rest.join(" ").trim();
+			if (title.length === 0) throw new Error("Usage: warlock board add \"<title>\" [--assignee a --reviewer b]");
+			return {
+				type: "add",
+				title,
+				assignee: stringOption(options, "assignee") ?? null,
+				reviewer: stringOption(options, "reviewer") ?? null,
+				by: agentOf(options, "by", environment)
+			};
+		}
+		case "status": {
+			const [idText, state] = rest;
+			if (idText === void 0) return { type: "overview" };
+			const id = parseId(idText, "The item id");
+			if (state === void 0) return {
+				type: "item",
+				id
+			};
+			if (!isBoardState(state)) throw new Error(`Unknown state ${JSON.stringify(state)}. States: ${BOARD_STATES.join(", ")}.`);
+			return {
+				type: "move",
+				id,
+				state,
+				by: agentOf(options, "by", environment),
+				note: stringOption(options, "note") ?? null
+			};
+		}
+		case "send": {
+			const [to, ...subjectWords] = rest;
+			const subject = subjectWords.join(" ").trim();
+			if (to === void 0 || subject.length === 0) throw new Error("Usage: warlock board send <agent> \"<subject>\" --from <agent> [--item id --body text|@file --verdict approved|changes-requested]");
+			const from = agentOf(options, "from", environment);
+			if (from === null) throw new Error("Name the sender with --from <agent> (or set WARLOCK_AGENT).");
+			const verdict = stringOption(options, "verdict");
+			if (verdict !== void 0 && !isBoardVerdict(verdict)) throw new Error(`--verdict must be "approved" or "changes-requested", got ${JSON.stringify(verdict)}.`);
+			const item = stringOption(options, "item");
+			return {
+				type: "send",
+				to,
+				from,
+				subject,
+				body: readBodyOption(stringOption(options, "body"), cwd),
+				item: item === void 0 ? null : parseId(item, "--item"),
+				verdict: verdict ?? null
+			};
+		}
+		case "watch": {
+			const [agent] = rest;
+			if (agent === void 0) throw new Error("Usage: warlock board watch <agent> [--timeout seconds --since N]");
+			const timeout = stringOption(options, "timeout");
+			const seconds = timeout === void 0 ? 600 : Number(timeout);
+			if (!Number.isFinite(seconds) || seconds <= 0) throw new Error(`--timeout must be a positive number of seconds, got ${JSON.stringify(timeout)}.`);
+			const since = stringOption(options, "since");
+			const sinceNumber = since === void 0 ? void 0 : Number(since);
+			if (sinceNumber !== void 0 && (!Number.isInteger(sinceNumber) || sinceNumber < 0)) throw new Error(`--since must be a whole number, got ${JSON.stringify(since)}.`);
+			return {
+				type: "watch",
+				agent,
+				timeoutMs: Math.round(seconds * 1e3),
+				since: sinceNumber
+			};
+		}
+		default: throw new Error(`Unknown board action ${JSON.stringify(action ?? "")}. Actions: ${BOARD_ACTIONS.join(", ")}.`);
+	}
+}
+/** `#3 [in-progress] Add the orders module  (implementer → reviewer)` */
+function formatBoardItemLine(item) {
+	const people = item.assignee || item.reviewer ? `  (${item.assignee ?? "-"} → ${item.reviewer ?? "-"})` : "";
+	return `#${item.id} [${item.state}] ${item.title}${people}`;
+}
+function formatMessage(message) {
+	const about = message.item === null ? "" : ` (item #${message.item})`;
+	return [
+		`── ${message.file}`,
+		`From ${message.from}${about}: ${message.subject}`,
+		...message.body.length > 0 ? ["", message.body] : [],
+		...message.verdict ? ["", BOARD_VERDICT_LINES[message.verdict]] : [],
+		""
+	];
+}
+/** Run one parsed invocation against the board in `cwd`. Throws `WarlockError`s with WL74xx codes. */
+async function runBoardInvocation(invocation, cwd = process.cwd()) {
+	switch (invocation.type) {
+		case "init": {
+			const result = initBoard(cwd);
+			return {
+				json: {
+					ok: true,
+					...result
+				},
+				lines: [result.created ? `Created ${result.directory}/` : `${result.directory}/ already exists`, ...result.gitignoreUpdated ? [`Added ${result.directory}/ to .gitignore`] : []],
+				exitCode: 0
+			};
+		}
+		case "add": {
+			const item = addBoardItem({
+				title: invocation.title,
+				assignee: invocation.assignee,
+				reviewer: invocation.reviewer,
+				by: invocation.by
+			}, cwd);
+			return {
+				json: {
+					ok: true,
+					item
+				},
+				lines: [`Added ${formatBoardItemLine(item)}`],
+				exitCode: 0
+			};
+		}
+		case "overview": {
+			const status = readBoardStatus(cwd);
+			const lines = status.items.length === 0 ? ["No items. Add one with `warlock board add \"<title>\"`."] : status.items.map(formatBoardItemLine);
+			if (status.inboxes.length > 0) {
+				lines.push("", "Inboxes:");
+				for (const inbox of status.inboxes) lines.push(`  ${inbox.agent.padEnd(16)} ${inbox.messages} message(s), ${inbox.unread} unread`);
+			}
+			return {
+				json: {
+					ok: true,
+					...status
+				},
+				lines,
+				exitCode: 0
+			};
+		}
+		case "item": {
+			const item = readBoardItem(invocation.id, cwd);
+			const next = nextBoardStates(item.state);
+			return {
+				json: {
+					ok: true,
+					item,
+					next
+				},
+				lines: [
+					formatBoardItemLine(item),
+					`  next: ${next.join(", ")}`,
+					...item.history.map((entry) => `  ${entry.at}  ${entry.from ?? "∅"} → ${entry.to}${entry.by ? ` by ${entry.by}` : ""}${entry.note ? ` — ${entry.note}` : ""}`)
+				],
+				exitCode: 0
+			};
+		}
+		case "move": {
+			const item = moveBoardItem(invocation.id, invocation.state, {
+				by: invocation.by,
+				note: invocation.note
+			}, cwd);
+			return {
+				json: {
+					ok: true,
+					item
+				},
+				lines: [`Moved ${formatBoardItemLine(item)}`],
+				exitCode: 0
+			};
+		}
+		case "send": {
+			const result = sendBoardMessage({
+				to: invocation.to,
+				from: invocation.from,
+				subject: invocation.subject,
+				body: invocation.body,
+				item: invocation.item,
+				verdict: invocation.verdict
+			}, cwd);
+			return {
+				json: {
+					ok: true,
+					...result
+				},
+				lines: [`Wrote ${result.message.file}`, ...result.item ? [`Moved ${formatBoardItemLine(result.item)}`] : []],
+				exitCode: 0
+			};
+		}
+		case "watch": {
+			const result = await watchBoard({
+				agent: invocation.agent,
+				timeoutMs: invocation.timeoutMs,
+				since: invocation.since
+			}, cwd);
+			return {
+				json: {
+					ok: true,
+					timedOut: false,
+					...result
+				},
+				lines: result.messages.flatMap(formatMessage),
+				exitCode: 0
+			};
+		}
+	}
+}
+/**
+* Action behind `warlock board <action> [args...]`.
+*
+* With `--json`, stdout carries exactly one JSON object — `{ ok: true, … }`, or
+* `{ ok: false, code, message }` for a coded failure (`timedOut: true` for a
+* watch timeout). Exit codes: 0 done, 1 refused or invalid, 3 watch timed out.
+*
+* @param data Parsed CLI args: the action and its positionals, and the flags.
+*/
+async function boardCommandAction({ args, options }) {
+	const json = options.json === true;
+	try {
+		const outcome = await runBoardInvocation(parseBoardInvocation(args, options));
+		if (json) console.log(JSON.stringify(outcome.json, null, 2));
+		else for (const line of outcome.lines) console.log(line);
+		if (outcome.exitCode !== 0) await flushAndExit(outcome.exitCode);
+	} catch (error) {
+		const timedOut = error instanceof WarlockError && error.code === "WL7404";
+		const exitCode = timedOut ? 3 : 1;
+		if (!json && !timedOut) throw error;
+		const message = error instanceof Error ? error.message : String(error);
+		if (json) console.log(JSON.stringify({
+			ok: false,
+			code: error instanceof WarlockError ? error.code : null,
+			message,
+			...timedOut ? { timedOut: true } : {}
+		}, null, 2));
+		else console.error(message);
+		await flushAndExit(exitCode);
+	}
+}
+
+//#endregion
+export { boardCommandAction };
+//# sourceMappingURL=board-command.action.mjs.map