@warlock.js/core 5.30.0 → 5.32.0

package/esm/tooling/inspect/inspect-report.types.d.mts

@@ -0,0 +1,228 @@
+import { WarlockErrorCode } from "../../errors/error-codes.mjs";
+//#region ../../packages/core/src/tooling/inspect/inspect-report.types.d.ts
+/**
+ * @fileoverview The `warlock inspect` report, schema version 1.
+ *
+ * STABILITY: within `schemaVersion: 1` fields are only ever ADDED. No field is
+ * removed, renamed or retyped, so a consumer written against this file keeps
+ * working on every later 5.x release. Consumers must ignore keys they do not
+ * know. A change that breaks that promise ships as `schemaVersion: 2` and is
+ * listed under BREAKING in the changelog. Free text (warning messages,
+ * descriptions) is not part of the contract.
+ *
+ * The same shape is published as JSON Schema (draft 2020-12) in
+ * `@warlock.js/core/schemas/inspect-report.schema.json` and as the
+ * `INSPECT_REPORT_JSON_SCHEMA` constant.
+ */
+/** The version of the report shape. Bumped only for a breaking change. */
+export declare const INSPECT_SCHEMA_VERSION = 1;
+/** Every section the report can contain, in output order. */
+export declare const INSPECT_SECTIONS: readonly ["routes", "models", "resources", "config", "events", "pages", "jobs", "schedules", "packages"];
+/** One section name. */
+export type InspectSection = (typeof INSPECT_SECTIONS)[number];
+/** A JSON Schema (draft 2020-12) fragment. */
+export type JsonSchema = Record<string, unknown>;
+/** Who guards a route, from the descriptor `authMiddleware()` attaches. */
+export type InspectRouteAuth = {
+  /** Whether an auth guard runs on the route. */
+  required: boolean;
+  /** Where the token is read: `"header"` (bearer) or `{ cookie }`. */
+  sources: ("header" | {
+    cookie: string;
+  })[];
+  /** User types the guard accepts; empty means any. */
+  userTypes: string[];
+};
+/** The rate limit a route runs under. */
+export type InspectRouteRateLimit = {
+  /** `route` = the route's own option, `global` = `http.rateLimit`, `none` = no limiter. */
+  source: "route" | "global" | "none";
+  /** Max requests per window; `"dynamic"` when configured as a function. */
+  max: number | "dynamic" | null;
+  /** Window in milliseconds, or the configured string (`"1 minute"`); `"dynamic"` for a function. */
+  timeWindow: number | string | null;
+};
+/** What the route's request log entries keep. */
+export type InspectRouteLogging = {
+  /** Whether the request body is logged. */
+  body: boolean;
+  /** Whether the query string is logged. */
+  query: boolean;
+  /** Whether `http.logging.private` rules exist that may remove more for some URLs. */
+  privateRules: boolean;
+};
+/** One request parameter (path, query or header). */
+export type InspectParameter = {
+  name: string;
+  in: "path" | "query" | "header" | "cookie";
+  required: boolean;
+  schema: JsonSchema;
+};
+/** One registered HTTP route. */
+export type InspectRoute = {
+  /** Uppercase method, `ALL` for `router.all`. */
+  method: string;
+  path: string;
+  name: string | null;
+  /** Project-relative file that registered the route. */
+  sourceFile: string | null;
+  /** Handler function name, `"anonymous"` when it has none. */
+  handler: string;
+  description: string | null;
+  /** Whether a page (SSR) route registered it. */
+  isPage: boolean;
+  /** Middleware function names in run order. */
+  middleware: string[];
+  auth: InspectRouteAuth;
+  /** `false` when the route opted out of the CSRF origin guard (`csrf: false`). */
+  csrf: boolean;
+  rateLimit: InspectRouteRateLimit;
+  logging: InspectRouteLogging;
+  request: {
+    parameters: InspectParameter[];
+    /** JSON Schema of the request body, or `null`. */
+    body: JsonSchema | null;
+    /** Whether `validation.validate` (custom middleware, not described) is set. */
+    customValidation: boolean;
+  };
+  /** Declared responses keyed by status code. */
+  responses: Record<string, {
+    description: string;
+    schema: JsonSchema | null;
+  }>;
+};
+/** One model column, from the model's Seal `schema`. */
+export type InspectModelColumn = {
+  name: string;
+  required: boolean;
+  schema: JsonSchema;
+};
+/** One model relation. */
+export type InspectModelRelation = {
+  name: string;
+  type: string;
+  /** Target model name, or `null` when it could not be resolved. */
+  model: string | null;
+  foreignKey: string | null;
+  localKey: string | null;
+};
+/** One model class. */
+export type InspectModel = {
+  name: string;
+  table: string | null;
+  primaryKey: string | null;
+  /** Data source name, when configured by name. */
+  dataSource: string | null;
+  sourceFile: string | null;
+  /** Whether `@RegisterModel()` put it in the registry. */
+  registered: boolean;
+  columns: InspectModelColumn[];
+  relations: InspectModelRelation[];
+  /** Name of the model's `static resource`, a key of `components.schemas`. */
+  resource: string | null;
+  deleteStrategy: string | null;
+  createdAtColumn: string | null;
+  updatedAtColumn: string | null;
+  deletedAtColumn: string | null;
+};
+/** One resource class reached from a route or a model. */
+export type InspectResource = {
+  name: string;
+  /** Its output shape (JSON Schema; nested resources are `$ref`s into `components.schemas`). */
+  schema: JsonSchema;
+  /** Models whose `static resource` is this resource. */
+  models: string[];
+};
+/** One config key: its path and value type. Values are never printed. */
+export type InspectConfigKey = {
+  key: string;
+  /** `string`, `number`, `boolean`, `null`, `array`, `object`, `function`, `regexp`, `date`, or a class name. */
+  type: string;
+  /** The `src/config/*` file the top-level key comes from, when it exists. */
+  file: string | null;
+};
+/** One event and the listeners app modules registered for it. */
+export type InspectEvent = {
+  event: string;
+  listeners: {
+    name: string;
+    sourceFile: string;
+  }[];
+};
+/** One page installed by `@warlock.js/web`. */
+export type InspectPage = {
+  path: string;
+  name: string | null;
+  file: string;
+  /** Layout files from the outermost to the page's own directory. */
+  layouts: string[];
+  /** Files on the chain (layouts, then the page) that export a `loader`. */
+  loaders: string[];
+  /** Action names the page exports (`"default"` for `action`). */
+  actions: string[];
+  /** `"user"` when the page or a layout statically requires a user. */
+  guard: string | null;
+};
+/** One queue job defined with `defineJob()`. */
+export type InspectJob = {
+  name: string;
+  queue: string;
+  attempts: number | null;
+  backoff: number | {
+    type: string;
+    delay: number;
+  } | null;
+  removeOnComplete: boolean | number | null;
+  removeOnFail: boolean | number | null;
+};
+/** One scheduled task on the `@warlock.js/scheduler` scheduler. */
+export type InspectSchedule = {
+  name: string;
+  cron: string | null;
+  intervals: Record<string, unknown>;
+  nextRun: string | null;
+};
+/** One installed `@warlock.js/*` package. */
+export type InspectPackage = {
+  name: string;
+  version: string;
+};
+/** Something inspect could not read, with its code when one applies. */
+export type InspectWarning = {
+  code: WarlockErrorCode | null;
+  message: string;
+  /** The section or file it concerns. */
+  source: string | null;
+};
+/** The whole report. Sections not requested are absent. */
+export type InspectReport = {
+  schemaVersion: typeof INSPECT_SCHEMA_VERSION;
+  generatedAt: string;
+  app: {
+    name: string | null;
+    version: string | null;
+    /** Absolute project root. */
+    root: string;
+    node: string;
+    environment: string;
+    runtimeStrategy: string;
+  };
+  /** The sections this report contains. */
+  sections: InspectSection[];
+  routes?: InspectRoute[];
+  models?: InspectModel[];
+  resources?: InspectResource[];
+  config?: InspectConfigKey[];
+  events?: InspectEvent[];
+  pages?: InspectPage[];
+  jobs?: InspectJob[];
+  schedules?: InspectSchedule[];
+  packages?: InspectPackage[];
+  /** Shared schemas that `$ref`s point at (`#/components/schemas/<name>`). */
+  components: {
+    schemas: Record<string, JsonSchema>;
+  };
+  warnings: InspectWarning[];
+};
+//#endregion
+//# sourceMappingURL=inspect-report.types.d.mts.map

