kizlo 0.20.2 → 0.22.0

package/dist/cli/mcp/schema.js

@@ -0,0 +1,212 @@
+//#region src/cli/mcp/schema.ts
+/** Where a converted definition is emitted, and the prefix a pointer to one carries. */
+const DEFS = "$defs";
+/**
+* Keywords that mean the same in both dialects and are copied straight across. The validation half
+* is what `SchemaCoercer` accepts on the WordPress side, so a bound the contract publishes reaches
+* the client that has to satisfy it instead of being dropped in translation.
+*/
+const COPIED = [
+	"title",
+	"description",
+	"deprecated",
+	"default",
+	"enum",
+	"format",
+	"pattern",
+	"minLength",
+	"maxLength",
+	"minItems",
+	"maxItems",
+	"minProperties",
+	"maxProperties",
+	"minimum",
+	"maximum",
+	"multipleOf",
+	"uniqueItems",
+	"exclusiveMinimum",
+	"exclusiveMaximum"
+];
+function run(document) {
+	return {
+		document,
+		defs: /* @__PURE__ */ new Map(),
+		extending: /* @__PURE__ */ new Set()
+	};
+}
+/**
+* Turn an introspection schema into the JSON Schema an MCP client validates a tool call against.
+*
+* Three things separate the two dialects. Introspection marks a field required on the field itself,
+* where JSON Schema lists the names on the object holding them. `$ref` and `$extends` name entries in
+* `document.schemas` rather than being JSON pointers, so both are rewritten here: a `$ref` becomes a
+* pointer into `$defs`, and an `$extends` is flattened. And `file` is not a JSON Schema type; it
+* becomes the `string`/`binary` pair OpenAPI uses for the same thing.
+*/
+function toJsonSchema(schema, document) {
+	const current = run(document);
+	return withDefs(convert(schema, current), current);
+}
+/**
+* The same, for an operation's request rather than one schema: each part it declares becomes a
+* property, so a caller validates and builds `{ params, query, body }` — the shape the request
+* builder takes. A part is required when the schema under it demands anything.
+*
+* The three parts share one run, so a definition two of them reach is emitted once at this root and
+* referenced from both rather than copied into each.
+*/
+function inputJsonSchema(input, document) {
+	const current = run(document);
+	const properties = {};
+	const required = [];
+	for (const part of [
+		"params",
+		"query",
+		"body"
+	]) {
+		const schema = input[part];
+		if (!schema) continue;
+		properties[part] = convert(schema, current);
+		if (schema.type === "object" ? demandsProperties(schema, document, /* @__PURE__ */ new Set()) : schema.required !== false) required.push(part);
+	}
+	return withDefs({
+		type: "object",
+		properties,
+		...required.length > 0 ? { required } : {}
+	}, current);
+}
+/** Attach what the result reached, so the schema a client receives can be read without the document. */
+function withDefs(schema, current) {
+	if (current.defs.size === 0) return schema;
+	return {
+		...schema,
+		[DEFS]: Object.fromEntries(current.defs)
+	};
+}
+/** Whether an object schema demands anything, through the references that carry its properties. */
+function demandsProperties(schema, document, seen) {
+	if (Object.values(schema.properties ?? {}).some((child) => child.required)) return true;
+	for (const id of [...schema.$ref ? [schema.$ref] : [], ...names(schema.$extends)]) {
+		const target = document.schemas[id];
+		if (!target || seen.has(id)) continue;
+		if (demandsProperties(target, document, new Set([...seen, id]))) return true;
+	}
+	return false;
+}
+/**
+* A schema is its own keywords laid over whatever it references, and the two kinds of reference are
+* rewritten differently. `$extends` is an overlay whose purpose is redeclaring an inherited property,
+* which a pointer cannot express, so its base is flattened and the schema's own keywords win.
+* `$ref` names the whole shape, so it stays a reference: one definition, pointed at from everywhere
+* that reaches it, which is what lets a schema describe its own recursion instead of being truncated.
+*/
+function convert(schema, current) {
+	let result = own(schema, current);
+	for (const id of names(schema.$extends)) result = merge(inline(id, current), result);
+	if (schema.$ref !== void 0) {
+		const pointer = define(schema.$ref, current);
+		if (pointer !== void 0) result = {
+			...result,
+			$ref: pointer
+		};
+	}
+	return schema.nullable ? widenToNull(result) : result;
+}
+/**
+* Let a converted schema accept `null`. A type takes it in place; a schema whose shape came from a
+* reference or a combinator has no type of its own to widen, so the union carries it instead.
+*/
+function widenToNull(schema) {
+	const type = schema.type;
+	if (typeof type === "string") return {
+		...schema,
+		type: [type, "null"]
+	};
+	if (Array.isArray(type)) return type.includes("null") ? schema : {
+		...schema,
+		type: [...type, "null"]
+	};
+	return { anyOf: [schema, { type: "null" }] };
+}
+/**
+* Ensure one `document.schemas` entry is defined, and answer with the pointer that addresses it.
+* Absent for a reference the document does not carry, which the caller leaves inlined.
+*/
+function define(id, current) {
+	const target = current.document.schemas[id];
+	if (!target) return void 0;
+	if (!current.defs.has(id)) {
+		current.defs.set(id, {});
+		current.defs.set(id, convert(target, current));
+	}
+	return `#/${DEFS}/${escapePointer(id)}`;
+}
+/** Resolve an `$extends` base for flattening, or the empty schema when it is absent or already open. */
+function inline(id, current) {
+	const target = current.document.schemas[id];
+	if (!target || current.extending.has(id)) return {};
+	current.extending.add(id);
+	try {
+		return convert(target, current);
+	} finally {
+		current.extending.delete(id);
+	}
+}
+/** RFC 6901 escaping, so an id carrying `~` or `/` still addresses the entry it named. */
+function escapePointer(id) {
+	return id.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+function names(value) {
+	if (value === void 0) return [];
+	return Array.isArray(value) ? value : [value];
+}
+/**
+* Lay `own` over `base`. Only the two keywords that describe an object's members combine: everything
+* else is a plain override, since a schema restating a `type` or a `description` means to replace it.
+*/
+function merge(base, own$1) {
+	const result = {
+		...base,
+		...own$1
+	};
+	const properties = {
+		...base.properties,
+		...own$1.properties
+	};
+	if (Object.keys(properties).length > 0) result.properties = properties;
+	const required = [...new Set([...base.required ?? [], ...own$1.required ?? []])];
+	if (required.length > 0) result.required = required;
+	return result;
+}
+/** The schema's own keywords, with the references it is built from left to {@link convert}. */
+function own(schema, current) {
+	const result = {};
+	for (const keyword of COPIED) {
+		const value = schema[keyword];
+		if (value !== void 0) result[keyword] = value;
+	}
+	if (schema.type === "file") {
+		result.type = "string";
+		result.format = "binary";
+	} else if (schema.type) result.type = schema.type;
+	if (schema.properties) {
+		const properties = {};
+		const required = [];
+		for (const [name, child] of Object.entries(schema.properties)) {
+			properties[name] = convert(child, current);
+			if (child.required) required.push(name);
+		}
+		result.properties = properties;
+		if (required.length > 0) result.required = required;
+	}
+	if (schema.items) result.items = convert(schema.items, current);
+	if (schema.anyOf) result.anyOf = schema.anyOf.map((member) => convert(member, current));
+	if (schema.oneOf) result.oneOf = schema.oneOf.map((member) => convert(member, current));
+	if (typeof schema.additionalProperties === "boolean") result.additionalProperties = schema.additionalProperties;
+	else if (schema.additionalProperties) result.additionalProperties = convert(schema.additionalProperties, current);
+	if (schema.patternProperties) result.patternProperties = Object.fromEntries(Object.entries(schema.patternProperties).map(([pattern, child]) => [pattern, convert(child, current)]));
+	return result;
+}
+
+//#endregion
+export { inputJsonSchema, toJsonSchema };

package/dist/cli/mcp/search.js

@@ -0,0 +1,255 @@
+import { routesOf, sortRoutes } from "./routes.js";
+import MiniSearch from "minisearch";
+
+//#region src/cli/mcp/search.ts
+/**
+* How deep a schema is walked for searchable terms. Deep enough to reach the properties an agent
+* would name, shallow enough that a broad contract does not turn one search into a tree walk.
+*/
+const MAX_DEPTH = 6;
+/** Methods that only read, which is what the read/write filter divides the catalog on. */
+const READ_METHODS = new Set([
+	"GET",
+	"HEAD",
+	"OPTIONS"
+]);
+/** Default page size, and the ceiling a caller may ask for. */
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+/**
+* How far below the best score in its tier a result may fall and still be returned.
+*
+* Terms are combined permissively, so one common token reaches an enormous number of routes: `post`
+* or `rest` alone selects most of a WordPress contract. Without a floor the tail of those matches is
+* counted as a match, and a caller told "504 of 504" learns nothing and has no reason to trust the
+* ranking. The floor is relative and applied within a tier, so it trims each tier's tail without
+* letting a strong identifier match suppress a weaker but differently-evidenced one.
+*/
+const SCORE_FLOOR = .25;
+/**
+* The indexed fields, and the evidence each one reports when it matches. Two fields answer to
+* `description` because a summary and a description are the same thing to someone reading a result.
+*/
+const EVIDENCE = {
+	route: "route",
+	path: "path",
+	namespace: "namespace",
+	summary: "description",
+	description: "description",
+	errors: "error",
+	inputParams: "input.params.property",
+	inputQuery: "input.query.property",
+	inputBody: "input.body.property",
+	responses: "response.property"
+};
+/**
+* Field weights. `settings` appears in dozens of route names and must count for almost nothing next
+* to a term that appears in two input schemas, which is what TF-IDF gives by construction; these
+* only express the tier preference on top of it.
+*/
+const BOOST = {
+	route: 8,
+	path: 6,
+	namespace: 4,
+	inputParams: 3,
+	inputQuery: 3,
+	inputBody: 3,
+	errors: 3,
+	summary: 2,
+	description: 2,
+	responses: 1
+};
+/**
+* Rank the document's routes against a query.
+*
+* The index is built per call, because the watcher replaces the document whenever WordPress moves
+* and a cached index would answer for routes that no longer exist. Exact identifier matches are
+* found before the index is consulted, so looking a route up by name is deterministic rather than
+* something a scorer has to be trusted to get right.
+*/
+function searchRoutes(document, options = {}) {
+	const all = sortRoutes(routesOf(document).values());
+	const namespaces = [...new Set(all.map((route) => route.namespace))].sort();
+	const ranked = rank(all.filter((route) => matchesFilters(route, options)), document, (options.query ?? "").trim());
+	const limit = Math.min(Math.max(options.limit ?? DEFAULT_LIMIT, 1), MAX_LIMIT);
+	const offset = decodeCursor(options.cursor);
+	const next = offset + limit;
+	return {
+		count: ranked.length,
+		routes: ranked.slice(offset, next),
+		...next < ranked.length ? { nextCursor: encodeCursor(next) } : {},
+		namespaces
+	};
+}
+function matchesFilters(route, options) {
+	if (options.namespace !== void 0 && route.namespace !== options.namespace) return false;
+	if (options.method !== void 0 && route.method !== options.method.toUpperCase()) return false;
+	if (options.access === "read" && !READ_METHODS.has(route.method)) return false;
+	if (options.access === "write" && READ_METHODS.has(route.method)) return false;
+	return true;
+}
+/**
+* An empty query browses through the wildcard rather than around the index, so one path answers both
+* and a browse cannot drift from a search in ordering or shape.
+*/
+function rank(routes, document, query) {
+	const browsing = query === "";
+	const index = new MiniSearch({
+		fields: Object.keys(BOOST),
+		storeFields: ["id"]
+	});
+	index.addAll(routes.map((route) => indexed(route, document)));
+	const byName = new Map(routes.map((route) => [route.name, route]));
+	const merged = /* @__PURE__ */ new Map();
+	const term = query.toLowerCase();
+	if (!browsing) for (const route of routes) {
+		const evidence = [];
+		if (route.name.toLowerCase() === term) evidence.push({
+			field: "route",
+			term: query
+		});
+		if (route.path.toLowerCase() === term) evidence.push({
+			field: "path",
+			term: query
+		});
+		if (route.namespace.toLowerCase() === term) evidence.push({
+			field: "namespace",
+			term: query
+		});
+		if (evidence.length > 0) merged.set(route.name, {
+			tier: 0,
+			score: Number.MAX_SAFE_INTEGER,
+			evidence
+		});
+	}
+	const found = browsing ? index.search(MiniSearch.wildcard) : index.search(query, {
+		prefix: true,
+		fuzzy: .2,
+		boost: BOOST
+	});
+	for (const result of found) {
+		if (!browsing && result.score <= 0) continue;
+		const name = String(result.id);
+		const evidence = evidenceOf(result.match);
+		const already = merged.get(name);
+		if (already) already.evidence = dedupe([...already.evidence, ...evidence]);
+		else merged.set(name, {
+			tier: tierOf(evidence),
+			score: result.score,
+			evidence
+		});
+	}
+	const entries = [...merged.entries()];
+	const bestByTier = /* @__PURE__ */ new Map();
+	for (const [, entry] of entries) bestByTier.set(entry.tier, Math.max(bestByTier.get(entry.tier) ?? 0, entry.score));
+	return (browsing ? entries : entries.filter(([, entry]) => entry.score >= (bestByTier.get(entry.tier) ?? 0) * SCORE_FLOOR)).sort(([leftName, left], [rightName, right]) => {
+		if (left.tier !== right.tier) return left.tier - right.tier;
+		if (left.score !== right.score) return right.score - left.score;
+		return leftName.localeCompare(rightName);
+	}).flatMap(([name, entry]) => {
+		const route = byName.get(name);
+		return route ? [describe(route, entry.evidence)] : [];
+	});
+}
+/**
+* Which tier a hit belongs to, below the exact identifier matches that take tier 0.
+*
+* What a route takes as an argument comes first, because that is what someone searching for
+* `custom_fields` means. Response properties rank behind it, since generic words such as `title`,
+* `status`, and `date` otherwise select nearly every content route. A partial identifier or a word
+* from a summary ranks last: prefix matching means `custom` reaches every `customers` route, and
+* those must not crowd out the route that actually accepts the field.
+*/
+function tierOf(evidence) {
+	const fields = new Set(evidence.map((item) => item.field));
+	if ([...fields].some((field) => field.startsWith("input.") || field === "error")) return 1;
+	if (fields.has("response.property")) return 2;
+	return 3;
+}
+function evidenceOf(match) {
+	const evidence = [];
+	for (const [term, fields] of Object.entries(match)) for (const field of fields) {
+		const named = EVIDENCE[field];
+		if (named) evidence.push({
+			field: named,
+			term
+		});
+	}
+	return dedupe(evidence);
+}
+function dedupe(evidence) {
+	const seen = /* @__PURE__ */ new Set();
+	return evidence.filter((item) => {
+		const key = `${item.field} ${item.term}`;
+		if (seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	});
+}
+function describe(route, evidence) {
+	return {
+		name: route.name,
+		namespace: route.namespace,
+		method: route.method,
+		path: route.path,
+		...route.summary !== void 0 ? { summary: route.summary } : {},
+		...route.deprecated ? { deprecated: true } : {},
+		evidence
+	};
+}
+function indexed(route, document) {
+	const { input, responses, errors } = route.operation;
+	return {
+		id: route.name,
+		route: route.name.replace(/[.\-_]/g, " "),
+		path: route.path.replace(/[/{}\-_]/g, " "),
+		namespace: route.namespace,
+		summary: route.summary ?? "",
+		description: route.description ?? "",
+		errors: errors.join(" "),
+		inputParams: terms(input.params, document),
+		inputQuery: terms(input.query, document),
+		inputBody: terms(input.body, document),
+		responses: Object.values(responses).map((response) => `${terms(response.body, document)} ${terms(response.headers, document)}`).join(" ")
+	};
+}
+function terms(schema, document) {
+	return collect(schema, document, 0, /* @__PURE__ */ new Set()).join(" ");
+}
+/**
+* Property names, titles, and descriptions reachable from a schema. Bounded by depth and guarded by
+* the ids already open on this branch, so a schema describing its own nesting cannot stall a search.
+*/
+function collect(schema, document, depth, seen) {
+	if (!schema || depth > MAX_DEPTH) return [];
+	const found = [];
+	if (schema.title) found.push(schema.title);
+	if (schema.description) found.push(schema.description);
+	for (const [name, child] of Object.entries(schema.properties ?? {})) found.push(name.replace(/[._-]/g, " "), ...collect(child, document, depth + 1, seen));
+	found.push(...collect(schema.items, document, depth + 1, seen));
+	for (const member of [...schema.anyOf ?? [], ...schema.oneOf ?? []]) found.push(...collect(member, document, depth + 1, seen));
+	if (typeof schema.additionalProperties === "object") found.push(...collect(schema.additionalProperties, document, depth + 1, seen));
+	for (const child of Object.values(schema.patternProperties ?? {})) found.push(...collect(child, document, depth + 1, seen));
+	for (const id of [...schema.$ref ? [schema.$ref] : [], ...refs(schema.$extends)]) {
+		if (seen.has(id)) continue;
+		found.push(...collect(document.schemas[id], document, depth + 1, new Set([...seen, id])));
+	}
+	return found;
+}
+function refs(value) {
+	if (value === void 0) return [];
+	return Array.isArray(value) ? value : [value];
+}
+/** An opaque page marker, so a caller pages by handing one back rather than doing arithmetic. */
+function encodeCursor(offset) {
+	return Buffer.from(`offset:${offset}`, "utf8").toString("base64url");
+}
+function decodeCursor(cursor) {
+	if (cursor === void 0) return 0;
+	const decoded = Buffer.from(cursor, "base64url").toString("utf8");
+	const offset = Number.parseInt(decoded.replace(/^offset:/, ""), 10);
+	return Number.isSafeInteger(offset) && offset >= 0 ? offset : 0;
+}
+
+//#endregion
+export { searchRoutes };