@webpieces/openapi-generator 0.0.1

package/README.md

@@ -0,0 +1,118 @@
+# @webpieces/openapi-generator
+
+Render a webpieces API contract to **OpenAPI 3.1.0**.
+
+```bash
+wp-openapi --manifest path/to/openapi.manifest.json --out path/to/generated [--format json|yaml|both]
+```
+
+## Which documents you get is a property of your CONTRACTS
+
+```typescript
+@ApiPath('/stores')
+@ApiType(SVC_TO_SVC, EXTERNAL_CUSTOMER)     // which documents this contract feeds
+export abstract class StoreApi { ... }
+```
+
+| `@ApiType` value | file | contents |
+|---|---|---|
+| `SVC_TO_SVC` | `full-private-openapi.json` | every method, hidden ones included, plus an internal-use-only line in `info.description`. Nothing renders it for humans |
+| `EXTERNAL_CUSTOMER` | `public-openapi.json` | the customer contract, minus every `{ hidden: true }` method |
+| `MCP` | `mcp-openapi.json` | the same contracts with the `x-mcp-*` extensions an MCP generator reads |
+
+**A document no contract declares is not written.** No `@ApiType` at all means `SVC_TO_SVC` only —
+fail-closed: a contract reaches customers by SAYING SO, so `grep -rn EXTERNAL_CUSTOMER` is your entire
+customer-facing surface on one screen.
+
+`--format` picks the serialization of whichever documents exist, and defaults to `both`.
+
+`diff full-private-openapi.json public-openapi.json` is the complete list of what you do not show a
+customer. Commit both, and hiding a method shows up in the PR that hides it.
+
+## Hiding ONE method
+
+```typescript
+/**
+ * Rebuilds a store's menu cache.
+ *
+ * Not published: an operator tool, and the customer contract has no concept of our cache.
+ */
+@Endpoint(POST, '/reindex', WRITE, RPC, { hidden: true })
+```
+
+The reason goes in the JSDoc — where the rest of the endpoint's documentation already lives. The
+method is absent from `public-openapi.json`: no path, no operation, no schema, no prose, and nothing
+announcing that anything was withheld.
+
+**Hiding is a documentation decision and never an access-control one.** The route is still served and
+still demands whatever credential it declares.
+
+## The manifest
+
+It carries exactly what is **not a property of the code**:
+
+```json
+{
+    "title": "Example Orders API",
+    "version": "1.0.0",
+    "descriptionFile": "description.md",
+    "servers": [{ "url": "https://api.example.com", "description": "Production." }],
+    "apis": [
+        { "entry": "src/OrdersApi.ts", "tag": "Orders" },
+        { "entry": "src/EventsApi.ts", "tag": "Webhooks", "kind": "webhook" }
+    ],
+    "securitySchemeNames": ["PartnerApiKey", "PartnerOrganization"],
+    "errors": {
+        "entry": "src/ApiErrors.ts",
+        "type": "ApiErrorResponse",
+        "responses": [{ "status": "400", "description": "The request failed validation." }]
+    },
+    "responseHeaders": [
+        {
+            "entry": "src/ResponseHeaders.ts",
+            "nameConstant": "REQUEST_ID_HEADER",
+            "description": "Correlates this response with our logs."
+        }
+    ]
+}
+```
+
+Every path is relative to the manifest's own directory.
+
+**The ORDER of `apis[]` is the published sidebar order.** Alphabetising it is not a cleanup.
+
+**`securitySchemeNames` holds the published KEYS only.** The schemes themselves, and the AND-ed
+`security` requirement, are DERIVED from the contract's `@WpAuthApiKey(regime, credentials)`. A
+`securitySchemes` block in the manifest would be a second copy of header names the running server
+never reads, and nothing could contradict it.
+
+**`responseHeaders` names a CONSTANT, never a header string.** JSON cannot import, so a literal there
+is a copy that a rename leaves silently stale. The generator folds the const and hard-fails if it
+cannot.
+
+## MCP
+
+`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.
+
+## It refuses to publish a field it has no schema for
+
+A field the model could not map renders as an empty schema, which in JSON Schema means "anything".
+`wp-openapi` exits non-zero instead, naming the JSON pointer of every one, and writes nothing. There
+is no flag to switch that off — the cure is at the contract, by naming the type.
+
+## Worked example
+
+`apps/app-example/partner-api` in this repo: a real contract, its manifest, the committed documents,
+and a spec that regenerates and diffs them.
+
+## Dependencies
+
+`typescript`, `@webpieces/api-doc-model` and `@webpieces/core-util`. No nx, no repo paths, no app
+types.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@webpieces/openapi-generator",
+  "version": "0.0.1",
+  "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",
+  "types": "./src/index.d.ts",
+  "author": "Dean Hiller",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deanhiller/webpieces-ts.git",
+    "directory": "packages/docs/openapi-generator"
+  },
+  "keywords": [
+    "webpieces",
+    "openapi",
+    "mcp",
+    "docs",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@webpieces/api-doc-model": "0.4.803",
+    "typescript": "5.9.3"
+  },
+  "bin": {
+    "wp-openapi": "./src/cli/wp-openapi.js"
+  }
+}

package/src/OpenApiGenerationError.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The ONE failure type this package throws. Generation either produces a complete pair of documents
+ * or throws this — it never prints a warning, never writes a partial file, and never guesses.
+ *
+ * It is a structured throw to the single top-level handler in `wp-openapi`, per
+ * `.claude/review/error-output.md`: `location` and `cure` are carried as FIELDS rather than baked
+ * into `message`, and `pointers` carries the JSON pointers of an unmapped-type refusal, so the CLI
+ * renders them per audience and this class hand-numbers nothing.
+ *
+ * It is NOT `RuleFailError`. That type lives in `@webpieces/rules-config` — the TOOLING stream, which
+ * a repo pins one release behind on purpose — and this package publishes with the SERVER libs so an
+ * app's `@webpieces/core-util` pin pins a generator that understands that app's decorators (see
+ * `responsibilities.md`). Depending across the two streams to reuse an error class would couple the
+ * generator's release to the rule engine's, which is the coupling the epic exists to avoid. This is
+ * the same call `@webpieces/api-doc-model` made, and for a reason of the same size.
+ */
+export declare class OpenApiGenerationError extends Error {
+    /** Where the problem IS — a manifest path, a contract file, or `<manifest>#/apis/0`. */
+    readonly location: string;
+    /** What to do instead, in one sentence. No numbering — the CLI owns that. */
+    readonly cure: string;
+    /**
+     * JSON pointers into the document that WOULD have been written, one per offending field.
+     * Empty for every failure that is not the unmapped-type refusal. It is a separate field
+     * rather than a list glued into `message` because the list is the actionable part: an agent
+     * fixes the contract one pointer at a time.
+     */
+    readonly pointers: readonly string[];
+    constructor(message: string, 
+    /** Where the problem IS — a manifest path, a contract file, or `<manifest>#/apis/0`. */
+    location: string, 
+    /** What to do instead, in one sentence. No numbering — the CLI owns that. */
+    cure: string, 
+    /**
+     * JSON pointers into the document that WOULD have been written, one per offending field.
+     * Empty for every failure that is not the unmapped-type refusal. It is a separate field
+     * rather than a list glued into `message` because the list is the actionable part: an agent
+     * fixes the contract one pointer at a time.
+     */
+    pointers?: readonly string[]);
+}

