@warlock.js/core 5.30.0 → 5.31.0

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,26 @@
+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}. */
+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).
+ */
+declare function createMcpContext(options: CreateMcpContextOptions): WarlockMcpContext;
+//#endregion
+export { CreateMcpContextOptions, createMcpContext };
+//# 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":";;;;;;KAYY,uBAAA;EAAA,8CAEV,GAAA;EAEA,WAAA,YAE0D;EAA1D,OAAA,GAAU,QAAA,WAAmB,cAAA,OAAqB,OAAA,CAAQ,aAAA;EAO1C;;;;EAFhB,QAAA,WAPA;EASA,QAAA,GAAW,IAAA,CAAK,sBAAA,UAPa;EAS7B,QAAA;AAAA;;;;;iBAgBc,gBAAA,CAAiB,OAAA,EAAS,uBAAA,GAA0B,iBAAiB"}

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,49 @@
+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}. */
+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. */
+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. */
+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.
+ */
+declare function buildDbSchema(models: readonly InspectModel[], filter?: string): DbSchema;
+//#endregion
+export { DbSchema, DbSchemaColumn, DbSchemaTable, buildDbSchema };
+//# 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":";;;;KAGY,cAAA;EACV,IAAA,UADwB;EAGxB,IAAA;EACA,QAAA;EACA,UAAA,WAFA;EAIA,UAAA;IAAc,KAAA;IAAsB,MAAA;EAAA;EACpC,MAAA,EAAQ,UAAU;AAAA;;KAIR,aAAA;EACV,KAAA;EACA,KAAA;EACA,UAAA;EACA,UAAA;EACA,UAAA;EACA,OAAA,EAAS,cAAA;EACT,SAAA,EAAW,YAAY;EACvB,UAAA;IAAc,SAAA;IAA0B,SAAA;IAA0B,SAAA;EAAA;EAClE,cAAA;AAAA;;KAIU,QAAA;EAL8B,kFAOxC,MAAA;EACA,MAAA,EAAQ,aAAa;AAAA;AAPP;AAIhB;;;;;;;;AAJgB,iBA+BA,aAAA,CAAc,MAAA,WAAiB,YAAA,IAAgB,MAAA,YAAkB,QAAQ"}

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,72 @@
+//#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. */
+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. */
+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. */
+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. */
+type DocsCorpus = {
+  files: string[];
+  sections: DocsSection[];
+};
+/** Split markdown text into heading-delimited sections. */
+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. */
+declare function loadDocsCorpus(cwd: string): Promise<DocsCorpus>;
+/** Lower-cased search terms of two or more characters. */
+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.
+ */
+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.
+ */
+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
+export { DOCS_CORPUS_GLOBS, DocsCorpus, DocsSearchHit, DocsSection, loadDocsCorpus, readDocsFile, searchDocs, searchTerms, splitSections };
+//# 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":";;AAYA;;;;AAKU;AAGV;AAAA,cARa,iBAAA;;KAQD,WAAA;EAEV,4BAAA,OAAA,UAIA;EAFA,IAAA,UAMA;EAJA,MAAA,+BAKI;EAHJ,OAAA,UAOU;EALV,IAAA;EACA,IAAA;AAAA;;KAIU,aAAA;EACV,OAAA;EACA,IAAA;EACA,MAAA,EAAQ,WAAW;EACnB,OAAA;EACA,IAAA;EACA,KAAA,UAEO;EAAP,OAAA;AAAA;;KAIU,UAAA;EACV,KAAA;EACA,QAAA,EAAU,WAAW;AAAA;;iBAmBP,aAAA,CACd,IAAA,UACA,IAAA;EAAQ,OAAA;EAAiB,IAAA;EAAc,MAAA,EAAQ,WAAA;AAAA,IAC9C,WAAW;;iBAoCQ,cAAA,CAAe,GAAA,WAAc,OAAO,CAAC,UAAA;;iBAwB3C,WAAA,CAAY,KAAa;;;;;;AA5D3B;AAoCd;iBAmEgB,UAAA,CACd,MAAA,EAAQ,UAAA,EACR,KAAA,UACA,OAAA;EAAW,KAAA;EAAgB,OAAA;AAAA,IAC1B,aAAa;;;;AAvEqD;AAwBrE;;iBA2GgB,YAAA,CACd,MAAA,EAAQ,UAAU,EAClB,GAAA,UACA,IAAA,UACA,OAAA;EAAW,OAAA;EAAkB,QAAA;AAAA;EAC1B,IAAA;EAAc,OAAA;EAAwB,IAAA;EAAc,SAAA;AAAA"}

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 {  };

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

@@ -0,0 +1,62 @@
+//#region ../../packages/core/src/tooling/mcp/load-ai-tools.d.ts
+/** The install line printed when the MCP transport packages are missing. */
+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`). */
+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. */
+type ServeTransportOptions = {
+  type: "stdio";
+} | {
+  type: "http";
+  host: string;
+  port: number;
+  path: string;
+  auth?: {
+    bearer: string;
+  };
+};
+/** The handle `start()` resolves. */
+type ServeHandle = {
+  url?: string;
+  close(): Promise<void>;
+};
+/** The slice of `@warlock.js/ai-tools` this command calls. */
+type AiToolsServeModule = {
+  serve(tools: ServeToolContract[], options: {
+    name: string;
+    version?: string;
+    transport: ServeTransportOptions;
+  }): {
+    start(): Promise<ServeHandle>;
+    stop(): Promise<void>;
+  };
+};
+/** Whether a loaded module exposes `serve()`. */
+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.
+ */
+declare function loadAiToolsServe(cwd: string, importer?: (specifier: string) => Promise<unknown>): Promise<AiToolsServeModule>;
+//#endregion
+export { AiToolsServeModule, MCP_INSTALL_HINT, ServeToolContract, ServeTransportOptions, isAiToolsServeModule, loadAiToolsServe };
+//# sourceMappingURL=load-ai-tools.d.mts.map