package/esm/tooling/inspect/inspect-report.types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect-report.types.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/inspect/inspect-report.types.ts"],"mappings":";;;;;;;;;;;;;;;;;qBAkBa;;qBAGA;;YAaD,yBAAyB;;YAGzB,aAAa;;YAGb;;EAEV;;EAEA;IAAuB;;;EAEvB;;;YAIU;;EAEV;;EAEA;;EAEA;;;YAIU;;EAEV;;EAEA;;EAEA;;;YAIU;EACV;EACA;EACA;EACA,QAAQ;;;YAIE;;EAEV;EACA;EACA;;EAEA;;EAEA;EACA;;EAEA;;EAEA;EACA,MAAM;;EAEN;EACA,WAAW;EACX,SAAS;EACT;IACE,YAAY;;IAEZ,MAAM;;IAEN;;;EAGF,WAAW;IAAiB;IAAqB,QAAQ;;;;YAI/C;EACV;EACA;EACA,QAAQ;;;YAIE;EACV;EACA;;EAEA;EACA;EACA;;;YAIU;EACV;EACA;EACA;;EAEA;EACA;;EAEA;EACA,SAAS;EACT,WAAW;;EAEX;EACA;EACA;EACA;EACA;;;YAIU;EACV;;EAEA,QAAQ;;EAER;;;YAIU;EACV;;EAEA;;EAEA;;;YAIU;EACV;EACA;IAAa;IAAc;;;;YAIjB;EACV;EACA;EACA;;EAEA;;EAEA;;EAEA;;EAEA;;;YAIU;EACV;EACA;EACA;EACA;IAAoB;IAAc;;EAClC;EACA;;;YAIU;EACV;EACA;EACA,WAAW;EACX;;;YAIU;EACV;EACA;;;YAIU;EACV,MAAM;EACN;;EAEA;;;YAIU;EACV,sBAAsB;EACtB;EACA;IACE;IACA;;IAEA;IACA;IACA;IACA;;;EAGF,UAAU;EACV,SAAS;EACT,SAAS;EACT,YAAY;EACZ,SAAS;EACT,SAAS;EACT,QAAQ;EACR,OAAO;EACP,YAAY;EACZ,WAAW;;EAEX;IAAc,SAAS,eAAe;;EACtC,UAAU"}

package/esm/tooling/inspect/inspect-report.types.mjs

@@ -0,0 +1,33 @@
+//#region ../../packages/core/src/tooling/inspect/inspect-report.types.ts
+/**
+* @fileoverview The `warlock inspect` report, schema version 1.
+*
+* STABILITY: within `schemaVersion: 1` fields are only ever ADDED. No field is
+* removed, renamed or retyped, so a consumer written against this file keeps
+* working on every later 5.x release. Consumers must ignore keys they do not
+* know. A change that breaks that promise ships as `schemaVersion: 2` and is
+* listed under BREAKING in the changelog. Free text (warning messages,
+* descriptions) is not part of the contract.
+*
+* The same shape is published as JSON Schema (draft 2020-12) in
+* `@warlock.js/core/schemas/inspect-report.schema.json` and as the
+* `INSPECT_REPORT_JSON_SCHEMA` constant.
+*/
+/** The version of the report shape. Bumped only for a breaking change. */
+const INSPECT_SCHEMA_VERSION = 1;
+/** Every section the report can contain, in output order. */
+const INSPECT_SECTIONS = [
+	"routes",
+	"models",
+	"resources",
+	"config",
+	"events",
+	"pages",
+	"jobs",
+	"schedules",
+	"packages"
+];
+
+//#endregion
+export { INSPECT_SCHEMA_VERSION, INSPECT_SECTIONS };
+//# sourceMappingURL=inspect-report.types.mjs.map