package/src/OpenApiGenerationError.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenApiGenerationError = void 0;
+/**
+ * The ONE failure type this package throws. Generation either produces a complete pair of documents
+ * or throws this — it never prints a warning, never writes a partial file, and never guesses.
+ *
+ * It is a structured throw to the single top-level handler in `wp-openapi`, per
+ * `.claude/review/error-output.md`: `location` and `cure` are carried as FIELDS rather than baked
+ * into `message`, and `pointers` carries the JSON pointers of an unmapped-type refusal, so the CLI
+ * renders them per audience and this class hand-numbers nothing.
+ *
+ * It is NOT `RuleFailError`. That type lives in `@webpieces/rules-config` — the TOOLING stream, which
+ * a repo pins one release behind on purpose — and this package publishes with the SERVER libs so an
+ * app's `@webpieces/core-util` pin pins a generator that understands that app's decorators (see
+ * `responsibilities.md`). Depending across the two streams to reuse an error class would couple the
+ * generator's release to the rule engine's, which is the coupling the epic exists to avoid. This is
+ * the same call `@webpieces/api-doc-model` made, and for a reason of the same size.
+ */
+class OpenApiGenerationError extends Error {
+    location;
+    cure;
+    pointers;
+    constructor(message, 
+    /** Where the problem IS — a manifest path, a contract file, or `<manifest>#/apis/0`. */
+    location, 
+    /** What to do instead, in one sentence. No numbering — the CLI owns that. */
+    cure, 
+    /**
+     * JSON pointers into the document that WOULD have been written, one per offending field.
+     * Empty for every failure that is not the unmapped-type refusal. It is a separate field
+     * rather than a list glued into `message` because the list is the actionable part: an agent
+     * fixes the contract one pointer at a time.
+     */
+    pointers = []) {
+        super(`${message} (${location})`);
+        this.location = location;
+        this.cure = cure;
+        this.pointers = pointers;
+        this.name = 'OpenApiGenerationError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.OpenApiGenerationError = OpenApiGenerationError;
+//# sourceMappingURL=OpenApiGenerationError.js.map

package/src/OpenApiGenerationError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenApiGenerationError.js","sourceRoot":"","sources":["../../../../../packages/docs/openapi-generator/src/OpenApiGenerationError.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAa,sBAAuB,SAAQ,KAAK;IAIhC;IAEA;IAOA;IAZb,YACI,OAAe;IACf,wFAAwF;IAC/E,QAAgB;IACzB,6EAA6E;IACpE,IAAY;IACrB;;;;;OAKG;IACM,WAA8B,EAAE;QAEzC,KAAK,CAAC,GAAG,OAAO,KAAK,QAAQ,GAAG,CAAC,CAAC;QAXzB,aAAQ,GAAR,QAAQ,CAAQ;QAEhB,SAAI,GAAJ,IAAI,CAAQ;QAOZ,aAAQ,GAAR,QAAQ,CAAwB;QAGzC,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACtD,CAAC;CACJ;AAnBD,wDAmBC","sourcesContent":["/**\n * The ONE failure type this package throws. Generation either produces a complete pair of documents\n * or throws this — it never prints a warning, never writes a partial file, and never guesses.\n *\n * It is a structured throw to the single top-level handler in `wp-openapi`, per\n * `.claude/review/error-output.md`: `location` and `cure` are carried as FIELDS rather than baked\n * into `message`, and `pointers` carries the JSON pointers of an unmapped-type refusal, so the CLI\n * renders them per audience and this class hand-numbers nothing.\n *\n * It is NOT `RuleFailError`. That type lives in `@webpieces/rules-config` — the TOOLING stream, which\n * a repo pins one release behind on purpose — and this package publishes with the SERVER libs so an\n * app's `@webpieces/core-util` pin pins a generator that understands that app's decorators (see\n * `responsibilities.md`). Depending across the two streams to reuse an error class would couple the\n * generator's release to the rule engine's, which is the coupling the epic exists to avoid. This is\n * the same call `@webpieces/api-doc-model` made, and for a reason of the same size.\n */\nexport class OpenApiGenerationError extends Error {\n    constructor(\n        message: string,\n        /** Where the problem IS — a manifest path, a contract file, or `<manifest>#/apis/0`. */\n        readonly location: string,\n        /** What to do instead, in one sentence. No numbering — the CLI owns that. */\n        readonly cure: string,\n        /**\n         * JSON pointers into the document that WOULD have been written, one per offending field.\n         * Empty for every failure that is not the unmapped-type refusal. It is a separate field\n         * rather than a list glued into `message` because the list is the actionable part: an agent\n         * fixes the contract one pointer at a time.\n         */\n        readonly pointers: readonly string[] = [],\n    ) {\n        super(`${message} (${location})`);\n        this.name = 'OpenApiGenerationError';\n        Object.setPrototypeOf(this, new.target.prototype);\n    }\n}\n"]}

package/src/cli/OpenApiCli.d.ts

@@ -0,0 +1,33 @@
+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[]);
+}
+/**
+ * `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
+ * runs it. The bin is the only thing that knows about the process.
+ *
+ * `--manifest` and `--out` are REQUIRED and have no defaults. A defaulted `--out` writes generated
+ * documents somewhere the caller did not name, and a defaulted `--manifest` picks a service out of
+ * whatever directory the command happened to start in.
+ */
+export declare class OpenApiCli {
+    private readonly loader;
+    private readonly generator;
+    private readonly writer;
+    /** @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;
+    /** `both` unless told otherwise: the second serialization comes free from the same document. */
+    private formatOf;
+    /**
+     * The value after a flag. An UNKNOWN flag is refused rather than ignored: a mistyped `--manifets`
+     * would otherwise fall through to "needs both flags", which sends the reader looking at the wrong
+     * thing.
+     */
+    private valueOf;
+}

