@webpieces/core-util 0.4.806 → 0.4.807

package/src/mcp/DtoSchema.js

@@ -1,84 +1,25 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DtoSchemaBuilder = exports.DtoValidationFailure = exports.ApiJsonSchema = exports.WpDtoFieldMetadata = exports.WpDtoMapFieldOptions = exports.WpMcpHeader = exports.WpDtoFieldOptions = void 0;
-exports.WpDto = WpDto;
-exports.WpDtoField = WpDtoField;
-exports.WpResponseDto = WpResponseDto;
-require("reflect-metadata");
-const DTO_MARKER = 'webpieces:dto-schema';
-const DTO_FIELDS = 'webpieces:dto-fields';
-const RESPONSE_DTOS = 'webpieces:response-dtos';
-/** Additive field metadata; the scalar/object type itself comes from `design:type`. */
-class WpDtoFieldOptions {
-    description;
-    required;
-    arrayItems;
-    integer;
-    minimum;
-    maximum;
-    enumValues;
-    mcpHeader;
-    constructor(description, 
-    /** Required/optional is explicit because TypeScript erases `?` at runtime. */
-    required, 
-    /** Required for arrays because TypeScript erases their element type. */
-    arrayItems, 
-    /** A reflected Number is otherwise emitted as JSON Schema `number`. */
-    integer = false, minimum, maximum, enumValues, 
-    /** MCP 2026 SEP-2243 header mirrored as `Mcp-Param-{name}`. */
-    mcpHeader) {
-        this.description = description;
-        this.required = required;
-        this.arrayItems = arrayItems;
-        this.integer = integer;
-        this.minimum = minimum;
-        this.maximum = maximum;
-        this.enumValues = enumValues;
-        this.mcpHeader = mcpHeader;
-    }
-}
-exports.WpDtoFieldOptions = WpDtoFieldOptions;
 /**
- * Names the `x-mcp-header` a primitive tool parameter is mirrored into (`Mcp-Param-{name}`). A class,
- * not a bare string, so the 8th `WpDtoFieldOptions` argument can never be mistaken for a map value
- * type (maps use `WpDtoMapFieldOptions`).
+ * The JSON Schema subset webpieces publishes on its API boundaries, and the ONE runtime validator of
+ * it.
+ *
+ * ## Nothing here reads reflect-metadata any more
+ *
+ * Until #984 this file also carried `@WpDto`, `@WpDtoField`, `WpDtoFieldOptions`,
+ * `WpDtoMapFieldOptions`, `WpMcpHeader`, `@WpResponseDto` and `DtoSchemaBuilder` — a second, runtime
+ * spelling of facts the TypeScript compiler already holds. #983 measured the two against each other
+ * and found the compiler reproduces every one of those arguments byte for byte, so they are deleted
+ * rather than deprecated (`.claude/rules/no-backwards-compat.md`): a schema is now BUILT at build
+ * time from the source by `@webpieces/api-doc-model`, and the runtime is HANDED the result.
+ *
+ * What survives is the schema itself, a builder for the boundaries that construct one by hand, and a
+ * validator that reads the schema instead of a decorator.
  */
