@webpieces/docs-site 0.0.1

package/src/render/SiteUrls.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SiteUrls = void 0;
+/**
+ * Every URL the site has, in ONE place.
+ *
+ * Each is a real FILE ending in `index.html`, and each is stated RELATIVE to the site root; a page
+ * prepends its own `../` prefix with {@link prefixFor}. Root-relative links (`/reference/…`) only
+ * work when the site is the whole host, and a generated reference is routinely served under a path —
+ * GitHub Pages does it by default — where a root-relative link 404s on every page but the home one.
+ * Ending each href in `index.html` rather than a bare directory is the same argument one level down:
+ * a directory URL needs a server willing to serve the index, and `file://` is not one.
+ */
+class SiteUrls {
+    /** The generated home page. */
+    home() {
+        return 'index.html';
+    }
+    /** `reference/<kebab-operation>/index.html` — one file per operation URL. */
+    operation(operation) {
+        return `reference/${operation.slug}/index.html`;
+    }
+    /** `schemas/<kebab-name>/index.html` — one file per named object DTO. */
+    schema(schema) {
+        return `schemas/${schema.slug}/index.html`;
+    }
+    /** `prose/<kebab-title>/index.html`. */
+    prose(page) {
+        return `prose/${page.slug}/index.html`;
+    }
+    /** `../` once per directory between a page and the site root. */
+    prefixFor(url) {
+        return '../'.repeat(url.split('/').length - 1);
+    }
+}
+exports.SiteUrls = SiteUrls;
+//# sourceMappingURL=SiteUrls.js.map

package/src/render/SiteUrls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SiteUrls.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/render/SiteUrls.ts"],"names":[],"mappings":";;;AAGA;;;;;;;;;GASG;AACH,MAAa,QAAQ;IACjB,+BAA+B;IAC/B,IAAI;QACA,OAAO,YAAY,CAAC;IACxB,CAAC;IAED,6EAA6E;IAC7E,SAAS,CAAC,SAAwB;QAC9B,OAAO,aAAa,SAAS,CAAC,IAAI,aAAa,CAAC;IACpD,CAAC;IAED,yEAAyE;IACzE,MAAM,CAAC,MAAmB;QACtB,OAAO,WAAW,MAAM,CAAC,IAAI,aAAa,CAAC;IAC/C,CAAC;IAED,wCAAwC;IACxC,KAAK,CAAC,IAAe;QACjB,OAAO,SAAS,IAAI,CAAC,IAAI,aAAa,CAAC;IAC3C,CAAC;IAED,iEAAiE;IACjE,SAAS,CAAC,GAAW;QACjB,OAAO,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACnD,CAAC;CACJ;AAzBD,4BAyBC","sourcesContent":["import { NamedSchema, OperationInfo } from '../spec/ApiSpec';\nimport { ProsePage } from '../manifest/DocsManifest';\n\n/**\n * Every URL the site has, in ONE place.\n *\n * Each is a real FILE ending in `index.html`, and each is stated RELATIVE to the site root; a page\n * prepends its own `../` prefix with {@link prefixFor}. Root-relative links (`/reference/…`) only\n * work when the site is the whole host, and a generated reference is routinely served under a path —\n * GitHub Pages does it by default — where a root-relative link 404s on every page but the home one.\n * Ending each href in `index.html` rather than a bare directory is the same argument one level down:\n * a directory URL needs a server willing to serve the index, and `file://` is not one.\n */\nexport class SiteUrls {\n    /** The generated home page. */\n    home(): string {\n        return 'index.html';\n    }\n\n    /** `reference/<kebab-operation>/index.html` — one file per operation URL. */\n    operation(operation: OperationInfo): string {\n        return `reference/${operation.slug}/index.html`;\n    }\n\n    /** `schemas/<kebab-name>/index.html` — one file per named object DTO. */\n    schema(schema: NamedSchema): string {\n        return `schemas/${schema.slug}/index.html`;\n    }\n\n    /** `prose/<kebab-title>/index.html`. */\n    prose(page: ProsePage): string {\n        return `prose/${page.slug}/index.html`;\n    }\n\n    /** `../` once per directory between a page and the site root. */\n    prefixFor(url: string): string {\n        return '../'.repeat(url.split('/').length - 1);\n    }\n}\n"]}

package/src/samples/CodeSamples.d.ts