package/src/cli/OpenApiCli.js

@@ -0,0 +1,100 @@
+"use strict";
+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 ArtifactWriter_1 = require("../emit/ArtifactWriter");
+const OpenApiGenerator_1 = require("../generate/OpenApiGenerator");
+const InputsLoader_1 = require("../load/InputsLoader");
+const OpenApiGenerationError_1 = require("../OpenApiGenerationError");
+const MANIFEST = '--manifest';
+const OUT = '--out';
+const FORMAT = '--format';
+const HELP = '--help';
+const FLAGS = [MANIFEST, OUT, FORMAT];
+const FORMATS = ['json', 'yaml', 'both'];
+exports.USAGE = [
+    'wp-openapi --manifest <openapi.manifest.json> --out <dir> [--format json|yaml|both]',
+    '',
+    'Renders the contracts a manifest names into OpenAPI 3.1.0. WHICH documents are written is a',
+    "property of the contracts themselves — each one's @ApiType(...) names the documents it feeds:",
+    '',
+    '  full-private-openapi   every contract declaring SVC_TO_SVC, hidden methods included',
+    '  public-openapi         contracts declaring EXTERNAL_CUSTOMER, minus every { hidden: true } method',
+    '  mcp-openapi            contracts declaring MCP, carrying the x-mcp-* extensions',
+    '',
+    'A document no contract asked for is not written. --format chooses the serialization of',
+    'whichever documents were written, and defaults to both.',
+    '',
+    'It exits non-zero, naming the JSON pointer of every offending field, rather than writing a',
+    'document containing a field it has no schema for. There is no flag to switch that off.',
+].join('\n');
+/** The result of one run: what was written, so a caller can print it or assert on it. */
+class CliResult {
+    written;
+    artifacts;
+    constructor(written, artifacts) {
+        this.written = written;
+        this.artifacts = artifacts;
+    }
+}
+exports.CliResult = CliResult;
+/**
+ * `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
+ * runs it. The bin is the only thing that knows about the process.
+ *
+ * `--manifest` and `--out` are REQUIRED and have no defaults. A defaulted `--out` writes generated
+ * documents somewhere the caller did not name, and a defaulted `--manifest` picks a service out of
+ * whatever directory the command happened to start in.
+ */
+class OpenApiCli {
+    loader = new InputsLoader_1.InputsLoader();
+    generator = new OpenApiGenerator_1.OpenApiGenerator();
+    writer = new ArtifactWriter_1.ArtifactWriter();
+    /** @param argv the arguments AFTER the program name. @param cwd what relative paths resolve against. */
+    run(argv, cwd) {
+        const manifest = this.valueOf(argv, MANIFEST);
+        const out = this.valueOf(argv, OUT);
+        if (manifest === undefined || out === undefined) {
+            throw new OpenApiGenerationError_1.OpenApiGenerationError(`wp-openapi needs both ${MANIFEST} and ${OUT}`, 'wp-openapi', `Run: wp-openapi ${MANIFEST} <openapi.manifest.json> ${OUT} <dir>`);
+        }
+        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);
+    }
+    wantsHelp(argv) {
+        return argv.includes(HELP);
+    }
+    /** `both` unless told otherwise: the second serialization comes free from the same document. */
+    formatOf(argv) {
+        const declared = this.valueOf(argv, FORMAT);
+        if (declared === undefined) {
+            return 'both';
+        }
+        if (!FORMATS.includes(declared)) {
+            throw new OpenApiGenerationError_1.OpenApiGenerationError(`unknown ${FORMAT} '${declared}'`, 'wp-openapi', `${FORMAT} takes one of: ${FORMATS.join(', ')}.`);
+        }
+        return declared;
+    }
+    /**
+     * The value after a flag. An UNKNOWN flag is refused rather than ignored: a mistyped `--manifets`
+     * would otherwise fall through to "needs both flags", which sends the reader looking at the wrong
+     * thing.
+     */
+    valueOf(argv, flag) {
+        for (let i = 0; i < argv.length; i++) {
+            const argument = argv[i];
+            if (argument === flag) {
+                return argv[i + 1];
+            }
+            if (argument.startsWith('--') && !FLAGS.includes(argument)) {
+                throw new OpenApiGenerationError_1.OpenApiGenerationError(`unknown flag '${argument}'`, 'wp-openapi', `wp-openapi takes ${FLAGS.join(', ')}, and nothing else.`);
+            }
+        }
+        return undefined;
+    }
+}
+exports.OpenApiCli = OpenApiCli;
+//# sourceMappingURL=OpenApiCli.js.map