package/esm/tooling/inspect/inspect-report.types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect-report.types.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/inspect/inspect-report.types.ts"],"sourcesContent":["import type { WarlockErrorCode } from \"../../errors/error-codes\";\n\n/**\n * @fileoverview The `warlock inspect` report, schema version 1.\n *\n * STABILITY: within `schemaVersion: 1` fields are only ever ADDED. No field is\n * removed, renamed or retyped, so a consumer written against this file keeps\n * working on every later 5.x release. Consumers must ignore keys they do not\n * know. A change that breaks that promise ships as `schemaVersion: 2` and is\n * listed under BREAKING in the changelog. Free text (warning messages,\n * descriptions) is not part of the contract.\n *\n * The same shape is published as JSON Schema (draft 2020-12) in\n * `@warlock.js/core/schemas/inspect-report.schema.json` and as the\n * `INSPECT_REPORT_JSON_SCHEMA` constant.\n */\n\n/** The version of the report shape. Bumped only for a breaking change. */\nexport const INSPECT_SCHEMA_VERSION = 1;\n\n/** Every section the report can contain, in output order. */\nexport const INSPECT_SECTIONS = [\n  \"routes\",\n  \"models\",\n  \"resources\",\n  \"config\",\n  \"events\",\n  \"pages\",\n  \"jobs\",\n  \"schedules\",\n  \"packages\",\n] as const;\n\n/** One section name. */\nexport type InspectSection = (typeof INSPECT_SECTIONS)[number];\n\n/** A JSON Schema (draft 2020-12) fragment. */\nexport type JsonSchema = Record<string, unknown>;\n\n/** Who guards a route, from the descriptor `authMiddleware()` attaches. */\nexport type InspectRouteAuth = {\n  /** Whether an auth guard runs on the route. */\n  required: boolean;\n  /** Where the token is read: `\"header\"` (bearer) or `{ cookie }`. */\n  sources: (\"header\" | { cookie: string })[];\n  /** User types the guard accepts; empty means any. */\n  userTypes: string[];\n};\n\n/** The rate limit a route runs under. */\nexport type InspectRouteRateLimit = {\n  /** `route` = the route's own option, `global` = `http.rateLimit`, `none` = no limiter. */\n  source: \"route\" | \"global\" | \"none\";\n  /** Max requests per window; `\"dynamic\"` when configured as a function. */\n  max: number | \"dynamic\" | null;\n  /** Window in milliseconds, or the configured string (`\"1 minute\"`); `\"dynamic\"` for a function. */\n  timeWindow: number | string | null;\n};\n\n/** What the route's request log entries keep. */\nexport type InspectRouteLogging = {\n  /** Whether the request body is logged. */\n  body: boolean;\n  /** Whether the query string is logged. */\n  query: boolean;\n  /** Whether `http.logging.private` rules exist that may remove more for some URLs. */\n  privateRules: boolean;\n};\n\n/** One request parameter (path, query or header). */\nexport type InspectParameter = {\n  name: string;\n  in: \"path\" | \"query\" | \"header\" | \"cookie\";\n  required: boolean;\n  schema: JsonSchema;\n};\n\n/** One registered HTTP route. */\nexport type InspectRoute = {\n  /** Uppercase method, `ALL` for `router.all`. */\n  method: string;\n  path: string;\n  name: string | null;\n  /** Project-relative file that registered the route. */\n  sourceFile: string | null;\n  /** Handler function name, `\"anonymous\"` when it has none. */\n  handler: string;\n  description: string | null;\n  /** Whether a page (SSR) route registered it. */\n  isPage: boolean;\n  /** Middleware function names in run order. */\n  middleware: string[];\n  auth: InspectRouteAuth;\n  /** `false` when the route opted out of the CSRF origin guard (`csrf: false`). */\n  csrf: boolean;\n  rateLimit: InspectRouteRateLimit;\n  logging: InspectRouteLogging;\n  request: {\n    parameters: InspectParameter[];\n    /** JSON Schema of the request body, or `null`. */\n    body: JsonSchema | null;\n    /** Whether `validation.validate` (custom middleware, not described) is set. */\n    customValidation: boolean;\n  };\n  /** Declared responses keyed by status code. */\n  responses: Record<string, { description: string; schema: JsonSchema | null }>;\n};\n\n/** One model column, from the model's Seal `schema`. */\nexport type InspectModelColumn = {\n  name: string;\n  required: boolean;\n  schema: JsonSchema;\n};\n\n/** One model relation. */\nexport type InspectModelRelation = {\n  name: string;\n  type: string;\n  /** Target model name, or `null` when it could not be resolved. */\n  model: string | null;\n  foreignKey: string | null;\n  localKey: string | null;\n};\n\n/** One model class. */\nexport type InspectModel = {\n  name: string;\n  table: string | null;\n  primaryKey: string | null;\n  /** Data source name, when configured by name. */\n  dataSource: string | null;\n  sourceFile: string | null;\n  /** Whether `@RegisterModel()` put it in the registry. */\n  registered: boolean;\n  columns: InspectModelColumn[];\n  relations: InspectModelRelation[];\n  /** Name of the model's `static resource`, a key of `components.schemas`. */\n  resource: string | null;\n  deleteStrategy: string | null;\n  createdAtColumn: string | null;\n  updatedAtColumn: string | null;\n  deletedAtColumn: string | null;\n};\n\n/** One resource class reached from a route or a model. */\nexport type InspectResource = {\n  name: string;\n  /** Its output shape (JSON Schema; nested resources are `$ref`s into `components.schemas`). */\n  schema: JsonSchema;\n  /** Models whose `static resource` is this resource. */\n  models: string[];\n};\n\n/** One config key: its path and value type. Values are never printed. */\nexport type InspectConfigKey = {\n  key: string;\n  /** `string`, `number`, `boolean`, `null`, `array`, `object`, `function`, `regexp`, `date`, or a class name. */\n  type: string;\n  /** The `src/config/*` file the top-level key comes from, when it exists. */\n  file: string | null;\n};\n\n/** One event and the listeners app modules registered for it. */\nexport type InspectEvent = {\n  event: string;\n  listeners: { name: string; sourceFile: string }[];\n};\n\n/** One page installed by `@warlock.js/web`. */\nexport type InspectPage = {\n  path: string;\n  name: string | null;\n  file: string;\n  /** Layout files from the outermost to the page's own directory. */\n  layouts: string[];\n  /** Files on the chain (layouts, then the page) that export a `loader`. */\n  loaders: string[];\n  /** Action names the page exports (`\"default\"` for `action`). */\n  actions: string[];\n  /** `\"user\"` when the page or a layout statically requires a user. */\n  guard: string | null;\n};\n\n/** One queue job defined with `defineJob()`. */\nexport type InspectJob = {\n  name: string;\n  queue: string;\n  attempts: number | null;\n  backoff: number | { type: string; delay: number } | null;\n  removeOnComplete: boolean | number | null;\n  removeOnFail: boolean | number | null;\n};\n\n/** One scheduled task on the `@warlock.js/scheduler` scheduler. */\nexport type InspectSchedule = {\n  name: string;\n  cron: string | null;\n  intervals: Record<string, unknown>;\n  nextRun: string | null;\n};\n\n/** One installed `@warlock.js/*` package. */\nexport type InspectPackage = {\n  name: string;\n  version: string;\n};\n\n/** Something inspect could not read, with its code when one applies. */\nexport type InspectWarning = {\n  code: WarlockErrorCode | null;\n  message: string;\n  /** The section or file it concerns. */\n  source: string | null;\n};\n\n/** The whole report. Sections not requested are absent. */\nexport type InspectReport = {\n  schemaVersion: typeof INSPECT_SCHEMA_VERSION;\n  generatedAt: string;\n  app: {\n    name: string | null;\n    version: string | null;\n    /** Absolute project root. */\n    root: string;\n    node: string;\n    environment: string;\n    runtimeStrategy: string;\n  };\n  /** The sections this report contains. */\n  sections: InspectSection[];\n  routes?: InspectRoute[];\n  models?: InspectModel[];\n  resources?: InspectResource[];\n  config?: InspectConfigKey[];\n  events?: InspectEvent[];\n  pages?: InspectPage[];\n  jobs?: InspectJob[];\n  schedules?: InspectSchedule[];\n  packages?: InspectPackage[];\n  /** Shared schemas that `$ref`s point at (`#/components/schemas/<name>`). */\n  components: { schemas: Record<string, JsonSchema> };\n  warnings: InspectWarning[];\n};\n"],"mappings":";;;;;;;;;;;;;;;;AAkBA,MAAa,yBAAyB;;AAGtC,MAAa,mBAAmB;CAC9B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF"}

