@warlock.js/core 5.29.0 → 5.31.0

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":";;cAMa,gBAAA;;KAGD,iBAAA;EACV,IAAA;EACA,WAAA;EACA,KAAA;EACA,OAAA,CAAQ,KAAA,EAAO,MAAA,oBAA0B,OAAA;EACzC,MAAA,CACE,GAAA,WACA,OAAA,aACC,OAAA;IACD,IAAA;IACA,KAAA,GAAQ,KAAA;IACR,KAAA;MAAS,KAAA;MAAe,MAAA;MAAgB,KAAA;IAAA;IACxC,MAAA,EAAQ,MAAA;EAAA;AAAA;;KAKA,qBAAA;EACN,IAAA;AAAA;EAEA,IAAA;EACA,IAAA;EACA,IAAA;EACA,IAAA;EACA,IAAA;IAAS,MAAA;EAAA;AAAA;;KAIH,WAAA;EAAgB,GAAA;EAAc,KAAA,IAAS,OAAO;AAAA;;KAG9C,kBAAA;EACV,KAAA,CACE,KAAA,EAAO,iBAAA,IACP,OAAA;IAAW,IAAA;IAAc,OAAA;IAAkB,SAAA,EAAW,qBAAA;EAAA;IACnD,KAAA,IAAS,OAAA,CAAQ,WAAA;IAAc,IAAA,IAAQ,OAAA;EAAA;AAAA;;iBAI9B,oBAAA,CAAqB,KAAA,YAAiB,KAAA,IAAS,kBAAkB;;AAf5D;AAIrB;;;;;;iBAuCsB,gBAAA,CACpB,GAAA,UACA,QAAA,IAAW,SAAA,aAAsB,OAAA,YAChC,OAAA,CAAQ,kBAAA"}

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

@@ -0,0 +1,44 @@
+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;
+	}
+	throw new WarlockError("WL7003", `warlock mcp needs @warlock.js/ai-tools (and @warlock.js/ai), which could not be loaded: ${lastError instanceof Error ? lastError.message : String(lastError)}. 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;CAKF,MAAM,IAAI,aACR,UACA,2FAJa,qBAAqB,QAAQ,UAAU,UAAU,OAAO,SAAS,EAIoB,kBAAkB,oBACpH,EAAE,OAAO,UAAU,CACrB;AACF"}

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

@@ -0,0 +1,60 @@
+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.
+ */
+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. */
+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>`). */
+declare const MCP_MAKE_GENERATORS: readonly ["module", "controller", "service", "use-case", "model", "repository", "resource", "migration"];
+/** The generator spec a `generate_make` call describes. */
+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.
+ */
+declare function createWarlockMcpTools(context: WarlockMcpContext): WarlockMcpTool[];
+/** The message a tool failure reaches the client with: code, message and the fix. */
+declare function describeToolError(error: unknown): string;
+//#endregion
+export { MCP_MAKE_GENERATORS, WarlockMcpContext, WarlockMcpTool, createWarlockMcpTools, describeToolError, makeSpecFromInput };
+//# 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":";;;;;;;;;;;AA8BA;;;KAAY,iBAAA;EAM4C,oBAJtD,GAAA,UASkB;EAPlB,WAAA,WAQI;EANJ,OAAA,CAAQ,QAAA,WAAmB,cAAA,KAAmB,OAAA,CAAQ,aAAA,GAYlD;EAVJ,KAAA,CAAM,OAAA;IACJ,OAAA;IACA,IAAA;IACA,IAAA,YAAgB,aAAA;EAAA,IACd,OAAA,CAAQ,WAAA,GAYkB;EAV9B,KAAA,CAAM,OAAA;IACJ,KAAA;IACA,OAAA;IACA,IAAA;EAAA,IACE,OAAA,CAAQ,aAAA,GAdZ;EAgBA,QAAA,IAAY,OAAA,CAAQ,cAAA,GAdO;EAgB3B,UAAA;IACE,IAAA,CAAK,IAAA,EAAM,aAAA,GAAgB,OAAA;IAC3B,KAAA,CAAM,IAAA,EAAM,aAAA,GAAgB,OAAA;EAAA,GAf5B;EAkBF,IAAA,IAAQ,OAAA,CAAQ,UAAA,GAhBd;EAkBF,QAAA;AAAA;;KAIU,cAAA;EAnBV,kGAqBA,IAAA;EACA,WAAA;EACA,KAAA,EAAO,cAAA,EAvBD;EAyBN,MAAA,WArBY;EAuBZ,QAAA,IAAY,KAAA,EAAO,MAAA;EACnB,GAAA,CAAI,KAAA,EAAO,MAAA,oBAA0B,OAAA;AAAA;;cAI1B,mBAAA;;iBAiPG,iBAAA,CAAkB,KAAA,EAAO,MAAA,oBAA0B,aAAa;;;;;;iBAgChE,qBAAA,CAAsB,OAAA,EAAS,iBAAA,GAAoB,cAAc;;iBAiTjE,iBAAA,CAAkB,KAAc"}

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

