@warlock.js/core 5.30.0 → 5.32.0

package/esm/tooling/mcp/docs-search.mjs

@@ -0,0 +1,178 @@
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import glob from "fast-glob";
+
+//#region ../../packages/core/src/tooling/mcp/docs-search.ts
+/**
+* Offline search over the documentation the app has INSTALLED: every
+* `@warlock.js/*` package's skills (`skills/**\/*.md`), `README.md` and
+* `llms.txt` / `llms-full.txt`. Nothing is fetched, so the answers match the
+* versions in `node_modules`, not whatever the website documents today.
+*/
+/** The globs, relative to the project root, that make up the corpus. */
+const DOCS_CORPUS_GLOBS = [
+	"node_modules/@warlock.js/*/skills/**/*.md",
+	"node_modules/@warlock.js/*/README.md",
+	"node_modules/@warlock.js/*/llms.txt",
+	"node_modules/@warlock.js/*/llms-full.txt"
+];
+const HEADING = /^(#{1,4})\s+(.+?)\s*#*\s*$/;
+const MAX_EXCERPT = 1200;
+function sourceOf(file) {
+	if (file.includes("/skills/")) return "skill";
+	return path.basename(file).toLowerCase() === "readme.md" ? "readme" : "llms";
+}
+function packageOf(file) {
+	return /node_modules\/(@warlock\.js\/[^/]+)\//.exec(file)?.[1] ?? "@warlock.js";
+}
+/** Split markdown text into heading-delimited sections. */
+function splitSections(text, meta) {
+	const sections = [];
+	const lines = text.split(/\r?\n/);
+	let heading = path.basename(meta.file);
+	let start = 1;
+	let buffer = [];
+	let inFence = false;
+	const flush = () => {
+		const body = buffer.join("\n").trim();
+		if (body.length > 0) sections.push({
+			...meta,
+			heading,
+			line: start,
+			text: body
+		});
+	};
+	lines.forEach((line, index) => {
+		if (line.trimStart().startsWith("```")) inFence = !inFence;
+		const match = inFence ? null : HEADING.exec(line);
+		if (match?.[2]) {
+			flush();
+			heading = match[2];
+			start = index + 1;
+			buffer = [line];
+			return;
+		}
+		buffer.push(line);
+	});
+	flush();
+	return sections;
+}
+/** Load the corpus of the app at `cwd`. Unreadable files are skipped. */
+async function loadDocsCorpus(cwd) {
+	const files = (await glob([...DOCS_CORPUS_GLOBS], {
+		cwd,
+		onlyFiles: true,
+		followSymbolicLinks: true
+	})).sort();
+	const sections = [];
+	for (const file of files) {
+		let text;
+		try {
+			text = readFileSync(path.join(cwd, file), "utf8");
+		} catch {
+			continue;
+		}
+		sections.push(...splitSections(text, {
+			package: packageOf(file),
+			file,
+			source: sourceOf(file)
+		}));
+	}
+	return {
+		files,
+		sections
+	};
+}
+/** Lower-cased search terms of two or more characters. */
+function searchTerms(query) {
+	return [...new Set(query.toLowerCase().split(/[^a-z0-9_.@/-]+/).map((term) => term.replace(/^[.\-/]+|[.\-/]+$/g, "")).filter((term) => term.length >= 2))];
+}
+function occurrences(haystack, needle) {
+	let count = 0;
+	let index = haystack.indexOf(needle);
+	while (index !== -1) {
+		count++;
+		index = haystack.indexOf(needle, index + needle.length);
+	}
+	return count;
+}
+function excerptOf(section, terms) {
+	const lines = section.text.split("\n");
+	const first = Math.max(0, lines.findIndex((line) => terms.some((term) => line.toLowerCase().includes(term))));
+	const from = Math.max(0, first - 3);
+	const excerpt = lines.slice(from, from + 18).join("\n");
+	return excerpt.length > MAX_EXCERPT ? `${excerpt.slice(0, MAX_EXCERPT)}…` : excerpt;
+}
+/**
+* Rank sections for a query: every term found in the heading counts 5, in the
+* body 1 per occurrence (capped), and each distinct term found adds 10, so a
+* section matching all terms beats one repeating a single term. Skills rank
+* above READMEs above llms files on equal scores; the generated `llms-full.txt`
+* repeats the skills, so it is weighted down.
+*/
+function searchDocs(corpus, query, options = {}) {
+	const terms = searchTerms(query);
+	if (terms.length === 0) return [];
+	const limit = options.limit ?? 8;
+	const sourceRank = {
+		skill: 0,
+		readme: 1,
+		llms: 2
+	};
+	const hits = [];
+	for (const section of corpus.sections) {
+		if (options.package && section.package !== options.package) continue;
+		const heading = section.heading.toLowerCase();
+		const body = section.text.toLowerCase();
+		let score = 0;
+		let matched = 0;
+		for (const term of terms) {
+			const inHeading = heading.includes(term);
+			const inBody = Math.min(occurrences(body, term), 10);
+			if (inHeading || inBody > 0) matched++;
+			score += (inHeading ? 5 : 0) + inBody;
+		}
+		if (matched === 0) continue;
+		score += matched * 10;
+		if (section.file.endsWith("llms-full.txt")) score = Math.floor(score / 2);
+		hits.push({
+			package: section.package,
+			file: section.file,
+			source: section.source,
+			heading: section.heading,
+			line: section.line,
+			score,
+			excerpt: excerptOf(section, terms)
+		});
+	}
+	return hits.sort((first, second) => second.score - first.score || sourceRank[first.source] - sourceRank[second.source] || first.file.localeCompare(second.file) || first.line - second.line).slice(0, limit);
+}
+/**
+* Read one corpus file (optionally one section of it). Only files of the
+* corpus can be read, so the tool never becomes a general file reader.
+*
+* @returns `undefined` when `file` is not in the corpus.
+*/
+function readDocsFile(corpus, cwd, file, options = {}) {
+	const normalized = file.split(path.sep).join("/").replace(/^\.\//, "");
+	if (!corpus.files.includes(normalized)) return void 0;
+	let text;
+	if (options.heading) {
+		const wanted = options.heading.toLowerCase();
+		const section = corpus.sections.find((candidate) => candidate.file === normalized && candidate.heading.toLowerCase() === wanted);
+		if (!section) return void 0;
+		text = section.text;
+	} else text = readFileSync(path.join(cwd, normalized), "utf8");
+	const maxBytes = options.maxBytes ?? 1e5;
+	const truncated = text.length > maxBytes;
+	return {
+		file: normalized,
+		heading: options.heading ?? null,
+		text: truncated ? text.slice(0, maxBytes) : text,
+		truncated
+	};
+}
+
+//#endregion
+export { DOCS_CORPUS_GLOBS, loadDocsCorpus, readDocsFile, searchDocs, searchTerms, splitSections };
+//# sourceMappingURL=docs-search.mjs.map

package/esm/tooling/mcp/docs-search.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-search.mjs","names":["fg"],"sources":["../../../../../../../../../packages/core/src/tooling/mcp/docs-search.ts"],"sourcesContent":["import fg from \"fast-glob\";\nimport { readFileSync } from \"node:fs\";\nimport path from \"node:path\";\n\n/**\n * Offline search over the documentation the app has INSTALLED: every\n * `@warlock.js/*` package's skills (`skills/**\\/*.md`), `README.md` and\n * `llms.txt` / `llms-full.txt`. Nothing is fetched, so the answers match the\n * versions in `node_modules`, not whatever the website documents today.\n */\n\n/** The globs, relative to the project root, that make up the corpus. */\nexport const DOCS_CORPUS_GLOBS = [\n  \"node_modules/@warlock.js/*/skills/**/*.md\",\n  \"node_modules/@warlock.js/*/README.md\",\n  \"node_modules/@warlock.js/*/llms.txt\",\n  \"node_modules/@warlock.js/*/llms-full.txt\",\n] as const;\n\n/** One searchable section: a file split at its markdown headings. */\nexport type DocsSection = {\n  /** `@warlock.js/<name>`. */\n  package: string;\n  /** Project-relative POSIX path of the file. */\n  file: string;\n  /** `skill`, `readme` or `llms`. */\n  source: \"skill\" | \"readme\" | \"llms\";\n  /** The section heading, or the file name for text before the first heading. */\n  heading: string;\n  /** 1-based line where the section starts. */\n  line: number;\n  text: string;\n};\n\n/** One search hit. */\nexport type DocsSearchHit = {\n  package: string;\n  file: string;\n  source: DocsSection[\"source\"];\n  heading: string;\n  line: number;\n  score: number;\n  /** The section's lines around the first match, bounded. */\n  excerpt: string;\n};\n\n/** The loaded corpus. */\nexport type DocsCorpus = {\n  files: string[];\n  sections: DocsSection[];\n};\n\nconst HEADING = /^(#{1,4})\\s+(.+?)\\s*#*\\s*$/;\nconst MAX_EXCERPT = 1200;\n\nfunction sourceOf(file: string): DocsSection[\"source\"] {\n  if (file.includes(\"/skills/\")) return \"skill\";\n\n  return path.basename(file).toLowerCase() === \"readme.md\" ? \"readme\" : \"llms\";\n}\n\nfunction packageOf(file: string): string {\n  const match = /node_modules\\/(@warlock\\.js\\/[^/]+)\\//.exec(file);\n\n  return match?.[1] ?? \"@warlock.js\";\n}\n\n/** Split markdown text into heading-delimited sections. */\nexport function splitSections(\n  text: string,\n  meta: { package: string; file: string; source: DocsSection[\"source\"] },\n): DocsSection[] {\n  const sections: DocsSection[] = [];\n  const lines = text.split(/\\r?\\n/);\n  let heading = path.basename(meta.file);\n  let start = 1;\n  let buffer: string[] = [];\n  let inFence = false;\n\n  const flush = () => {\n    const body = buffer.join(\"\\n\").trim();\n\n    if (body.length > 0) sections.push({ ...meta, heading, line: start, text: body });\n  };\n\n  lines.forEach((line, index) => {\n    if (line.trimStart().startsWith(\"```\")) inFence = !inFence;\n\n    const match = inFence ? null : HEADING.exec(line);\n\n    if (match?.[2]) {\n      flush();\n      heading = match[2];\n      start = index + 1;\n      buffer = [line];\n      return;\n    }\n\n    buffer.push(line);\n  });\n\n  flush();\n\n  return sections;\n}\n\n/** Load the corpus of the app at `cwd`. Unreadable files are skipped. */\nexport async function loadDocsCorpus(cwd: string): Promise<DocsCorpus> {\n  const files = (\n    await fg([...DOCS_CORPUS_GLOBS], { cwd, onlyFiles: true, followSymbolicLinks: true })\n  ).sort();\n  const sections: DocsSection[] = [];\n\n  for (const file of files) {\n    let text: string;\n\n    try {\n      text = readFileSync(path.join(cwd, file), \"utf8\");\n    } catch {\n      continue;\n    }\n\n    sections.push(\n      ...splitSections(text, { package: packageOf(file), file, source: sourceOf(file) }),\n    );\n  }\n\n  return { files, sections };\n}\n\n/** Lower-cased search terms of two or more characters. */\nexport function searchTerms(query: string): string[] {\n  return [\n    ...new Set(\n      query\n        .toLowerCase()\n        .split(/[^a-z0-9_.@/-]+/)\n        .map((term) => term.replace(/^[.\\-/]+|[.\\-/]+$/g, \"\"))\n        .filter((term) => term.length >= 2),\n    ),\n  ];\n}\n\nfunction occurrences(haystack: string, needle: string): number {\n  let count = 0;\n  let index = haystack.indexOf(needle);\n\n  while (index !== -1) {\n    count++;\n    index = haystack.indexOf(needle, index + needle.length);\n  }\n\n  return count;\n}\n\nfunction excerptOf(section: DocsSection, terms: readonly string[]): string {\n  const lines = section.text.split(\"\\n\");\n  const first = Math.max(\n    0,\n    lines.findIndex((line) => terms.some((term) => line.toLowerCase().includes(term))),\n  );\n  const from = Math.max(0, first - 3);\n  const excerpt = lines.slice(from, from + 18).join(\"\\n\");\n\n  return excerpt.length > MAX_EXCERPT ? `${excerpt.slice(0, MAX_EXCERPT)}…` : excerpt;\n}\n\n/**\n * Rank sections for a query: every term found in the heading counts 5, in the\n * body 1 per occurrence (capped), and each distinct term found adds 10, so a\n * section matching all terms beats one repeating a single term. Skills rank\n * above READMEs above llms files on equal scores; the generated `llms-full.txt`\n * repeats the skills, so it is weighted down.\n */\nexport function searchDocs(\n  corpus: DocsCorpus,\n  query: string,\n  options: { limit?: number; package?: string } = {},\n): DocsSearchHit[] {\n  const terms = searchTerms(query);\n\n  if (terms.length === 0) return [];\n\n  const limit = options.limit ?? 8;\n  const sourceRank: Record<DocsSection[\"source\"], number> = { skill: 0, readme: 1, llms: 2 };\n  const hits: DocsSearchHit[] = [];\n\n  for (const section of corpus.sections) {\n    if (options.package && section.package !== options.package) continue;\n\n    const heading = section.heading.toLowerCase();\n    const body = section.text.toLowerCase();\n    let score = 0;\n    let matched = 0;\n\n    for (const term of terms) {\n      const inHeading = heading.includes(term);\n      const inBody = Math.min(occurrences(body, term), 10);\n\n      if (inHeading || inBody > 0) matched++;\n\n      score += (inHeading ? 5 : 0) + inBody;\n    }\n\n    if (matched === 0) continue;\n\n    score += matched * 10;\n\n    if (section.file.endsWith(\"llms-full.txt\")) score = Math.floor(score / 2);\n\n    hits.push({\n      package: section.package,\n      file: section.file,\n      source: section.source,\n      heading: section.heading,\n      line: section.line,\n      score,\n      excerpt: excerptOf(section, terms),\n    });\n  }\n\n  return hits\n    .sort(\n      (first, second) =>\n        second.score - first.score ||\n        sourceRank[first.source] - sourceRank[second.source] ||\n        first.file.localeCompare(second.file) ||\n        first.line - second.line,\n    )\n    .slice(0, limit);\n}\n\n/**\n * Read one corpus file (optionally one section of it). Only files of the\n * corpus can be read, so the tool never becomes a general file reader.\n *\n * @returns `undefined` when `file` is not in the corpus.\n */\nexport function readDocsFile(\n  corpus: DocsCorpus,\n  cwd: string,\n  file: string,\n  options: { heading?: string; maxBytes?: number } = {},\n): { file: string; heading: string | null; text: string; truncated: boolean } | undefined {\n  const normalized = file.split(path.sep).join(\"/\").replace(/^\\.\\//, \"\");\n\n  if (!corpus.files.includes(normalized)) return undefined;\n\n  let text: string;\n\n  if (options.heading) {\n    const wanted = options.heading.toLowerCase();\n    const section = corpus.sections.find(\n      (candidate) => candidate.file === normalized && candidate.heading.toLowerCase() === wanted,\n    );\n\n    if (!section) return undefined;\n\n    text = section.text;\n  } else {\n    text = readFileSync(path.join(cwd, normalized), \"utf8\");\n  }\n\n  const maxBytes = options.maxBytes ?? 100_000;\n  const truncated = text.length > maxBytes;\n\n  return {\n    file: normalized,\n    heading: options.heading ?? null,\n    text: truncated ? text.slice(0, maxBytes) : text,\n    truncated,\n  };\n}\n"],"mappings":"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"}