package/esm/tooling/mcp/create-mcp-context.d.mts

@@ -0,0 +1,29 @@
+import { InspectReport, InspectSection } from "../inspect/inspect-report.types.mjs";
+import { ConnectDevtoolsOptions } from "../devtools/devtools-client.mjs";
+import { WarlockMcpContext } from "./mcp-tools.mjs";
+//#region ../../packages/core/src/tooling/mcp/create-mcp-context.d.ts
+/** Options of {@link createMcpContext}. */
+export type CreateMcpContextOptions = {
+  /** Project root. Default: `process.cwd()`. */
+  cwd?: string;
+  /** Let generate tools write into the project. Default `false`. */
+  allowWrites?: boolean;
+  /** How the app is described: a booted snapshot (`warlock mcp`) or the live process (`warlock dev --mcp`). */
+  inspect: (sections: readonly InspectSection[]) => Promise<InspectReport>;
+  /**
+   * The `warlock` CLI script. Runs the typecheck in a child process (so a heap
+   * overflow cannot end the server) and the generators. Default: core's bin.
+   */
+  cliEntry?: string;
+  /** Where the dev server is, for `requests_recent`. Default: `.warlock/dev-server.json`. */
+  devtools?: Omit<ConnectDevtoolsOptions, "cwd">;
+  /** The `warlock add` feature names to advertise. */
+  features?: readonly string[];
+};
+/**
+ * The real {@link WarlockMcpContext}: `warlock check`, `runTests`, the devtools
+ * client, the sandboxed generators and the installed-docs corpus (loaded once).
+ */
+export declare function createMcpContext(options: CreateMcpContextOptions): WarlockMcpContext;
+//#endregion
+//# sourceMappingURL=create-mcp-context.d.mts.map

package/esm/tooling/mcp/create-mcp-context.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-mcp-context.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/mcp/create-mcp-context.ts"],"mappings":";;;;;YAYY;;EAEV;;EAEA;;EAEA,UAAU,mBAAmB,qBAAqB,QAAQ;;;;;EAK1D;;EAEA,WAAW,KAAK;;EAEhB;;;;;;wBAgBc,iBAAiB,SAAS,0BAA0B"}

package/esm/tooling/mcp/create-mcp-context.mjs