@@ -0,0 +1,49 @@
+import { ApiSpec, OperationInfo } from '../spec/ApiSpec';
+import { ExampleBuilder } from '../spec/ExampleBuilder';
+/** One language's sample for one operation. `id` is the tab's value, `label` is what a reader sees. */
+export declare class CodeSample {
+    readonly id: string;
+    readonly label: string;
+    readonly source: string;
+    constructor(id: string, label: string, source: string);
+}
+/** One header a sample sends: the name the document declares, and a placeholder for the value. */
+export declare class SampleHeader {
+    readonly name: string;
+    readonly value: string;
+    constructor(name: string, value: string);
+}
+/**
+ * Builds the code samples FROM THE SPEC: the server url, the path, the header names the document's
+ * own security schemes declare, and an example body generated from the request schema.
+ *
+ * Nothing here is authored per operation, which is the point. A sample somebody wrote by hand is a
+ * copy of the contract that no build can contradict, so the first rename leaves a partner pasting a
+ * header the server stopped reading.
+ *
+ * ## No samples for a webhook
+ *
+ * A webhook's url belongs to the PARTNER. A curl of ours against one would invite them to call
+ * something that does not exist, so the whole card is absent rather than present-and-wrong.
+ *
+ * ## No vendor logos
+ *
+ * The languages are labelled in words. The gopher and the Java cup are other companies'
+ * trademarks, and a docs generator that ships them hands every consumer that problem too.
+ */
+export declare class CodeSampleBuilder {
+    private readonly spec;
+    private readonly examples;
+    constructor(spec: ApiSpec, examples: ExampleBuilder);
+    /** Every sample for an operation, in published tab order. Empty for a webhook. */
+    samplesFor(operation: OperationInfo): readonly CodeSample[];
+    /** The header each security scheme this operation requires is sent in. */
+    headersFor(operation: OperationInfo): readonly SampleHeader[];
+    private baseUrl;
+    private hostName;
+    private http;
+    private javascript;
+    private go;
+    private java;
+    private indent;
+}