package/src/cli/OpenApiCli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenApiCli.js","sourceRoot":"","sources":["../../../../../../packages/docs/openapi-generator/src/cli/OpenApiCli.ts"],"names":[],"mappings":";;;;AAAA,wDAAkC;AAClC,2DAAyF;AACzF,mEAAgE;AAChE,uDAAoD;AACpD,sEAAmE;AAEnE,MAAM,QAAQ,GAAG,YAAY,CAAC;AAC9B,MAAM,GAAG,GAAG,OAAO,CAAC;AACpB,MAAM,MAAM,GAAG,UAAU,CAAC;AAC1B,MAAM,IAAI,GAAG,QAAQ,CAAC;AAEtB,MAAM,KAAK,GAAG,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;AACtC,MAAM,OAAO,GAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAE/C,QAAA,KAAK,GAAG;IACjB,qFAAqF;IACrF,EAAE;IACF,6FAA6F;IAC7F,+FAA+F;IAC/F,EAAE;IACF,uFAAuF;IACvF,qGAAqG;IACrG,mFAAmF;IACnF,EAAE;IACF,wFAAwF;IACxF,yDAAyD;IACzD,EAAE;IACF,4FAA4F;IAC5F,wFAAwF;CAC3F,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,yFAAyF;AACzF,MAAa,SAAS;IAEL;IACA;IAFb,YACa,OAA0B,EAC1B,SAAuC;QADvC,YAAO,GAAP,OAAO,CAAmB;QAC1B,cAAS,GAAT,SAAS,CAA8B;IACjD,CAAC;CACP;AALD,8BAKC;AAED;;;;;;;;GAQG;AACH,MAAa,UAAU;IACF,MAAM,GAAG,IAAI,2BAAY,EAAE,CAAC;IAC5B,SAAS,GAAG,IAAI,mCAAgB,EAAE,CAAC;IACnC,MAAM,GAAG,IAAI,+BAAc,EAAE,CAAC;IAE/C,wGAAwG;IACxG,GAAG,CAAC,IAAuB,EAAE,GAAW;QACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACpC,IAAI,QAAQ,KAAK,SAAS,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YAC9C,MAAM,IAAI,+CAAsB,CAC5B,yBAAyB,QAAQ,QAAQ,GAAG,EAAE,EAC9C,YAAY,EACZ,mBAAmB,QAAQ,4BAA4B,GAAG,QAAQ,CACrE,CAAC;QACN,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC7D,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAClD,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;QACxE,OAAO,IAAI,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,SAAS,CAAC,EAAE,SAAS,CAAC,CAAC;IAC1F,CAAC;IAED,SAAS,CAAC,IAAuB;QAC7B,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,gGAAgG;IACxF,QAAQ,CAAC,IAAuB;QACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC5C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,MAAM,CAAC;QAClB,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,+CAAsB,CAC5B,WAAW,MAAM,KAAK,QAAQ,GAAG,EACjC,YAAY,EACZ,GAAG,MAAM,kBAAkB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACnD,CAAC;QACN,CAAC;QACD,OAAO,QAAwB,CAAC;IACpC,CAAC;IAED;;;;OAIG;IACK,OAAO,CAAC,IAAuB,EAAE,IAAY;QACjD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACnC,MAAM,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC;YAC1B,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;gBACpB,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACvB,CAAC;YACD,IAAI,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACzD,MAAM,IAAI,+CAAsB,CAC5B,iBAAiB,QAAQ,GAAG,EAC5B,YAAY,EACZ,oBAAoB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAC5D,CAAC;YACN,CAAC;QACL,CAAC;QACD,OAAO,SAAS,CAAC;IACrB,CAAC;CACJ;AA/DD,gCA+DC","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"]}