@@ -0,0 +1,75 @@
+import { WarlockError } from "../../errors/warlock-error.mjs";
+import { runCheck } from "../check/run-check.mjs";
+import { childTypecheckRunner } from "../../cli/commands/check/child-typecheck.mjs";
+import { connectDevtools } from "../devtools/devtools-client.mjs";
+import { runTests } from "../check/run-tests.mjs";
+import { resolveCliEntry } from "../generate/run-cli.mjs";
+import { applyGeneration, sandboxBackend } from "../generate/generation.mjs";
+import "../generate/index.mjs";
+import { loadDocsCorpus } from "./docs-search.mjs";
+import path from "node:path";
+
+//#region ../../packages/core/src/tooling/mcp/create-mcp-context.ts
+/** The project's `warlock` bin, or `undefined` (the generators then report the problem when used). */
+function findCliEntry(cwd) {
+	try {
+		return resolveCliEntry(cwd);
+	} catch {
+		return;
+	}
+}
+/**
+* The real {@link WarlockMcpContext}: `warlock check`, `runTests`, the devtools
+* client, the sandboxed generators and the installed-docs corpus (loaded once).
+*/
+function createMcpContext(options) {
+	const cwd = path.resolve(options.cwd ?? process.cwd());
+	const allowWrites = options.allowWrites === true;
+	const cliEntry = options.cliEntry ?? findCliEntry(cwd);
+	const sandbox = sandboxBackend(cliEntry ? { cliEntry } : {});
+	let corpus;
+	return {
+		cwd,
+		allowWrites,
+		inspect: options.inspect,
+		check: ({ changed, base, skip }) => {
+			const flags = [...changed ? ["--changed"] : [], ...base ? ["--base", base] : []];
+			return runCheck({
+				cwd,
+				changed,
+				base,
+				skip,
+				...cliEntry ? { typecheck: childTypecheckRunner(cliEntry, flags) } : {}
+			});
+		},
+		tests: ({ files, changed, base }) => runTests({
+			cwd,
+			files,
+			changed,
+			base
+		}),
+		devtools: () => connectDevtools({
+			cwd,
+			...options.devtools
+		}),
+		generation: {
+			plan: (spec) => sandbox.plan(spec, { cwd }),
+			apply: async (spec) => {
+				if (!allowWrites) throw new WarlockError("WL7005", "This MCP server is read-only; restart it with --allow-writes to let generate tools write.");
+				return applyGeneration(spec, {
+					cwd,
+					...cliEntry ? { cliEntry } : {}
+				});
+			}
+		},
+		docs: () => {
+			corpus ??= loadDocsCorpus(cwd);
+			return corpus;
+		},
+		features: options.features
+	};
+}
+
+//#endregion
+export { createMcpContext };
+//# sourceMappingURL=create-mcp-context.mjs.map

package/esm/tooling/mcp/create-mcp-context.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-mcp-context.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/mcp/create-mcp-context.ts"],"sourcesContent":["import path from \"node:path\";\nimport { childTypecheckRunner } from \"../../cli/commands/check/child-typecheck\";\nimport { WarlockError } from \"../../errors/warlock-error\";\nimport { runCheck } from \"../check/run-check\";\nimport { runTests } from \"../check/run-tests\";\nimport { connectDevtools, type ConnectDevtoolsOptions } from \"../devtools/devtools-client\";\nimport { applyGeneration, resolveCliEntry, sandboxBackend } from \"../generate\";\nimport type { InspectReport, InspectSection } from \"../inspect/inspect-report.types\";\nimport { type DocsCorpus, loadDocsCorpus } from \"./docs-search\";\nimport type { WarlockMcpContext } from \"./mcp-tools\";\n\n/** Options of {@link createMcpContext}. */\nexport type CreateMcpContextOptions = {\n  /** Project root. Default: `process.cwd()`. */\n  cwd?: string;\n  /** Let generate tools write into the project. Default `false`. */\n  allowWrites?: boolean;\n  /** How the app is described: a booted snapshot (`warlock mcp`) or the live process (`warlock dev --mcp`). */\n  inspect: (sections: readonly InspectSection[]) => Promise<InspectReport>;\n  /**\n   * The `warlock` CLI script. Runs the typecheck in a child process (so a heap\n   * overflow cannot end the server) and the generators. Default: core's bin.\n   */\n  cliEntry?: string;\n  /** Where the dev server is, for `requests_recent`. Default: `.warlock/dev-server.json`. */\n  devtools?: Omit<ConnectDevtoolsOptions, \"cwd\">;\n  /** The `warlock add` feature names to advertise. */\n  features?: readonly string[];\n};\n\n/** The project's `warlock` bin, or `undefined` (the generators then report the problem when used). */\nfunction findCliEntry(cwd: string): string | undefined {\n  try {\n    return resolveCliEntry(cwd);\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * The real {@link WarlockMcpContext}: `warlock check`, `runTests`, the devtools\n * client, the sandboxed generators and the installed-docs corpus (loaded once).\n */\nexport function createMcpContext(options: CreateMcpContextOptions): WarlockMcpContext {\n  const cwd = path.resolve(options.cwd ?? process.cwd());\n  const allowWrites = options.allowWrites === true;\n  const cliEntry = options.cliEntry ?? findCliEntry(cwd);\n  const sandbox = sandboxBackend(cliEntry ? { cliEntry } : {});\n  let corpus: Promise<DocsCorpus> | undefined;\n\n  return {\n    cwd,\n    allowWrites,\n    inspect: options.inspect,\n    check: ({ changed, base, skip }) => {\n      const flags = [...(changed ? [\"--changed\"] : []), ...(base ? [\"--base\", base] : [])];\n\n      return runCheck({\n        cwd,\n        changed,\n        base,\n        skip,\n        ...(cliEntry ? { typecheck: childTypecheckRunner(cliEntry, flags) } : {}),\n      });\n    },\n    tests: ({ files, changed, base }) => runTests({ cwd, files, changed, base }),\n    devtools: () => connectDevtools({ cwd, ...options.devtools }),\n    generation: {\n      plan: (spec) => sandbox.plan(spec, { cwd }),\n      apply: async (spec) => {\n        if (!allowWrites) {\n          throw new WarlockError(\n            \"WL7005\",\n            \"This MCP server is read-only; restart it with --allow-writes to let generate tools write.\",\n          );\n        }\n\n        return applyGeneration(spec, { cwd, ...(cliEntry ? { cliEntry } : {}) });\n      },\n    },\n    docs: () => {\n      corpus ??= loadDocsCorpus(cwd);\n\n      return corpus;\n    },\n    features: options.features,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;AA+BA,SAAS,aAAa,KAAiC;CACrD,IAAI;EACF,OAAO,gBAAgB,GAAG;CAC5B,QAAQ;EACN;CACF;AACF;;;;;AAMA,SAAgB,iBAAiB,SAAqD;CACpF,MAAM,MAAM,KAAK,QAAQ,QAAQ,OAAO,QAAQ,IAAI,CAAC;CACrD,MAAM,cAAc,QAAQ,gBAAgB;CAC5C,MAAM,WAAW,QAAQ,YAAY,aAAa,GAAG;CACrD,MAAM,UAAU,eAAe,WAAW,EAAE,SAAS,IAAI,CAAC,CAAC;CAC3D,IAAI;CAEJ,OAAO;EACL;EACA;EACA,SAAS,QAAQ;EACjB,QAAQ,EAAE,SAAS,MAAM,WAAW;GAClC,MAAM,QAAQ,CAAC,GAAI,UAAU,CAAC,WAAW,IAAI,CAAC,GAAI,GAAI,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC,CAAE;GAEnF,OAAO,SAAS;IACd;IACA;IACA;IACA;IACA,GAAI,WAAW,EAAE,WAAW,qBAAqB,UAAU,KAAK,EAAE,IAAI,CAAC;GACzE,CAAC;EACH;EACA,QAAQ,EAAE,OAAO,SAAS,WAAW,SAAS;GAAE;GAAK;GAAO;GAAS;EAAK,CAAC;EAC3E,gBAAgB,gBAAgB;GAAE;GAAK,GAAG,QAAQ;EAAS,CAAC;EAC5D,YAAY;GACV,OAAO,SAAS,QAAQ,KAAK,MAAM,EAAE,IAAI,CAAC;GAC1C,OAAO,OAAO,SAAS;IACrB,IAAI,CAAC,aACH,MAAM,IAAI,aACR,UACA,2FACF;IAGF,OAAO,gBAAgB,MAAM;KAAE;KAAK,GAAI,WAAW,EAAE,SAAS,IAAI,CAAC;IAAG,CAAC;GACzE;EACF;EACA,YAAY;GACV,WAAW,eAAe,GAAG;GAE7B,OAAO;EACT;EACA,UAAU,QAAQ;CACpB;AACF"}