-class WpMcpHeader {
-    name;
-    constructor(name) {
-        this.name = name;
-    }
-}
-exports.WpMcpHeader = WpMcpHeader;
-/**
- * Field metadata for a typed map such as `Record<string, string>` or `Record<string, SomeDto>`.
- * Keys are open strings; every VALUE must match `mapValues`. The value type is explicit for the same
- * reason `arrayItems` is: TypeScript erases it, and a `Record` reflects as plain `Object`.
- */
-class WpDtoMapFieldOptions {
-    description;
-    required;
-    mapValues;
-    constructor(description, 
-    /** Required/optional is explicit because TypeScript erases `?` at runtime. */
-    required, mapValues) {
-        this.description = description;
-        this.required = required;
-        this.mapValues = mapValues;
-    }
-}
-exports.WpDtoMapFieldOptions = WpDtoMapFieldOptions;
-class WpDtoFieldMetadata {
-    propertyKey;
-    options;
-    constructor(propertyKey, options) {
-        this.propertyKey = propertyKey;
-        this.options = options;
-    }
-}
-exports.WpDtoFieldMetadata = WpDtoFieldMetadata;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiJsonSchemaValidator = exports.DtoValidationFailure = exports.ObjectSchemaBuilder = exports.ApiJsonSchema = void 0;
 /** The JSON Schema subset emitted for Webpieces API DTOs. */
 class ApiJsonSchema {
+    /** One type, or `[T, "null"]` for a nullable field. */
     type;
     description;
     properties;
@@ -92,8 +33,71 @@ class ApiJsonSchema {
     constructor(type) {
         this.type = type;
     }
+    /**
+     * The non-`null` member of the type, which is the one that decides how a value is checked.
+     *
+     * These three are STATIC and not instance methods on purpose: an instance method would put a
+     * function on the structural type, and this class is handed straight to the MCP SDK, whose
+     * parameter types are index-signature JSON objects that a class carrying methods no longer
+     * satisfies. It stays a data-only structure (`CLAUDE.md` §1) and the helpers live beside it.
+     */
+    // webpieces-disable no-function-outside-class -- static reader of this class
+    static baseTypeOf(schema) {
+        if (schema.type === undefined)
+            return undefined;
+        if (typeof schema.type === 'string')
+            return schema.type;
+        return schema.type.find((one) => one !== 'null');
+    }
+    /** True when the schema was widened with `"null"`, i.e. the property may hold `null`. */
+    // webpieces-disable no-function-outside-class -- static reader of this class
+    static allowsNull(schema) {
+        return typeof schema.type !== 'string' && (schema.type?.includes('null') ?? false);
+    }
+    /**
+     * The one closure gate for an object schema. Closed means no key can carry an unspecified value:
+     * either extra keys are forbidden (`additionalProperties: false`) or every extra key's value is
+     * typed (`additionalProperties: <schema>`, a typed map). A missing or `true` value is open.
+     * Use this instead of `schema.additionalProperties === false`, which rejects typed maps.
+     */
+    // webpieces-disable no-function-outside-class -- static reader of this class
+    static isClosed(schema) {
+        const extra = schema.additionalProperties;
+        return extra === false || (typeof extra === 'object' && extra !== null);
+    }
 }
 exports.ApiJsonSchema = ApiJsonSchema;
+/**
+ * Builds the CLOSED object schema a hand-written runtime boundary validates against — `@WpStream`'s
+ * two event schemas are the whole of its client list today.
+ *
+ * It exists because the alternative spellings are both worse: a decorator that re-states the field
+ * types the compiler already knows is exactly what #984 deleted, and a bare object literal is what
+ * `CLAUDE.md` §3 forbids. A generated schema never comes through here — it is read from the build's
+ * own artifact.
+ */
+class ObjectSchemaBuilder {
+    schema = new ApiJsonSchema('object');
+    requiredNames = [];
+    constructor() {
+        this.schema.properties = {};
+        this.schema.additionalProperties = false;
+    }
+    required(name, type) {
+        this.requiredNames.push(name);
+        return this.optional(name, type);
+    }
+    optional(name, type) {
+        this.schema.properties[name] = type;
+        return this;
+    }
+    build() {
+        if (this.requiredNames.length > 0)
+            this.schema.required = [...this.requiredNames];
+        return this.schema;
+    }
+}
+exports.ObjectSchemaBuilder = ObjectSchemaBuilder;
 /** A validation result safe to show to an API caller/model. */
 class DtoValidationFailure {
     field;
@@ -106,305 +110,110 @@ class DtoValidationFailure {
     }
 }
 exports.DtoValidationFailure = DtoValidationFailure;
-/** Marks a request/response class as a schema-bearing DTO, including intentionally empty DTOs. */
-// webpieces-disable no-function-outside-class -- decorator factories are inherently module-scope
-function WpDto() {
-    return (target) => Reflect.defineMetadata(DTO_MARKER, true, target);
-}
-/** Adds documentation and runtime-only shape facts to a DTO property. */
-// webpieces-disable no-function-outside-class -- decorator factories are inherently module-scope
-function WpDtoField(options) {
-    if (options.description.trim() === '') {
-        throw new Error('@WpDtoField requires non-empty field documentation.');
-    }
-    return (target, propertyKey) => {
-        const dtoClass = target.constructor;
-        const fields = Reflect.getMetadata(DTO_FIELDS, dtoClass) ?? {};
-        const name = String(propertyKey);
-        fields[name] = new WpDtoFieldMetadata(name, options);
-        Reflect.defineMetadata(DTO_FIELDS, fields, dtoClass);
-    };
-}
-/** Declares an async API method's response DTO because reflection sees Promise, not its generic. */
-// webpieces-disable no-function-outside-class -- decorator factories are inherently module-scope
-function WpResponseDto(responseDto) {
-    return (target, propertyKey) => {
-        const apiClass = target.constructor;
-        const responses = Reflect.getMetadata(RESPONSE_DTOS, apiClass) ?? {};
-        responses[String(propertyKey)] = responseDto;
-        Reflect.defineMetadata(RESPONSE_DTOS, responses, apiClass);
-    };
-}
-/** Builds and validates the same DTO schema used for MCP input and structured output. */
-class DtoSchemaBuilder {
-    requestClassOf(apiClass, methodName) {
-        // webpieces-disable no-any-unknown -- reflect-metadata returns erased runtime constructor tokens
-        const params = Reflect.getMetadata('design:paramtypes', apiClass.prototype, methodName);
-        if (!params || params.length !== 1) {
-            throw new Error(`${apiClass.name}.${methodName} must take exactly one @WpDto request class to be an MCP tool.`);
-        }
-        return params[0];
-    }
-    responseClassOf(apiClass, methodName) {
-        const responses = Reflect.getMetadata(RESPONSE_DTOS, apiClass) ?? {};
-        const response = responses[methodName];
-        if (!response) {
-            throw new Error(`${apiClass.name}.${methodName} must declare @WpResponseDto(() => ResponseClass) before MCP exposure.`);
-        }
-        return response();
-    }
-    /**
-     * The one closure gate for an object schema. Closed means no key can carry an unspecified value:
-     * either extra keys are forbidden (`additionalProperties: false`) or every extra key's value is
-     * typed (`additionalProperties: <schema>`, a typed map). A missing or `true` value is open.
-     * Use this instead of `schema.additionalProperties === false`, which rejects typed maps.
-     */
-    isClosedSchema(schema) {
-        const extra = schema.additionalProperties;
-        return extra === false || (typeof extra === 'object' && extra !== null);
-    }
-    build(dtoClass) {
-        const schema = this.buildAt(dtoClass, new Set());
-        this.validateMcpHeaders(schema, new Map());
-        return schema;
-    }
-    validate(dtoClass, value) {
-        return this.validateAt(dtoClass, value, '$');
-    }
-    buildAt(dtoClass, parents) {
-        this.requireDto(dtoClass);
-        if (parents.has(dtoClass)) {
-            throw new Error(`Recursive DTO ${dtoClass.name} cannot use an inline MCP schema.`);
-        }
-        const nextParents = new Set(parents);
-        nextParents.add(dtoClass);
-        const schema = new ApiJsonSchema('object');
-        schema.properties = {};
-        schema.additionalProperties = false;
-        const required = [];
-        for (const field of this.fields(dtoClass)) {
-            schema.properties[field.propertyKey] = this.fieldSchema(dtoClass, field, nextParents);
-            if (field.options.required)
-                required.push(field.propertyKey);
-        }
-        if (required.length > 0)
-            schema.required = required;
-        return schema;
+/**
+ * Validates a value against an {@link ApiJsonSchema} — the ONE runtime narrowing boundary for MCP
+ * tool arguments, MCP structured output and typed stream events.
+ *
+ * It reads the SCHEMA, which is the same object the build published to agents, so a document that
+ * says a field is required and a server that accepts it missing cannot disagree. The predecessor
+ * walked reflect-metadata instead, which meant the published document and the accepted request were
+ * derived from two different declarations.
+ */
+class ApiJsonSchemaValidator {
+    validate(schema, value) {
+        return this.validateAt(schema, value, '$');
     }
-    fieldSchema(dtoClass, field, parents) {
-        // webpieces-disable no-any-unknown -- reflect-metadata returns an erased constructor token
-        const reflected = Reflect.getMetadata('design:type', dtoClass.prototype, field.propertyKey);
-        if (!reflected)
-            throw new Error(`No reflected type for ${dtoClass.name}.${field.propertyKey}.`);
-        this.validateOptions(dtoClass, field, reflected);
-        const options = field.options;
-        if (options instanceof WpDtoMapFieldOptions) {
-            const mapSchema = new ApiJsonSchema('object');
-            mapSchema.description = options.description;
-            mapSchema.additionalProperties = this.itemSchema(options.mapValues, parents);
-            return mapSchema;
-        }
-        let schema;
-        switch (reflected.name) {
-            case 'String':
-                schema = new ApiJsonSchema('string');
-                break;
-            case 'Number':
-                schema = new ApiJsonSchema(options.integer ? 'integer' : 'number');
-                break;
-            case 'Boolean':
-                schema = new ApiJsonSchema('boolean');
-                break;
-            case 'Array':
-                if (!options.arrayItems) {
-                    throw new Error(`${dtoClass.name}.${field.propertyKey} must declare arrayItems.`);
-                }
-                schema = new ApiJsonSchema('array');
-                schema.items = this.itemSchema(options.arrayItems, parents);
-                break;
+    validateAt(schema, value, path) {
+        if (value === null) {
+            return ApiJsonSchema.allowsNull(schema)
+                ? undefined
+                : new DtoValidationFailure(path, `${path} must not be null`);
+        }
+        switch (ApiJsonSchema.baseTypeOf(schema)) {
+            case 'object':
+                return this.validateObject(schema, value, path);
+            case 'array':
+                return this.validateArray(schema, value, path);
+            case 'string':
+                return this.validateString(schema, value, path);
+            case 'number':
+            case 'integer':
+                return this.validateNumber(schema, value, path);
+            case 'boolean':
+                return typeof value === 'boolean'
+                    ? undefined
+                    : new DtoValidationFailure(path, `${path} must be a boolean`);
             default:
-                schema = this.buildAt(reflected, parents);
+                return undefined;
         }
-        schema.description = options.description;
-        if (options.minimum !== undefined)
-            schema.minimum = options.minimum;
-        if (options.maximum !== undefined)
-            schema.maximum = options.maximum;
-        if (options.enumValues)
-            schema.enum = [...options.enumValues];
-        if (options.mcpHeader)
-            schema['x-mcp-header'] = options.mcpHeader.name;
-        return schema;
     }
-    validateOptions(dtoClass, field, reflected) {
-        const label = `${dtoClass.name}.${field.propertyKey}`;
-        const options = field.options;
-        if (options instanceof WpDtoMapFieldOptions) {
-            if (reflected !== Object) {
-                throw new Error(`${label} declares mapValues but is not a map (Record<string, V>).`);
-            }
-            return;
-        }
-        if (reflected === Object) {
-            throw new Error(`${label} has type Object: an interface or Record can never be a @WpDto. ` +
-                'For a map, use WpDtoMapFieldOptions.');
-        }
-        if (reflected.name !== 'Array' && options.arrayItems) {
-            throw new Error(`${label} declares arrayItems but is not an array.`);
-        }
-        if (reflected.name !== 'Number' &&
-            (options.integer || options.minimum !== undefined || options.maximum !== undefined)) {
-            throw new Error(`${label} declares numeric constraints but is not a number.`);
-        }
-        if (options.minimum !== undefined &&
-            options.maximum !== undefined &&
-            options.minimum > options.maximum) {
-            throw new Error(`${label} minimum cannot exceed maximum.`);
-        }
-        if (options.enumValues && reflected.name !== 'String') {
-            throw new Error(`${label} enumValues require a string field.`);
-        }
-        if (options.mcpHeader !== undefined) {
-            if (!/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(options.mcpHeader.name)) {
-                throw new Error(`${label} mcpHeader must be an RFC 9110 token.`);
-            }
-            if (!['String', 'Number', 'Boolean'].includes(reflected.name)) {
-                throw new Error(`${label} mcpHeader requires a primitive field.`);
-            }
-            if (reflected.name === 'Number' && !options.integer) {
-                throw new Error(`${label} mcpHeader cannot mirror a non-integer number (MCP 2026-07-28).`);
-            }
-        }
-    }
-    itemSchema(item, parents) {
-        if (typeof item !== 'string')
-            return this.buildAt(item, parents);
-        return new ApiJsonSchema(item === 'integer' ? 'integer' : item);
-    }
-    validateMcpHeaders(schema, seen) {
-        const header = schema['x-mcp-header'];
-        if (header) {
-            const key = header.toLowerCase();
-            const prior = seen.get(key);
-            if (prior) {
-                throw new Error(`mcpHeader '${header}' duplicates '${prior}' case-insensitively.`);
-            }
-            seen.set(key, header);
-        }
-        for (const child of Object.values(schema.properties ?? {})) {
-            this.validateMcpHeaders(child, seen);
-        }
-    }
-    validateAt(dtoClass, value, path) {
-        this.requireDto(dtoClass);
+    validateObject(schema, value, path) {
         if (typeof value !== 'object' || value === null || Array.isArray(value)) {
             return new DtoValidationFailure(path, `${path} must be an object`);
         }
-        const fields = this.fields(dtoClass);
-        const known = new Set(fields.map((field) => field.propertyKey));
+        const properties = schema.properties ?? {};
+        const extra = schema.additionalProperties;
         for (const key of Object.keys(value)) {
-            if (!known.has(key))
-                return new DtoValidationFailure(`${path}.${key}`, `${path}.${key} is not allowed`);
-        }
-        for (const field of fields) {
-            const fieldValue = Object.getOwnPropertyDescriptor(value, field.propertyKey)?.value;
-            if (fieldValue === undefined) {
-                if (field.options.required) {
-                    return new DtoValidationFailure(`${path}.${field.propertyKey}`, `${path}.${field.propertyKey} is required`);
+            const entry = Object.getOwnPropertyDescriptor(value, key)?.value;
+            const declared = Object.getOwnPropertyDescriptor(properties, key)?.value;
+            if (declared === undefined) {
+                if (typeof extra !== 'object' || extra === null) {
+                    return new DtoValidationFailure(`${path}.${key}`, `${path}.${key} is not allowed`);
                 }
+                const failure = this.validateAt(extra, entry, `${path}.${key}`);
+                if (failure)
+                    return failure;
                 continue;
             }
-            const failure = this.validateField(dtoClass, field, fieldValue, `${path}.${field.propertyKey}`);
+            const failure = this.validateAt(declared, entry, `${path}.${key}`);
             if (failure)
                 return failure;
         }
-        return undefined;
-    }
-    validateField(dtoClass, field, value, path) {
-        // webpieces-disable no-any-unknown -- reflect-metadata returns an erased constructor token
-        const reflected = Reflect.getMetadata('design:type', dtoClass.prototype, field.propertyKey);
-        const options = field.options;
-        if (options instanceof WpDtoMapFieldOptions)
-            return this.validateMap(options, value, path);
-        const expected = reflected?.name;
-        if (expected === 'Array')
-            return this.validateArray(options, value, path);
-        if (expected === 'String') {
-            if (typeof value !== 'string')
-                return new DtoValidationFailure(path, `${path} must be a string`);
-            if (options.enumValues && !options.enumValues.includes(value)) {
-                return new DtoValidationFailure(path, `${path} must be one of: ${options.enumValues.join(', ')}`);
-            }
-            return undefined;
-        }
-        if (expected === 'Number') {
-            if (typeof value !== 'number' || !Number.isFinite(value)) {
-                return new DtoValidationFailure(path, `${path} must be a number`);
-            }
-            if (options.integer && !Number.isInteger(value)) {
-                return new DtoValidationFailure(path, `${path} must be an integer`);
+        for (const name of schema.required ?? []) {
+            if (Object.getOwnPropertyDescriptor(value, name)?.value === undefined) {
+                return new DtoValidationFailure(`${path}.${name}`, `${path}.${name} is required`);
             }
-            if (options.minimum !== undefined && value < options.minimum) {
-                return new DtoValidationFailure(path, `${path} must be >= ${options.minimum}`);
-            }
-            if (options.maximum !== undefined && value > options.maximum) {
-                return new DtoValidationFailure(path, `${path} must be <= ${options.maximum}`);
-            }
-            return undefined;
         }
-        if (expected === 'Boolean') {
-            return typeof value === 'boolean'
-                ? undefined
-                : new DtoValidationFailure(path, `${path} must be a boolean`);
-        }
-        return this.validateAt(reflected, value, path);
+        return undefined;
     }
-    validateArray(options, value, path) {
-        if (!Array.isArray(value))
+    validateArray(schema, value, path) {
+        if (!Array.isArray(value)) {
             return new DtoValidationFailure(path, `${path} must be an array`);
-        if (!options.arrayItems)
-            return new DtoValidationFailure(path, `${path} has no item type`);
+        }
+        const items = schema.items;
+        if (items === undefined)
+            return undefined;
         for (let index = 0; index < value.length; index += 1) {
-            const failure = this.validateElement(options.arrayItems, value[index], `${path}[${index}]`);
+            const failure = this.validateAt(items, value[index], `${path}[${index}]`);
             if (failure)
                 return failure;
         }
         return undefined;
     }
-    validateMap(options, value, path) {
-        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-            return new DtoValidationFailure(path, `${path} must be an object map`);
+    validateString(schema, value, path) {
+        if (typeof value !== 'string') {
+            return new DtoValidationFailure(path, `${path} must be a string`);
         }
-        const prototype = Object.getPrototypeOf(value);
-        if (prototype !== Object.prototype && prototype !== null) {
-            return new DtoValidationFailure(path, `${path} must be a plain object map`);
-        }
-        for (const key of Object.keys(value)) {
-            const entry = Object.getOwnPropertyDescriptor(value, key)?.value;
-            const failure = this.validateElement(options.mapValues, entry, `${path}.${key}`);
-            if (failure)
-                return failure;
+        if (schema.enum && !schema.enum.includes(value)) {
+            return new DtoValidationFailure(path, `${path} must be one of: ${schema.enum.join(', ')}`);
         }
         return undefined;
     }
-    validateElement(type, item, path) {
-        if (typeof type !== 'string')
-            return this.validateAt(type, item, path);
-        const wanted = type === 'integer' ? 'number' : type;
-        if (typeof item !== wanted || (type === 'integer' && !Number.isInteger(item))) {
-            return new DtoValidationFailure(path, `${path} must be ${type}`);
+    validateNumber(schema, value, path) {
+        if (typeof value !== 'number' || !Number.isFinite(value)) {
+            return new DtoValidationFailure(path, `${path} must be a number`);
         }
-        return undefined;
-    }
-    fields(dtoClass) {
-        const fields = Reflect.getMetadata(DTO_FIELDS, dtoClass) ?? {};
-        return Object.values(fields);
-    }
-    requireDto(dtoClass) {
-        if (!Reflect.getMetadata(DTO_MARKER, dtoClass)) {
-            throw new Error(`${dtoClass.name} must be decorated with @WpDto() for schema generation.`);
+        if (ApiJsonSchema.baseTypeOf(schema) === 'integer' && !Number.isInteger(value)) {
+            return new DtoValidationFailure(path, `${path} must be an integer`);
         }
+        if (schema.minimum !== undefined && value < schema.minimum) {
+            return new DtoValidationFailure(path, `${path} must be >= ${schema.minimum}`);
+        }
+        if (schema.maximum !== undefined && value > schema.maximum) {
+            return new DtoValidationFailure(path, `${path} must be <= ${schema.maximum}`);
+        }
+        return undefined;
     }
 }
-exports.DtoSchemaBuilder = DtoSchemaBuilder;
+exports.ApiJsonSchemaValidator = ApiJsonSchemaValidator;
 //# sourceMappingURL=DtoSchema.js.map