package/esm/tooling/mcp/index.mjs

@@ -0,0 +1,9 @@
+import { DOCS_CORPUS_GLOBS, loadDocsCorpus, readDocsFile, searchDocs, searchTerms, splitSections } from "./docs-search.mjs";
+import { createMcpContext } from "./create-mcp-context.mjs";
+import { MCP_INSTALL_HINT, isAiToolsServeModule, loadAiToolsServe } from "./load-ai-tools.mjs";
+import { buildDbSchema } from "./db-schema.mjs";
+import { inputSchema, toStandardSchema, validateToolInput } from "./tool-input.mjs";
+import { MCP_MAKE_GENERATORS, createWarlockMcpTools, describeToolError, makeSpecFromInput } from "./mcp-tools.mjs";
+import { isLoopbackHost, resolveMcpTransport, startWarlockMcpServer, toServeContract } from "./start-mcp-server.mjs";
+
+export { DOCS_CORPUS_GLOBS, MCP_INSTALL_HINT, MCP_MAKE_GENERATORS, buildDbSchema, createMcpContext, createWarlockMcpTools, describeToolError, inputSchema, isAiToolsServeModule, isLoopbackHost, loadAiToolsServe, loadDocsCorpus, makeSpecFromInput, readDocsFile, resolveMcpTransport, searchDocs, searchTerms, splitSections, startWarlockMcpServer, toServeContract, toStandardSchema, validateToolInput };