package/esm/tooling/mcp/db-schema.d.mts

@@ -0,0 +1,50 @@
+import { InspectModel, JsonSchema } from "../inspect/inspect-report.types.mjs";
+//#region ../../packages/core/src/tooling/mcp/db-schema.d.ts
+/** One column of a {@link DbSchemaTable}. */
+export type DbSchemaColumn = {
+  name: string;
+  /** The JSON Schema `type` (`string`, `integer`, …), `format` appended when set (`string:date-time`). */
+  type: string;
+  required: boolean;
+  primaryKey: boolean;
+  /** Set when a `belongsTo` relation uses this column. */
+  references: {
+    model: string | null;
+    column: string | null;
+  } | null;
+  schema: JsonSchema;
+};
+/** One table, as the app's models declare it. */
+export type DbSchemaTable = {
+  table: string | null;
+  model: string;
+  dataSource: string | null;
+  sourceFile: string | null;
+  primaryKey: string | null;
+  columns: DbSchemaColumn[];
+  relations: InspectModel["relations"];
+  timestamps: {
+    createdAt: string | null;
+    updatedAt: string | null;
+    deletedAt: string | null;
+  };
+  deleteStrategy: string | null;
+};
+/** What the `db_schema` tool returns. */
+export type DbSchema = {
+  /** Where the facts come from: the models' Seal schemas, not the live database. */
+  source: "models";
+  tables: DbSchemaTable[];
+};
+/**
+ * The database schema the models declare: one table per model with its
+ * columns (from the model's Seal `schema`), primary key, foreign keys of its
+ * `belongsTo` relations, relations, timestamp columns and delete strategy.
+ *
+ * Built from `inspectApp()`'s `models` section — the declared shape, which is
+ * what code is written against. It does not open a database connection, so
+ * columns that exist only in a migration are not listed.
+ */
+export declare function buildDbSchema(models: readonly InspectModel[], filter?: string): DbSchema;
+//#endregion
+//# sourceMappingURL=db-schema.d.mts.map

package/esm/tooling/mcp/db-schema.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-schema.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/mcp/db-schema.ts"],"mappings":";;;YAGY;EACV;;EAEA;EACA;EACA;;EAEA;IAAc;IAAsB;;EACpC,QAAQ;;;YAIE;EACV;EACA;EACA;EACA;EACA;EACA,SAAS;EACT,WAAW;EACX;IAAc;IAA0B;IAA0B;;EAClE;;;YAIU;;EAEV;EACA,QAAQ;;;;;;;;;;;wBAwBM,cAAc,iBAAiB,gBAAgB,kBAAkB"}

package/esm/tooling/mcp/db-schema.mjs