package/src/cli/WpOpenApiMain.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The body of the `wp-openapi` bin: argument handling, the SINGLE top-level handler, and the exit
+ * code — with nothing that touches the process itself, so the suite runs the whole command.
+ *
+ * ## The single top-level handler
+ *
+ * Everything below here THROWS {@link OpenApiGenerationError} and prints nothing, so this is the only
+ * renderer of a failure and the only writer of an exit code (`.claude/review/error-output.md`). It
+ * renders from the error's FIELDS — the message, the location, the cure, the pointers — rather than
+ * from a string somebody baked a cure into, so one audience's formatting never freezes into a thrower.
+ *
+ * ## Why an unmapped field exits NON-ZERO
+ *
+ * A field with no schema publishes as "anything", so a document containing one is a green build
+ * handing a partner a field with no shape. That is worse than no document, because nobody reads a
+ * published contract looking for the field that was quietly left undefined. There is deliberately no
+ * flag to downgrade it — the cure is at the contract, by naming the type, and every pointer needed to
+ * do that is printed.
+ */
+export declare class WpOpenApiMain {
+    private readonly cli;
+    /** @returns the process exit code. 0 on success, 1 on a stated failure. */
+    run(argv: readonly string[], cwd: string, out: NodeJS.WriteStream): number;
+    private render;
+}