package/esm/tooling/mcp/load-ai-tools.d.mts

@@ -0,0 +1,61 @@
+//#region ../../packages/core/src/tooling/mcp/load-ai-tools.d.ts
+/** The install line printed when the MCP transport packages are missing. */
+export declare const MCP_INSTALL_HINT = "npm install -D @warlock.js/ai-tools @warlock.js/ai";
+/** The tool shape `ai.mcp.serve` consumes, built structurally (see `@warlock.js/ai`'s `ToolContract`). */
+export type ServeToolContract = {
+  name: string;
+  description: string;
+  input: unknown;
+  execute(input: Record<string, unknown>): Promise<unknown>;
+  invoke(raw: unknown, context?: unknown): Promise<{
+    data?: unknown;
+    error?: Error;
+    usage: {
+      input: number;
+      output: number;
+      total: number;
+    };
+    report: Record<string, unknown>;
+  }>;
+};
+/** The transport options of `ai.mcp.serve` this command uses. */
+export type ServeTransportOptions = {
+  type: "stdio";
+} | {
+  type: "http";
+  host: string;
+  port: number;
+  path: string;
+  auth?: {
+    bearer: string;
+  };
+};
+/** The handle `start()` resolves. */
+export type ServeHandle = {
+  url?: string;
+  close(): Promise<void>;
+};
+/** The slice of `@warlock.js/ai-tools` this command calls. */
+export type AiToolsServeModule = {
+  serve(tools: ServeToolContract[], options: {
+    name: string;
+    version?: string;
+    transport: ServeTransportOptions;
+  }): {
+    start(): Promise<ServeHandle>;
+    stop(): Promise<void>;
+  };
+};
+/** Whether a loaded module exposes `serve()`. */
+export declare function isAiToolsServeModule(value: unknown): value is AiToolsServeModule;
+/**
+ * Import `@warlock.js/ai-tools` lazily — it is an optional peer, so a project
+ * that never runs `warlock mcp` does not need it. Tries core's own resolution
+ * first (pnpm links installed peers next to core), then the app's.
+ *
+ * Throws `WL7003` with the install line when it (or `@warlock.js/ai`, which
+ * it imports) is missing.
+ */
+export declare function loadAiToolsServe(cwd: string, importer?: (specifier: string) => Promise<unknown>): Promise<AiToolsServeModule>;
+//#endregion
+//# sourceMappingURL=load-ai-tools.d.mts.map