@@ -0,0 +1,513 @@
+import { WarlockError } from "../../errors/warlock-error.mjs";
+import { ERROR_CODES, errorCodeDocsUrl, explainErrorCode, isWarlockErrorCode } from "../../errors/error-codes.mjs";
+import { INSPECT_SECTIONS } from "../inspect/inspect-report.types.mjs";
+import { CHECK_STEPS } from "../check/check-report.types.mjs";
+import { MAKE_GENERATORS, isMakeGenerator } from "../generate/generator-spec.mjs";
+import "../generate/index.mjs";
+import { readDocsFile, searchDocs } from "./docs-search.mjs";
+import { buildDbSchema } from "./db-schema.mjs";
+import { inputSchema } from "./tool-input.mjs";
+
+//#region ../../packages/core/src/tooling/mcp/mcp-tools.ts
+/** The `make` generators the `generate_make` tool can run (`warlock generate.<name>`). */
+const MCP_MAKE_GENERATORS = MAKE_GENERATORS;
+function stringArg(input, key) {
+	const value = input[key];
+	return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+function booleanArg(input, key) {
+	return input[key] === true;
+}
+function integerArg(input, key, fallback) {
+	const value = input[key];
+	return typeof value === "number" && Number.isInteger(value) ? value : fallback;
+}
+function stringsArg(input, key) {
+	const value = input[key];
+	return Array.isArray(value) ? value.filter((item) => typeof item === "string") : void 0;
+}
+function includesText(values, needle) {
+	const lowered = needle.toLowerCase();
+	return values.some((value) => typeof value === "string" && value.toLowerCase().includes(lowered));
+}
+const MUTATING = new Set([
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE"
+]);
+function filterRoutes(routes, input) {
+	const filter = stringArg(input, "filter");
+	const method = stringArg(input, "method")?.toUpperCase();
+	const unguarded = booleanArg(input, "unguardedWrites");
+	return routes.filter((route) => (!filter || includesText([
+		route.path,
+		route.name,
+		route.handler,
+		route.sourceFile
+	], filter)) && (!method || route.method === method) && (!unguarded || MUTATING.has(route.method) && !route.auth.required && !route.isPage));
+}
+/** The `filter` match of one entry of a section, by the fields an agent would search. */
+function sectionEntryMatches(section, entry, filter) {
+	if (typeof entry !== "object" || entry === null) return false;
+	return includesText({
+		routes: [
+			"path",
+			"name",
+			"handler",
+			"sourceFile"
+		],
+		models: [
+			"name",
+			"table",
+			"sourceFile"
+		],
+		resources: ["name"],
+		config: ["key", "file"],
+		events: ["event"],
+		pages: [
+			"path",
+			"name",
+			"file"
+		],
+		jobs: ["name", "queue"],
+		schedules: ["name"],
+		packages: ["name"]
+	}[section].map((field) => {
+		const value = Reflect.get(entry, field);
+		return typeof value === "string" ? value : null;
+	}), filter);
+}
+const SECTION_DESCRIPTIONS = {
+	routes: "Registered HTTP routes from the booted router: method, path, name, source file, handler, middleware chain in run order, auth guard, CSRF, rate limit, logging policy, request JSON Schemas and declared responses ($refs resolve against `components`).",
+	models: "Cascade model classes: table, primary key, data source, columns (from the model's Seal schema), relations, resource, delete strategy and timestamp columns.",
+	resources: "Resources reached from route responses or models, with their output shape as JSON Schema and the models that use them.",
+	config: "Every loaded config key as a dotted path with its TYPE (never its value) and the src/config file it came from.",
+	events: "Event listeners app modules registered while loading, grouped by event, with the registering file.",
+	pages: "Pages @warlock.js/web installed: path, name, file, layout chain, loaders, actions and guard.",
+	jobs: "Queue jobs defined with defineJob() from @warlock.js/queue: name, queue, attempts, backoff, retention.",
+	schedules: "Scheduled tasks from @warlock.js/scheduler: name, cron expression, intervals, next run.",
+	packages: "Installed @warlock.js/* packages and their versions."
+};
+function inspectSectionTool(context, section) {
+	const properties = { filter: {
+		type: "string",
+		description: "Case-insensitive substring to keep only matching entries (names, paths, keys, files)."
+	} };
+	if (section === "routes") {
+		properties.method = {
+			type: "string",
+			description: "Only routes with this HTTP method (GET, POST, …)."
+		};
+		properties.unguardedWrites = {
+			type: "boolean",
+			description: "Only POST/PUT/PATCH/DELETE API routes that have no auth guard."
+		};
+	}
+	return {
+		name: `inspect_${section}`,
+		description: `${SECTION_DESCRIPTIONS[section]} Read from the app's registries (the same data as \`warlock inspect --json --section ${section}\`), not from source text. Read-only.`,
+		input: inputSchema(properties),
+		writes: false,
+		async run(input) {
+			const report = await context.inspect([section]);
+			const entries = report[section] ?? [];
+			const filter = stringArg(input, "filter");
+			const kept = section === "routes" && report.routes ? filterRoutes(report.routes, input) : filter ? entries.filter((entry) => sectionEntryMatches(section, entry, filter)) : entries;
+			const withSchemas = section === "routes" || section === "models" || section === "resources";
+			return {
+				schemaVersion: report.schemaVersion,
+				[section]: kept,
+				total: entries.length,
+				...withSchemas ? { components: report.components } : {},
+				warnings: report.warnings
+			};
+		}
+	};
+}
+function summarizeRequest(summary, record) {
+	if (!record) return summary;
+	const nPlusOneShapes = new Set(record.warnings.filter((warning) => warning.type === "n+1" && typeof warning.shape === "string").map((warning) => warning.shape));
+	return {
+		...summary,
+		error: record.error ?? null,
+		phases: record.phases,
+		queries: record.queries.map((query) => ({
+			...query,
+			nPlusOne: typeof query.shape === "string" && nPlusOneShapes.has(query.shape)
+		})),
+		warnings: record.warnings,
+		logs: record.logs,
+		cache: record.cache,
+		mails: record.mails,
+		timings: {
+			totalMs: record.durationMs ?? null,
+			phasesMs: record.phases.reduce((totals, phase) => {
+				totals[phase.name] = (totals[phase.name] ?? 0) + phase.durationMs;
+				return totals;
+			}, {}),
+			queriesMs: record.queries.reduce((total, query) => total + (typeof query.durationMs === "number" ? query.durationMs : 0), 0)
+		}
+	};
+}
+function writeProperty() {
+	return { write: {
+		type: "boolean",
+		description: "Write the files into the project. Default false: only return the diff (the generator runs in a throw-away copy of the project)."
+	} };
+}
+function refuseWrite(context) {
+	return (input) => input.write === true && !context.allowWrites ? `WL7005: this MCP server is read-only; restart it with --allow-writes to let generate tools write. Without it they return the diff only.` : null;
+}
+const MAKE_FLAGS = {
+	withValidation: {
+		type: "boolean",
+		description: "controller: also generate a validation schema and bind it (--with-validation)."
+	},
+	withResource: {
+		type: "boolean",
+		description: "model: also generate a resource (--with-resource)."
+	},
+	table: {
+		type: "string",
+		description: "model: the table name (--table)."
+	},
+	minimal: {
+		type: "boolean",
+		description: "module: a minimal skeleton instead of the full CRUD scaffold (--minimal)."
+	},
+	noTimestamps: {
+		type: "boolean",
+		description: "model / migration: no timestamp columns (--no-timestamps)."
+	},
+	add: {
+		type: "string",
+		description: "migration: columns to add, DSL name:type:modifier,… (--add)."
+	},
+	drop: {
+		type: "string",
+		description: "migration: comma-separated columns to drop (--drop)."
+	},
+	rename: {
+		type: "string",
+		description: "migration: columns to rename, old:new,… (--rename)."
+	},
+	force: {
+		type: "boolean",
+		description: "Overwrite files that already exist (--force)."
+	},
+	overwrite: {
+		type: "boolean",
+		description: "module / model: with force, also replace files that differ from the output (--overwrite)."
+	}
+};
+const FLAG_NAMES = {
+	withValidation: "with-validation",
+	withResource: "with-resource",
+	table: "table",
+	minimal: "minimal",
+	noTimestamps: "no-timestamps",
+	add: "add",
+	drop: "drop",
+	rename: "rename",
+	force: "force",
+	overwrite: "overwrite"
+};
+/** The generator spec a `generate_make` call describes. */
+function makeSpecFromInput(input) {
+	const generator = stringArg(input, "generator");
+	const name = stringArg(input, "name");
+	if (!generator || !isMakeGenerator(generator) || !name) throw new Error(`generate_make needs a generator (${MCP_MAKE_GENERATORS.join(", ")}) and a name.`);
+	const flags = {};
+	for (const [key, flag] of Object.entries(FLAG_NAMES)) {
+		const value = input[key];
+		if (value === true) flags[flag] = true;
+		if (typeof value === "string" && value.length > 0) flags[flag] = value;
+	}
+	return {
+		type: "make",
+		generator,
+		name,
+		flags
+	};
+}
+/**
+* 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.
+*/
+function createWarlockMcpTools(context) {
+	return [
+		{
+			name: "inspect_app",
+			description: "Summary of the app: name, version, Node, environment, how many routes/models/resources/config keys/events/pages/jobs/schedules/packages it has, and inspect warnings (WL codes for modules that failed to load). Start here, then call the inspect_<section> tool you need. Read-only.",
+			input: inputSchema({}),
+			writes: false,
+			async run() {
+				const report = await context.inspect(INSPECT_SECTIONS);
+				const counts = Object.fromEntries(INSPECT_SECTIONS.map((section) => [section, report[section]?.length ?? 0]));
+				return {
+					schemaVersion: report.schemaVersion,
+					app: report.app,
+					counts,
+					warnings: report.warnings
+				};
+			}
+		},
+		...INSPECT_SECTIONS.map((section) => inspectSectionTool(context, section)),
+		{
+			name: "db_schema",
+			description: "The database schema the app's models declare: one entry per table with columns (type, required, primary key, foreign key of belongsTo relations), relations, timestamp columns and delete strategy. Built from the models' Seal schemas — no database connection is opened, so migration-only columns are not listed. Read-only.",
+			input: inputSchema({ model: {
+				type: "string",
+				description: "Only this model (class name) or table."
+			} }),
+			writes: false,
+			async run(input) {
+				return buildDbSchema((await context.inspect(["models"])).models ?? [], stringArg(input, "model"));
+			}
+		},
+		{
+			name: "docs_search",
+			description: "Search the documentation of the @warlock.js packages INSTALLED in this app (their skills, README and llms files under node_modules) — offline, so answers match the installed versions. Returns ranked sections with the file, heading, line and an excerpt; read a whole skill with docs_read. Read-only.",
+			input: inputSchema({
+				query: {
+					type: "string",
+					description: "Words to look for, e.g. 'validation schema file upload'."
+				},
+				limit: {
+					type: "integer",
+					description: "Maximum hits (default 8).",
+					minimum: 1,
+					maximum: 25
+				},
+				package: {
+					type: "string",
+					description: "Only this package, e.g. '@warlock.js/cascade'."
+				}
+			}, ["query"]),
+			writes: false,
+			async run(input) {
+				const corpus = await context.docs();
+				const query = stringArg(input, "query") ?? "";
+				return {
+					query,
+					files: corpus.files.length,
+					hits: searchDocs(corpus, query, {
+						limit: integerArg(input, "limit", 8),
+						package: stringArg(input, "package")
+					})
+				};
+			}
+		},
+		{
+			name: "docs_read",
+			description: "Read one file returned by docs_search (a skill, README or llms file of an installed @warlock.js package), whole or one section by its heading. Only files of that corpus can be read. Read-only.",
+			input: inputSchema({
+				file: {
+					type: "string",
+					description: "The `file` of a docs_search hit."
+				},
+				heading: {
+					type: "string",
+					description: "Only the section with this exact heading."
+				}
+			}, ["file"]),
+			writes: false,
+			async run(input) {
+				const corpus = await context.docs();
+				const file = stringArg(input, "file") ?? "";
+				const found = readDocsFile(corpus, context.cwd, file, { heading: stringArg(input, "heading") });
+				if (!found) throw new Error(`"${file}" is not an installed docs file (or has no such heading). Use docs_search first.`);
+				return found;
+			}
+		},
+		{
+			name: "explain",
+			description: "Explain a stable Warlock error code (WL3001, WL7301, WL8003, …): what it means, whether it is your code or this machine, the one-line fix, the skill that covers it and its docs link. Without a code, lists every code. Read-only.",
+			input: inputSchema({ code: {
+				type: "string",
+				description: "The code, e.g. WL3001."
+			} }),
+			writes: false,
+			async run(input) {
+				const code = stringArg(input, "code");
+				if (!code) return Object.values(ERROR_CODES).map((definition) => ({
+					code: definition.code,
+					title: definition.title,
+					category: definition.category
+				}));
+				const definition = explainErrorCode(code);
+				if (!definition) throw new Error(`Unknown error code "${code}". Call explain without a code to list them.`);
+				return {
+					...definition,
+					docs: isWarlockErrorCode(definition.code) ? errorCodeDocsUrl(definition.code) : null
+				};
+			}
+		},
+		{
+			name: "check_run",
+			description: "Run `warlock check`: typecheck, lint, the affected tests and the framework convention checks, as one report with one problem per entry (stable WL code, file:line, fix hint, skill). exitCode 1 means your code, 2 means this machine (missing service, Node version, crashed tool) — do not edit code for a 2. Use changed: true while iterating. Does not write project files.",
+			input: inputSchema({
+				changed: {
+					type: "boolean",
+					description: "Only the files changed against HEAD (plus untracked) and what they affect."
+				},
+				base: {
+					type: "string",
+					description: "Compare with the merge base of this git ref instead (implies changed)."
+				},
+				skip: {
+					type: "array",
+					description: "Steps to skip.",
+					items: {
+						type: "string",
+						enum: CHECK_STEPS
+					}
+				}
+			}),
+			writes: false,
+			async run(input) {
+				const skip = (stringsArg(input, "skip") ?? []).filter((step) => CHECK_STEPS.includes(step));
+				return context.check({
+					changed: booleanArg(input, "changed"),
+					base: stringArg(input, "base"),
+					skip
+				});
+			}
+		},
+		{
+			name: "test_run",
+			description: "Run the app's vitest tests: given test files run as they are; given source files, the tests that import them run (vitest related); changed: true runs the tests related to the files changed in git; neither runs the whole suite. Returns totals and one problem per failure (WL7301 failed test, WL7302 file failed to load, WL8xxx this machine). Does not write project files.",
+			input: inputSchema({
+				files: {
+					type: "array",
+					description: "Project-relative files (tests or sources).",
+					items: { type: "string" }
+				},
+				changed: {
+					type: "boolean",
+					description: "The tests related to the files changed against HEAD."
+				},
+				base: {
+					type: "string",
+					description: "With changed: compare with the merge base of this ref."
+				}
+			}),
+			writes: false,
+			async run(input) {
+				return context.tests({
+					files: stringsArg(input, "files"),
+					changed: booleanArg(input, "changed"),
+					base: stringArg(input, "base")
+				});
+			}
+		},
+		{
+			name: "requests_recent",
+			description: "The most recent HTTP requests the running dev server handled, from @warlock.js/devtools (needs `warlock dev` with devtools installed): method, path, matched route, status, duration, and — with details — the phase timeline (route match, each middleware, validation, handler), every query with its duration and an nPlusOne flag, N+1 warnings, logs, cache operations and captured mails. Request and response bodies are not recorded by devtools; use `warlock trace` for those. Read-only.",
+			input: inputSchema({
+				limit: {
+					type: "integer",
+					description: "How many requests (default 10, newest first).",
+					minimum: 1,
+					maximum: 50
+				},
+				method: {
+					type: "string",
+					description: "Only this HTTP method."
+				},
+				path: {
+					type: "string",
+					description: "Only paths containing this text."
+				},
+				status: {
+					type: "integer",
+					description: "Only this response status.",
+					minimum: 100,
+					maximum: 599
+				},
+				details: {
+					type: "boolean",
+					description: "Include the full timeline of each request (default true)."
+				}
+			}),
+			writes: false,
+			async run(input) {
+				const devtools = await context.devtools();
+				const method = stringArg(input, "method")?.toUpperCase();
+				const pathFilter = stringArg(input, "path");
+				const status = typeof input.status === "number" ? input.status : void 0;
+				const details = input.details !== false;
+				const summaries = (await devtools.listRequests()).filter((summary) => (!method || summary.method === method) && (!pathFilter || summary.path.includes(pathFilter)) && (status === void 0 || summary.status === status)).sort((first, second) => second.startedAt - first.startedAt).slice(0, integerArg(input, "limit", 10));
+				const requests = [];
+				for (const summary of summaries) requests.push(summarizeRequest(summary, details ? await devtools.getRequest(summary.id) : void 0));
+				return {
+					devtools: {
+						url: devtools.url,
+						path: devtools.devtoolsPath
+					},
+					requests
+				};
+			}
+		},
+		{
+			name: "generate_make",
+			description: `Run a \`warlock generate.<generator>\` scaffold (${MCP_MAKE_GENERATORS.join(", ")}) and return the unified diff of every file it would create or change. By default nothing in the project is written: the generator runs in a throw-away copy.${context.allowWrites ? " Pass write: true to write the files into the project." : " This server is read-only (no --allow-writes)."} Names are module/name for everything but module (e.g. posts/create-post) and the model path for migration.`,
+			input: inputSchema({
+				generator: {
+					type: "string",
+					description: "Which generator.",
+					enum: MCP_MAKE_GENERATORS
+				},
+				name: {
+					type: "string",
+					description: "The generator's argument: `posts` for module, `posts/create-post` for the others, the model path for migration."
+				},
+				...MAKE_FLAGS,
+				...context.allowWrites ? writeProperty() : {}
+			}, ["generator", "name"]),
+			writes: context.allowWrites,
+			precheck: refuseWrite(context),
+			async run(input) {
+				const spec = makeSpecFromInput(input);
+				return input.write === true ? context.generation.apply(spec) : context.generation.plan(spec);
+			}
+		},
+		{
+			name: "generate_add",
+			description: `Run \`warlock add <features…>\` (an installable framework feature: a database driver, queue, web, devtools, …) and return the unified diff of every file it would create or change, package.json included. Dependencies are recorded, never installed, in the preview.${context.allowWrites ? " Pass write: true to apply it to the project (this installs the dependencies)." : " This server is read-only (no --allow-writes)."}`,
+			input: inputSchema({
+				features: {
+					type: "array",
+					description: "Feature names, e.g. ['devtools'].",
+					items: context.features?.length ? {
+						type: "string",
+						enum: context.features
+					} : { type: "string" }
+				},
+				...context.allowWrites ? writeProperty() : {}
+			}, ["features"]),
+			writes: context.allowWrites,
+			precheck: refuseWrite(context),
+			async run(input) {
+				const features = stringsArg(input, "features") ?? [];
+				if (features.length === 0) throw new Error("generate_add needs at least one feature name.");
+				const spec = {
+					type: "add",
+					features
+				};
+				return input.write === true ? context.generation.apply(spec) : context.generation.plan(spec);
+			}
+		}
+	];
+}
+/** The message a tool failure reaches the client with: code, message and the fix. */
+function describeToolError(error) {
+	if (error instanceof WarlockError) return `${error.code}: ${error.message} Fix: ${ERROR_CODES[error.code].fix}`;
+	return error instanceof Error ? error.message : String(error);
+}
+
+//#endregion
+export { MCP_MAKE_GENERATORS, createWarlockMcpTools, describeToolError, makeSpecFromInput };
+//# sourceMappingURL=mcp-tools.mjs.map