package/src/cli/WpOpenApiMain.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WpOpenApiMain = void 0;
+const OpenApiCli_1 = require("./OpenApiCli");
+const OpenApiGenerationError_1 = require("../OpenApiGenerationError");
+/**
+ * The body of the `wp-openapi` bin: argument handling, the SINGLE top-level handler, and the exit
+ * code — with nothing that touches the process itself, so the suite runs the whole command.
+ *
+ * ## The single top-level handler
+ *
+ * Everything below here THROWS {@link OpenApiGenerationError} and prints nothing, so this is the only
+ * renderer of a failure and the only writer of an exit code (`.claude/review/error-output.md`). It
+ * renders from the error's FIELDS — the message, the location, the cure, the pointers — rather than
+ * from a string somebody baked a cure into, so one audience's formatting never freezes into a thrower.
+ *
+ * ## Why an unmapped field exits NON-ZERO
+ *
+ * A field with no schema publishes as "anything", so a document containing one is a green build
+ * handing a partner a field with no shape. That is worse than no document, because nobody reads a
+ * published contract looking for the field that was quietly left undefined. There is deliberately no
+ * flag to downgrade it — the cure is at the contract, by naming the type, and every pointer needed to
+ * do that is printed.
+ */
+class WpOpenApiMain {
+    cli = new OpenApiCli_1.OpenApiCli();
+    /** @returns the process exit code. 0 on success, 1 on a stated failure. */
+    run(argv, cwd, out) {
+        if (this.cli.wantsHelp(argv)) {
+            out.write(`${OpenApiCli_1.USAGE}\n`);
+            return 0;
+        }
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- this IS the single top-level handler
+        try {
+            const result = this.cli.run(argv, cwd);
+            for (const file of result.written) {
+                out.write(`wrote ${file}\n`);
+            }
+            return 0;
+            // webpieces-disable no-any-unknown -- the catch binding, which TypeScript types for us
+        }
+        catch (err) {
+            //const error = toError(err);
+            out.write(`${this.render(err)}\n`);
+            return 1;
+        }
+    }
+    // webpieces-disable no-any-unknown -- a caught value; this method is the audience-facing narrowing of it
+    render(err) {
+        if (!(err instanceof OpenApiGenerationError_1.OpenApiGenerationError)) {
+            return `wp-openapi failed: ${err instanceof Error ? err.message : String(err)}`;
+        }
+        const lines = [`wp-openapi refused: ${err.message}`];
+        for (const pointer of err.pointers) {
+            lines.push(`  ${pointer}`);
+        }
+        lines.push(`  ${err.cure}`);
+        return lines.join('\n');
+    }
+}
+exports.WpOpenApiMain = WpOpenApiMain;
+//# sourceMappingURL=WpOpenApiMain.js.map

