@webpieces/core-util 0.4.890 → 0.4.892

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/core-util",
-  "version": "0.4.890",
+  "version": "0.4.892",
   "description": "Utility functions for WebPieces - works in browser and Node.js",
   "type": "commonjs",
   "main": "./src/index.js",

package/src/mcp/DtoSchema.d.ts

@@ -57,7 +57,12 @@ export declare class ApiJsonSchema {
     /** `false` closes an object; a schema makes it a typed map whose values all match that schema. */
     additionalProperties?: boolean | ApiJsonSchema;
     items?: ApiJsonSchema;
-    enum?: string[];
+    /**
+     * The allowed values. A NULLABLE enum carries `null` here as well as in {@link type}: JSON Schema
+     * checks `enum` independently of `type`, so `{type: ["string","null"], enum: ["a"]}` still rejects
+     * `null` (#1197).
+     */
+    enum?: (string | null)[];
     minimum?: number;
     maximum?: number;
     /**

package/src/mcp/DtoSchema.js

@@ -54,6 +54,11 @@ class ApiJsonSchema {
     /** `false` closes an object; a schema makes it a typed map whose values all match that schema. */
     additionalProperties;
     items;
+    /**
+     * The allowed values. A NULLABLE enum carries `null` here as well as in {@link type}: JSON Schema
+     * checks `enum` independently of `type`, so `{type: ["string","null"], enum: ["a"]}` still rejects
+     * `null` (#1197).
+     */
     enum;
     minimum;
     maximum;
@@ -168,9 +173,16 @@ class ApiJsonSchemaValidator {
     }
     validateAt(schema, value, path) {
         if (value === null) {
-            return ApiJsonSchema.allowsNull(schema)
-                ? undefined
-                : new DtoValidationFailure(path, `${path} must not be null`);
+            if (!ApiJsonSchema.allowsNull(schema)) {
+                return new DtoValidationFailure(path, `${path} must not be null`);
+            }
+            // `enum` is checked independently of `type`, exactly as every JSON Schema client checks
+            // it: a nullable enum whose `enum` omits null is refused HERE rather than by the agent's
+            // client after the call already ran (#1197).
+            if (schema.enum && !schema.enum.includes(null)) {
+                return new DtoValidationFailure(path, `${path} must be one of: ${schema.enum.map(String).join(', ')}`);
+            }
+            return undefined;
         }
         if (schema.oneOf !== undefined) {
             return this.validateUnion(schema, value, path);
@@ -244,7 +256,7 @@ class ApiJsonSchemaValidator {
     static branchValuesOf(branch, property) {
         const declared = Object.getOwnPropertyDescriptor(branch.properties ?? {}, property)
             ?.value;
-        return declared?.enum ?? [];
+        return (declared?.enum ?? []).filter((value) => value !== null);
     }
     validateObject(schema, value, path) {
         if (typeof value !== 'object' || value === null || Array.isArray(value)) {
@@ -301,7 +313,7 @@ class ApiJsonSchemaValidator {
             return new DtoValidationFailure(path, `${path} must be a string`);
         }
         if (schema.enum && !schema.enum.includes(value)) {
-            return new DtoValidationFailure(path, `${path} must be one of: ${schema.enum.join(', ')}`);
+            return new DtoValidationFailure(path, `${path} must be one of: ${schema.enum.map(String).join(', ')}`);
         }
         return undefined;
     }

package/src/mcp/DtoSchema.js.map

@@ -1 +1 @@
-{"version":3,"file":"DtoSchema.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/mcp/DtoSchema.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The JSON Schema subset webpieces publishes on its API boundaries, and the ONE runtime validator of\n * it.\n *\n * ## Nothing here reads reflect-metadata any more\n *\n * Until #984 this file also carried `@WpDto`, `@WpDtoField`, `WpDtoFieldOptions`,\n * `WpDtoMapFieldOptions`, `WpMcpHeader`, `@WpResponseDto` and `DtoSchemaBuilder` — a second, runtime\n * spelling of facts the TypeScript compiler already holds. #983 measured the two against each other\n * and found the compiler reproduces every one of those arguments byte for byte, so they are deleted\n * rather than deprecated (`.claude/rules/no-backwards-compat.md`): a schema is now BUILT at build\n * time from the source by `@webpieces/api-doc-model`, and the runtime is HANDED the result.\n *\n * What survives is the schema itself, a builder for the boundaries that construct one by hand, and a\n * validator that reads the schema instead of a decorator.\n */\n\n/** Runtime values accepted at the DTO validation boundary. */\nexport type DtoValue = object | string | number | boolean | null;\n\n/**\n * One JSON Schema `type`. `null` is a member because NULLABLE is expressed as `[\"string\", \"null\"]`,\n * which is how JSON Schema says \"present, and may hold null\" — a different wire document from an\n * ABSENT property, and one the reflect-metadata runtime could neither see nor write down.\n */\nexport type ApiJsonSchemaType =\n    | 'object'\n    | 'string'\n    | 'number'\n    | 'integer'\n    | 'boolean'\n    | 'array'\n    | 'null';\n\n/**\n * The DISCRIMINATOR of a {@link ApiJsonSchema.oneOf} — which property narrows the union, and what\n * each of its values names.\n *\n * The shape MIRRORS what `OpenApiGenerator`'s `SchemaRenderer` already emits for the same union\n * (`propertyName` + `mapping`), because a union has exactly ONE published spelling in this repo and\n * the OpenAPI renderer is the reference implementation of it. The one difference is what a mapping\n * VALUE holds: OpenAPI maps a value to `#/components/schemas/ScheduledWindow`, and an MCP tool\n * schema is INLINE and has no `$ref` to point at, so it maps to the branch's type NAME.\n *\n * `mapping` is DOCUMENTATION for the reader. {@link ApiJsonSchemaValidator} never narrows with it:\n * it selects the branch whose own `enum` carries the value, so the accepted request and the\n * published document cannot disagree about which branch a value means.\n */\nexport class ApiJsonSchemaDiscriminator {\n    constructor(\n        /** The property every branch declares as exactly one string literal, e.g. `kind`. */\n        public propertyName: string,\n        /** discriminator value -> the branch's TYPE NAME (MCP is inline: there is no `$ref`). */\n        public mapping: Record<string, string>,\n    ) {}\n}\n\n/** The JSON Schema subset emitted for Webpieces API DTOs. */\nexport class ApiJsonSchema {\n    /** One type, or `[T, \"null\"]` for a nullable field. */\n    type?: ApiJsonSchemaType | readonly ApiJsonSchemaType[];\n    description?: string;\n    properties?: Record<string, ApiJsonSchema>;\n    required?: string[];\n    /** `false` closes an object; a schema makes it a typed map whose values all match that schema. */\n    additionalProperties?: boolean | ApiJsonSchema;\n    items?: ApiJsonSchema;\n    enum?: string[];\n    minimum?: number;\n    maximum?: number;\n    /**\n     * The branches of a union, INLINE (MCP tool schemas have no `$ref`), in declaration order.\n     *\n     * A union is legal NESTED, inside a property. It is NOT legal at the ROOT of a tool's parameter\n     * schema — both the OpenAI and the Anthropic function-calling APIs reject a top-level\n     * `oneOf`/`anyOf`/`allOf`, and because a server sends its whole tool list on every request, one\n     * such tool makes EVERY request 400. That is refused at build time by the `no-root-union-api-type`\n     * rule, before a contract can be published at all.\n     */\n    oneOf?: readonly ApiJsonSchema[];\n    /**\n     * Set ONLY when every branch carries the same property typed as one string literal — DERIVED,\n     * never invented. A union TypeScript itself cannot narrow is published as a bare {@link oneOf},\n     * because claiming a narrowing the source does not have is worse than admitting there is none.\n     */\n    discriminator?: ApiJsonSchemaDiscriminator;\n    /** MCP 2026 SEP-2243 schema extension consumed by the official SDK. */\n    declare 'x-mcp-header'?: string;\n\n    constructor(type?: ApiJsonSchemaType | readonly ApiJsonSchemaType[]) {\n        this.type = type;\n    }\n\n    /**\n     * The non-`null` member of the type, which is the one that decides how a value is checked.\n     *\n     * These three are STATIC and not instance methods on purpose: an instance method would put a\n     * function on the structural type, and this class is handed straight to the MCP SDK, whose\n     * parameter types are index-signature JSON objects that a class carrying methods no longer\n     * satisfies. It stays a data-only structure (`CLAUDE.md` §1) and the helpers live beside it.\n     */\n    // webpieces-disable no-function-outside-class -- static reader of this class\n    static baseTypeOf(schema: ApiJsonSchema): ApiJsonSchemaType | undefined {\n        if (schema.type === undefined) return undefined;\n        if (typeof schema.type === 'string') return schema.type;\n        return schema.type.find((one: ApiJsonSchemaType) => one !== 'null');\n    }\n\n    /** True when the schema was widened with `\"null\"`, i.e. the property may hold `null`. */\n    // webpieces-disable no-function-outside-class -- static reader of this class\n    static allowsNull(schema: ApiJsonSchema): boolean {\n        return typeof schema.type !== 'string' && (schema.type?.includes('null') ?? false);\n    }\n\n    /**\n     * The one closure gate for an object schema. Closed means no key can carry an unspecified value:\n     * either extra keys are forbidden (`additionalProperties: false`) or every extra key's value is\n     * typed (`additionalProperties: <schema>`, a typed map). A missing or `true` value is open.\n     * Use this instead of `schema.additionalProperties === false`, which rejects typed maps.\n     */\n    // webpieces-disable no-function-outside-class -- static reader of this class\n    static isClosed(schema: ApiJsonSchema): boolean {\n        const extra = schema.additionalProperties;\n        return extra === false || (typeof extra === 'object' && extra !== null);\n    }\n}\n\n/**\n * Builds the CLOSED object schema a hand-written runtime boundary validates against — `@WpStream`'s\n * two event schemas are the whole of its client list today.\n *\n * It exists because the alternative spellings are both worse: a decorator that re-states the field\n * types the compiler already knows is exactly what #984 deleted, and a bare object literal is what\n * `CLAUDE.md` §3 forbids. A generated schema never comes through here — it is read from the build's\n * own artifact.\n */\nexport class ObjectSchemaBuilder {\n    private readonly schema = new ApiJsonSchema('object');\n    private readonly requiredNames: string[] = [];\n\n    constructor() {\n        this.schema.properties = {};\n        this.schema.additionalProperties = false;\n    }\n\n    required(name: string, type: ApiJsonSchema): this {\n        this.requiredNames.push(name);\n        return this.optional(name, type);\n    }\n\n    optional(name: string, type: ApiJsonSchema): this {\n        this.schema.properties![name] = type;\n        return this;\n    }\n\n    build(): ApiJsonSchema {\n        if (this.requiredNames.length > 0) this.schema.required = [...this.requiredNames];\n        return this.schema;\n    }\n}\n\n/** A validation result safe to show to an API caller/model. */\nexport class DtoValidationFailure {\n    constructor(\n        /** JSON path of the offending value, e.g. `$.address.city`. */\n        public readonly field: string,\n        public readonly message: string,\n    ) {}\n}\n\n/**\n * Validates a value against an {@link ApiJsonSchema} — the ONE runtime narrowing boundary for MCP\n * tool arguments, MCP structured output and typed stream events.\n *\n * It reads the SCHEMA, which is the same object the build published to agents, so a document that\n * says a field is required and a server that accepts it missing cannot disagree. The predecessor\n * walked reflect-metadata instead, which meant the published document and the accepted request were\n * derived from two different declarations.\n */\nexport class ApiJsonSchemaValidator {\n    validate(schema: ApiJsonSchema, value: DtoValue): DtoValidationFailure | undefined {\n        return this.validateAt(schema, value, '$');\n    }\n\n    private validateAt(\n        schema: ApiJsonSchema,\n        value: DtoValue,\n        path: string,\n    ): DtoValidationFailure | undefined {\n        if (value === null) {\n            return ApiJsonSchema.allowsNull(schema)\n                ? undefined\n                : new DtoValidationFailure(path, `${path} must not be null`);\n        }\n        if (schema.oneOf !== undefined) {\n            return this.validateUnion(schema, value, path);\n        }\n        switch (ApiJsonSchema.baseTypeOf(schema)) {\n            case 'object':\n                return this.validateObject(schema, value, path);\n            case 'array':\n                return this.validateArray(schema, value, path);\n            case 'string':\n                return this.validateString(schema, value, path);\n            case 'number':\n            case 'integer':\n                return this.validateNumber(schema, value, path);\n            case 'boolean':\n                return typeof value === 'boolean'\n                    ? undefined\n                    : new DtoValidationFailure(path, `${path} must be a boolean`);\n            default:\n                return undefined;\n        }\n    }\n\n    /**\n     * A union, validated BY DISCRIMINATOR.\n     *\n     * The discriminator property is read FIRST and the branch chosen from it, so a value naming no\n     * branch is reported as what it is — `$.window.kind must be one of: scheduled | asap`, naming the\n     * field that is wrong and the values it may hold. Trying every branch and reporting \"no branch\n     * matched\" tells a caller nothing they can act on: it names neither the offending property nor\n     * the legal values, and it hides a branch that matched on `kind` and failed three levels down.\n     *\n     * The branch is selected by the branches' own `enum`s, never by\n     * {@link ApiJsonSchemaDiscriminator.mapping} — the branches ARE the schema, so selection and\n     * validation read one source and cannot disagree.\n     */\n    private validateUnion(\n        schema: ApiJsonSchema,\n        value: DtoValue,\n        path: string,\n    ): DtoValidationFailure | undefined {\n        const branches = schema.oneOf ?? [];\n        if (typeof value !== 'object' || value === null || Array.isArray(value)) {\n            return new DtoValidationFailure(path, `${path} must be an object`);\n        }\n        const discriminator = schema.discriminator;\n        if (discriminator === undefined) {\n            return this.validateAnyBranch(branches, value, path);\n        }\n        const property = discriminator.propertyName;\n        const held: DtoValue = Object.getOwnPropertyDescriptor(value, property)?.value;\n        const branch = branches.find((one: ApiJsonSchema) =>\n            ApiJsonSchemaValidator.branchValuesOf(one, property).includes(held as string),\n        );\n        if (branch === undefined) {\n            const legal = branches\n                .flatMap((one: ApiJsonSchema) =>\n                    ApiJsonSchemaValidator.branchValuesOf(one, property),\n                )\n                .join(' | ');\n            return new DtoValidationFailure(\n                `${path}.${property}`,\n                `${path}.${property} must be one of: ${legal}`,\n            );\n        }\n        return this.validateAt(branch, value, path);\n    }\n\n    /**\n     * A union with NO discriminator — one TypeScript itself cannot narrow. Every branch is tried and\n     * the value accepted when one matches. There is no better report when none does: the source does\n     * not narrow, so no property can honestly be named as the wrong one.\n     */\n    private validateAnyBranch(\n        branches: readonly ApiJsonSchema[],\n        value: DtoValue,\n        path: string,\n    ): DtoValidationFailure | undefined {\n        for (const branch of branches) {\n            if (this.validateAt(branch, value, path) === undefined) {\n                return undefined;\n            }\n        }\n        return new DtoValidationFailure(\n            path,\n            `${path} matches none of the ${branches.length} accepted shapes`,\n        );\n    }\n\n    /** The string literals ONE branch declares for the discriminator property. */\n    // webpieces-disable no-function-outside-class -- private static reader of a branch schema\n    private static branchValuesOf(branch: ApiJsonSchema, property: string): readonly string[] {\n        const declared = Object.getOwnPropertyDescriptor(branch.properties ?? {}, property)\n            ?.value as ApiJsonSchema | undefined;\n        return declared?.enum ?? [];\n    }\n\n    private validateObject(\n        schema: ApiJsonSchema,\n        value: DtoValue,\n        path: string,\n    ): DtoValidationFailure | undefined {\n        if (typeof value !== 'object' || value === null || Array.isArray(value)) {\n            return new DtoValidationFailure(path, `${path} must be an object`);\n        }\n        const properties = schema.properties ?? {};\n        const extra = schema.additionalProperties;\n        for (const key of Object.keys(value)) {\n            const entry: DtoValue = Object.getOwnPropertyDescriptor(value, key)?.value;\n            // A key HOLDING `undefined` is ABSENT: `JSON.stringify` drops it, so the document the\n            // caller receives never carries it, and the `required` loop below already reads\n            // `=== undefined` as missing. Validating it here made the two halves of this one walk\n            // disagree — `{ next: hasMore ? cursor : undefined }` was refused as \"must be a string\"\n            // although its JSON is valid (#1055). `null` is a VALUE and is still checked.\n            if ((entry as DtoValue | undefined) === undefined) continue;\n            const declared = Object.getOwnPropertyDescriptor(properties, key)?.value as\n                | ApiJsonSchema\n                | undefined;\n            if (declared === undefined) {\n                if (typeof extra !== 'object' || extra === null) {\n                    return new DtoValidationFailure(\n                        `${path}.${key}`,\n                        `${path}.${key} is not allowed`,\n                    );\n                }\n                const failure = this.validateAt(extra, entry, `${path}.${key}`);\n                if (failure) return failure;\n                continue;\n            }\n            const failure = this.validateAt(declared, entry, `${path}.${key}`);\n            if (failure) return failure;\n        }\n        for (const name of schema.required ?? []) {\n            if (Object.getOwnPropertyDescriptor(value, name)?.value === undefined) {\n                return new DtoValidationFailure(`${path}.${name}`, `${path}.${name} is required`);\n            }\n        }\n        return undefined;\n    }\n\n    private validateArray(\n        schema: ApiJsonSchema,\n        value: DtoValue,\n        path: string,\n    ): DtoValidationFailure | undefined {\n        if (!Array.isArray(value)) {\n            return new DtoValidationFailure(path, `${path} must be an array`);\n        }\n        const items = schema.items;\n        if (items === undefined) return undefined;\n        for (let index = 0; index < value.length; index += 1) {\n            const failure = this.validateAt(items, value[index], `${path}[${index}]`);\n            if (failure) return failure;\n        }\n        return undefined;\n    }\n\n    private validateString(\n        schema: ApiJsonSchema,\n        value: DtoValue,\n        path: string,\n    ): DtoValidationFailure | undefined {\n        if (typeof value !== 'string') {\n            return new DtoValidationFailure(path, `${path} must be a string`);\n        }\n        if (schema.enum && !schema.enum.includes(value)) {\n            return new DtoValidationFailure(\n                path,\n                `${path} must be one of: ${schema.enum.join(', ')}`,\n            );\n        }\n        return undefined;\n    }\n\n    private validateNumber(\n        schema: ApiJsonSchema,\n        value: DtoValue,\n        path: string,\n    ): DtoValidationFailure | undefined {\n        if (typeof value !== 'number' || !Number.isFinite(value)) {\n            return new DtoValidationFailure(path, `${path} must be a number`);\n        }\n        if (ApiJsonSchema.baseTypeOf(schema) === 'integer' && !Number.isInteger(value)) {\n            return new DtoValidationFailure(path, `${path} must be an integer`);\n        }\n        if (schema.minimum !== undefined && value < schema.minimum) {\n            return new DtoValidationFailure(path, `${path} must be >= ${schema.minimum}`);\n        }\n        if (schema.maximum !== undefined && value > schema.maximum) {\n            return new DtoValidationFailure(path, `${path} must be <= ${schema.maximum}`);\n        }\n        return undefined;\n    }\n}\n"]}
+{"version":3,"file":"DtoSchema.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/mcp/DtoSchema.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The JSON Schema subset webpieces publishes on its API boundaries, and the ONE runtime validator of\n * it.\n *\n * ## Nothing here reads reflect-metadata any more\n *\n * Until #984 this file also carried `@WpDto`, `@WpDtoField`, `WpDtoFieldOptions`,\n * `WpDtoMapFieldOptions`, `WpMcpHeader`, `@WpResponseDto` and `DtoSchemaBuilder` — a second, runtime\n * spelling of facts the TypeScript compiler already holds. #983 measured the two against each other\n * and found the compiler reproduces every one of those arguments byte for byte, so they are deleted\n * rather than deprecated (`.claude/rules/no-backwards-compat.md`): a schema is now BUILT at build\n * time from the source by `@webpieces/api-doc-model`, and the runtime is HANDED the result.\n *\n * What survives is the schema itself, a builder for the boundaries that construct one by hand, and a\n * validator that reads the schema instead of a decorator.\n */\n\n/** Runtime values accepted at the DTO validation boundary. */\nexport type DtoValue = object | string | number | boolean | null;\n\n/**\n * One JSON Schema `type`. `null` is a member because NULLABLE is expressed as `[\"string\", \"null\"]`,\n * which is how JSON Schema says \"present, and may hold null\" — a different wire document from an\n * ABSENT property, and one the reflect-metadata runtime could neither see nor write down.\n */\nexport type ApiJsonSchemaType =\n    | 'object'\n    | 'string'\n    | 'number'\n    | 'integer'\n    | 'boolean'\n    | 'array'\n    | 'null';\n\n/**\n * The DISCRIMINATOR of a {@link ApiJsonSchema.oneOf} — which property narrows the union, and what\n * each of its values names.\n *\n * The shape MIRRORS what `OpenApiGenerator`'s `SchemaRenderer` already emits for the same union\n * (`propertyName` + `mapping`), because a union has exactly ONE published spelling in this repo and\n * the OpenAPI renderer is the reference implementation of it. The one difference is what a mapping\n * VALUE holds: OpenAPI maps a value to `#/components/schemas/ScheduledWindow`, and an MCP tool\n * schema is INLINE and has no `$ref` to point at, so it maps to the branch's type NAME.\n *\n * `mapping` is DOCUMENTATION for the reader. {@link ApiJsonSchemaValidator} never narrows with it:\n * it selects the branch whose own `enum` carries the value, so the accepted request and the\n * published document cannot disagree about which branch a value means.\n */\nexport class ApiJsonSchemaDiscriminator {\n    constructor(\n        /** The property every branch declares as exactly one string literal, e.g. `kind`. */\n        public propertyName: string,\n        /** discriminator value -> the branch's TYPE NAME (MCP is inline: there is no `$ref`). */\n        public mapping: Record<string, string>,\n    ) {}\n}\n\n/** The JSON Schema subset emitted for Webpieces API DTOs. */\nexport class ApiJsonSchema {\n    /** One type, or `[T, \"null\"]` for a nullable field. */\n    type?: ApiJsonSchemaType | readonly ApiJsonSchemaType[];\n    description?: string;\n    properties?: Record<string, ApiJsonSchema>;\n    required?: string[];\n    /** `false` closes an object; a schema makes it a typed map whose values all match that schema. */\n    additionalProperties?: boolean | ApiJsonSchema;\n    items?: ApiJsonSchema;\n    /**\n     * The allowed values. A NULLABLE enum carries `null` here as well as in {@link type}: JSON Schema\n     * checks `enum` independently of `type`, so `{type: [\"string\",\"null\"], enum: [\"a\"]}` still rejects\n     * `null` (#1197).\n     */\n    enum?: (string | null)[];\n    minimum?: number;\n    maximum?: number;\n    /**\n     * The branches of a union, INLINE (MCP tool schemas have no `$ref`), in declaration order.\n     *\n     * A union is legal NESTED, inside a property. It is NOT legal at the ROOT of a tool's parameter\n     * schema — both the OpenAI and the Anthropic function-calling APIs reject a top-level\n     * `oneOf`/`anyOf`/`allOf`, and because a server sends its whole tool list on every request, one\n     * such tool makes EVERY request 400. That is refused at build time by the `no-root-union-api-type`\n     * rule, before a contract can be published at all.\n     */\n    oneOf?: readonly ApiJsonSchema[];\n    /**\n     * Set ONLY when every branch carries the same property typed as one string literal — DERIVED,\n     * never invented. A union TypeScript itself cannot narrow is published as a bare {@link oneOf},\n     * because claiming a narrowing the source does not have is worse than admitting there is none.\n     */\n    discriminator?: ApiJsonSchemaDiscriminator;\n    /** MCP 2026 SEP-2243 schema extension consumed by the official SDK. */\n    declare 'x-mcp-header'?: string;\n\n    constructor(type?: ApiJsonSchemaType | readonly ApiJsonSchemaType[]) {\n        this.type = type;\n    }\n\n    /**\n     * The non-`null` member of the type, which is the one that decides how a value is checked.\n     *\n     * These three are STATIC and not instance methods on purpose: an instance method would put a\n     * function on the structural type, and this class is handed straight to the MCP SDK, whose\n     * parameter types are index-signature JSON objects that a class carrying methods no longer\n     * satisfies. It stays a data-only structure (`CLAUDE.md` §1) and the helpers live beside it.\n     */\n    // webpieces-disable no-function-outside-class -- static reader of this class\n    static baseTypeOf(schema: ApiJsonSchema): ApiJsonSchemaType | undefined {\n        if (schema.type === undefined) return undefined;\n        if (typeof schema.type === 'string') return schema.type;\n        return schema.type.find((one: ApiJsonSchemaType) => one !== 'null');\n    }\n\n    /** True when the schema was widened with `\"null\"`, i.e. the property may hold `null`. */\n    // webpieces-disable no-function-outside-class -- static reader of this class\n    static allowsNull(schema: ApiJsonSchema): boolean {\n        return typeof schema.type !== 'string' && (schema.type?.includes('null') ?? false);\n    }\n\n    /**\n     * The one closure gate for an object schema. Closed means no key can carry an unspecified value:\n     * either extra keys are forbidden (`additionalProperties: false`) or every extra key's value is\n     * typed (`additionalProperties: <schema>`, a typed map). A missing or `true` value is open.\n     * Use this instead of `schema.additionalProperties === false`, which rejects typed maps.\n     */\n    // webpieces-disable no-function-outside-class -- static reader of this class\n    static isClosed(schema: ApiJsonSchema): boolean {\n        const extra = schema.additionalProperties;\n        return extra === false || (typeof extra === 'object' && extra !== null);\n    }\n}\n\n/**\n * Builds the CLOSED object schema a hand-written runtime boundary validates against — `@WpStream`'s\n * two event schemas are the whole of its client list today.\n *\n * It exists because the alternative spellings are both worse: a decorator that re-states the field\n * types the compiler already knows is exactly what #984 deleted, and a bare object literal is what\n * `CLAUDE.md` §3 forbids. A generated schema never comes through here — it is read from the build's\n * own artifact.\n */\nexport class ObjectSchemaBuilder {\n    private readonly schema = new ApiJsonSchema('object');\n    private readonly requiredNames: string[] = [];\n\n    constructor() {\n        this.schema.properties = {};\n        this.schema.additionalProperties = false;\n    }\n\n    required(name: string, type: ApiJsonSchema): this {\n        this.requiredNames.push(name);\n        return this.optional(name, type);\n    }\n\n    optional(name: string, type: ApiJsonSchema): this {\n        this.schema.properties![name] = type;\n        return this;\n    }\n\n    build(): ApiJsonSchema {\n        if (this.requiredNames.length > 0) this.schema.required = [...this.requiredNames];\n        return this.schema;\n    }\n}\n\n/** A validation result safe to show to an API caller/model. */\nexport class DtoValidationFailure {\n    constructor(\n        /** JSON path of the offending value, e.g. `$.address.city`. */\n        public readonly field: string,\n        public readonly message: string,\n    ) {}\n}\n\n/**\n * Validates a value against an {@link ApiJsonSchema} — the ONE runtime narrowing boundary for MCP\n * tool arguments, MCP structured output and typed stream events.\n *\n * It reads the SCHEMA, which is the same object the build published to agents, so a document that\n * says a field is required and a server that accepts it missing cannot disagree. The predecessor\n * walked reflect-metadata instead, which meant the published document and the accepted request were\n * derived from two different declarations.\n */\nexport class ApiJsonSchemaValidator {\n    validate(schema: ApiJsonSchema, value: DtoValue): DtoValidationFailure | undefined {\n        return this.validateAt(schema, value, '$');\n    }\n\n    private validateAt(\n        schema: ApiJsonSchema,\n        value: DtoValue,\n        path: string,\n    ): DtoValidationFailure | undefined {\n        if (value === null) {\n            if (!ApiJsonSchema.allowsNull(schema)) {\n                return new DtoValidationFailure(path, `${path} must not be null`);\n            }\n            // `enum` is checked independently of `type`, exactly as every JSON Schema client checks\n            // it: a nullable enum whose `enum` omits null is refused HERE rather than by the agent's\n            // client after the call already ran (#1197).\n            if (schema.enum && !schema.enum.includes(null)) {\n                return new DtoValidationFailure(\n                    path,\n                    `${path} must be one of: ${schema.enum.map(String).join(', ')}`,\n                );\n            }\n            return undefined;\n        }\n        if (schema.oneOf !== undefined) {\n            return this.validateUnion(schema, value, path);\n        }\n        switch (ApiJsonSchema.baseTypeOf(schema)) {\n            case 'object':\n                return this.validateObject(schema, value, path);\n            case 'array':\n                return this.validateArray(schema, value, path);\n            case 'string':\n                return this.validateString(schema, value, path);\n            case 'number':\n            case 'integer':\n                return this.validateNumber(schema, value, path);\n            case 'boolean':\n                return typeof value === 'boolean'\n                    ? undefined\n                    : new DtoValidationFailure(path, `${path} must be a boolean`);\n            default:\n                return undefined;\n        }\n    }\n\n    /**\n     * A union, validated BY DISCRIMINATOR.\n     *\n     * The discriminator property is read FIRST and the branch chosen from it, so a value naming no\n     * branch is reported as what it is — `$.window.kind must be one of: scheduled | asap`, naming the\n     * field that is wrong and the values it may hold. Trying every branch and reporting \"no branch\n     * matched\" tells a caller nothing they can act on: it names neither the offending property nor\n     * the legal values, and it hides a branch that matched on `kind` and failed three levels down.\n     *\n     * The branch is selected by the branches' own `enum`s, never by\n     * {@link ApiJsonSchemaDiscriminator.mapping} — the branches ARE the schema, so selection and\n     * validation read one source and cannot disagree.\n     */\n    private validateUnion(\n        schema: ApiJsonSchema,\n        value: DtoValue,\n        path: string,\n    ): DtoValidationFailure | undefined {\n        const branches = schema.oneOf ?? [];\n        if (typeof value !== 'object' || value === null || Array.isArray(value)) {\n            return new DtoValidationFailure(path, `${path} must be an object`);\n        }\n        const discriminator = schema.discriminator;\n        if (discriminator === undefined) {\n            return this.validateAnyBranch(branches, value, path);\n        }\n        const property = discriminator.propertyName;\n        const held: DtoValue = Object.getOwnPropertyDescriptor(value, property)?.value;\n        const branch = branches.find((one: ApiJsonSchema) =>\n            ApiJsonSchemaValidator.branchValuesOf(one, property).includes(held as string),\n        );\n        if (branch === undefined) {\n            const legal = branches\n                .flatMap((one: ApiJsonSchema) =>\n                    ApiJsonSchemaValidator.branchValuesOf(one, property),\n                )\n                .join(' | ');\n            return new DtoValidationFailure(\n                `${path}.${property}`,\n                `${path}.${property} must be one of: ${legal}`,\n            );\n        }\n        return this.validateAt(branch, value, path);\n    }\n\n    /**\n     * A union with NO discriminator — one TypeScript itself cannot narrow. Every branch is tried and\n     * the value accepted when one matches. There is no better report when none does: the source does\n     * not narrow, so no property can honestly be named as the wrong one.\n     */\n    private validateAnyBranch(\n        branches: readonly ApiJsonSchema[],\n        value: DtoValue,\n        path: string,\n    ): DtoValidationFailure | undefined {\n        for (const branch of branches) {\n            if (this.validateAt(branch, value, path) === undefined) {\n                return undefined;\n            }\n        }\n        return new DtoValidationFailure(\n            path,\n            `${path} matches none of the ${branches.length} accepted shapes`,\n        );\n    }\n\n    /** The string literals ONE branch declares for the discriminator property. */\n    // webpieces-disable no-function-outside-class -- private static reader of a branch schema\n    private static branchValuesOf(branch: ApiJsonSchema, property: string): readonly string[] {\n        const declared = Object.getOwnPropertyDescriptor(branch.properties ?? {}, property)\n            ?.value as ApiJsonSchema | undefined;\n        return (declared?.enum ?? []).filter((value: string | null): value is string => value !== null);\n    }\n\n    private validateObject(\n        schema: ApiJsonSchema,\n        value: DtoValue,\n        path: string,\n    ): DtoValidationFailure | undefined {\n        if (typeof value !== 'object' || value === null || Array.isArray(value)) {\n            return new DtoValidationFailure(path, `${path} must be an object`);\n        }\n        const properties = schema.properties ?? {};\n        const extra = schema.additionalProperties;\n        for (const key of Object.keys(value)) {\n            const entry: DtoValue = Object.getOwnPropertyDescriptor(value, key)?.value;\n            // A key HOLDING `undefined` is ABSENT: `JSON.stringify` drops it, so the document the\n            // caller receives never carries it, and the `required` loop below already reads\n            // `=== undefined` as missing. Validating it here made the two halves of this one walk\n            // disagree — `{ next: hasMore ? cursor : undefined }` was refused as \"must be a string\"\n            // although its JSON is valid (#1055). `null` is a VALUE and is still checked.\n            if ((entry as DtoValue | undefined) === undefined) continue;\n            const declared = Object.getOwnPropertyDescriptor(properties, key)?.value as\n                | ApiJsonSchema\n                | undefined;\n            if (declared === undefined) {\n                if (typeof extra !== 'object' || extra === null) {\n                    return new DtoValidationFailure(\n                        `${path}.${key}`,\n                        `${path}.${key} is not allowed`,\n                    );\n                }\n                const failure = this.validateAt(extra, entry, `${path}.${key}`);\n                if (failure) return failure;\n                continue;\n            }\n            const failure = this.validateAt(declared, entry, `${path}.${key}`);\n            if (failure) return failure;\n        }\n        for (const name of schema.required ?? []) {\n            if (Object.getOwnPropertyDescriptor(value, name)?.value === undefined) {\n                return new DtoValidationFailure(`${path}.${name}`, `${path}.${name} is required`);\n            }\n        }\n        return undefined;\n    }\n\n    private validateArray(\n        schema: ApiJsonSchema,\n        value: DtoValue,\n        path: string,\n    ): DtoValidationFailure | undefined {\n        if (!Array.isArray(value)) {\n            return new DtoValidationFailure(path, `${path} must be an array`);\n        }\n        const items = schema.items;\n        if (items === undefined) return undefined;\n        for (let index = 0; index < value.length; index += 1) {\n            const failure = this.validateAt(items, value[index], `${path}[${index}]`);\n            if (failure) return failure;\n        }\n        return undefined;\n    }\n\n    private validateString(\n        schema: ApiJsonSchema,\n        value: DtoValue,\n        path: string,\n    ): DtoValidationFailure | undefined {\n        if (typeof value !== 'string') {\n            return new DtoValidationFailure(path, `${path} must be a string`);\n        }\n        if (schema.enum && !schema.enum.includes(value)) {\n            return new DtoValidationFailure(\n                path,\n                `${path} must be one of: ${schema.enum.map(String).join(', ')}`,\n            );\n        }\n        return undefined;\n    }\n\n    private validateNumber(\n        schema: ApiJsonSchema,\n        value: DtoValue,\n        path: string,\n    ): DtoValidationFailure | undefined {\n        if (typeof value !== 'number' || !Number.isFinite(value)) {\n            return new DtoValidationFailure(path, `${path} must be a number`);\n        }\n        if (ApiJsonSchema.baseTypeOf(schema) === 'integer' && !Number.isInteger(value)) {\n            return new DtoValidationFailure(path, `${path} must be an integer`);\n        }\n        if (schema.minimum !== undefined && value < schema.minimum) {\n            return new DtoValidationFailure(path, `${path} must be >= ${schema.minimum}`);\n        }\n        if (schema.maximum !== undefined && value > schema.maximum) {\n            return new DtoValidationFailure(path, `${path} must be <= ${schema.maximum}`);\n        }\n        return undefined;\n    }\n}\n"]}

package/src/mcp/McpToolCatalogFile.js.map

@@ -1 +1 @@
-{"version":3,"file":"McpToolCatalogFile.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/mcp/McpToolCatalogFile.ts"],"names":[],"mappings":"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","sourcesContent":["import { ApiJsonSchema, ApiJsonSchemaDiscriminator, ApiJsonSchemaType } from './DtoSchema';\nimport { Mcp } from './Mcp';\nimport { WpMcpToolHints } from './McpMetadata';\n\n/**\n * ONE generated MCP tool definition, including server-only profile membership.\n *\n * It is BUILT from the source by `@webpieces/api-doc-model`'s `McpSchemaRenderer` at build time, and\n * READ here at boot — so the tool an agent is shown and the tool the server accepts are the same\n * bytes by construction, not by two declarations agreeing.\n *\n * It lives in `core-util` rather than in the extractor package because both ends need it and only\n * one end may depend on the TypeScript compiler API. `ApiJsonSchema` and {@link WpMcpToolHints},\n * which it is made of, are already here for the same reason.\n */\nexport class McpToolDefinition {\n    constructor(\n        /** The stable protocol name from `@WpMcpTool('<name>', '<title>')`. */\n        readonly name: string,\n        /**\n         * The human-readable display name from `@WpMcpTool('<name>', '<title>')`. REQUIRED (#1180):\n         * `tools/list` publishes it as both `Tool.title` and `annotations.title`, and a catalog entry\n         * without one is refused on load rather than silently publishing an untitled tool.\n         */\n        readonly title: string,\n        /** The contract method it was rendered from, so a mismatch report can name the source. */\n        readonly methodName: string,\n        /**\n         * The tool documentation: the method's `@mcp` tag when it has one, its JSDoc body otherwise.\n         * Documentation has exactly ONE source — the doc comment above the declaration — for the\n         * partner reading OpenAPI and the agent reading `tools/list` alike.\n         */\n        readonly description: string,\n        /**\n         * All four hints. Three are COMPUTED from `@Endpoint`'s `operation` by\n         * `mcpHintsForOperation`, which is the one place that mapping lives; `openWorldHint` comes\n         * from `@Endpoint`'s `openWorld` option.\n         */\n        readonly hints: WpMcpToolHints,\n        readonly inputSchema: ApiJsonSchema,\n        readonly outputSchema: ApiJsonSchema,\n        readonly profiles: readonly string[],\n    ) {\n        this.profiles = Mcp.profiles(profiles, 'MCP catalog tool');\n    }\n}\n\n/** Thrown when a catalog is not one this release can read or write. */\nexport class McpToolCatalogError extends Error {\n    constructor(\n        message: string,\n        /** What to do instead, in one sentence. */\n        readonly cure: string,\n    ) {\n        super(`${message} ${cure}`);\n        this.name = 'McpToolCatalogError';\n        Object.setPrototypeOf(this, new.target.prototype);\n    }\n}\n\n/** The one cure every catalog failure prescribes: rebuild the artifact from the contracts. */\nconst REGENERATE =\n    'Rebuild the api library that declares the contract (its `openapi-generate` target runs ' +\n    '`wp-openapi`, which writes one `mcp-<ContractClass>-tools.json` per MCP contract).';\n\nconst FILE_PREFIX = 'mcp-';\nconst FILE_SUFFIX = '-tools.json';\n\n/** A class name, which is what the file name carries. Anything else is not one of these files. */\nconst CONTRACT_NAME = /^[A-Za-z_$][A-Za-z0-9_$]*$/;\n\n/**\n * ONE contract's MCP tools, keyed by protocol name — the artifact `wp-openapi` writes as\n * `mcp-<ContractClass>-tools.json`, one file per contract that declares `MCP` and has at least one\n * `@WpMcpTool`, beside the library's OpenAPI documents.\n *\n * ## Why one file per CONTRACT and not one per library\n *\n * One api library holds many contracts (it is how a public partner API is grouped), and a server binds\n * contracts, not libraries — `McpApiBinding.local(LangCourseAuthorApi, ...)`. With one file per\n * contract the server can check every binding against exactly the file generated from THAT contract,\n * and refuse a file it was handed for a contract it does not bind. A single per-library file could only\n * say \"some tool is missing\" (#1021).\n *\n * This is the browser-safe CODEC — the bytes and the file name. Reading the files from an installed\n * package is `McpToolCatalog.fromPackages` in `@webpieces/mcp-server`, because only a node process\n * has a filesystem to read them from.\n */\nexport class McpToolCatalogFile {\n    private readonly byName: ReadonlyMap<string, McpToolDefinition>;\n\n    constructor(\n        /** The contract CLASS name — `binding.api.name` at runtime, the class declaration at build time. */\n        readonly contractName: string,\n        readonly tools: readonly McpToolDefinition[],\n    ) {\n        if (!CONTRACT_NAME.test(contractName)) {\n            throw new McpToolCatalogError(\n                `'${contractName}' is not a contract class name, so it cannot name an MCP tool catalog.`,\n                REGENERATE,\n            );\n        }\n        const byName = new Map<string, McpToolDefinition>();\n        for (const tool of tools) {\n            if (byName.has(tool.name)) {\n                throw new McpToolCatalogError(\n                    `Duplicate MCP tool name '${tool.name}' in the generated catalog of ${contractName}.`,\n                    'Tool names are the protocol identity and must be globally unique — rename one ' +\n                        \"of the two @WpMcpTool('<name>', '<title>') declarations.\",\n                );\n            }\n            byName.set(tool.name, tool);\n        }\n        this.byName = byName;\n    }\n\n    /** `mcp-<ContractClass>-tools.json`. */\n    get fileName(): string {\n        return McpToolCatalogFile.fileNameFor(this.contractName);\n    }\n\n    find(name: string): McpToolDefinition | undefined {\n        return this.byName.get(name);\n    }\n\n    /** The names this catalog carries, sorted, so a failure can print what WAS published. */\n    names(): readonly string[] {\n        return [...this.byName.keys()].sort();\n    }\n\n    /** The bytes `wp-openapi` writes. Sorted by name so the artifact is diffable. */\n    toJsonText(): string {\n        const tools = [...this.tools].sort((left: McpToolDefinition, right: McpToolDefinition) =>\n            left.name.localeCompare(right.name),\n        );\n        return `${JSON.stringify(tools, undefined, 2)}\\n`;\n    }\n\n    /** The file name the catalog of `contractName` is written to and read from. */\n    // webpieces-disable no-function-outside-class -- static helper of this class\n    static fileNameFor(contractName: string): string {\n        return `${FILE_PREFIX}${contractName}${FILE_SUFFIX}`;\n    }\n\n    /** The contract a file name is the catalog of, or `undefined` when it is not one of these files. */\n    // webpieces-disable no-function-outside-class -- static helper of this class\n    static contractNameOf(fileName: string): string | undefined {\n        if (!fileName.startsWith(FILE_PREFIX) || !fileName.endsWith(FILE_SUFFIX)) return undefined;\n        const name = fileName.slice(FILE_PREFIX.length, fileName.length - FILE_SUFFIX.length);\n        return CONTRACT_NAME.test(name) ? name : undefined;\n    }\n\n    /**\n     * Reads one `mcp-<ContractClass>-tools.json`. The contract is the one the FILE NAME names. Every\n     * nested value is rebuilt as a real class instance, because this is the one place untyped bytes\n     * become the schemas a live protocol surface publishes.\n     *\n     * Malformed JSON is not caught here: it throws `SyntaxError` to the caller's own top-level\n     * handler, which is where every other read-the-world failure in webpieces is reported.\n     */\n    // webpieces-disable no-function-outside-class -- static factory of this class\n    static fromJsonText(fileName: string, text: string): McpToolCatalogFile {\n        const contractName = McpToolCatalogFile.contractNameOf(fileName);\n        if (contractName === undefined) {\n            throw new McpToolCatalogError(\n                `'${fileName}' is not an MCP tool catalog file name; they are named ` +\n                    `${FILE_PREFIX}<ContractClass>${FILE_SUFFIX}.`,\n                REGENERATE,\n            );\n        }\n        return new McpToolCatalogFile(contractName, new McpCatalogJson().parse(text));\n    }\n}\n\n/**\n * The PARSE BOUNDARY: untyped bytes in, real class instances out.\n *\n * A class of its own rather than statics on {@link McpToolCatalogFile} so every step is an ordinary\n * instance method — and because it is the one place in this file where `unknown` is the correct type\n * rather than a missing one. Nothing else in webpieces should ever hold a half-narrowed schema.\n */\nclass McpCatalogJson {\n    parse(text: string): readonly McpToolDefinition[] {\n        // webpieces-disable no-any-unknown -- this IS the untyped-bytes boundary; every step below narrows it\n        const parsed: unknown = JSON.parse(text);\n        if (!Array.isArray(parsed)) {\n            throw new McpToolCatalogError(\n                'The MCP tool catalog must be a JSON array of tool definitions.',\n                REGENERATE,\n            );\n        }\n        // webpieces-disable no-any-unknown -- parsing JSON is exactly where unknown belongs\n        return parsed.map((entry: unknown) => this.toolFrom(entry));\n    }\n\n    // webpieces-disable no-any-unknown -- parsing JSON is exactly where unknown belongs\n    private toolFrom(entry: unknown): McpToolDefinition {\n        const record = this.record(entry, 'a tool definition');\n        const hints = this.record(record['hints'], 'a tool definition hints block');\n        return new McpToolDefinition(\n            this.text(record['name'], 'name'),\n            this.title(record['title'], record['name']),\n            this.text(record['methodName'], 'methodName'),\n            this.text(record['description'], 'description'),\n            new WpMcpToolHints(\n                hints['readOnlyHint'] === true,\n                hints['destructiveHint'] === true,\n                hints['idempotentHint'] === true,\n                hints['openWorldHint'] === true,\n            ),\n            this.schemaFrom(record['inputSchema']),\n            this.schemaFrom(record['outputSchema']),\n            this.profiles(record['profiles']),\n        );\n    }\n\n    // webpieces-disable no-any-unknown -- JSON catalog parse boundary\n    private profiles(value: unknown): readonly string[] {\n        if (!Array.isArray(value) || !value.every((entry: unknown) => typeof entry === 'string')) {\n            throw new McpToolCatalogError(\n                'The MCP tool catalog requires profiles (#1187); stale artifacts are refused.',\n                REGENERATE,\n            );\n        }\n        return Mcp.profiles(value, 'MCP catalog profiles',\n            (message: string) => new McpToolCatalogError(message, REGENERATE));\n    }\n\n    // webpieces-disable no-any-unknown -- parsing JSON is exactly where unknown belongs\n    private schemaFrom(value: unknown): ApiJsonSchema {\n        const record = this.record(value, 'a JSON schema');\n        const schema = new ApiJsonSchema(\n            record['type'] as ApiJsonSchemaType | readonly ApiJsonSchemaType[],\n        );\n        if (typeof record['description'] === 'string') schema.description = record['description'];\n        if (typeof record['minimum'] === 'number') schema.minimum = record['minimum'];\n        if (typeof record['maximum'] === 'number') schema.maximum = record['maximum'];\n        if (Array.isArray(record['required'])) schema.required = record['required'] as string[];\n        if (Array.isArray(record['enum'])) schema.enum = record['enum'] as string[];\n        if (typeof record['x-mcp-header'] === 'string') {\n            schema['x-mcp-header'] = record['x-mcp-header'];\n        }\n        if (record['items'] !== undefined) schema.items = this.schemaFrom(record['items']);\n        const extra = record['additionalProperties'];\n        if (typeof extra === 'boolean') schema.additionalProperties = extra;\n        else if (extra !== undefined) schema.additionalProperties = this.schemaFrom(extra);\n        const properties = record['properties'];\n        if (properties !== undefined) {\n            const built: Record<string, ApiJsonSchema> = {};\n            for (const [key, child] of Object.entries(\n                this.record(properties, 'a schema properties block'),\n            )) {\n                built[key] = this.schemaFrom(child);\n            }\n            schema.properties = built;\n        }\n        const oneOf = record['oneOf'];\n        if (Array.isArray(oneOf)) {\n            // webpieces-disable no-any-unknown -- parsing JSON is exactly where unknown belongs\n            schema.oneOf = oneOf.map((branch: unknown) => this.schemaFrom(branch));\n            schema.discriminator = this.discriminatorFrom(record['discriminator']);\n        }\n        return schema;\n    }\n\n    /**\n     * The `discriminator` block, or undefined — a union TypeScript cannot narrow is published WITHOUT\n     * one, so an absent block is a legal document and not a missing field.\n     */\n    // webpieces-disable no-any-unknown -- parsing JSON is exactly where unknown belongs\n    private discriminatorFrom(value: unknown): ApiJsonSchemaDiscriminator | undefined {\n        if (value === undefined) return undefined;\n        const record = this.record(value, 'a schema discriminator block');\n        const mapping: Record<string, string> = {};\n        for (const [key, branch] of Object.entries(\n            this.record(record['mapping'], 'a discriminator mapping block'),\n        )) {\n            mapping[key] = this.text(branch, `discriminator mapping '${key}'`);\n        }\n        return new ApiJsonSchemaDiscriminator(\n            this.text(record['propertyName'], 'discriminator propertyName'),\n            mapping,\n        );\n    }\n\n    // webpieces-disable no-any-unknown -- parsing JSON is exactly where unknown belongs\n    private record(value: unknown, what: string): Record<string, unknown> {\n        if (typeof value !== 'object' || value === null || Array.isArray(value)) {\n            throw new McpToolCatalogError(`The MCP tool catalog is missing ${what}.`, REGENERATE);\n        }\n        // webpieces-disable no-any-unknown -- the narrowed result of the check above\n        return value as Record<string, unknown>;\n    }\n\n    /**\n     * The REQUIRED, non-blank `title` (#1180). A catalog generated before titles existed has none, and\n     * is refused here so a stale artifact fails the boot loudly instead of publishing untitled tools.\n     */\n    // webpieces-disable no-any-unknown -- parsing JSON is exactly where unknown belongs\n    private title(value: unknown, name: unknown): string {\n        if (typeof value !== 'string' || value.trim() === '') {\n            throw new McpToolCatalogError(\n                `The MCP tool catalog has no 'title' on tool '${String(name)}'; every tool needs a ` +\n                    \"human-readable title from @WpMcpTool('<name>', '<title>'). The catalog predates \" +\n                    'required titles (#1180).',\n                REGENERATE,\n            );\n        }\n        return value;\n    }\n\n    // webpieces-disable no-any-unknown -- parsing JSON is exactly where unknown belongs\n    private text(value: unknown, field: string): string {\n        if (typeof value !== 'string') {\n            throw new McpToolCatalogError(\n                `The MCP tool catalog has no '${field}' on a tool definition.`,\n                REGENERATE,\n            );\n        }\n        return value;\n    }\n}\n"]}
+{"version":3,"file":"McpToolCatalogFile.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/mcp/McpToolCatalogFile.ts"],"names":[],"mappings":"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","sourcesContent":["import { ApiJsonSchema, ApiJsonSchemaDiscriminator, ApiJsonSchemaType } from './DtoSchema';\nimport { Mcp } from './Mcp';\nimport { WpMcpToolHints } from './McpMetadata';\n\n/**\n * ONE generated MCP tool definition, including server-only profile membership.\n *\n * It is BUILT from the source by `@webpieces/api-doc-model`'s `McpSchemaRenderer` at build time, and\n * READ here at boot — so the tool an agent is shown and the tool the server accepts are the same\n * bytes by construction, not by two declarations agreeing.\n *\n * It lives in `core-util` rather than in the extractor package because both ends need it and only\n * one end may depend on the TypeScript compiler API. `ApiJsonSchema` and {@link WpMcpToolHints},\n * which it is made of, are already here for the same reason.\n */\nexport class McpToolDefinition {\n    constructor(\n        /** The stable protocol name from `@WpMcpTool('<name>', '<title>')`. */\n        readonly name: string,\n        /**\n         * The human-readable display name from `@WpMcpTool('<name>', '<title>')`. REQUIRED (#1180):\n         * `tools/list` publishes it as both `Tool.title` and `annotations.title`, and a catalog entry\n         * without one is refused on load rather than silently publishing an untitled tool.\n         */\n        readonly title: string,\n        /** The contract method it was rendered from, so a mismatch report can name the source. */\n        readonly methodName: string,\n        /**\n         * The tool documentation: the method's `@mcp` tag when it has one, its JSDoc body otherwise.\n         * Documentation has exactly ONE source — the doc comment above the declaration — for the\n         * partner reading OpenAPI and the agent reading `tools/list` alike.\n         */\n        readonly description: string,\n        /**\n         * All four hints. Three are COMPUTED from `@Endpoint`'s `operation` by\n         * `mcpHintsForOperation`, which is the one place that mapping lives; `openWorldHint` comes\n         * from `@Endpoint`'s `openWorld` option.\n         */\n        readonly hints: WpMcpToolHints,\n        readonly inputSchema: ApiJsonSchema,\n        readonly outputSchema: ApiJsonSchema,\n        readonly profiles: readonly string[],\n    ) {\n        this.profiles = Mcp.profiles(profiles, 'MCP catalog tool');\n    }\n}\n\n/** Thrown when a catalog is not one this release can read or write. */\nexport class McpToolCatalogError extends Error {\n    constructor(\n        message: string,\n        /** What to do instead, in one sentence. */\n        readonly cure: string,\n    ) {\n        super(`${message} ${cure}`);\n        this.name = 'McpToolCatalogError';\n        Object.setPrototypeOf(this, new.target.prototype);\n    }\n}\n\n/** The one cure every catalog failure prescribes: rebuild the artifact from the contracts. */\nconst REGENERATE =\n    'Rebuild the api library that declares the contract (its `openapi-generate` target runs ' +\n    '`wp-openapi`, which writes one `mcp-<ContractClass>-tools.json` per MCP contract).';\n\nconst FILE_PREFIX = 'mcp-';\nconst FILE_SUFFIX = '-tools.json';\n\n/** A class name, which is what the file name carries. Anything else is not one of these files. */\nconst CONTRACT_NAME = /^[A-Za-z_$][A-Za-z0-9_$]*$/;\n\n/**\n * ONE contract's MCP tools, keyed by protocol name — the artifact `wp-openapi` writes as\n * `mcp-<ContractClass>-tools.json`, one file per contract that declares `MCP` and has at least one\n * `@WpMcpTool`, beside the library's OpenAPI documents.\n *\n * ## Why one file per CONTRACT and not one per library\n *\n * One api library holds many contracts (it is how a public partner API is grouped), and a server binds\n * contracts, not libraries — `McpApiBinding.local(LangCourseAuthorApi, ...)`. With one file per\n * contract the server can check every binding against exactly the file generated from THAT contract,\n * and refuse a file it was handed for a contract it does not bind. A single per-library file could only\n * say \"some tool is missing\" (#1021).\n *\n * This is the browser-safe CODEC — the bytes and the file name. Reading the files from an installed\n * package is `McpToolCatalog.fromPackages` in `@webpieces/mcp-server`, because only a node process\n * has a filesystem to read them from.\n */\nexport class McpToolCatalogFile {\n    private readonly byName: ReadonlyMap<string, McpToolDefinition>;\n\n    constructor(\n        /** The contract CLASS name — `binding.api.name` at runtime, the class declaration at build time. */\n        readonly contractName: string,\n        readonly tools: readonly McpToolDefinition[],\n    ) {\n        if (!CONTRACT_NAME.test(contractName)) {\n            throw new McpToolCatalogError(\n                `'${contractName}' is not a contract class name, so it cannot name an MCP tool catalog.`,\n                REGENERATE,\n            );\n        }\n        const byName = new Map<string, McpToolDefinition>();\n        for (const tool of tools) {\n            if (byName.has(tool.name)) {\n                throw new McpToolCatalogError(\n                    `Duplicate MCP tool name '${tool.name}' in the generated catalog of ${contractName}.`,\n                    'Tool names are the protocol identity and must be globally unique — rename one ' +\n                        \"of the two @WpMcpTool('<name>', '<title>') declarations.\",\n                );\n            }\n            byName.set(tool.name, tool);\n        }\n        this.byName = byName;\n    }\n\n    /** `mcp-<ContractClass>-tools.json`. */\n    get fileName(): string {\n        return McpToolCatalogFile.fileNameFor(this.contractName);\n    }\n\n    find(name: string): McpToolDefinition | undefined {\n        return this.byName.get(name);\n    }\n\n    /** The names this catalog carries, sorted, so a failure can print what WAS published. */\n    names(): readonly string[] {\n        return [...this.byName.keys()].sort();\n    }\n\n    /** The bytes `wp-openapi` writes. Sorted by name so the artifact is diffable. */\n    toJsonText(): string {\n        const tools = [...this.tools].sort((left: McpToolDefinition, right: McpToolDefinition) =>\n            left.name.localeCompare(right.name),\n        );\n        return `${JSON.stringify(tools, undefined, 2)}\\n`;\n    }\n\n    /** The file name the catalog of `contractName` is written to and read from. */\n    // webpieces-disable no-function-outside-class -- static helper of this class\n    static fileNameFor(contractName: string): string {\n        return `${FILE_PREFIX}${contractName}${FILE_SUFFIX}`;\n    }\n\n    /** The contract a file name is the catalog of, or `undefined` when it is not one of these files. */\n    // webpieces-disable no-function-outside-class -- static helper of this class\n    static contractNameOf(fileName: string): string | undefined {\n        if (!fileName.startsWith(FILE_PREFIX) || !fileName.endsWith(FILE_SUFFIX)) return undefined;\n        const name = fileName.slice(FILE_PREFIX.length, fileName.length - FILE_SUFFIX.length);\n        return CONTRACT_NAME.test(name) ? name : undefined;\n    }\n\n    /**\n     * Reads one `mcp-<ContractClass>-tools.json`. The contract is the one the FILE NAME names. Every\n     * nested value is rebuilt as a real class instance, because this is the one place untyped bytes\n     * become the schemas a live protocol surface publishes.\n     *\n     * Malformed JSON is not caught here: it throws `SyntaxError` to the caller's own top-level\n     * handler, which is where every other read-the-world failure in webpieces is reported.\n     */\n    // webpieces-disable no-function-outside-class -- static factory of this class\n    static fromJsonText(fileName: string, text: string): McpToolCatalogFile {\n        const contractName = McpToolCatalogFile.contractNameOf(fileName);\n        if (contractName === undefined) {\n            throw new McpToolCatalogError(\n                `'${fileName}' is not an MCP tool catalog file name; they are named ` +\n                    `${FILE_PREFIX}<ContractClass>${FILE_SUFFIX}.`,\n                REGENERATE,\n            );\n        }\n        return new McpToolCatalogFile(contractName, new McpCatalogJson().parse(text));\n    }\n}\n\n/**\n * The PARSE BOUNDARY: untyped bytes in, real class instances out.\n *\n * A class of its own rather than statics on {@link McpToolCatalogFile} so every step is an ordinary\n * instance method — and because it is the one place in this file where `unknown` is the correct type\n * rather than a missing one. Nothing else in webpieces should ever hold a half-narrowed schema.\n */\nclass McpCatalogJson {\n    parse(text: string): readonly McpToolDefinition[] {\n        // webpieces-disable no-any-unknown -- this IS the untyped-bytes boundary; every step below narrows it\n        const parsed: unknown = JSON.parse(text);\n        if (!Array.isArray(parsed)) {\n            throw new McpToolCatalogError(\n                'The MCP tool catalog must be a JSON array of tool definitions.',\n                REGENERATE,\n            );\n        }\n        // webpieces-disable no-any-unknown -- parsing JSON is exactly where unknown belongs\n        return parsed.map((entry: unknown) => this.toolFrom(entry));\n    }\n\n    // webpieces-disable no-any-unknown -- parsing JSON is exactly where unknown belongs\n    private toolFrom(entry: unknown): McpToolDefinition {\n        const record = this.record(entry, 'a tool definition');\n        const hints = this.record(record['hints'], 'a tool definition hints block');\n        return new McpToolDefinition(\n            this.text(record['name'], 'name'),\n            this.title(record['title'], record['name']),\n            this.text(record['methodName'], 'methodName'),\n            this.text(record['description'], 'description'),\n            new WpMcpToolHints(\n                hints['readOnlyHint'] === true,\n                hints['destructiveHint'] === true,\n                hints['idempotentHint'] === true,\n                hints['openWorldHint'] === true,\n            ),\n            this.schemaFrom(record['inputSchema']),\n            this.schemaFrom(record['outputSchema']),\n            this.profiles(record['profiles']),\n        );\n    }\n\n    // webpieces-disable no-any-unknown -- JSON catalog parse boundary\n    private profiles(value: unknown): readonly string[] {\n        if (!Array.isArray(value) || !value.every((entry: unknown) => typeof entry === 'string')) {\n            throw new McpToolCatalogError(\n                'The MCP tool catalog requires profiles (#1187); stale artifacts are refused.',\n                REGENERATE,\n            );\n        }\n        return Mcp.profiles(value, 'MCP catalog profiles',\n            (message: string) => new McpToolCatalogError(message, REGENERATE));\n    }\n\n    // webpieces-disable no-any-unknown -- parsing JSON is exactly where unknown belongs\n    private schemaFrom(value: unknown): ApiJsonSchema {\n        const record = this.record(value, 'a JSON schema');\n        const schema = new ApiJsonSchema(\n            record['type'] as ApiJsonSchemaType | readonly ApiJsonSchemaType[],\n        );\n        if (typeof record['description'] === 'string') schema.description = record['description'];\n        if (typeof record['minimum'] === 'number') schema.minimum = record['minimum'];\n        if (typeof record['maximum'] === 'number') schema.maximum = record['maximum'];\n        if (Array.isArray(record['required'])) schema.required = record['required'] as string[];\n        if (Array.isArray(record['enum'])) schema.enum = record['enum'] as (string | null)[];\n        if (typeof record['x-mcp-header'] === 'string') {\n            schema['x-mcp-header'] = record['x-mcp-header'];\n        }\n        if (record['items'] !== undefined) schema.items = this.schemaFrom(record['items']);\n        const extra = record['additionalProperties'];\n        if (typeof extra === 'boolean') schema.additionalProperties = extra;\n        else if (extra !== undefined) schema.additionalProperties = this.schemaFrom(extra);\n        const properties = record['properties'];\n        if (properties !== undefined) {\n            const built: Record<string, ApiJsonSchema> = {};\n            for (const [key, child] of Object.entries(\n                this.record(properties, 'a schema properties block'),\n            )) {\n                built[key] = this.schemaFrom(child);\n            }\n            schema.properties = built;\n        }\n        const oneOf = record['oneOf'];\n        if (Array.isArray(oneOf)) {\n            // webpieces-disable no-any-unknown -- parsing JSON is exactly where unknown belongs\n            schema.oneOf = oneOf.map((branch: unknown) => this.schemaFrom(branch));\n            schema.discriminator = this.discriminatorFrom(record['discriminator']);\n        }\n        return schema;\n    }\n\n    /**\n     * The `discriminator` block, or undefined — a union TypeScript cannot narrow is published WITHOUT\n     * one, so an absent block is a legal document and not a missing field.\n     */\n    // webpieces-disable no-any-unknown -- parsing JSON is exactly where unknown belongs\n    private discriminatorFrom(value: unknown): ApiJsonSchemaDiscriminator | undefined {\n        if (value === undefined) return undefined;\n        const record = this.record(value, 'a schema discriminator block');\n        const mapping: Record<string, string> = {};\n        for (const [key, branch] of Object.entries(\n            this.record(record['mapping'], 'a discriminator mapping block'),\n        )) {\n            mapping[key] = this.text(branch, `discriminator mapping '${key}'`);\n        }\n        return new ApiJsonSchemaDiscriminator(\n            this.text(record['propertyName'], 'discriminator propertyName'),\n            mapping,\n        );\n    }\n\n    // webpieces-disable no-any-unknown -- parsing JSON is exactly where unknown belongs\n    private record(value: unknown, what: string): Record<string, unknown> {\n        if (typeof value !== 'object' || value === null || Array.isArray(value)) {\n            throw new McpToolCatalogError(`The MCP tool catalog is missing ${what}.`, REGENERATE);\n        }\n        // webpieces-disable no-any-unknown -- the narrowed result of the check above\n        return value as Record<string, unknown>;\n    }\n\n    /**\n     * The REQUIRED, non-blank `title` (#1180). A catalog generated before titles existed has none, and\n     * is refused here so a stale artifact fails the boot loudly instead of publishing untitled tools.\n     */\n    // webpieces-disable no-any-unknown -- parsing JSON is exactly where unknown belongs\n    private title(value: unknown, name: unknown): string {\n        if (typeof value !== 'string' || value.trim() === '') {\n            throw new McpToolCatalogError(\n                `The MCP tool catalog has no 'title' on tool '${String(name)}'; every tool needs a ` +\n                    \"human-readable title from @WpMcpTool('<name>', '<title>'). The catalog predates \" +\n                    'required titles (#1180).',\n                REGENERATE,\n            );\n        }\n        return value;\n    }\n\n    // webpieces-disable no-any-unknown -- parsing JSON is exactly where unknown belongs\n    private text(value: unknown, field: string): string {\n        if (typeof value !== 'string') {\n            throw new McpToolCatalogError(\n                `The MCP tool catalog has no '${field}' on a tool definition.`,\n                REGENERATE,\n            );\n        }\n        return value;\n    }\n}\n"]}