@@ -0,0 +1,56 @@
+//#region ../../packages/core/src/tooling/mcp/db-schema.ts
+function columnType(schema) {
+	const type = schema.type;
+	return `${Array.isArray(type) ? type.filter((entry) => typeof entry === "string").join("|") : typeof type === "string" ? type : "unknown"}${typeof schema.format === "string" ? `:${schema.format}` : ""}`;
+}
+/**
+* The database schema the models declare: one table per model with its
+* columns (from the model's Seal `schema`), primary key, foreign keys of its
+* `belongsTo` relations, relations, timestamp columns and delete strategy.
+*
+* Built from `inspectApp()`'s `models` section — the declared shape, which is
+* what code is written against. It does not open a database connection, so
+* columns that exist only in a migration are not listed.
+*/
+function buildDbSchema(models, filter) {
+	const wanted = filter?.toLowerCase();
+	return {
+		source: "models",
+		tables: models.filter((model) => !wanted || model.name.toLowerCase() === wanted || (model.table ?? "").toLowerCase() === wanted).map((model) => {
+			const foreignKeys = new Map(model.relations.filter((relation) => relation.type === "belongsTo" && relation.foreignKey).map((relation) => [relation.foreignKey, relation]));
+			const columns = model.columns.map((column) => {
+				const relation = foreignKeys.get(column.name);
+				return {
+					name: column.name,
+					type: columnType(column.schema),
+					required: column.required,
+					primaryKey: column.name === model.primaryKey,
+					references: relation ? {
+						model: relation.model,
+						column: relation.localKey ?? "id"
+					} : null,
+					schema: column.schema
+				};
+			});
+			return {
+				table: model.table,
+				model: model.name,
+				dataSource: model.dataSource,
+				sourceFile: model.sourceFile,
+				primaryKey: model.primaryKey,
+				columns,
+				relations: model.relations,
+				timestamps: {
+					createdAt: model.createdAtColumn,
+					updatedAt: model.updatedAtColumn,
+					deletedAt: model.deletedAtColumn
+				},
+				deleteStrategy: model.deleteStrategy
+			};
+		}).sort((first, second) => (first.table ?? first.model).localeCompare(second.table ?? second.model))
+	};
+}
+
+//#endregion
+export { buildDbSchema };
+//# sourceMappingURL=db-schema.mjs.map

package/esm/tooling/mcp/db-schema.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-schema.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/mcp/db-schema.ts"],"sourcesContent":["import type { InspectModel, JsonSchema } from \"../inspect/inspect-report.types\";\n\n/** One column of a {@link DbSchemaTable}. */\nexport type DbSchemaColumn = {\n  name: string;\n  /** The JSON Schema `type` (`string`, `integer`, …), `format` appended when set (`string:date-time`). */\n  type: string;\n  required: boolean;\n  primaryKey: boolean;\n  /** Set when a `belongsTo` relation uses this column. */\n  references: { model: string | null; column: string | null } | null;\n  schema: JsonSchema;\n};\n\n/** One table, as the app's models declare it. */\nexport type DbSchemaTable = {\n  table: string | null;\n  model: string;\n  dataSource: string | null;\n  sourceFile: string | null;\n  primaryKey: string | null;\n  columns: DbSchemaColumn[];\n  relations: InspectModel[\"relations\"];\n  timestamps: { createdAt: string | null; updatedAt: string | null; deletedAt: string | null };\n  deleteStrategy: string | null;\n};\n\n/** What the `db_schema` tool returns. */\nexport type DbSchema = {\n  /** Where the facts come from: the models' Seal schemas, not the live database. */\n  source: \"models\";\n  tables: DbSchemaTable[];\n};\n\nfunction columnType(schema: JsonSchema): string {\n  const type = schema.type;\n  const name = Array.isArray(type)\n    ? type.filter((entry): entry is string => typeof entry === \"string\").join(\"|\")\n    : typeof type === \"string\"\n      ? type\n      : \"unknown\";\n  const format = typeof schema.format === \"string\" ? `:${schema.format}` : \"\";\n\n  return `${name}${format}`;\n}\n\n/**\n * The database schema the models declare: one table per model with its\n * columns (from the model's Seal `schema`), primary key, foreign keys of its\n * `belongsTo` relations, relations, timestamp columns and delete strategy.\n *\n * Built from `inspectApp()`'s `models` section — the declared shape, which is\n * what code is written against. It does not open a database connection, so\n * columns that exist only in a migration are not listed.\n */\nexport function buildDbSchema(models: readonly InspectModel[], filter?: string): DbSchema {\n  const wanted = filter?.toLowerCase();\n\n  const tables = models\n    .filter(\n      (model) =>\n        !wanted ||\n        model.name.toLowerCase() === wanted ||\n        (model.table ?? \"\").toLowerCase() === wanted,\n    )\n    .map((model): DbSchemaTable => {\n      const foreignKeys = new Map(\n        model.relations\n          .filter((relation) => relation.type === \"belongsTo\" && relation.foreignKey)\n          .map((relation) => [relation.foreignKey, relation]),\n      );\n      const columns = model.columns.map((column): DbSchemaColumn => {\n        const relation = foreignKeys.get(column.name);\n\n        return {\n          name: column.name,\n          type: columnType(column.schema),\n          required: column.required,\n          primaryKey: column.name === model.primaryKey,\n          references: relation\n            ? { model: relation.model, column: relation.localKey ?? \"id\" }\n            : null,\n          schema: column.schema,\n        };\n      });\n\n      return {\n        table: model.table,\n        model: model.name,\n        dataSource: model.dataSource,\n        sourceFile: model.sourceFile,\n        primaryKey: model.primaryKey,\n        columns,\n        relations: model.relations,\n        timestamps: {\n          createdAt: model.createdAtColumn,\n          updatedAt: model.updatedAtColumn,\n          deletedAt: model.deletedAtColumn,\n        },\n        deleteStrategy: model.deleteStrategy,\n      };\n    })\n    .sort((first, second) =>\n      (first.table ?? first.model).localeCompare(second.table ?? second.model),\n    );\n\n  return { source: \"models\", tables };\n}\n"],"mappings":";AAkCA,SAAS,WAAW,QAA4B;CAC9C,MAAM,OAAO,OAAO;CAQpB,OAAO,GAPM,MAAM,QAAQ,IAAI,IAC3B,KAAK,QAAQ,UAA2B,OAAO,UAAU,QAAQ,CAAC,CAAC,KAAK,GAAG,IAC3E,OAAO,SAAS,WACd,OACA,YACS,OAAO,OAAO,WAAW,WAAW,IAAI,OAAO,WAAW;AAG3E;;;;;;;;;;AAWA,SAAgB,cAAc,QAAiC,QAA2B;CACxF,MAAM,SAAS,QAAQ,YAAY;CAkDnC,OAAO;EAAE,QAAQ;EAAU,QAhDZ,OACZ,QACE,UACC,CAAC,UACD,MAAM,KAAK,YAAY,MAAM,WAC5B,MAAM,SAAS,GAAE,CAAE,YAAY,MAAM,MAC1C,CAAC,CACA,KAAK,UAAyB;GAC7B,MAAM,cAAc,IAAI,IACtB,MAAM,UACH,QAAQ,aAAa,SAAS,SAAS,eAAe,SAAS,UAAU,CAAC,CAC1E,KAAK,aAAa,CAAC,SAAS,YAAY,QAAQ,CAAC,CACtD;GACA,MAAM,UAAU,MAAM,QAAQ,KAAK,WAA2B;IAC5D,MAAM,WAAW,YAAY,IAAI,OAAO,IAAI;IAE5C,OAAO;KACL,MAAM,OAAO;KACb,MAAM,WAAW,OAAO,MAAM;KAC9B,UAAU,OAAO;KACjB,YAAY,OAAO,SAAS,MAAM;KAClC,YAAY,WACR;MAAE,OAAO,SAAS;MAAO,QAAQ,SAAS,YAAY;KAAK,IAC3D;KACJ,QAAQ,OAAO;IACjB;GACF,CAAC;GAED,OAAO;IACL,OAAO,MAAM;IACb,OAAO,MAAM;IACb,YAAY,MAAM;IAClB,YAAY,MAAM;IAClB,YAAY,MAAM;IAClB;IACA,WAAW,MAAM;IACjB,YAAY;KACV,WAAW,MAAM;KACjB,WAAW,MAAM;KACjB,WAAW,MAAM;IACnB;IACA,gBAAgB,MAAM;GACxB;EACF,CAAC,CAAC,CACD,MAAM,OAAO,YACX,MAAM,SAAS,MAAM,MAAK,CAAE,cAAc,OAAO,SAAS,OAAO,KAAK,CAG3C;CAAE;AACpC"}