package/src/samples/CodeSamples.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CodeSampleBuilder = exports.SampleHeader = exports.CodeSample = void 0;
+/** One language's sample for one operation. `id` is the tab's value, `label` is what a reader sees. */
+class CodeSample {
+    id;
+    label;
+    source;
+    constructor(id, label, source) {
+        this.id = id;
+        this.label = label;
+        this.source = source;
+    }
+}
+exports.CodeSample = CodeSample;
+/** One header a sample sends: the name the document declares, and a placeholder for the value. */
+class SampleHeader {
+    name;
+    value;
+    constructor(name, value) {
+        this.name = name;
+        this.value = value;
+    }
+}
+exports.SampleHeader = SampleHeader;
+/**
+ * Builds the code samples FROM THE SPEC: the server url, the path, the header names the document's
+ * own security schemes declare, and an example body generated from the request schema.
+ *
+ * Nothing here is authored per operation, which is the point. A sample somebody wrote by hand is a
+ * copy of the contract that no build can contradict, so the first rename leaves a partner pasting a
+ * header the server stopped reading.
+ *
+ * ## No samples for a webhook
+ *
+ * A webhook's url belongs to the PARTNER. A curl of ours against one would invite them to call
+ * something that does not exist, so the whole card is absent rather than present-and-wrong.
+ *
+ * ## No vendor logos
+ *
+ * The languages are labelled in words. The gopher and the Java cup are other companies'
+ * trademarks, and a docs generator that ships them hands every consumer that problem too.
+ */
+class CodeSampleBuilder {
+    spec;
+    examples;
+    constructor(spec, examples) {
+        this.spec = spec;
+        this.examples = examples;
+    }
+    /** Every sample for an operation, in published tab order. Empty for a webhook. */
+    samplesFor(operation) {
+        if (operation.isWebhook) {
+            return [];
+        }
+        const url = `${this.baseUrl()}${operation.path}`;
+        const headers = this.headersFor(operation);
+        const body = this.examples.render(this.examples.build(operation.requestSchema));
+        return [
+            new CodeSample('http', 'HTTP', this.http(operation, headers, body)),
+            new CodeSample('javascript', 'JavaScript', this.javascript(operation, url, headers, body)),
+            new CodeSample('go', 'Go', this.go(operation, url, headers, body)),
+            new CodeSample('java', 'Java', this.java(operation, url, headers, body)),
+        ];
+    }
+    /** The header each security scheme this operation requires is sent in. */
+    headersFor(operation) {
+        const headers = [];
+        for (const key of operation.securityKeys) {
+            const scheme = this.spec.securitySchemes.find((one) => one.key === key);
+            if (scheme !== undefined && scheme.sentIn === 'header' && scheme.headerName !== '') {
+                headers.push(new SampleHeader(scheme.headerName, `<your ${scheme.key}>`));
+            }
+        }
+        return headers;
+    }
+    baseUrl() {
+        const first = this.spec.servers[0];
+        return first === undefined ? '' : first.url.replace(/\/$/, '');
+    }
+    hostName() {
+        const host = this.baseUrl().replace(/^https?:\/\//, '');
+        return host === '' ? 'your-api-host' : host;
+    }
+    http(operation, headers, body) {
+        const lines = [
+            `${operation.httpMethod} ${operation.path} HTTP/1.1`,
+            `Host: ${this.hostName()}`,
+        ];
+        for (const header of headers) {
+            lines.push(`${header.name}: ${header.value}`);
+        }
+        if (body !== '') {
+            lines.push('Content-Type: application/json');
+            lines.push('');
+            lines.push(body);
+        }
+        return lines.join('\n');
+    }
+    javascript(operation, url, headers, body) {
+        const lines = [
+            // webpieces-disable no-fetch -- sample TEXT a partner pastes into their own client; nothing here calls anything
+            `const response = await fetch('${url}', {`,
+            `    method: '${operation.httpMethod}',`,
+            '    headers: {',
+        ];
+        for (const header of headers) {
+            lines.push(`        '${header.name}': '${header.value}',`);
+        }
+        if (body !== '') {
+            lines.push("        'Content-Type': 'application/json',");
+        }
+        lines.push('    },');
+        if (body !== '') {
+            lines.push(`    body: JSON.stringify(${this.indent(body, '    ')}),`);
+        }
+        lines.push('});');
+        lines.push('const result = await response.json();');
+        return lines.join('\n');
+    }
+    go(operation, url, headers, body) {
+        const lines = [];
+        if (body === '') {
+            lines.push(`req, _ := http.NewRequest("${operation.httpMethod}", "${url}", nil)`);
+        }
+        else {
+            lines.push(`body := []byte(\`${body}\`)`);
+            lines.push(`req, _ := http.NewRequest("${operation.httpMethod}", "${url}", bytes.NewReader(body))`);
+            lines.push('req.Header.Set("Content-Type", "application/json")');
+        }
+        for (const header of headers) {
+            lines.push(`req.Header.Set("${header.name}", "${header.value}")`);
+        }
+        lines.push('resp, err := http.DefaultClient.Do(req)');
+        return lines.join('\n');
+    }
+    java(operation, url, headers, body) {
+        const lines = [
+            'HttpRequest request = HttpRequest.newBuilder()',
+            `    .uri(URI.create("${url}"))`,
+        ];
+        for (const header of headers) {
+            lines.push(`    .header("${header.name}", "${header.value}")`);
+        }
+        if (body === '') {
+            lines.push(`    .method("${operation.httpMethod}", HttpRequest.BodyPublishers.noBody())`);
+        }
+        else {
+            lines.push('    .header("Content-Type", "application/json")');
+            lines.push(`    .method("${operation.httpMethod}", HttpRequest.BodyPublishers.ofString("""`);
+            lines.push(body);
+            lines.push('"""))');
+        }
+        lines.push('    .build();');
+        lines.push('HttpResponse<String> response = client.send(request, BodyHandlers.ofString());');
+        return lines.join('\n');
+    }
+    indent(body, prefix) {
+        return body
+            .split('\n')
+            .map((line, index) => (index === 0 ? line : `${prefix}${line}`))
+            .join('\n');
+    }
+}
+exports.CodeSampleBuilder = CodeSampleBuilder;
+//# sourceMappingURL=CodeSamples.js.map

package/src/samples/CodeSamples.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CodeSamples.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/samples/CodeSamples.ts"],"names":[],"mappings":"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","sourcesContent":["import { ApiSpec, OperationInfo, SecuritySchemeInfo } from '../spec/ApiSpec';\nimport { ExampleBuilder } from '../spec/ExampleBuilder';\n\n/** One language's sample for one operation. `id` is the tab's value, `label` is what a reader sees. */\nexport class CodeSample {\n    constructor(\n        readonly id: string,\n        readonly label: string,\n        readonly source: string,\n    ) {}\n}\n\n/** One header a sample sends: the name the document declares, and a placeholder for the value. */\nexport class SampleHeader {\n    constructor(\n        readonly name: string,\n        readonly value: string,\n    ) {}\n}\n\n/**\n * Builds the code samples FROM THE SPEC: the server url, the path, the header names the document's\n * own security schemes declare, and an example body generated from the request schema.\n *\n * Nothing here is authored per operation, which is the point. A sample somebody wrote by hand is a\n * copy of the contract that no build can contradict, so the first rename leaves a partner pasting a\n * header the server stopped reading.\n *\n * ## No samples for a webhook\n *\n * A webhook's url belongs to the PARTNER. A curl of ours against one would invite them to call\n * something that does not exist, so the whole card is absent rather than present-and-wrong.\n *\n * ## No vendor logos\n *\n * The languages are labelled in words. The gopher and the Java cup are other companies'\n * trademarks, and a docs generator that ships them hands every consumer that problem too.\n */\nexport class CodeSampleBuilder {\n    constructor(\n        private readonly spec: ApiSpec,\n        private readonly examples: ExampleBuilder,\n    ) {}\n\n    /** Every sample for an operation, in published tab order. Empty for a webhook. */\n    samplesFor(operation: OperationInfo): readonly CodeSample[] {\n        if (operation.isWebhook) {\n            return [];\n        }\n        const url = `${this.baseUrl()}${operation.path}`;\n        const headers = this.headersFor(operation);\n        const body = this.examples.render(this.examples.build(operation.requestSchema));\n        return [\n            new CodeSample('http', 'HTTP', this.http(operation, headers, body)),\n            new CodeSample(\n                'javascript',\n                'JavaScript',\n                this.javascript(operation, url, headers, body),\n            ),\n            new CodeSample('go', 'Go', this.go(operation, url, headers, body)),\n            new CodeSample('java', 'Java', this.java(operation, url, headers, body)),\n        ];\n    }\n\n    /** The header each security scheme this operation requires is sent in. */\n    headersFor(operation: OperationInfo): readonly SampleHeader[] {\n        const headers: SampleHeader[] = [];\n        for (const key of operation.securityKeys) {\n            const scheme = this.spec.securitySchemes.find(\n                (one: SecuritySchemeInfo): boolean => one.key === key,\n            );\n            if (scheme !== undefined && scheme.sentIn === 'header' && scheme.headerName !== '') {\n                headers.push(new SampleHeader(scheme.headerName, `<your ${scheme.key}>`));\n            }\n        }\n        return headers;\n    }\n\n    private baseUrl(): string {\n        const first = this.spec.servers[0];\n        return first === undefined ? '' : first.url.replace(/\\/$/, '');\n    }\n\n    private hostName(): string {\n        const host = this.baseUrl().replace(/^https?:\\/\\//, '');\n        return host === '' ? 'your-api-host' : host;\n    }\n\n    private http(operation: OperationInfo, headers: readonly SampleHeader[], body: string): string {\n        const lines = [\n            `${operation.httpMethod} ${operation.path} HTTP/1.1`,\n            `Host: ${this.hostName()}`,\n        ];\n        for (const header of headers) {\n            lines.push(`${header.name}: ${header.value}`);\n        }\n        if (body !== '') {\n            lines.push('Content-Type: application/json');\n            lines.push('');\n            lines.push(body);\n        }\n        return lines.join('\\n');\n    }\n\n    private javascript(\n        operation: OperationInfo,\n        url: string,\n        headers: readonly SampleHeader[],\n        body: string,\n    ): string {\n        const lines = [\n            // webpieces-disable no-fetch -- sample TEXT a partner pastes into their own client; nothing here calls anything\n            `const response = await fetch('${url}', {`,\n            `    method: '${operation.httpMethod}',`,\n            '    headers: {',\n        ];\n        for (const header of headers) {\n            lines.push(`        '${header.name}': '${header.value}',`);\n        }\n        if (body !== '') {\n            lines.push(\"        'Content-Type': 'application/json',\");\n        }\n        lines.push('    },');\n        if (body !== '') {\n            lines.push(`    body: JSON.stringify(${this.indent(body, '    ')}),`);\n        }\n        lines.push('});');\n        lines.push('const result = await response.json();');\n        return lines.join('\\n');\n    }\n\n    private go(\n        operation: OperationInfo,\n        url: string,\n        headers: readonly SampleHeader[],\n        body: string,\n    ): string {\n        const lines: string[] = [];\n        if (body === '') {\n            lines.push(`req, _ := http.NewRequest(\"${operation.httpMethod}\", \"${url}\", nil)`);\n        } else {\n            lines.push(`body := []byte(\\`${body}\\`)`);\n            lines.push(\n                `req, _ := http.NewRequest(\"${operation.httpMethod}\", \"${url}\", bytes.NewReader(body))`,\n            );\n            lines.push('req.Header.Set(\"Content-Type\", \"application/json\")');\n        }\n        for (const header of headers) {\n            lines.push(`req.Header.Set(\"${header.name}\", \"${header.value}\")`);\n        }\n        lines.push('resp, err := http.DefaultClient.Do(req)');\n        return lines.join('\\n');\n    }\n\n    private java(\n        operation: OperationInfo,\n        url: string,\n        headers: readonly SampleHeader[],\n        body: string,\n    ): string {\n        const lines = [\n            'HttpRequest request = HttpRequest.newBuilder()',\n            `    .uri(URI.create(\"${url}\"))`,\n        ];\n        for (const header of headers) {\n            lines.push(`    .header(\"${header.name}\", \"${header.value}\")`);\n        }\n        if (body === '') {\n            lines.push(\n                `    .method(\"${operation.httpMethod}\", HttpRequest.BodyPublishers.noBody())`,\n            );\n        } else {\n            lines.push('    .header(\"Content-Type\", \"application/json\")');\n            lines.push(\n                `    .method(\"${operation.httpMethod}\", HttpRequest.BodyPublishers.ofString(\"\"\"`,\n            );\n            lines.push(body);\n            lines.push('\"\"\"))');\n        }\n        lines.push('    .build();');\n        lines.push(\n            'HttpResponse<String> response = client.send(request, BodyHandlers.ofString());',\n        );\n        return lines.join('\\n');\n    }\n\n    private indent(body: string, prefix: string): string {\n        return body\n            .split('\\n')\n            .map((line: string, index: number): string => (index === 0 ? line : `${prefix}${line}`))\n            .join('\\n');\n    }\n}\n"]}

package/src/serve/DevServer.d.ts

@@ -0,0 +1,35 @@
+/** The only interface this server ever binds. It is not configurable, on purpose. */
+export declare const LOOPBACK = "127.0.0.1";
+/**
+ * A LOCALHOST-ONLY static preview of a generated site — what `wp-docs-site --serve` runs.
+ *
+ * ## It is a preview, and it is not a host
+ *
+ * It binds {@link LOOPBACK} and nothing else, so it is not reachable from another machine. It is not
+ * hardened and it is not authenticated: there is no logging, no rate limiting, no TLS and no access
+ * control, and nothing here should be read as a claim that adding an address would make it safe to
+ * expose. Hosting a generated site is explicitly out of this package's scope (#985) — the output is
+ * a folder, and a real static host serves it.
+ *
+ * The one security property it DOES enforce is that a request cannot escape the output directory:
+ * the resolved path is checked against the root, so `../../etc/passwd` is a 404 rather than a read.
+ * That is not hardening, it is the minimum for a process that opens a socket at all.
+ */
+export declare class DevServer {
+    private readonly root;
+    private server;
+    constructor(root: string);
+    /** Binds and resolves with the port actually listening. `0` asks the OS for a free one. */
+    start(port: number): Promise<number>;
+    /** The bound port, or 0 when nothing is listening. */
+    port(): number;
+    /** The url a human opens. */
+    url(): string;
+    stop(): Promise<void>;
+    private handle;
+    /**
+     * The file a request maps to, or `undefined` for anything outside the root or not there.
+     * A directory maps to its `index.html`, which is what makes `/reference/fetch-orders/` work.
+     */
+    fileFor(requestUrl: string): string | undefined;
+}

package/src/serve/DevServer.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DevServer = exports.LOOPBACK = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("node:fs"));
+const http = tslib_1.__importStar(require("node:http"));
+const path = tslib_1.__importStar(require("node:path"));
+const DocsSiteError_1 = require("../DocsSiteError");
+/** The only interface this server ever binds. It is not configurable, on purpose. */
+exports.LOOPBACK = '127.0.0.1';
+/** Extension to content type. Four entries, because a generated site holds four kinds of file. */
+const CONTENT_TYPES = new Map([
+    ['.html', 'text/html; charset=utf-8'],
+    ['.css', 'text/css; charset=utf-8'],
+    ['.js', 'text/javascript; charset=utf-8'],
+    ['.json', 'application/json; charset=utf-8'],
+]);
+/**
+ * A LOCALHOST-ONLY static preview of a generated site — what `wp-docs-site --serve` runs.
+ *
+ * ## It is a preview, and it is not a host
+ *
+ * It binds {@link LOOPBACK} and nothing else, so it is not reachable from another machine. It is not
+ * hardened and it is not authenticated: there is no logging, no rate limiting, no TLS and no access
+ * control, and nothing here should be read as a claim that adding an address would make it safe to
+ * expose. Hosting a generated site is explicitly out of this package's scope (#985) — the output is
+ * a folder, and a real static host serves it.
+ *
+ * The one security property it DOES enforce is that a request cannot escape the output directory:
+ * the resolved path is checked against the root, so `../../etc/passwd` is a 404 rather than a read.
+ * That is not hardening, it is the minimum for a process that opens a socket at all.
+ */
+class DevServer {
+    root;
+    server;
+    constructor(root) {
+        this.root = root;
+    }
+    /** Binds and resolves with the port actually listening. `0` asks the OS for a free one. */
+    start(port) {
+        if (!fs.existsSync(this.root)) {
+            throw new DocsSiteError_1.DocsSiteError('there is no generated site to preview', this.root, 'Run wp-docs-site --spec <document> --out <dir> first, then --serve the same --out.');
+        }
+        const server = http.createServer((request, response) => {
+            this.handle(request, response);
+        });
+        this.server = server;
+        return new Promise((resolve) => {
+            server.listen(port, exports.LOOPBACK, () => {
+                resolve(this.port());
+            });
+        });
+    }
+    /** The bound port, or 0 when nothing is listening. */
+    port() {
+        const address = this.server?.address();
+        if (address === undefined || address === null || typeof address === 'string') {
+            return 0;
+        }
+        return address.port;
+    }
+    /** The url a human opens. */
+    url() {
+        return `http://${exports.LOOPBACK}:${this.port()}/`;
+    }
+    stop() {
+        const server = this.server;
+        if (server === undefined) {
+            return Promise.resolve();
+        }
+        this.server = undefined;
+        return new Promise((resolve) => {
+            server.close(() => {
+                resolve();
+            });
+        });
+    }
+    handle(request, response) {
+        const file = this.fileFor(request.url ?? '/');
+        if (file === undefined) {
+            response.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+            response.end('not found');
+            return;
+        }
+        const type = CONTENT_TYPES.get(path.extname(file)) ?? 'application/octet-stream';
+        response.writeHead(200, { 'content-type': type });
+        response.end(fs.readFileSync(file));
+    }
+    /**
+     * The file a request maps to, or `undefined` for anything outside the root or not there.
+     * A directory maps to its `index.html`, which is what makes `/reference/fetch-orders/` work.
+     */
+    fileFor(requestUrl) {
+        const withoutQuery = requestUrl.split('?')[0] ?? '/';
+        const decoded = decodeURIComponent(withoutQuery);
+        const resolvedRoot = path.resolve(this.root);
+        const target = path.resolve(resolvedRoot, `.${decoded}`);
+        if (target !== resolvedRoot && !target.startsWith(`${resolvedRoot}${path.sep}`)) {
+            return undefined;
+        }
+        if (fs.existsSync(target) && fs.statSync(target).isDirectory()) {
+            const index = path.join(target, 'index.html');
+            return fs.existsSync(index) ? index : undefined;
+        }
+        return fs.existsSync(target) ? target : undefined;
+    }
+}
+exports.DevServer = DevServer;
+//# sourceMappingURL=DevServer.js.map

package/src/serve/DevServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DevServer.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/serve/DevServer.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'node:fs';\nimport * as http from 'node:http';\nimport * as path from 'node:path';\nimport { DocsSiteError } from '../DocsSiteError';\n\n/** The only interface this server ever binds. It is not configurable, on purpose. */\nexport const LOOPBACK = '127.0.0.1';\n\n/** Extension to content type. Four entries, because a generated site holds four kinds of file. */\nconst CONTENT_TYPES = new Map<string, string>([\n    ['.html', 'text/html; charset=utf-8'],\n    ['.css', 'text/css; charset=utf-8'],\n    ['.js', 'text/javascript; charset=utf-8'],\n    ['.json', 'application/json; charset=utf-8'],\n]);\n\n/**\n * A LOCALHOST-ONLY static preview of a generated site — what `wp-docs-site --serve` runs.\n *\n * ## It is a preview, and it is not a host\n *\n * It binds {@link LOOPBACK} and nothing else, so it is not reachable from another machine. It is not\n * hardened and it is not authenticated: there is no logging, no rate limiting, no TLS and no access\n * control, and nothing here should be read as a claim that adding an address would make it safe to\n * expose. Hosting a generated site is explicitly out of this package's scope (#985) — the output is\n * a folder, and a real static host serves it.\n *\n * The one security property it DOES enforce is that a request cannot escape the output directory:\n * the resolved path is checked against the root, so `../../etc/passwd` is a 404 rather than a read.\n * That is not hardening, it is the minimum for a process that opens a socket at all.\n */\nexport class DevServer {\n    private server: http.Server | undefined;\n\n    constructor(private readonly root: string) {}\n\n    /** Binds and resolves with the port actually listening. `0` asks the OS for a free one. */\n    start(port: number): Promise<number> {\n        if (!fs.existsSync(this.root)) {\n            throw new DocsSiteError(\n                'there is no generated site to preview',\n                this.root,\n                'Run wp-docs-site --spec <document> --out <dir> first, then --serve the same --out.',\n            );\n        }\n        const server = http.createServer(\n            (request: http.IncomingMessage, response: http.ServerResponse): void => {\n                this.handle(request, response);\n            },\n        );\n        this.server = server;\n        return new Promise<number>((resolve: (value: number) => void): void => {\n            server.listen(port, LOOPBACK, (): void => {\n                resolve(this.port());\n            });\n        });\n    }\n\n    /** The bound port, or 0 when nothing is listening. */\n    port(): number {\n        const address = this.server?.address();\n        if (address === undefined || address === null || typeof address === 'string') {\n            return 0;\n        }\n        return address.port;\n    }\n\n    /** The url a human opens. */\n    url(): string {\n        return `http://${LOOPBACK}:${this.port()}/`;\n    }\n\n    stop(): Promise<void> {\n        const server = this.server;\n        if (server === undefined) {\n            return Promise.resolve();\n        }\n        this.server = undefined;\n        return new Promise<void>((resolve: () => void): void => {\n            server.close((): void => {\n                resolve();\n            });\n        });\n    }\n\n    private handle(request: http.IncomingMessage, response: http.ServerResponse): void {\n        const file = this.fileFor(request.url ?? '/');\n        if (file === undefined) {\n            response.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });\n            response.end('not found');\n            return;\n        }\n        const type = CONTENT_TYPES.get(path.extname(file)) ?? 'application/octet-stream';\n        response.writeHead(200, { 'content-type': type });\n        response.end(fs.readFileSync(file));\n    }\n\n    /**\n     * The file a request maps to, or `undefined` for anything outside the root or not there.\n     * A directory maps to its `index.html`, which is what makes `/reference/fetch-orders/` work.\n     */\n    fileFor(requestUrl: string): string | undefined {\n        const withoutQuery = requestUrl.split('?')[0] ?? '/';\n        const decoded = decodeURIComponent(withoutQuery);\n        const resolvedRoot = path.resolve(this.root);\n        const target = path.resolve(resolvedRoot, `.${decoded}`);\n        if (target !== resolvedRoot && !target.startsWith(`${resolvedRoot}${path.sep}`)) {\n            return undefined;\n        }\n        if (fs.existsSync(target) && fs.statSync(target).isDirectory()) {\n            const index = path.join(target, 'index.html');\n            return fs.existsSync(index) ? index : undefined;\n        }\n        return fs.existsSync(target) ? target : undefined;\n    }\n}\n"]}

package/src/spec/ApiSpec.d.ts

@@ -0,0 +1,110 @@
+import { JsonNode } from './JsonNode';
+/**
+ * The model this package renders. It is read from a document STRUCTURALLY (see {@link JsonNode}), so
+ * it is deliberately NOT `@webpieces/openapi-generator`'s document classes even though it looks like
+ * them: a compile-time dependency on the generator would make "generated by us" a precondition for
+ * "renderable by us", and #985 is explicit that any conforming 3.0 or 3.1 document renders here.
+ *
+ * Everything below is data, so everything below is a class (`CLAUDE.md` §1).
+ */
+/** One entry of the document's `servers[]`. The first one is what the code samples call. */
+export declare class ServerInfo {
+    readonly url: string;
+    readonly description: string | undefined;
+    constructor(url: string, description: string | undefined);
+}
+/**
+ * One published security scheme. Only the fields a partner has to ACT on are carried: what to send
+ * and where. `headerName` is empty for a scheme that is not sent in a header, and the code samples
+ * then omit it rather than inventing a header name the server never reads.
+ */
+export declare class SecuritySchemeInfo {
+    readonly key: string;
+    readonly kind: string;
+    readonly sentIn: string;
+    readonly headerName: string;
+    readonly description: string | undefined;
+    constructor(key: string, kind: string, sentIn: string, headerName: string, description: string | undefined);
+}
+/** One response of one operation. */
+export declare class ResponseInfo {
+    readonly status: string;
+    readonly description: string;
+    readonly schema: JsonNode | undefined;
+    constructor(status: string, description: string, schema: JsonNode | undefined);
+}
+/**
+ * One rendered page's worth of operation.
+ *
+ * A WEBHOOK carries `isWebhook`, and with it no method, no path and no code samples. The url belongs
+ * to the PARTNER, so a curl of ours against one would invite them to call something that does not
+ * exist — see `responsibilities.md`.
+ */
+export declare class OperationInfo {
+    readonly name: string;
+    readonly slug: string;
+    readonly httpMethod: string;
+    readonly path: string;
+    readonly description: string;
+    readonly tag: string;
+    readonly requestSchema: JsonNode | undefined;
+    readonly responses: readonly ResponseInfo[];
+    readonly isWebhook: boolean;
+    readonly securityKeys: readonly string[];
+    /**
+     * The event NAME a webhook is keyed by in the document's `webhooks:` block, and the empty
+     * string for an ordinary operation. It is carried separately from `name` because the two
+     * are different published facts — `orderStateChanged` is what we call the method,
+     * `order.state-changed` is what the partner matches on the wire.
+     */
+    readonly eventName: string;
+    constructor(name: string, slug: string, httpMethod: string, path: string, description: string, tag: string, requestSchema: JsonNode | undefined, responses: readonly ResponseInfo[], isWebhook: boolean, securityKeys: readonly string[], 
+    /**
+     * The event NAME a webhook is keyed by in the document's `webhooks:` block, and the empty
+     * string for an ordinary operation. It is carried separately from `name` because the two
+     * are different published facts — `orderStateChanged` is what we call the method,
+     * `order.state-changed` is what the partner matches on the wire.
+     */
+    eventName: string);
+}
+/**
+ * One nav section: an OpenAPI tag and the operations under it, webhooks appended after the
+ * operations that share the tag. EVERY tag gets one — a tag missing from the sidebar is an operation
+ * a partner cannot find, which reads exactly like an operation that does not exist.
+ */
+export declare class TagSection {
+    readonly name: string;
+    readonly description: string;
+    readonly operations: readonly OperationInfo[];
+    constructor(name: string, description: string, operations: readonly OperationInfo[]);
+}
+/**
+ * One named schema from `components.schemas`.
+ *
+ * `hasOwnPage` is true for an OBJECT only. A named enum or scalar alias stays inline at every use
+ * site, because a page carrying one line of chips is a click that costs the reader the context they
+ * were reading in.
+ */
+export declare class NamedSchema {
+    readonly name: string;
+    readonly slug: string;
+    readonly node: JsonNode;
+    readonly hasOwnPage: boolean;
+    constructor(name: string, slug: string, node: JsonNode, hasOwnPage: boolean);
+}
+/** The whole document, read once. */
+export declare class ApiSpec {
+    readonly title: string;
+    readonly version: string;
+    readonly description: string;
+    readonly servers: readonly ServerInfo[];
+    readonly sections: readonly TagSection[];
+    readonly securitySchemes: readonly SecuritySchemeInfo[];
+    readonly schemas: readonly NamedSchema[];
+    readonly documentSecurityKeys: readonly string[];
+    constructor(title: string, version: string, description: string, servers: readonly ServerInfo[], sections: readonly TagSection[], securitySchemes: readonly SecuritySchemeInfo[], schemas: readonly NamedSchema[], documentSecurityKeys: readonly string[]);
+    /** The named schema `name` refers to, or `undefined` when the document does not define it. */
+    schemaNamed(name: string): NamedSchema | undefined;
+    /** Every operation, across every section, in published order. */
+    operations(): readonly OperationInfo[];
+}