@webpieces/openapi-generator 0.4.805 → 0.4.807

package/README.md

@@ -95,11 +95,16 @@ cannot.
 `MCP` in `@ApiType` requires `@WpMcpTool` on at least one method, and `@WpMcpTool` on a contract that
 does not declare `MCP` is an error. Membership has one spelling.
 
-The agent reads the SAME `description` a human does — the method's JSDoc, byte for byte.
-`@WpMcpTool`'s own `description` field is never read: two authored copies of one paragraph drift the
-first time somebody edits one. The tool carries only what JSDoc cannot say — the stable protocol name.
-`readOnlyHint`, `destructiveHint` and `idempotentHint` are computed from the endpoint's declared
-`operation`; `openWorldHint` comes from `{ openWorld: true }` on the endpoint.
+The agent reads the SAME `description` a human does — the method's JSDoc, byte for byte. Two authored
+copies of one paragraph drift the first time somebody edits one, so `@WpMcpTool('search_stores')`
+carries only what JSDoc cannot say: the stable protocol name. `readOnlyHint`, `destructiveHint` and
+`idempotentHint` are computed from the endpoint's declared `operation`; `openWorldHint` comes from
+`{ openWorld: true }` on the endpoint.
+
+Alongside `mcp-openapi.json`, a run writes **`mcp-tools.json`** whenever some contract declares `MCP`.
+That one is not a document: it is the RUNTIME catalog `WpMcpServer` is constructed with, so the schema
+an agent is shown in `tools/list` and the schema the server validates a call against are the same
+bytes. `--format` does not apply to it.
 
 ## It refuses to publish a field it has no schema for
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/openapi-generator",
-  "version": "0.4.805",
+  "version": "0.4.807",
   "description": "Render an ApiDocModel to OpenAPI 3.1.0 — the canonical internal document and the customer-published one, JSON and YAML, from one generation pass. Ships the wp-openapi bin.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -23,7 +23,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@webpieces/api-doc-model": "0.4.805",
+    "@webpieces/api-doc-model": "0.4.807",
+    "@webpieces/core-util": "0.4.807",
     "typescript": "5.9.3"
   },
   "bin": {

package/src/cli/OpenApiCli.d.ts

@@ -1,10 +1,15 @@
+import { SkippedMcpTool } from '@webpieces/api-doc-model';
 import { GeneratedArtifact } from '../emit/ArtifactWriter';
 export declare const USAGE: string;
 /** The result of one run: what was written, so a caller can print it or assert on it. */
 export declare class CliResult {
     readonly written: readonly string[];
     readonly artifacts: readonly GeneratedArtifact[];
-    constructor(written: readonly string[], artifacts: readonly GeneratedArtifact[]);
+    /** `@WpMcpTool`s the MCP catalog could not carry, with the reason. Never silent. */
+    readonly skippedMcpTools: readonly SkippedMcpTool[];
+    constructor(written: readonly string[], artifacts: readonly GeneratedArtifact[], 
+    /** `@WpMcpTool`s the MCP catalog could not carry, with the reason. Never silent. */
+    skippedMcpTools?: readonly SkippedMcpTool[]);
 }
 /**
  * `wp-openapi`'s argument parsing and composition, with NO process-level concerns in it — no
@@ -22,6 +27,18 @@ export declare class OpenApiCli {
     /** @param argv the arguments AFTER the program name. @param cwd what relative paths resolve against. */
     run(argv: readonly string[], cwd: string): CliResult;
     wantsHelp(argv: readonly string[]): boolean;
+    /**
+     * `mcp-tools.json` — the RUNTIME artifact, beside the three documents.
+     *
+     * It is not a document and is not serialized by `--format`: `WpMcpServer` is constructed with it,
+     * and `McpToolRegistry` fails fast at boot when a registered `@WpMcpTool` is missing from it. That
+     * is what took the MCP runtime off reflect-metadata (#984) — the schema an agent is shown and the
+     * schema the server accepts are now the same bytes, rather than two derivations of one contract.
+     *
+     * Written only when some contract declares `MCP`, which is the same rule `mcp-openapi.json`
+     * follows, for the same reason: an empty file is a claim that there are no tools.
+     */
+    private static mcpCatalog;
     /** `both` unless told otherwise: the second serialization comes free from the same document. */
     private formatOf;
     /**

package/src/cli/OpenApiCli.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OpenApiCli = exports.CliResult = exports.USAGE = void 0;
 const tslib_1 = require("tslib");
 const path = tslib_1.__importStar(require("node:path"));
+const core_util_1 = require("@webpieces/core-util");
+const api_doc_model_1 = require("@webpieces/api-doc-model");
 const ArtifactWriter_1 = require("../emit/ArtifactWriter");
 const OpenApiGenerator_1 = require("../generate/OpenApiGenerator");
 const InputsLoader_1 = require("../load/InputsLoader");
@@ -23,6 +25,9 @@ exports.USAGE = [
     '  public-openapi         contracts declaring EXTERNAL_CUSTOMER, minus every { hidden: true } method',
     '  mcp-openapi            contracts declaring MCP, carrying the x-mcp-* extensions',
     '',
+    'Alongside them, mcp-tools.json is written whenever some contract declares MCP: the RUNTIME',
+    'artifact WpMcpServer is constructed with. It is not a document, so --format does not apply.',
+    '',
     'A document no contract asked for is not written. --format chooses the serialization of',
     'whichever documents were written, and defaults to both.',
     '',
@@ -33,12 +38,25 @@ exports.USAGE = [
 class CliResult {
     written;
     artifacts;
-    constructor(written, artifacts) {
+    skippedMcpTools;
+    constructor(written, artifacts, 
+    /** `@WpMcpTool`s the MCP catalog could not carry, with the reason. Never silent. */
+    skippedMcpTools = []) {
         this.written = written;
         this.artifacts = artifacts;
+        this.skippedMcpTools = skippedMcpTools;
     }
 }
 exports.CliResult = CliResult;