package/esm/tooling/mcp/load-ai-tools.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-ai-tools.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/mcp/load-ai-tools.ts"],"mappings":";;qBAMa;;YAGD;EACV;EACA;EACA;EACA,QAAQ,OAAO,0BAA0B;EACzC,OACE,cACA,oBACC;IACD;IACA,QAAQ;IACR;MAAS;MAAe;MAAgB;;IACxC,QAAQ;;;;YAKA;EACN;;EAEA;EACA;EACA;EACA;EACA;IAAS;;;;YAIH;EAAgB;EAAc,SAAS;;;YAGvC;EACV,MACE,OAAO,qBACP;IAAW;IAAc;IAAkB,WAAW;;IACnD,SAAS,QAAQ;IAAc,QAAQ;;;;wBAI9B,qBAAqB,iBAAiB,SAAS;;;;;;;;;wBA4BzC,iBACpB,aACA,YAAW,sBAAsB,mBAChC,QAAQ"}

package/esm/tooling/mcp/load-ai-tools.mjs

@@ -0,0 +1,45 @@
+import { WarlockError } from "../../errors/warlock-error.mjs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { resolve as resolve$1 } from "import-meta-resolve";
+
+//#region ../../packages/core/src/tooling/mcp/load-ai-tools.ts
+/** The install line printed when the MCP transport packages are missing. */
+const MCP_INSTALL_HINT = "npm install -D @warlock.js/ai-tools @warlock.js/ai";
+/** Whether a loaded module exposes `serve()`. */
+function isAiToolsServeModule(value) {
+	return typeof value === "object" && value !== null && typeof Reflect.get(value, "serve") === "function";
+}
+function isMissingModule(error, names) {
+	if (typeof error !== "object" || error === null) return false;
+	const code = Reflect.get(error, "code");
+	const message = error instanceof Error ? error.message : "";
+	return (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") && names.some((name) => message.includes(`'${name}'`) || message.includes(`"${name}"`));
+}
+const PACKAGES = ["@warlock.js/ai-tools", "@warlock.js/ai"];
+/**
+* Import `@warlock.js/ai-tools` lazily — it is an optional peer, so a project
+* that never runs `warlock mcp` does not need it. Tries core's own resolution
+* first (pnpm links installed peers next to core), then the app's.
+*
+* Throws `WL7003` with the install line when it (or `@warlock.js/ai`, which
+* it imports) is missing.
+*/
+async function loadAiToolsServe(cwd, importer = (specifier) => import(specifier)) {
+	const attempts = [() => importer("@warlock.js/ai-tools"), () => importer(resolve$1("@warlock.js/ai-tools", pathToFileURL(path.join(cwd, "package.json")).href))];
+	let lastError;
+	for (const attempt of attempts) try {
+		const module = await attempt();
+		if (isAiToolsServeModule(module)) return module;
+		lastError = /* @__PURE__ */ new Error("@warlock.js/ai-tools does not export serve()");
+	} catch (error) {
+		lastError = error;
+		if (!isMissingModule(error, PACKAGES) && !(error instanceof Error && /Cannot find package/.test(error.message))) break;
+	}
+	const reason = lastError instanceof Error ? lastError.message : String(lastError);
+	throw new WarlockError("WL7003", `warlock mcp needs @warlock.js/ai-tools (and @warlock.js/ai), which could not be loaded: ${reason}. Install them: ${MCP_INSTALL_HINT}`, { cause: lastError });
+}
+
+//#endregion
+export { MCP_INSTALL_HINT, isAiToolsServeModule, loadAiToolsServe };
+//# sourceMappingURL=load-ai-tools.mjs.map

package/esm/tooling/mcp/load-ai-tools.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-ai-tools.mjs","names":["resolveModule"],"sources":["../../../../../../../../../packages/core/src/tooling/mcp/load-ai-tools.ts"],"sourcesContent":["import path from \"node:path\";\nimport { pathToFileURL } from \"node:url\";\nimport { resolve as resolveModule } from \"import-meta-resolve\";\nimport { WarlockError } from \"../../errors/warlock-error\";\n\n/** The install line printed when the MCP transport packages are missing. */\nexport const MCP_INSTALL_HINT = \"npm install -D @warlock.js/ai-tools @warlock.js/ai\";\n\n/** The tool shape `ai.mcp.serve` consumes, built structurally (see `@warlock.js/ai`'s `ToolContract`). */\nexport type ServeToolContract = {\n  name: string;\n  description: string;\n  input: unknown;\n  execute(input: Record<string, unknown>): Promise<unknown>;\n  invoke(\n    raw: unknown,\n    context?: unknown,\n  ): Promise<{\n    data?: unknown;\n    error?: Error;\n    usage: { input: number; output: number; total: number };\n    report: Record<string, unknown>;\n  }>;\n};\n\n/** The transport options of `ai.mcp.serve` this command uses. */\nexport type ServeTransportOptions =\n  | { type: \"stdio\" }\n  | {\n      type: \"http\";\n      host: string;\n      port: number;\n      path: string;\n      auth?: { bearer: string };\n    };\n\n/** The handle `start()` resolves. */\nexport type ServeHandle = { url?: string; close(): Promise<void> };\n\n/** The slice of `@warlock.js/ai-tools` this command calls. */\nexport type AiToolsServeModule = {\n  serve(\n    tools: ServeToolContract[],\n    options: { name: string; version?: string; transport: ServeTransportOptions },\n  ): { start(): Promise<ServeHandle>; stop(): Promise<void> };\n};\n\n/** Whether a loaded module exposes `serve()`. */\nexport function isAiToolsServeModule(value: unknown): value is AiToolsServeModule {\n  return (\n    typeof value === \"object\" && value !== null && typeof Reflect.get(value, \"serve\") === \"function\"\n  );\n}\n\nfunction isMissingModule(error: unknown, names: readonly string[]): boolean {\n  if (typeof error !== \"object\" || error === null) return false;\n\n  const code = Reflect.get(error, \"code\");\n  const message = error instanceof Error ? error.message : \"\";\n\n  return (\n    (code === \"ERR_MODULE_NOT_FOUND\" || code === \"MODULE_NOT_FOUND\") &&\n    names.some((name) => message.includes(`'${name}'`) || message.includes(`\"${name}\"`))\n  );\n}\n\nconst PACKAGES = [\"@warlock.js/ai-tools\", \"@warlock.js/ai\"] as const;\n\n/**\n * Import `@warlock.js/ai-tools` lazily — it is an optional peer, so a project\n * that never runs `warlock mcp` does not need it. Tries core's own resolution\n * first (pnpm links installed peers next to core), then the app's.\n *\n * Throws `WL7003` with the install line when it (or `@warlock.js/ai`, which\n * it imports) is missing.\n */\nexport async function loadAiToolsServe(\n  cwd: string,\n  importer: (specifier: string) => Promise<unknown> = (specifier) => import(specifier),\n): Promise<AiToolsServeModule> {\n  const attempts: (() => Promise<unknown>)[] = [\n    () => importer(\"@warlock.js/ai-tools\"),\n    () =>\n      importer(\n        resolveModule(\"@warlock.js/ai-tools\", pathToFileURL(path.join(cwd, \"package.json\")).href),\n      ),\n  ];\n  let lastError: unknown;\n\n  for (const attempt of attempts) {\n    try {\n      const module = await attempt();\n\n      if (isAiToolsServeModule(module)) return module;\n\n      lastError = new Error(\"@warlock.js/ai-tools does not export serve()\");\n    } catch (error) {\n      lastError = error;\n\n      if (\n        !isMissingModule(error, PACKAGES) &&\n        !(error instanceof Error && /Cannot find package/.test(error.message))\n      ) {\n        break;\n      }\n    }\n  }\n\n  const reason = lastError instanceof Error ? lastError.message : String(lastError);\n\n  throw new WarlockError(\n    \"WL7003\",\n    `warlock mcp needs @warlock.js/ai-tools (and @warlock.js/ai), which could not be loaded: ${reason}. Install them: ${MCP_INSTALL_HINT}`,\n    { cause: lastError },\n  );\n}\n"],"mappings":";;;;;;;AAMA,MAAa,mBAAmB;;AA0ChC,SAAgB,qBAAqB,OAA6C;CAChF,OACE,OAAO,UAAU,YAAY,UAAU,QAAQ,OAAO,QAAQ,IAAI,OAAO,OAAO,MAAM;AAE1F;AAEA,SAAS,gBAAgB,OAAgB,OAAmC;CAC1E,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO;CAExD,MAAM,OAAO,QAAQ,IAAI,OAAO,MAAM;CACtC,MAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU;CAEzD,QACG,SAAS,0BAA0B,SAAS,uBAC7C,MAAM,MAAM,SAAS,QAAQ,SAAS,IAAI,KAAK,EAAE,KAAK,QAAQ,SAAS,IAAI,KAAK,EAAE,CAAC;AAEvF;AAEA,MAAM,WAAW,CAAC,wBAAwB,gBAAgB;;;;;;;;;AAU1D,eAAsB,iBACpB,KACA,YAAqD,cAAc,OAAO,YAC7C;CAC7B,MAAM,WAAuC,OACrC,SAAS,sBAAsB,SAEnC,SACEA,UAAc,wBAAwB,cAAc,KAAK,KAAK,KAAK,cAAc,CAAC,CAAC,CAAC,IAAI,CAC1F,CACJ;CACA,IAAI;CAEJ,KAAK,MAAM,WAAW,UACpB,IAAI;EACF,MAAM,SAAS,MAAM,QAAQ;EAE7B,IAAI,qBAAqB,MAAM,GAAG,OAAO;EAEzC,4BAAY,IAAI,MAAM,8CAA8C;CACtE,SAAS,OAAO;EACd,YAAY;EAEZ,IACE,CAAC,gBAAgB,OAAO,QAAQ,KAChC,EAAE,iBAAiB,SAAS,sBAAsB,KAAK,MAAM,OAAO,IAEpE;CAEJ;CAGF,MAAM,SAAS,qBAAqB,QAAQ,UAAU,UAAU,OAAO,SAAS;CAEhF,MAAM,IAAI,aACR,UACA,2FAA2F,OAAO,kBAAkB,oBACpH,EAAE,OAAO,UAAU,CACrB;AACF"}