package/esm/tooling/mcp/docs-search.d.mts

@@ -0,0 +1,77 @@
+//#region ../../packages/core/src/tooling/mcp/docs-search.d.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. */
+export declare const DOCS_CORPUS_GLOBS: readonly ["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"];
+/** One searchable section: a file split at its markdown headings. */
+export type DocsSection = {
+  /** `@warlock.js/<name>`. */
+  package: string;
+  /** Project-relative POSIX path of the file. */
+  file: string;
+  /** `skill`, `readme` or `llms`. */
+  source: "skill" | "readme" | "llms";
+  /** The section heading, or the file name for text before the first heading. */
+  heading: string;
+  /** 1-based line where the section starts. */
+  line: number;
+  text: string;
+};
+/** One search hit. */
+export type DocsSearchHit = {
+  package: string;
+  file: string;
+  source: DocsSection["source"];
+  heading: string;
+  line: number;
+  score: number;
+  /** The section's lines around the first match, bounded. */
+  excerpt: string;
+};
+/** The loaded corpus. */
+export type DocsCorpus = {
+  files: string[];
+  sections: DocsSection[];
+};
+/** Split markdown text into heading-delimited sections. */
+export declare function splitSections(text: string, meta: {
+  package: string;
+  file: string;
+  source: DocsSection["source"];
+}): DocsSection[];
+/** Load the corpus of the app at `cwd`. Unreadable files are skipped. */
+export declare function loadDocsCorpus(cwd: string): Promise<DocsCorpus>;
+/** Lower-cased search terms of two or more characters. */
+export declare function searchTerms(query: string): string[];
+/**
+ * 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.
+ */
+export declare function searchDocs(corpus: DocsCorpus, query: string, options?: {
+  limit?: number;
+  package?: string;
+}): DocsSearchHit[];
+/**
+ * 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.
+ */
+export declare function readDocsFile(corpus: DocsCorpus, cwd: string, file: string, options?: {
+  heading?: string;
+  maxBytes?: number;
+}): {
+  file: string;
+  heading: string | null;
+  text: string;
+  truncated: boolean;
+} | undefined;
+//#endregion
+//# sourceMappingURL=docs-search.d.mts.map

package/esm/tooling/mcp/docs-search.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-search.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/mcp/docs-search.ts"],"mappings":";;;;;;;;qBAYa;;YAQD;;EAEV;;EAEA;;EAEA;;EAEA;;EAEA;EACA;;;YAIU;EACV;EACA;EACA,QAAQ;EACR;EACA;EACA;;EAEA;;;YAIU;EACV;EACA,UAAU;;;wBAmBI,cACd,cACA;EAAQ;EAAiB;EAAc,QAAQ;IAC9C;;wBAoCmB,eAAe,cAAc,QAAQ;;wBAwB3C,YAAY;;;;;;;;wBA2CZ,WACd,QAAQ,YACR,eACA;EAAW;EAAgB;IAC1B;;;;;;;wBA4Da,aACd,QAAQ,YACR,aACA,cACA;EAAW;EAAkB;;EAC1B;EAAc;EAAwB;EAAc"}