package/src/cli/WpOpenApiMain.js.map

@@ -0,0 +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"]}

package/src/cli/wp-openapi.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/src/cli/wp-openapi.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const WpOpenApiMain_1 = require("./WpOpenApiMain");
+/**
+ * The `wp-openapi` bin. It is four lines because everything it does lives in {@link WpOpenApiMain},
+ * which the suite runs exactly as a user does — a bin whose body is only reachable by spawning a
+ * process is a bin nothing tests.
+ *
+ * The bin is declared in `publishConfig.bin`, never at the top level
+ * (`.claude/rules/packaging-and-bins.md`): pnpm chmods every `bin` target while linking a package
+ * from its SOURCE directory, where `src/` holds only `.ts` until tsc runs, so a top-level `bin` makes
+ * every `pnpm install` print an ENOENT warning. `scripts/publish-packages.sh` hoists it into the
+ * PUBLISHED manifest, and fails the release if it ever goes missing.
+ */
+// webpieces-disable no-process-exit-outside-main -- this IS main; WpOpenApiMain never touches the process
+process.exitCode = new WpOpenApiMain_1.WpOpenApiMain().run(process.argv.slice(2), process.cwd(), process.stdout);
+//# sourceMappingURL=wp-openapi.js.map

package/src/cli/wp-openapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wp-openapi.js","sourceRoot":"","sources":["../../../../../../packages/docs/openapi-generator/src/cli/wp-openapi.ts"],"names":[],"mappings":";;;AACA,mDAAgD;AAEhD;;;;;;;;;;GAUG;AACH,0GAA0G;AAC1G,OAAO,CAAC,QAAQ,GAAG,IAAI,6BAAa,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC","sourcesContent":["#!/usr/bin/env node\nimport { WpOpenApiMain } from './WpOpenApiMain';\n\n/**\n * The `wp-openapi` bin. It is four lines because everything it does lives in {@link WpOpenApiMain},\n * which the suite runs exactly as a user does — a bin whose body is only reachable by spawning a\n * process is a bin nothing tests.\n *\n * The bin is declared in `publishConfig.bin`, never at the top level\n * (`.claude/rules/packaging-and-bins.md`): pnpm chmods every `bin` target while linking a package\n * from its SOURCE directory, where `src/` holds only `.ts` until tsc runs, so a top-level `bin` makes\n * every `pnpm install` print an ENOENT warning. `scripts/publish-packages.sh` hoists it into the\n * PUBLISHED manifest, and fails the release if it ever goes missing.\n */\n// webpieces-disable no-process-exit-outside-main -- this IS main; WpOpenApiMain never touches the process\nprocess.exitCode = new WpOpenApiMain().run(process.argv.slice(2), process.cwd(), process.stdout);\n"]}

package/src/emit/ArtifactWriter.d.ts

@@ -0,0 +1,44 @@
+import { GeneratedDocument, GeneratedDocuments } from '../generate/GenerationInputs';
+/** One file this generation pass produces: its name, and its exact bytes. */
+export declare class GeneratedArtifact {
+    readonly fileName: string;
+    readonly text: string;
+    constructor(fileName: string, text: string);
+}
+/** Which serializations to write. Orthogonal to WHICH documents `@ApiType` selected. */
+export type OutputFormat = 'json' | 'yaml' | 'both';
+/**
+ * The generated documents, serialized.
+ *
+ * | file | audience |
+ * |---|---|
+ * | `full-private-openapi.json` | internal. Every contract declaring `SVC_TO_SVC`, hidden methods included. Nothing renders it for humans |
+ * | `public-openapi.json` | customers. Contracts declaring `EXTERNAL_CUSTOMER`, minus every `{ hidden: true }` method |
+ * | `mcp-openapi.json` | agents. Contracts declaring `MCP`, carrying the `x-mcp-*` extensions |
+ *
+ * A document is written only when some contract declared its type, which is decided by the generator
+ * — this class writes what it is given. `--format` then chooses `.json`, `.yaml` or both from the
+ * SAME in-memory document, so the two serializations cannot disagree.
+ *
+ * ## Why the goldens commit JSON only
+ *
+ * Committing both would double the review surface every decorator change has to be diffed against,
+ * for a second file that is the first one restated. One spec parses each emitted YAML and asserts
+ * deep equality with its JSON counterpart instead, which proves the YAML is correct without asking
+ * anybody to read it.
+ *
+ * ## Why the JSON documents ARE committed
+ *
+ * `diff full-private-openapi.json public-openapi.json` is the complete list of what these contracts
+ * do not show a customer. That only works as a review device if both files are in the tree, so hiding
+ * a method shows up as a diff in the PR that hides it.
+ */
+export declare class ArtifactWriter {
+    private readonly json;
+    private readonly yaml;
+    artifacts(documents: GeneratedDocuments, format: OutputFormat): readonly GeneratedArtifact[];
+    /** Write them all, creating `outDir` if it does not exist. Returns the absolute paths written. */
+    write(outDir: string, artifacts: readonly GeneratedArtifact[]): readonly string[];
+    /** The document objects, for a caller that wants them rather than their bytes. */
+    documentsOf(documents: GeneratedDocuments): readonly GeneratedDocument[];
+}