package/esm/tooling/mcp/mcp-tools.d.mts

@@ -0,0 +1,70 @@
+import { InspectReport, InspectSection } from "../inspect/inspect-report.types.mjs";
+import { CheckReport, CheckStepName } from "../check/check-report.types.mjs";
+import { TestRunReport } from "../check/run-tests.mjs";
+import { DevtoolsClient } from "../devtools/devtools-client.mjs";
+import { GeneratorSpec } from "../generate/generator-spec.mjs";
+import { DocsCorpus } from "./docs-search.mjs";
+import { McpInputSchema } from "./tool-input.mjs";
+//#region ../../packages/core/src/tooling/mcp/mcp-tools.d.ts
+/**
+ * What the `warlock mcp` tools run against. The CLI fills it from a read-only
+ * boot of the app; `warlock dev --mcp` fills it from the live dev process;
+ * tests pass fakes.
+ */
+export type WarlockMcpContext = {
+  /** Project root. */
+  cwd: string;
+  /** Whether tools may write project files (`--allow-writes`). */
+  allowWrites: boolean;
+  /** Describe the app (see `inspectApp`). */
+  inspect(sections: readonly InspectSection[]): Promise<InspectReport>;
+  /** Run `warlock check`. */
+  check(options: {
+    changed?: boolean;
+    base?: string;
+    skip?: readonly CheckStepName[];
+  }): Promise<CheckReport>;
+  /** Run tests for files, the changed files, or the suite. */
+  tests(options: {
+    files?: readonly string[];
+    changed?: boolean;
+    base?: string;
+  }): Promise<TestRunReport>;
+  /** Connect to the running dev server's devtools API (throws WL8008 / WL8009). */
+  devtools(): Promise<DevtoolsClient>;
+  /** Preview (and, with `allowWrites`, apply) a `make` / `add` generator. */
+  generation: {
+    plan(spec: GeneratorSpec): Promise<unknown>;
+    apply(spec: GeneratorSpec): Promise<unknown>;
+  };
+  /** The installed docs corpus (cached by the caller). */
+  docs(): Promise<DocsCorpus>;
+  /** The `warlock add` feature names, advertised as the `generate_add` enum. */
+  features?: readonly string[];
+};
+/** One tool the server exposes. */
+export type WarlockMcpTool = {
+  /** Underscored, never dotted: model APIs refuse dots in tool names (`^[a-zA-Z0-9_-]{1,128}$`). */
+  name: string;
+  description: string;
+  input: McpInputSchema;
+  /** Whether a call can change project files. Only exposed with `allowWrites`. */
+  writes: boolean;
+  /** A check run before validation; return a message to refuse the call. */
+  precheck?: (input: Record<string, unknown>) => string | null;
+  run(input: Record<string, unknown>): Promise<unknown>;
+};
+/** The `make` generators the `generate_make` tool can run (`warlock generate.<name>`). */
+export declare const MCP_MAKE_GENERATORS: readonly ["module", "controller", "service", "use-case", "model", "repository", "resource", "migration"];
+/** The generator spec a `generate_make` call describes. */
+export declare function makeSpecFromInput(input: Record<string, unknown>): GeneratorSpec;
+/**
+ * The tools `warlock mcp` serves. Read-only unless `context.allowWrites`:
+ * generate tools then accept `write: true`; without it they only return the
+ * diff a generator would produce.
+ */
+export declare function createWarlockMcpTools(context: WarlockMcpContext): WarlockMcpTool[];
+/** The message a tool failure reaches the client with: code, message and the fix. */
+export declare function describeToolError(error: unknown): string;
+//#endregion
+//# sourceMappingURL=mcp-tools.d.mts.map

package/esm/tooling/mcp/mcp-tools.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tools.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/mcp/mcp-tools.ts"],"mappings":";;;;;;;;;;;;;YA8BY;;EAEV;;EAEA;;EAEA,QAAQ,mBAAmB,mBAAmB,QAAQ;;EAEtD,MAAM;IACJ;IACA;IACA,gBAAgB;MACd,QAAQ;;EAEZ,MAAM;IACJ;IACA;IACA;MACE,QAAQ;;EAEZ,YAAY,QAAQ;;EAEpB;IACE,KAAK,MAAM,gBAAgB;IAC3B,MAAM,MAAM,gBAAgB;;;EAG9B,QAAQ,QAAQ;;EAEhB;;;YAIU;;EAEV;EACA;EACA,OAAO;;EAEP;;EAEA,YAAY,OAAO;EACnB,IAAI,OAAO,0BAA0B;;;qBAI1B;;wBAiPG,kBAAkB,OAAO,0BAA0B;;;;;;wBAgCnD,sBAAsB,SAAS,oBAAoB;;wBAiTnD,kBAAkB"}