+/** The MCP half of one run: the artifact to write, if any, and what it could not carry. */
+class McpArtifacts {
+    artifacts;
+    skipped;
+    constructor(artifacts, skipped) {
+        this.artifacts = artifacts;
+        this.skipped = skipped;
+    }
+}
 /**
  * `wp-openapi`'s argument parsing and composition, with NO process-level concerns in it — no
  * `process.exit`, no `console` — so the whole command is exercised by the suite exactly as a user
@@ -61,12 +79,41 @@ class OpenApiCli {
         }
         const inputs = this.loader.load(path.resolve(cwd, manifest));
         const documents = this.generator.generate(inputs);
-        const artifacts = this.writer.artifacts(documents, this.formatOf(argv));
-        return new CliResult(this.writer.write(path.resolve(cwd, out), artifacts), artifacts);
+        const mcp = OpenApiCli.mcpCatalog(inputs);
+        const artifacts = [
+            ...this.writer.artifacts(documents, this.formatOf(argv)),
+            ...mcp.artifacts,
+        ];
+        return new CliResult(this.writer.write(path.resolve(cwd, out), artifacts), artifacts, mcp.skipped);
     }
     wantsHelp(argv) {
         return argv.includes(HELP);
     }
+    /**
+     * `mcp-tools.json` — the RUNTIME artifact, beside the three documents.
+     *
+     * It is not a document and is not serialized by `--format`: `WpMcpServer` is constructed with it,
+     * and `McpToolRegistry` fails fast at boot when a registered `@WpMcpTool` is missing from it. That
+     * is what took the MCP runtime off reflect-metadata (#984) — the schema an agent is shown and the
+     * schema the server accepts are now the same bytes, rather than two derivations of one contract.
+     *
+     * Written only when some contract declares `MCP`, which is the same rule `mcp-openapi.json`
+     * follows, for the same reason: an empty file is a claim that there are no tools.
+     */
+    // webpieces-disable no-function-outside-class -- private static composition step of this class
+    static mcpCatalog(inputs) {
+        const models = inputs.contracts
+            .filter((contract) => contract.model.apiTypes.includes(core_util_1.MCP))
+            .map((contract) => contract.model);
+        if (models.length === 0) {
+            return new McpArtifacts([], []);
+        }
+        const rendered = api_doc_model_1.McpSchemaRenderer.catalogOf(models);
+        const artifacts = rendered.catalog.tools.length === 0
+            ? []
+            : [new ArtifactWriter_1.GeneratedArtifact('mcp-tools.json', rendered.catalog.toJsonText())];
+        return new McpArtifacts(artifacts, rendered.skipped);
+    }
     /** `both` unless told otherwise: the second serialization comes free from the same document. */
     formatOf(argv) {
         const declared = this.valueOf(argv, FORMAT);

package/src/cli/OpenApiCli.js.map

@@ -1 +1 @@
-{"version":3,"file":"OpenApiCli.js","sourceRoot":"","sources":["../../../../../../packages/docs/openapi-generator/src/cli/OpenApiCli.ts"],"names":[],"mappings":"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","sourcesContent":["import * as path from 'node:path';\nimport { ArtifactWriter, GeneratedArtifact, OutputFormat } from '../emit/ArtifactWriter';\nimport { OpenApiGenerator } from '../generate/OpenApiGenerator';\nimport { InputsLoader } from '../load/InputsLoader';\nimport { OpenApiGenerationError } from '../OpenApiGenerationError';\n\nconst MANIFEST = '--manifest';\nconst OUT = '--out';\nconst FORMAT = '--format';\nconst HELP = '--help';\n\nconst FLAGS = [MANIFEST, OUT, FORMAT];\nconst FORMATS: readonly string[] = ['json', 'yaml', 'both'];\n\nexport const USAGE = [\n    'wp-openapi --manifest <openapi.manifest.json> --out <dir> [--format json|yaml|both]',\n    '',\n    'Renders the contracts a manifest names into OpenAPI 3.1.0. WHICH documents are written is a',\n    \"property of the contracts themselves — each one's @ApiType(...) names the documents it feeds:\",\n    '',\n    '  full-private-openapi   every contract declaring SVC_TO_SVC, hidden methods included',\n    '  public-openapi         contracts declaring EXTERNAL_CUSTOMER, minus every { hidden: true } method',\n    '  mcp-openapi            contracts declaring MCP, carrying the x-mcp-* extensions',\n    '',\n    'A document no contract asked for is not written. --format chooses the serialization of',\n    'whichever documents were written, and defaults to both.',\n    '',\n    'It exits non-zero, naming the JSON pointer of every offending field, rather than writing a',\n    'document containing a field it has no schema for. There is no flag to switch that off.',\n].join('\\n');\n\n/** The result of one run: what was written, so a caller can print it or assert on it. */\nexport class CliResult {\n    constructor(\n        readonly written: readonly string[],\n        readonly artifacts: readonly GeneratedArtifact[],\n    ) {}\n}\n\n/**\n * `wp-openapi`'s argument parsing and composition, with NO process-level concerns in it — no\n * `process.exit`, no `console` — so the whole command is exercised by the suite exactly as a user\n * runs it. The bin is the only thing that knows about the process.\n *\n * `--manifest` and `--out` are REQUIRED and have no defaults. A defaulted `--out` writes generated\n * documents somewhere the caller did not name, and a defaulted `--manifest` picks a service out of\n * whatever directory the command happened to start in.\n */\nexport class OpenApiCli {\n    private readonly loader = new InputsLoader();\n    private readonly generator = new OpenApiGenerator();\n    private readonly writer = new ArtifactWriter();\n\n    /** @param argv the arguments AFTER the program name. @param cwd what relative paths resolve against. */\n    run(argv: readonly string[], cwd: string): CliResult {\n        const manifest = this.valueOf(argv, MANIFEST);\n        const out = this.valueOf(argv, OUT);\n        if (manifest === undefined || out === undefined) {\n            throw new OpenApiGenerationError(\n                `wp-openapi needs both ${MANIFEST} and ${OUT}`,\n                'wp-openapi',\n                `Run: wp-openapi ${MANIFEST} <openapi.manifest.json> ${OUT} <dir>`,\n            );\n        }\n        const inputs = this.loader.load(path.resolve(cwd, manifest));\n        const documents = this.generator.generate(inputs);\n        const artifacts = this.writer.artifacts(documents, this.formatOf(argv));\n        return new CliResult(this.writer.write(path.resolve(cwd, out), artifacts), artifacts);\n    }\n\n    wantsHelp(argv: readonly string[]): boolean {\n        return argv.includes(HELP);\n    }\n\n    /** `both` unless told otherwise: the second serialization comes free from the same document. */\n    private formatOf(argv: readonly string[]): OutputFormat {\n        const declared = this.valueOf(argv, FORMAT);\n        if (declared === undefined) {\n            return 'both';\n        }\n        if (!FORMATS.includes(declared)) {\n            throw new OpenApiGenerationError(\n                `unknown ${FORMAT} '${declared}'`,\n                'wp-openapi',\n                `${FORMAT} takes one of: ${FORMATS.join(', ')}.`,\n            );\n        }\n        return declared as OutputFormat;\n    }\n\n    /**\n     * The value after a flag. An UNKNOWN flag is refused rather than ignored: a mistyped `--manifets`\n     * would otherwise fall through to \"needs both flags\", which sends the reader looking at the wrong\n     * thing.\n     */\n    private valueOf(argv: readonly string[], flag: string): string | undefined {\n        for (let i = 0; i < argv.length; i++) {\n            const argument = argv[i]!;\n            if (argument === flag) {\n                return argv[i + 1];\n            }\n            if (argument.startsWith('--') && !FLAGS.includes(argument)) {\n                throw new OpenApiGenerationError(\n                    `unknown flag '${argument}'`,\n                    'wp-openapi',\n                    `wp-openapi takes ${FLAGS.join(', ')}, and nothing else.`,\n                );\n            }\n        }\n        return undefined;\n    }\n}\n"]}
+{"version":3,"file":"OpenApiCli.js","sourceRoot":"","sources":["../../../../../../packages/docs/openapi-generator/src/cli/OpenApiCli.ts"],"names":[],"mappings":"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","sourcesContent":["import * as path from 'node:path';\nimport { MCP } from '@webpieces/core-util';\nimport { McpCatalogRender, McpSchemaRenderer, SkippedMcpTool } from '@webpieces/api-doc-model';\nimport { ArtifactWriter, GeneratedArtifact, OutputFormat } from '../emit/ArtifactWriter';\nimport { ContractModel, GenerationInputs } from '../generate/GenerationInputs';\nimport { OpenApiGenerator } from '../generate/OpenApiGenerator';\nimport { InputsLoader } from '../load/InputsLoader';\nimport { OpenApiGenerationError } from '../OpenApiGenerationError';\n\nconst MANIFEST = '--manifest';\nconst OUT = '--out';\nconst FORMAT = '--format';\nconst HELP = '--help';\n\nconst FLAGS = [MANIFEST, OUT, FORMAT];\nconst FORMATS: readonly string[] = ['json', 'yaml', 'both'];\n\nexport const USAGE = [\n    'wp-openapi --manifest <openapi.manifest.json> --out <dir> [--format json|yaml|both]',\n    '',\n    'Renders the contracts a manifest names into OpenAPI 3.1.0. WHICH documents are written is a',\n    \"property of the contracts themselves — each one's @ApiType(...) names the documents it feeds:\",\n    '',\n    '  full-private-openapi   every contract declaring SVC_TO_SVC, hidden methods included',\n    '  public-openapi         contracts declaring EXTERNAL_CUSTOMER, minus every { hidden: true } method',\n    '  mcp-openapi            contracts declaring MCP, carrying the x-mcp-* extensions',\n    '',\n    'Alongside them, mcp-tools.json is written whenever some contract declares MCP: the RUNTIME',\n    'artifact WpMcpServer is constructed with. It is not a document, so --format does not apply.',\n    '',\n    'A document no contract asked for is not written. --format chooses the serialization of',\n    'whichever documents were written, and defaults to both.',\n    '',\n    'It exits non-zero, naming the JSON pointer of every offending field, rather than writing a',\n    'document containing a field it has no schema for. There is no flag to switch that off.',\n].join('\\n');\n\n/** The result of one run: what was written, so a caller can print it or assert on it. */\nexport class CliResult {\n    constructor(\n        readonly written: readonly string[],\n        readonly artifacts: readonly GeneratedArtifact[],\n        /** `@WpMcpTool`s the MCP catalog could not carry, with the reason. Never silent. */\n        readonly skippedMcpTools: readonly SkippedMcpTool[] = [],\n    ) {}\n}\n\n/** The MCP half of one run: the artifact to write, if any, and what it could not carry. */\nclass McpArtifacts {\n    constructor(\n        readonly artifacts: readonly GeneratedArtifact[],\n        readonly skipped: readonly SkippedMcpTool[],\n    ) {}\n}\n\n/**\n * `wp-openapi`'s argument parsing and composition, with NO process-level concerns in it — no\n * `process.exit`, no `console` — so the whole command is exercised by the suite exactly as a user\n * runs it. The bin is the only thing that knows about the process.\n *\n * `--manifest` and `--out` are REQUIRED and have no defaults. A defaulted `--out` writes generated\n * documents somewhere the caller did not name, and a defaulted `--manifest` picks a service out of\n * whatever directory the command happened to start in.\n */\nexport class OpenApiCli {\n    private readonly loader = new InputsLoader();\n    private readonly generator = new OpenApiGenerator();\n    private readonly writer = new ArtifactWriter();\n\n    /** @param argv the arguments AFTER the program name. @param cwd what relative paths resolve against. */\n    run(argv: readonly string[], cwd: string): CliResult {\n        const manifest = this.valueOf(argv, MANIFEST);\n        const out = this.valueOf(argv, OUT);\n        if (manifest === undefined || out === undefined) {\n            throw new OpenApiGenerationError(\n                `wp-openapi needs both ${MANIFEST} and ${OUT}`,\n                'wp-openapi',\n                `Run: wp-openapi ${MANIFEST} <openapi.manifest.json> ${OUT} <dir>`,\n            );\n        }\n        const inputs = this.loader.load(path.resolve(cwd, manifest));\n        const documents = this.generator.generate(inputs);\n        const mcp = OpenApiCli.mcpCatalog(inputs);\n        const artifacts = [\n            ...this.writer.artifacts(documents, this.formatOf(argv)),\n            ...mcp.artifacts,\n        ];\n        return new CliResult(\n            this.writer.write(path.resolve(cwd, out), artifacts),\n            artifacts,\n            mcp.skipped,\n        );\n    }\n\n    wantsHelp(argv: readonly string[]): boolean {\n        return argv.includes(HELP);\n    }\n\n    /**\n     * `mcp-tools.json` — the RUNTIME artifact, beside the three documents.\n     *\n     * It is not a document and is not serialized by `--format`: `WpMcpServer` is constructed with it,\n     * and `McpToolRegistry` fails fast at boot when a registered `@WpMcpTool` is missing from it. That\n     * is what took the MCP runtime off reflect-metadata (#984) — the schema an agent is shown and the\n     * schema the server accepts are now the same bytes, rather than two derivations of one contract.\n     *\n     * Written only when some contract declares `MCP`, which is the same rule `mcp-openapi.json`\n     * follows, for the same reason: an empty file is a claim that there are no tools.\n     */\n    // webpieces-disable no-function-outside-class -- private static composition step of this class\n    private static mcpCatalog(inputs: GenerationInputs): McpArtifacts {\n        const models = inputs.contracts\n            .filter((contract: ContractModel) => contract.model.apiTypes.includes(MCP))\n            .map((contract: ContractModel) => contract.model);\n        if (models.length === 0) {\n            return new McpArtifacts([], []);\n        }\n        const rendered: McpCatalogRender = McpSchemaRenderer.catalogOf(models);\n        const artifacts =\n            rendered.catalog.tools.length === 0\n                ? []\n                : [new GeneratedArtifact('mcp-tools.json', rendered.catalog.toJsonText())];\n        return new McpArtifacts(artifacts, rendered.skipped);\n    }\n\n    /** `both` unless told otherwise: the second serialization comes free from the same document. */\n    private formatOf(argv: readonly string[]): OutputFormat {\n        const declared = this.valueOf(argv, FORMAT);\n        if (declared === undefined) {\n            return 'both';\n        }\n        if (!FORMATS.includes(declared)) {\n            throw new OpenApiGenerationError(\n                `unknown ${FORMAT} '${declared}'`,\n                'wp-openapi',\n                `${FORMAT} takes one of: ${FORMATS.join(', ')}.`,\n            );\n        }\n        return declared as OutputFormat;\n    }\n\n    /**\n     * The value after a flag. An UNKNOWN flag is refused rather than ignored: a mistyped `--manifets`\n     * would otherwise fall through to \"needs both flags\", which sends the reader looking at the wrong\n     * thing.\n     */\n    private valueOf(argv: readonly string[], flag: string): string | undefined {\n        for (let i = 0; i < argv.length; i++) {\n            const argument = argv[i]!;\n            if (argument === flag) {\n                return argv[i + 1];\n            }\n            if (argument.startsWith('--') && !FLAGS.includes(argument)) {\n                throw new OpenApiGenerationError(\n                    `unknown flag '${argument}'`,\n                    'wp-openapi',\n                    `wp-openapi takes ${FLAGS.join(', ')}, and nothing else.`,\n                );\n            }\n        }\n        return undefined;\n    }\n}\n"]}

package/src/cli/WpOpenApiMain.js

@@ -36,6 +36,12 @@ class WpOpenApiMain {
             for (const file of result.written) {
                 out.write(`wrote ${file}\n`);
             }
+            // NAMED, never silent. A tool with no MCP schema is one no server can carry, and
+            // `McpToolRegistry` refuses to boot while it is still declared — see
+            // `McpSchemaRenderer.catalogOf` for why that is the right place for the failure.
+            for (const skipped of result.skippedMcpTools) {
+                out.write(`no MCP schema, left out of mcp-tools.json: ${skipped}\n`);
+            }
             return 0;
             // webpieces-disable no-any-unknown -- the catch binding, which TypeScript types for us
         }

package/src/cli/WpOpenApiMain.js.map

@@ -1 +1 @@
-{"version":3,"file":"WpOpenApiMain.js","sourceRoot":"","sources":["../../../../../../packages/docs/openapi-generator/src/cli/WpOpenApiMain.ts"],"names":[],"mappings":";;;AAAA,6CAA4D;AAC5D,sEAAmE;AAEnE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAa,aAAa;IACL,GAAG,GAAG,IAAI,uBAAU,EAAE,CAAC;IAExC,2EAA2E;IAC3E,GAAG,CAAC,IAAuB,EAAE,GAAW,EAAE,GAAuB;QAC7D,IAAI,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,GAAG,CAAC,KAAK,CAAC,GAAG,kBAAK,IAAI,CAAC,CAAC;YACxB,OAAO,CAAC,CAAC;QACb,CAAC;QACD,sGAAsG;QACtG,IAAI,CAAC;YACD,MAAM,MAAM,GAAc,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAClD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;gBAChC,GAAG,CAAC,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC;YACjC,CAAC;YACD,OAAO,CAAC,CAAC;YACT,uFAAuF;QAC3F,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACpB,6BAA6B;YAC7B,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACnC,OAAO,CAAC,CAAC;QACb,CAAC;IACL,CAAC;IAED,yGAAyG;IACjG,MAAM,CAAC,GAAY;QACvB,IAAI,CAAC,CAAC,GAAG,YAAY,+CAAsB,CAAC,EAAE,CAAC;YAC3C,OAAO,sBAAsB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;QACpF,CAAC;QACD,MAAM,KAAK,GAAG,CAAC,uBAAuB,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACrD,KAAK,MAAM,OAAO,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;YACjC,KAAK,CAAC,IAAI,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC;QAC/B,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;QAC5B,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;CACJ;AApCD,sCAoCC","sourcesContent":["import { CliResult, OpenApiCli, USAGE } from './OpenApiCli';\nimport { OpenApiGenerationError } from '../OpenApiGenerationError';\n\n/**\n * The body of the `wp-openapi` bin: argument handling, the SINGLE top-level handler, and the exit\n * code — with nothing that touches the process itself, so the suite runs the whole command.\n *\n * ## The single top-level handler\n *\n * Everything below here THROWS {@link OpenApiGenerationError} and prints nothing, so this is the only\n * renderer of a failure and the only writer of an exit code (`.claude/review/error-output.md`). It\n * renders from the error's FIELDS — the message, the location, the cure, the pointers — rather than\n * from a string somebody baked a cure into, so one audience's formatting never freezes into a thrower.\n *\n * ## Why an unmapped field exits NON-ZERO\n *\n * A field with no schema publishes as \"anything\", so a document containing one is a green build\n * handing a partner a field with no shape. That is worse than no document, because nobody reads a\n * published contract looking for the field that was quietly left undefined. There is deliberately no\n * flag to downgrade it — the cure is at the contract, by naming the type, and every pointer needed to\n * do that is printed.\n */\nexport class WpOpenApiMain {\n    private readonly cli = new OpenApiCli();\n\n    /** @returns the process exit code. 0 on success, 1 on a stated failure. */\n    run(argv: readonly string[], cwd: string, out: NodeJS.WriteStream): number {\n        if (this.cli.wantsHelp(argv)) {\n            out.write(`${USAGE}\\n`);\n            return 0;\n        }\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- this IS the single top-level handler\n        try {\n            const result: CliResult = this.cli.run(argv, cwd);\n            for (const file of result.written) {\n                out.write(`wrote ${file}\\n`);\n            }\n            return 0;\n            // webpieces-disable no-any-unknown -- the catch binding, which TypeScript types for us\n        } catch (err: unknown) {\n            //const error = toError(err);\n            out.write(`${this.render(err)}\\n`);\n            return 1;\n        }\n    }\n\n    // webpieces-disable no-any-unknown -- a caught value; this method is the audience-facing narrowing of it\n    private render(err: unknown): string {\n        if (!(err instanceof OpenApiGenerationError)) {\n            return `wp-openapi failed: ${err instanceof Error ? err.message : String(err)}`;\n        }\n        const lines = [`wp-openapi refused: ${err.message}`];\n        for (const pointer of err.pointers) {\n            lines.push(`  ${pointer}`);\n        }\n        lines.push(`  ${err.cure}`);\n        return lines.join('\\n');\n    }\n}\n"]}
+{"version":3,"file":"WpOpenApiMain.js","sourceRoot":"","sources":["../../../../../../packages/docs/openapi-generator/src/cli/WpOpenApiMain.ts"],"names":[],"mappings":";;;AAAA,6CAA4D;AAC5D,sEAAmE;AAEnE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAa,aAAa;IACL,GAAG,GAAG,IAAI,uBAAU,EAAE,CAAC;IAExC,2EAA2E;IAC3E,GAAG,CAAC,IAAuB,EAAE,GAAW,EAAE,GAAuB;QAC7D,IAAI,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,GAAG,CAAC,KAAK,CAAC,GAAG,kBAAK,IAAI,CAAC,CAAC;YACxB,OAAO,CAAC,CAAC;QACb,CAAC;QACD,sGAAsG;QACtG,IAAI,CAAC;YACD,MAAM,MAAM,GAAc,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAClD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;gBAChC,GAAG,CAAC,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC;YACjC,CAAC;YACD,iFAAiF;YACjF,qEAAqE;YACrE,iFAAiF;YACjF,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,eAAe,EAAE,CAAC;gBAC3C,GAAG,CAAC,KAAK,CAAC,8CAA8C,OAAO,IAAI,CAAC,CAAC;YACzE,CAAC;YACD,OAAO,CAAC,CAAC;YACT,uFAAuF;QAC3F,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACpB,6BAA6B;YAC7B,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACnC,OAAO,CAAC,CAAC;QACb,CAAC;IACL,CAAC;IAED,yGAAyG;IACjG,MAAM,CAAC,GAAY;QACvB,IAAI,CAAC,CAAC,GAAG,YAAY,+CAAsB,CAAC,EAAE,CAAC;YAC3C,OAAO,sBAAsB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;QACpF,CAAC;QACD,MAAM,KAAK,GAAG,CAAC,uBAAuB,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACrD,KAAK,MAAM,OAAO,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;YACjC,KAAK,CAAC,IAAI,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC;QAC/B,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;QAC5B,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;CACJ;AA1CD,sCA0CC","sourcesContent":["import { CliResult, OpenApiCli, USAGE } from './OpenApiCli';\nimport { OpenApiGenerationError } from '../OpenApiGenerationError';\n\n/**\n * The body of the `wp-openapi` bin: argument handling, the SINGLE top-level handler, and the exit\n * code — with nothing that touches the process itself, so the suite runs the whole command.\n *\n * ## The single top-level handler\n *\n * Everything below here THROWS {@link OpenApiGenerationError} and prints nothing, so this is the only\n * renderer of a failure and the only writer of an exit code (`.claude/review/error-output.md`). It\n * renders from the error's FIELDS — the message, the location, the cure, the pointers — rather than\n * from a string somebody baked a cure into, so one audience's formatting never freezes into a thrower.\n *\n * ## Why an unmapped field exits NON-ZERO\n *\n * A field with no schema publishes as \"anything\", so a document containing one is a green build\n * handing a partner a field with no shape. That is worse than no document, because nobody reads a\n * published contract looking for the field that was quietly left undefined. There is deliberately no\n * flag to downgrade it — the cure is at the contract, by naming the type, and every pointer needed to\n * do that is printed.\n */\nexport class WpOpenApiMain {\n    private readonly cli = new OpenApiCli();\n\n    /** @returns the process exit code. 0 on success, 1 on a stated failure. */\n    run(argv: readonly string[], cwd: string, out: NodeJS.WriteStream): number {\n        if (this.cli.wantsHelp(argv)) {\n            out.write(`${USAGE}\\n`);\n            return 0;\n        }\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- this IS the single top-level handler\n        try {\n            const result: CliResult = this.cli.run(argv, cwd);\n            for (const file of result.written) {\n                out.write(`wrote ${file}\\n`);\n            }\n            // NAMED, never silent. A tool with no MCP schema is one no server can carry, and\n            // `McpToolRegistry` refuses to boot while it is still declared — see\n            // `McpSchemaRenderer.catalogOf` for why that is the right place for the failure.\n            for (const skipped of result.skippedMcpTools) {\n                out.write(`no MCP schema, left out of mcp-tools.json: ${skipped}\\n`);\n            }\n            return 0;\n            // webpieces-disable no-any-unknown -- the catch binding, which TypeScript types for us\n        } catch (err: unknown) {\n            //const error = toError(err);\n            out.write(`${this.render(err)}\\n`);\n            return 1;\n        }\n    }\n\n    // webpieces-disable no-any-unknown -- a caught value; this method is the audience-facing narrowing of it\n    private render(err: unknown): string {\n        if (!(err instanceof OpenApiGenerationError)) {\n            return `wp-openapi failed: ${err instanceof Error ? err.message : String(err)}`;\n        }\n        const lines = [`wp-openapi refused: ${err.message}`];\n        for (const pointer of err.pointers) {\n            lines.push(`  ${pointer}`);\n        }\n        lines.push(`  ${err.cure}`);\n        return lines.join('\\n');\n    }\n}\n"]}