package/src/emit/ArtifactWriter.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArtifactWriter = exports.GeneratedArtifact = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("node:fs"));
+const path = tslib_1.__importStar(require("node:path"));
+const JsonWriter_1 = require("../json/JsonWriter");
+const YamlWriter_1 = require("../json/YamlWriter");
+/** One file this generation pass produces: its name, and its exact bytes. */
+class GeneratedArtifact {
+    fileName;
+    text;
+    constructor(fileName, text) {
+        this.fileName = fileName;
+        this.text = text;
+    }
+}
+exports.GeneratedArtifact = GeneratedArtifact;
+/**
+ * The generated documents, serialized.
+ *
+ * | file | audience |
+ * |---|---|
+ * | `full-private-openapi.json` | internal. Every contract declaring `SVC_TO_SVC`, hidden methods included. Nothing renders it for humans |
+ * | `public-openapi.json` | customers. Contracts declaring `EXTERNAL_CUSTOMER`, minus every `{ hidden: true }` method |
+ * | `mcp-openapi.json` | agents. Contracts declaring `MCP`, carrying the `x-mcp-*` extensions |
+ *
+ * A document is written only when some contract declared its type, which is decided by the generator
+ * — this class writes what it is given. `--format` then chooses `.json`, `.yaml` or both from the
+ * SAME in-memory document, so the two serializations cannot disagree.
+ *
+ * ## Why the goldens commit JSON only
+ *
+ * Committing both would double the review surface every decorator change has to be diffed against,
+ * for a second file that is the first one restated. One spec parses each emitted YAML and asserts
+ * deep equality with its JSON counterpart instead, which proves the YAML is correct without asking
+ * anybody to read it.
+ *
+ * ## Why the JSON documents ARE committed
+ *
+ * `diff full-private-openapi.json public-openapi.json` is the complete list of what these contracts
+ * do not show a customer. That only works as a review device if both files are in the tree, so hiding
+ * a method shows up as a diff in the PR that hides it.
+ */
+class ArtifactWriter {
+    json = new JsonWriter_1.JsonWriter();
+    yaml = new YamlWriter_1.YamlWriter();
+    artifacts(documents, format) {
+        const artifacts = [];
+        for (const generated of documents.documents) {
+            if (format !== 'yaml') {
+                artifacts.push(new GeneratedArtifact(`${generated.fileName}.json`, this.json.write(generated.document)));
+            }
+            if (format !== 'json') {
+                artifacts.push(new GeneratedArtifact(`${generated.fileName}.yaml`, this.yaml.write(generated.document)));
+            }
+        }
+        return artifacts;
+    }
+    /** Write them all, creating `outDir` if it does not exist. Returns the absolute paths written. */
+    write(outDir, artifacts) {
+        fs.mkdirSync(outDir, { recursive: true });
+        return artifacts.map((artifact) => {
+            const file = path.join(outDir, artifact.fileName);
+            fs.writeFileSync(file, artifact.text, 'utf8');
+            return file;
+        });
+    }
+    /** The document objects, for a caller that wants them rather than their bytes. */
+    documentsOf(documents) {
+        return documents.documents;
+    }
+}
+exports.ArtifactWriter = ArtifactWriter;
+//# sourceMappingURL=ArtifactWriter.js.map