@webpieces/docs-site 0.0.1

package/README.md

@@ -0,0 +1,83 @@
+# @webpieces/docs-site
+
+A static, three-pane API reference site from **any** OpenAPI 3.0-or-3.1 document.
+
+```bash
+wp-docs-site --spec path/to/public-openapi.json --prose path/to/docs --out path/to/site
+wp-docs-site --spec path/to/public-openapi.json --out path/to/site --serve
+```
+
+**Node builtins only** — no framework, no markdown library, no bundler. Adding an API reference to
+your project does not grow your dependency surface, and this package's own build is `tsc`.
+
+## What you get
+
+```
+site/
+  index.html                          the overview: info.description, plus every tag and its operations
+  styles.css  site.js                 one stylesheet, one script
+  prose/<kebab-title>/index.html      one per page docs.manifest.json names, in ITS order
+  reference/<kebab-operation>/index.html
+  schemas/<kebab-name>/index.html     one per named OBJECT dto
+```
+
+One PRE-RENDERED file per URL. A deep link resolves without JavaScript, the folder works on any
+static host (and under a path prefix, and over `file://`), and a JSDoc edit shows up as a diff on the
+one page it affects. The client script does three things only: disclosure state, the language tabs,
+and the theme.
+
+## The prose directory
+
+```json
+{
+    "title": "Example Orders API",
+    "pages": [
+        { "file": "getting-started.md", "title": "Getting started" },
+        { "file": "authentication.md", "title": "Authentication" }
+    ]
+}
+```
+
+**The order of `pages` is the published order.** So is the document's `tags[]` for the reference.
+Neither is sorted — alphabetising either reorders what a partner reads first.
+
+A page the manifest names but the directory does not hold fails the run. A markdown file the manifest
+does NOT name is simply not published: the manifest is the published list.
+
+The markdown is a documented SUBSET of CommonMark — headings, fenced code, tables, lists,
+blockquotes, rules, paragraphs, and inline `code` / `**bold**` / `*italic*` / `[links](url)` — over
+trusted, PR-reviewed input. Everything is HTML-escaped before any mark is applied.
+
+## Reading the reference
+
+- **Every tag is its own nav section.** A tag missing from the sidebar is an operation a partner
+  cannot find, which reads exactly like an operation that does not exist.
+- **A webhook** files into the section of the tag it shares, appended after that tag's operations and
+  badged, with no method, no path and no code samples. The url is yours, not ours.
+- **A `oneOf` request body** renders every branch expanded and labelled by its discriminator value —
+  never tabbed, because a tab is invisible to Ctrl-F and to print.
+- **A named object DTO gets its own page**, and every reference to it is a LINK. The generated
+  example body resolves the same reference fully, because a hyperlink cannot live in a JSON sample.
+- **An enum** shows the COMPLETE `Possible values:` chip line, inline, with no page of its own.
+- A nullable field shows the NON-null type; a `format` renders as `string<date-time>`.
+
+## Code samples
+
+Built FROM THE SPEC — the server url, the path, the header names your `securitySchemes` declare, and
+an example body generated from the request schema — in HTTP, JavaScript, Go and Java. Nothing is
+authored per operation, so a rename cannot leave a partner pasting a header the server stopped
+reading.
+
+The languages are labelled in words. The gopher and the Java cup are other companies' trademarks.
+
+## `--serve` is a preview, not a host
+
+It binds `127.0.0.1` and nothing else. It is not hardened and not authenticated: no logging, no rate
+limiting, no TLS, no access control. Put the generated FOLDER on a real static host.
+
+## It does not depend on the generator
+
+This package does not import `@webpieces/openapi-generator`, even though the two model the same
+document. A compile-time dependency would make "generated by us" a precondition for "renderable by
+us". The document is read structurally, and the suite renders a 3.0 document written in 3.0's dialect
+to keep that honest. See `responsibilities.md`.

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@webpieces/docs-site",
+  "version": "0.0.1",
+  "description": "Render a static, three-pane API reference site from any OpenAPI 3.0-or-3.1 document plus a directory of markdown prose. Node builtins only. Ships the wp-docs-site 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/docs-site"
+  },
+  "keywords": [
+    "webpieces",
+    "openapi",
+    "docs",
+    "static-site",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "wp-docs-site": "./src/cli/wp-docs-site.js"
+  }
+}

package/src/DocsSiteError.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The ONE failure type this package throws. A run either renders a complete site or throws this — it
+ * never prints a warning, never writes a half-site, and never guesses at a document it cannot read.
+ *
+ * It is a structured throw to the single top-level handler in `WpDocsSiteMain`, per
+ * `.claude/review/error-output.md`: `location` and `cure` are carried as FIELDS rather than baked
+ * into `message`, so the CLI renders them per audience and this class hand-numbers nothing.
+ *
+ * It is NOT `RuleFailError`, and for the same reason `@webpieces/openapi-generator` gave: that type
+ * lives in `@webpieces/rules-config`, the TOOLING stream a repo pins one release behind on purpose,
+ * while `packages/docs/*` publish with the SERVER libs. It is also not `OpenApiGenerationError` —
+ * this package renders ANY conforming document and therefore depends on the generator not at all.
+ */
+export declare class DocsSiteError extends Error {
+    /** Where the problem IS — a spec path, a prose directory, or `<spec>#/paths/~1orders`. */
+    readonly location: string;
+    /** What to do instead, in one sentence. No numbering — the CLI owns that. */
+    readonly cure: string;
+    constructor(message: string, 
+    /** Where the problem IS — a spec path, a prose directory, or `<spec>#/paths/~1orders`. */
+    location: string, 
+    /** What to do instead, in one sentence. No numbering — the CLI owns that. */
+    cure: string);
+}

package/src/DocsSiteError.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocsSiteError = void 0;
+/**
+ * The ONE failure type this package throws. A run either renders a complete site or throws this — it
+ * never prints a warning, never writes a half-site, and never guesses at a document it cannot read.
+ *
+ * It is a structured throw to the single top-level handler in `WpDocsSiteMain`, per
+ * `.claude/review/error-output.md`: `location` and `cure` are carried as FIELDS rather than baked
+ * into `message`, so the CLI renders them per audience and this class hand-numbers nothing.
+ *
+ * It is NOT `RuleFailError`, and for the same reason `@webpieces/openapi-generator` gave: that type
+ * lives in `@webpieces/rules-config`, the TOOLING stream a repo pins one release behind on purpose,
+ * while `packages/docs/*` publish with the SERVER libs. It is also not `OpenApiGenerationError` —
+ * this package renders ANY conforming document and therefore depends on the generator not at all.
+ */
+class DocsSiteError extends Error {
+    location;
+    cure;
+    constructor(message, 
+    /** Where the problem IS — a spec path, a prose directory, or `<spec>#/paths/~1orders`. */
+    location, 
+    /** What to do instead, in one sentence. No numbering — the CLI owns that. */
+    cure) {
+        super(`${message} (${location})`);
+        this.location = location;
+        this.cure = cure;
+        this.name = 'DocsSiteError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.DocsSiteError = DocsSiteError;
+//# sourceMappingURL=DocsSiteError.js.map

package/src/DocsSiteError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocsSiteError.js","sourceRoot":"","sources":["../../../../../packages/docs/docs-site/src/DocsSiteError.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;GAYG;AACH,MAAa,aAAc,SAAQ,KAAK;IAIvB;IAEA;IALb,YACI,OAAe;IACf,0FAA0F;IACjF,QAAgB;IACzB,6EAA6E;IACpE,IAAY;QAErB,KAAK,CAAC,GAAG,OAAO,KAAK,QAAQ,GAAG,CAAC,CAAC;QAJzB,aAAQ,GAAR,QAAQ,CAAQ;QAEhB,SAAI,GAAJ,IAAI,CAAQ;QAGrB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACtD,CAAC;CACJ;AAZD,sCAYC","sourcesContent":["/**\n * The ONE failure type this package throws. A run either renders a complete site or throws this — it\n * never prints a warning, never writes a half-site, and never guesses at a document it cannot read.\n *\n * It is a structured throw to the single top-level handler in `WpDocsSiteMain`, per\n * `.claude/review/error-output.md`: `location` and `cure` are carried as FIELDS rather than baked\n * into `message`, so the CLI renders them per audience and this class hand-numbers nothing.\n *\n * It is NOT `RuleFailError`, and for the same reason `@webpieces/openapi-generator` gave: that type\n * lives in `@webpieces/rules-config`, the TOOLING stream a repo pins one release behind on purpose,\n * while `packages/docs/*` publish with the SERVER libs. It is also not `OpenApiGenerationError` —\n * this package renders ANY conforming document and therefore depends on the generator not at all.\n */\nexport class DocsSiteError extends Error {\n    constructor(\n        message: string,\n        /** Where the problem IS — a spec path, a prose directory, or `<spec>#/paths/~1orders`. */\n        readonly location: string,\n        /** What to do instead, in one sentence. No numbering — the CLI owns that. */\n        readonly cure: string,\n    ) {\n        super(`${message} (${location})`);\n        this.name = 'DocsSiteError';\n        Object.setPrototypeOf(this, new.target.prototype);\n    }\n}\n"]}

package/src/assets/SiteScript.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The whole client script, as one string written to `site.js` beside the pages.
+ *
+ * It does THREE things, and the list is deliberately short: disclosure state, the language tabs and
+ * the theme. Every URL in this site is already a file on disk, so routing, fetching and rendering
+ * are not its job — with JS off the page still reads, only the tabs stop switching and every sample
+ * is visible at once, which is a worse page rather than a blank one.
+ */
+export declare class SiteScript {
+    static readonly JS = "\n(function () {\n    var KEY = 'webpieces-docs-theme';\n    var LANG = 'webpieces-docs-language';\n\n    function readStored(key) {\n        // Reading storage THROWS in a private window, so every access is guarded at the boundary.\n        // webpieces-disable no-unmanaged-exceptions -- this IS the boundary; the page must read with storage unavailable\n        try {\n            return window.localStorage.getItem(key);\n        } catch (err) {\n            return null;\n        }\n    }\n\n    function store(key, value) {\n        // webpieces-disable no-unmanaged-exceptions -- same boundary, writing; a refused write is not an error here\n        try {\n            window.localStorage.setItem(key, value);\n        } catch (err) {\n            /* a private window refuses storage; the page works without it */\n        }\n    }\n\n    function applyTheme(theme) {\n        document.documentElement.setAttribute('data-theme', theme);\n        store(KEY, theme);\n    }\n\n    function selectLanguage(id) {\n        var tabs = document.querySelectorAll('.tab');\n        for (var i = 0; i < tabs.length; i++) {\n            tabs[i].setAttribute('aria-selected', tabs[i].getAttribute('data-language') === id ? 'true' : 'false');\n        }\n        var samples = document.querySelectorAll('.sample');\n        for (var j = 0; j < samples.length; j++) {\n            samples[j].hidden = samples[j].getAttribute('data-language') !== id;\n        }\n        store(LANG, id);\n    }\n\n    document.addEventListener('click', function (event) {\n        var target = event.target;\n        if (!target || !target.getAttribute) {\n            return;\n        }\n        if (target.classList.contains('tab')) {\n            selectLanguage(target.getAttribute('data-language'));\n        }\n        if (target.classList.contains('collapse-all')) {\n            var open = document.querySelectorAll('.pane-body details[open]');\n            for (var i = 0; i < open.length; i++) {\n                open[i].open = false;\n            }\n        }\n        if (target.classList.contains('theme-toggle')) {\n            applyTheme(document.documentElement.getAttribute('data-theme') === 'dark' ? 'light' : 'dark');\n        }\n    });\n\n    var storedTheme = readStored(KEY);\n    if (storedTheme) {\n        applyTheme(storedTheme);\n    } else if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {\n        applyTheme('dark');\n    }\n\n    var storedLanguage = readStored(LANG);\n    if (storedLanguage && document.querySelector('.tab[data-language=\"' + storedLanguage + '\"]')) {\n        selectLanguage(storedLanguage);\n    }\n})();\n";
+}

package/src/assets/SiteScript.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SiteScript = void 0;
+/**
+ * The whole client script, as one string written to `site.js` beside the pages.
+ *
+ * It does THREE things, and the list is deliberately short: disclosure state, the language tabs and
+ * the theme. Every URL in this site is already a file on disk, so routing, fetching and rendering
+ * are not its job — with JS off the page still reads, only the tabs stop switching and every sample
+ * is visible at once, which is a worse page rather than a blank one.
+ */
+class SiteScript {
+    static JS = `
+(function () {
+    var KEY = 'webpieces-docs-theme';
+    var LANG = 'webpieces-docs-language';
+
+    function readStored(key) {
+        // Reading storage THROWS in a private window, so every access is guarded at the boundary.
+        // webpieces-disable no-unmanaged-exceptions -- this IS the boundary; the page must read with storage unavailable
+        try {
+            return window.localStorage.getItem(key);
+        } catch (err) {
+            return null;
+        }
+    }
+
+    function store(key, value) {
+        // webpieces-disable no-unmanaged-exceptions -- same boundary, writing; a refused write is not an error here
+        try {
+            window.localStorage.setItem(key, value);
+        } catch (err) {
+            /* a private window refuses storage; the page works without it */
+        }
+    }
+
+    function applyTheme(theme) {
+        document.documentElement.setAttribute('data-theme', theme);
+        store(KEY, theme);
+    }
+
+    function selectLanguage(id) {
+        var tabs = document.querySelectorAll('.tab');
+        for (var i = 0; i < tabs.length; i++) {
+            tabs[i].setAttribute('aria-selected', tabs[i].getAttribute('data-language') === id ? 'true' : 'false');
+        }
+        var samples = document.querySelectorAll('.sample');
+        for (var j = 0; j < samples.length; j++) {
+            samples[j].hidden = samples[j].getAttribute('data-language') !== id;
+        }
+        store(LANG, id);
+    }
+
+    document.addEventListener('click', function (event) {
+        var target = event.target;
+        if (!target || !target.getAttribute) {
+            return;
+        }
+        if (target.classList.contains('tab')) {
+            selectLanguage(target.getAttribute('data-language'));
+        }
+        if (target.classList.contains('collapse-all')) {
+            var open = document.querySelectorAll('.pane-body details[open]');
+            for (var i = 0; i < open.length; i++) {
+                open[i].open = false;
+            }
+        }
+        if (target.classList.contains('theme-toggle')) {
+            applyTheme(document.documentElement.getAttribute('data-theme') === 'dark' ? 'light' : 'dark');
+        }
+    });
+
+    var storedTheme = readStored(KEY);
+    if (storedTheme) {
+        applyTheme(storedTheme);
+    } else if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
+        applyTheme('dark');
+    }
+
+    var storedLanguage = readStored(LANG);
+    if (storedLanguage && document.querySelector('.tab[data-language="' + storedLanguage + '"]')) {
+        selectLanguage(storedLanguage);
+    }
+})();
+`;
+}
+exports.SiteScript = SiteScript;
+//# sourceMappingURL=SiteScript.js.map

package/src/assets/SiteScript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SiteScript.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/assets/SiteScript.ts"],"names":[],"mappings":";;;AAAA;;;;;;;GAOG;AACH,MAAa,UAAU;IACnB,MAAM,CAAU,EAAE,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwExB,CAAC;;AAzEF,gCA0EC","sourcesContent":["/**\n * The whole client script, as one string written to `site.js` beside the pages.\n *\n * It does THREE things, and the list is deliberately short: disclosure state, the language tabs and\n * the theme. Every URL in this site is already a file on disk, so routing, fetching and rendering\n * are not its job — with JS off the page still reads, only the tabs stop switching and every sample\n * is visible at once, which is a worse page rather than a blank one.\n */\nexport class SiteScript {\n    static readonly JS = `\n(function () {\n    var KEY = 'webpieces-docs-theme';\n    var LANG = 'webpieces-docs-language';\n\n    function readStored(key) {\n        // Reading storage THROWS in a private window, so every access is guarded at the boundary.\n        // webpieces-disable no-unmanaged-exceptions -- this IS the boundary; the page must read with storage unavailable\n        try {\n            return window.localStorage.getItem(key);\n        } catch (err) {\n            return null;\n        }\n    }\n\n    function store(key, value) {\n        // webpieces-disable no-unmanaged-exceptions -- same boundary, writing; a refused write is not an error here\n        try {\n            window.localStorage.setItem(key, value);\n        } catch (err) {\n            /* a private window refuses storage; the page works without it */\n        }\n    }\n\n    function applyTheme(theme) {\n        document.documentElement.setAttribute('data-theme', theme);\n        store(KEY, theme);\n    }\n\n    function selectLanguage(id) {\n        var tabs = document.querySelectorAll('.tab');\n        for (var i = 0; i < tabs.length; i++) {\n            tabs[i].setAttribute('aria-selected', tabs[i].getAttribute('data-language') === id ? 'true' : 'false');\n        }\n        var samples = document.querySelectorAll('.sample');\n        for (var j = 0; j < samples.length; j++) {\n            samples[j].hidden = samples[j].getAttribute('data-language') !== id;\n        }\n        store(LANG, id);\n    }\n\n    document.addEventListener('click', function (event) {\n        var target = event.target;\n        if (!target || !target.getAttribute) {\n            return;\n        }\n        if (target.classList.contains('tab')) {\n            selectLanguage(target.getAttribute('data-language'));\n        }\n        if (target.classList.contains('collapse-all')) {\n            var open = document.querySelectorAll('.pane-body details[open]');\n            for (var i = 0; i < open.length; i++) {\n                open[i].open = false;\n            }\n        }\n        if (target.classList.contains('theme-toggle')) {\n            applyTheme(document.documentElement.getAttribute('data-theme') === 'dark' ? 'light' : 'dark');\n        }\n    });\n\n    var storedTheme = readStored(KEY);\n    if (storedTheme) {\n        applyTheme(storedTheme);\n    } else if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {\n        applyTheme('dark');\n    }\n\n    var storedLanguage = readStored(LANG);\n    if (storedLanguage && document.querySelector('.tab[data-language=\"' + storedLanguage + '\"]')) {\n        selectLanguage(storedLanguage);\n    }\n})();\n`;\n}\n"]}

package/src/assets/SiteStyles.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The whole stylesheet, as one string written to `styles.css` beside the pages.
+ *
+ * It is hand-written rather than generated by a framework because #985 puts the framework, the
+ * bundler and the markdown library out of scope: adding an API reference to an upstream project must
+ * not grow that project's dependency surface, and this package's own build has to stay `tsc`.
+ *
+ * Colours are declared once as custom properties and redefined for dark mode, so a theme toggle is
+ * one attribute on `<html>` and nothing else in the site knows about it.
+ */
+export declare class SiteStyles {
+    static readonly CSS = "\n:root {\n    --bg: #ffffff;\n    --bg-soft: #f6f7f9;\n    --fg: #1d2129;\n    --fg-soft: #5b6472;\n    --line: #e2e5ea;\n    --accent: #2f5cff;\n    --code-bg: #f2f3f6;\n    --badge-fg: #ffffff;\n}\n:root[data-theme='dark'] {\n    --bg: #14171c;\n    --bg-soft: #1b1f26;\n    --fg: #e7eaf0;\n    --fg-soft: #9aa4b2;\n    --line: #2a2f38;\n    --accent: #7f9bff;\n    --code-bg: #10131a;\n    --badge-fg: #14171c;\n}\n* { box-sizing: border-box; }\nbody {\n    margin: 0;\n    background: var(--bg);\n    color: var(--fg);\n    font: 15px/1.6 -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;\n}\na { color: var(--accent); text-decoration: none; }\na:hover { text-decoration: underline; }\ncode, pre { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 13px; }\ncode { background: var(--code-bg); padding: 1px 4px; border-radius: 3px; }\npre { background: var(--code-bg); padding: 12px; border-radius: 6px; overflow-x: auto; }\npre code { background: none; padding: 0; }\ntable { border-collapse: collapse; width: 100%; margin: 12px 0; }\nth, td { border: 1px solid var(--line); padding: 6px 10px; text-align: left; vertical-align: top; }\nth { background: var(--bg-soft); }\nhr { border: 0; border-top: 1px solid var(--line); margin: 24px 0; }\nblockquote { margin: 12px 0; padding: 4px 14px; border-left: 3px solid var(--line); color: var(--fg-soft); }\n\n.site { display: grid; grid-template-columns: 260px minmax(0, 1fr) 360px; gap: 0; min-height: 100vh; }\n.pane-nav { border-right: 1px solid var(--line); padding: 20px 16px; background: var(--bg-soft); }\n.pane-body { padding: 28px 32px; min-width: 0; }\n.pane-cards { border-left: 1px solid var(--line); padding: 20px 16px; background: var(--bg-soft); }\n.pane-cards-inner { position: sticky; top: 20px; }\n\n.site-title { font-weight: 700; font-size: 15px; margin-bottom: 4px; display: block; color: var(--fg); }\n.site-version { color: var(--fg-soft); font-size: 12px; margin-bottom: 16px; }\n.nav-group { margin-bottom: 10px; }\n.nav-group > summary { cursor: pointer; font-weight: 600; font-size: 12px; letter-spacing: .06em; text-transform: uppercase; color: var(--fg-soft); }\n.nav-group ul { list-style: none; margin: 6px 0 0; padding: 0 0 0 4px; }\n.nav-group li { margin: 2px 0; }\n.nav-group a { display: flex; gap: 6px; align-items: center; padding: 3px 6px; border-radius: 4px; color: var(--fg); }\n.nav-group a.current { background: var(--accent); color: var(--badge-fg); }\n.nav-group a.current .badge { background: var(--badge-fg); color: var(--accent); }\n\n.badge { font-size: 10px; font-weight: 700; letter-spacing: .04em; padding: 1px 5px; border-radius: 3px; background: var(--accent); color: var(--badge-fg); }\n.op-head { display: flex; gap: 10px; align-items: center; flex-wrap: wrap; margin-bottom: 4px; }\n.op-path { background: var(--code-bg); padding: 3px 8px; border-radius: 4px; }\n\n.card { border: 1px solid var(--line); border-radius: 8px; background: var(--bg); margin-bottom: 16px; }\n.card-head { display: flex; justify-content: space-between; align-items: center; padding: 8px 12px; border-bottom: 1px solid var(--line); font-size: 11px; font-weight: 700; letter-spacing: .08em; text-transform: uppercase; color: var(--fg-soft); }\n.card-body { padding: 12px; }\n.card-body pre { margin: 0; }\nbutton { font: inherit; font-size: 11px; cursor: pointer; background: none; border: 1px solid var(--line); border-radius: 4px; padding: 2px 8px; color: var(--fg-soft); }\nbutton:hover { color: var(--fg); }\n.tabs { display: flex; gap: 4px; flex-wrap: wrap; padding: 8px 12px 0; }\n.tab[aria-selected='true'] { border-color: var(--accent); color: var(--accent); }\n.sample[hidden] { display: none; }\n\n.field { border-top: 1px solid var(--line); padding: 10px 0; }\n.field-head { display: flex; gap: 8px; align-items: baseline; flex-wrap: wrap; }\n.field-name { font-weight: 600; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }\n.field-type { color: var(--fg-soft); font-size: 12px; }\n.field-required { color: #c0392b; font-size: 11px; font-weight: 700; letter-spacing: .04em; }\n.field-doc { margin: 4px 0 0; color: var(--fg-soft); }\n.field-children { margin-left: 16px; border-left: 1px solid var(--line); padding-left: 12px; }\n.chips { margin-top: 6px; font-size: 12px; color: var(--fg-soft); }\n.chip { display: inline-block; background: var(--code-bg); border: 1px solid var(--line); border-radius: 10px; padding: 0 8px; margin: 2px 4px 2px 0; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }\n.variant { border: 1px solid var(--line); border-radius: 8px; padding: 10px 14px; margin: 12px 0; }\n.variant-head { font-weight: 600; }\ndetails.disclosure > summary { cursor: pointer; color: var(--fg-soft); font-size: 12px; }\n\n@media (max-width: 1100px) {\n    .site { grid-template-columns: 1fr; }\n    .pane-nav, .pane-cards { border: 0; }\n    .pane-cards-inner { position: static; }\n}\n";
+}

package/src/assets/SiteStyles.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SiteStyles = void 0;
+/**
+ * The whole stylesheet, as one string written to `styles.css` beside the pages.
+ *
+ * It is hand-written rather than generated by a framework because #985 puts the framework, the
+ * bundler and the markdown library out of scope: adding an API reference to an upstream project must
+ * not grow that project's dependency surface, and this package's own build has to stay `tsc`.
+ *
+ * Colours are declared once as custom properties and redefined for dark mode, so a theme toggle is
+ * one attribute on `<html>` and nothing else in the site knows about it.
+ */
+class SiteStyles {
+    static CSS = `
+:root {
+    --bg: #ffffff;
+    --bg-soft: #f6f7f9;
+    --fg: #1d2129;
+    --fg-soft: #5b6472;
+    --line: #e2e5ea;
+    --accent: #2f5cff;
+    --code-bg: #f2f3f6;
+    --badge-fg: #ffffff;
+}
+:root[data-theme='dark'] {
+    --bg: #14171c;
+    --bg-soft: #1b1f26;
+    --fg: #e7eaf0;
+    --fg-soft: #9aa4b2;
+    --line: #2a2f38;
+    --accent: #7f9bff;
+    --code-bg: #10131a;
+    --badge-fg: #14171c;
+}
+* { box-sizing: border-box; }
+body {
+    margin: 0;
+    background: var(--bg);
+    color: var(--fg);
+    font: 15px/1.6 -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
+}
+a { color: var(--accent); text-decoration: none; }
+a:hover { text-decoration: underline; }
+code, pre { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 13px; }
+code { background: var(--code-bg); padding: 1px 4px; border-radius: 3px; }
+pre { background: var(--code-bg); padding: 12px; border-radius: 6px; overflow-x: auto; }
+pre code { background: none; padding: 0; }
+table { border-collapse: collapse; width: 100%; margin: 12px 0; }
+th, td { border: 1px solid var(--line); padding: 6px 10px; text-align: left; vertical-align: top; }
+th { background: var(--bg-soft); }
+hr { border: 0; border-top: 1px solid var(--line); margin: 24px 0; }
+blockquote { margin: 12px 0; padding: 4px 14px; border-left: 3px solid var(--line); color: var(--fg-soft); }
+
+.site { display: grid; grid-template-columns: 260px minmax(0, 1fr) 360px; gap: 0; min-height: 100vh; }
+.pane-nav { border-right: 1px solid var(--line); padding: 20px 16px; background: var(--bg-soft); }
+.pane-body { padding: 28px 32px; min-width: 0; }
+.pane-cards { border-left: 1px solid var(--line); padding: 20px 16px; background: var(--bg-soft); }
+.pane-cards-inner { position: sticky; top: 20px; }
+
+.site-title { font-weight: 700; font-size: 15px; margin-bottom: 4px; display: block; color: var(--fg); }
+.site-version { color: var(--fg-soft); font-size: 12px; margin-bottom: 16px; }
+.nav-group { margin-bottom: 10px; }
+.nav-group > summary { cursor: pointer; font-weight: 600; font-size: 12px; letter-spacing: .06em; text-transform: uppercase; color: var(--fg-soft); }
+.nav-group ul { list-style: none; margin: 6px 0 0; padding: 0 0 0 4px; }
+.nav-group li { margin: 2px 0; }
+.nav-group a { display: flex; gap: 6px; align-items: center; padding: 3px 6px; border-radius: 4px; color: var(--fg); }
+.nav-group a.current { background: var(--accent); color: var(--badge-fg); }
+.nav-group a.current .badge { background: var(--badge-fg); color: var(--accent); }
+
+.badge { font-size: 10px; font-weight: 700; letter-spacing: .04em; padding: 1px 5px; border-radius: 3px; background: var(--accent); color: var(--badge-fg); }
+.op-head { display: flex; gap: 10px; align-items: center; flex-wrap: wrap; margin-bottom: 4px; }
+.op-path { background: var(--code-bg); padding: 3px 8px; border-radius: 4px; }
+
+.card { border: 1px solid var(--line); border-radius: 8px; background: var(--bg); margin-bottom: 16px; }
+.card-head { display: flex; justify-content: space-between; align-items: center; padding: 8px 12px; border-bottom: 1px solid var(--line); font-size: 11px; font-weight: 700; letter-spacing: .08em; text-transform: uppercase; color: var(--fg-soft); }
+.card-body { padding: 12px; }
+.card-body pre { margin: 0; }
+button { font: inherit; font-size: 11px; cursor: pointer; background: none; border: 1px solid var(--line); border-radius: 4px; padding: 2px 8px; color: var(--fg-soft); }
+button:hover { color: var(--fg); }
+.tabs { display: flex; gap: 4px; flex-wrap: wrap; padding: 8px 12px 0; }
+.tab[aria-selected='true'] { border-color: var(--accent); color: var(--accent); }
+.sample[hidden] { display: none; }
+
+.field { border-top: 1px solid var(--line); padding: 10px 0; }
+.field-head { display: flex; gap: 8px; align-items: baseline; flex-wrap: wrap; }
+.field-name { font-weight: 600; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+.field-type { color: var(--fg-soft); font-size: 12px; }
+.field-required { color: #c0392b; font-size: 11px; font-weight: 700; letter-spacing: .04em; }
+.field-doc { margin: 4px 0 0; color: var(--fg-soft); }
+.field-children { margin-left: 16px; border-left: 1px solid var(--line); padding-left: 12px; }
+.chips { margin-top: 6px; font-size: 12px; color: var(--fg-soft); }
+.chip { display: inline-block; background: var(--code-bg); border: 1px solid var(--line); border-radius: 10px; padding: 0 8px; margin: 2px 4px 2px 0; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+.variant { border: 1px solid var(--line); border-radius: 8px; padding: 10px 14px; margin: 12px 0; }
+.variant-head { font-weight: 600; }
+details.disclosure > summary { cursor: pointer; color: var(--fg-soft); font-size: 12px; }
+
+@media (max-width: 1100px) {
+    .site { grid-template-columns: 1fr; }
+    .pane-nav, .pane-cards { border: 0; }
+    .pane-cards-inner { position: static; }
+}
+`;
+}
+exports.SiteStyles = SiteStyles;
+//# sourceMappingURL=SiteStyles.js.map

package/src/assets/SiteStyles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SiteStyles.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/assets/SiteStyles.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;GASG;AACH,MAAa,UAAU;IACnB,MAAM,CAAU,GAAG,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwFzB,CAAC;;AAzFF,gCA0FC","sourcesContent":["/**\n * The whole stylesheet, as one string written to `styles.css` beside the pages.\n *\n * It is hand-written rather than generated by a framework because #985 puts the framework, the\n * bundler and the markdown library out of scope: adding an API reference to an upstream project must\n * not grow that project's dependency surface, and this package's own build has to stay `tsc`.\n *\n * Colours are declared once as custom properties and redefined for dark mode, so a theme toggle is\n * one attribute on `<html>` and nothing else in the site knows about it.\n */\nexport class SiteStyles {\n    static readonly CSS = `\n:root {\n    --bg: #ffffff;\n    --bg-soft: #f6f7f9;\n    --fg: #1d2129;\n    --fg-soft: #5b6472;\n    --line: #e2e5ea;\n    --accent: #2f5cff;\n    --code-bg: #f2f3f6;\n    --badge-fg: #ffffff;\n}\n:root[data-theme='dark'] {\n    --bg: #14171c;\n    --bg-soft: #1b1f26;\n    --fg: #e7eaf0;\n    --fg-soft: #9aa4b2;\n    --line: #2a2f38;\n    --accent: #7f9bff;\n    --code-bg: #10131a;\n    --badge-fg: #14171c;\n}\n* { box-sizing: border-box; }\nbody {\n    margin: 0;\n    background: var(--bg);\n    color: var(--fg);\n    font: 15px/1.6 -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;\n}\na { color: var(--accent); text-decoration: none; }\na:hover { text-decoration: underline; }\ncode, pre { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 13px; }\ncode { background: var(--code-bg); padding: 1px 4px; border-radius: 3px; }\npre { background: var(--code-bg); padding: 12px; border-radius: 6px; overflow-x: auto; }\npre code { background: none; padding: 0; }\ntable { border-collapse: collapse; width: 100%; margin: 12px 0; }\nth, td { border: 1px solid var(--line); padding: 6px 10px; text-align: left; vertical-align: top; }\nth { background: var(--bg-soft); }\nhr { border: 0; border-top: 1px solid var(--line); margin: 24px 0; }\nblockquote { margin: 12px 0; padding: 4px 14px; border-left: 3px solid var(--line); color: var(--fg-soft); }\n\n.site { display: grid; grid-template-columns: 260px minmax(0, 1fr) 360px; gap: 0; min-height: 100vh; }\n.pane-nav { border-right: 1px solid var(--line); padding: 20px 16px; background: var(--bg-soft); }\n.pane-body { padding: 28px 32px; min-width: 0; }\n.pane-cards { border-left: 1px solid var(--line); padding: 20px 16px; background: var(--bg-soft); }\n.pane-cards-inner { position: sticky; top: 20px; }\n\n.site-title { font-weight: 700; font-size: 15px; margin-bottom: 4px; display: block; color: var(--fg); }\n.site-version { color: var(--fg-soft); font-size: 12px; margin-bottom: 16px; }\n.nav-group { margin-bottom: 10px; }\n.nav-group > summary { cursor: pointer; font-weight: 600; font-size: 12px; letter-spacing: .06em; text-transform: uppercase; color: var(--fg-soft); }\n.nav-group ul { list-style: none; margin: 6px 0 0; padding: 0 0 0 4px; }\n.nav-group li { margin: 2px 0; }\n.nav-group a { display: flex; gap: 6px; align-items: center; padding: 3px 6px; border-radius: 4px; color: var(--fg); }\n.nav-group a.current { background: var(--accent); color: var(--badge-fg); }\n.nav-group a.current .badge { background: var(--badge-fg); color: var(--accent); }\n\n.badge { font-size: 10px; font-weight: 700; letter-spacing: .04em; padding: 1px 5px; border-radius: 3px; background: var(--accent); color: var(--badge-fg); }\n.op-head { display: flex; gap: 10px; align-items: center; flex-wrap: wrap; margin-bottom: 4px; }\n.op-path { background: var(--code-bg); padding: 3px 8px; border-radius: 4px; }\n\n.card { border: 1px solid var(--line); border-radius: 8px; background: var(--bg); margin-bottom: 16px; }\n.card-head { display: flex; justify-content: space-between; align-items: center; padding: 8px 12px; border-bottom: 1px solid var(--line); font-size: 11px; font-weight: 700; letter-spacing: .08em; text-transform: uppercase; color: var(--fg-soft); }\n.card-body { padding: 12px; }\n.card-body pre { margin: 0; }\nbutton { font: inherit; font-size: 11px; cursor: pointer; background: none; border: 1px solid var(--line); border-radius: 4px; padding: 2px 8px; color: var(--fg-soft); }\nbutton:hover { color: var(--fg); }\n.tabs { display: flex; gap: 4px; flex-wrap: wrap; padding: 8px 12px 0; }\n.tab[aria-selected='true'] { border-color: var(--accent); color: var(--accent); }\n.sample[hidden] { display: none; }\n\n.field { border-top: 1px solid var(--line); padding: 10px 0; }\n.field-head { display: flex; gap: 8px; align-items: baseline; flex-wrap: wrap; }\n.field-name { font-weight: 600; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }\n.field-type { color: var(--fg-soft); font-size: 12px; }\n.field-required { color: #c0392b; font-size: 11px; font-weight: 700; letter-spacing: .04em; }\n.field-doc { margin: 4px 0 0; color: var(--fg-soft); }\n.field-children { margin-left: 16px; border-left: 1px solid var(--line); padding-left: 12px; }\n.chips { margin-top: 6px; font-size: 12px; color: var(--fg-soft); }\n.chip { display: inline-block; background: var(--code-bg); border: 1px solid var(--line); border-radius: 10px; padding: 0 8px; margin: 2px 4px 2px 0; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }\n.variant { border: 1px solid var(--line); border-radius: 8px; padding: 10px 14px; margin: 12px 0; }\n.variant-head { font-weight: 600; }\ndetails.disclosure > summary { cursor: pointer; color: var(--fg-soft); font-size: 12px; }\n\n@media (max-width: 1100px) {\n    .site { grid-template-columns: 1fr; }\n    .pane-nav, .pane-cards { border: 0; }\n    .pane-cards-inner { position: static; }\n}\n`;\n}\n"]}

package/src/cli/DocsSiteCli.d.ts

@@ -0,0 +1,37 @@
+import { RenderedSite } from '../render/SitePage';
+export declare const USAGE: string;
+/** What one run produced, so a caller can print it or assert on it. */
+export declare class CliResult {
+    readonly written: readonly string[];
+    readonly site: RenderedSite;
+    readonly outDir: string;
+    readonly serve: boolean;
+    readonly port: number;
+    constructor(written: readonly string[], site: RenderedSite, outDir: string, serve: boolean, port: number);
+}
+/**
+ * `wp-docs-site`'s argument parsing and composition, with NO process-level concerns in it — no
+ * `process.exit`, no `console` — so the suite exercises the whole command exactly as a user runs it.
+ *
+ * `--spec` and `--out` are REQUIRED and have no defaults. A defaulted `--out` writes a site
+ * somewhere the caller did not name; a defaulted `--spec` documents whichever service the command
+ * happened to start in.
+ */
+export declare class DocsSiteCli {
+    private readonly specs;
+    private readonly reader;
+    private readonly prose;
+    private readonly renderer;
+    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;
+    private proseDirOf;
+    private portOf;
+    /**
+     * The value after a flag. An UNKNOWN flag is refused rather than ignored: a mistyped `--spce`
+     * would otherwise fall through to "needs both flags", which sends the reader looking at the
+     * wrong thing.
+     */
+    private valueOf;
+}

package/src/cli/DocsSiteCli.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocsSiteCli = exports.CliResult = exports.USAGE = void 0;
+const tslib_1 = require("tslib");
+const path = tslib_1.__importStar(require("node:path"));
+const DocsSiteError_1 = require("../DocsSiteError");
+const ProseLoader_1 = require("../manifest/ProseLoader");
+const SiteRenderer_1 = require("../render/SiteRenderer");
+const SiteWriter_1 = require("../emit/SiteWriter");
+const SpecLoader_1 = require("../spec/SpecLoader");
+const SpecReader_1 = require("../spec/SpecReader");
+const SPEC = '--spec';
+const PROSE = '--prose';
+const OUT = '--out';
+const PORT = '--port';
+const SERVE = '--serve';
+const HELP = '--help';
+const VALUE_FLAGS = [SPEC, PROSE, OUT, PORT];
+const BARE_FLAGS = [SERVE, HELP];
+exports.USAGE = [
+    'wp-docs-site --spec <openapi.json> [--prose <dir>] --out <dir> [--serve] [--port <n>]',
+    '',
+    'Renders a static, three-pane API reference site: one PRE-RENDERED HTML file per URL, so a deep',
+    'link resolves without JavaScript and the output is a folder any static host serves.',
+    '',
+    '  --spec    an OpenAPI 3.0 or 3.1 JSON document. Any conforming document — this renderer does',
+    '            not require the document to have been generated by webpieces.',
+    '  --prose   a directory holding docs.manifest.json and the markdown it names, in ITS order.',
+    '  --out     where to write the site. Nothing in it is deleted.',
+    '  --serve   after writing, preview the result on 127.0.0.1 and nothing else. It is a PREVIEW:',
+    '            not hardened, not authenticated, and not a way to host the site.',
+    '  --port    the preview port. 0, the default, asks the operating system for a free one.',
+].join('\n');
+/** What one run produced, so a caller can print it or assert on it. */
+class CliResult {
+    written;
+    site;
+    outDir;
+    serve;
+    port;
+    constructor(written, site, outDir, serve, port) {
+        this.written = written;
+        this.site = site;
+        this.outDir = outDir;
+        this.serve = serve;
+        this.port = port;
+    }
+}
+exports.CliResult = CliResult;
+/**
+ * `wp-docs-site`'s argument parsing and composition, with NO process-level concerns in it — no
+ * `process.exit`, no `console` — so the suite exercises the whole command exactly as a user runs it.
+ *
+ * `--spec` and `--out` are REQUIRED and have no defaults. A defaulted `--out` writes a site
+ * somewhere the caller did not name; a defaulted `--spec` documents whichever service the command
+ * happened to start in.
+ */
+class DocsSiteCli {
+    specs = new SpecLoader_1.SpecLoader();
+    reader = new SpecReader_1.SpecReader();
+    prose = new ProseLoader_1.ProseLoader();
+    renderer = new SiteRenderer_1.SiteRenderer();
+    writer = new SiteWriter_1.SiteWriter();
+    /** @param argv the arguments AFTER the program name. @param cwd what relative paths resolve against. */
+    run(argv, cwd) {
+        const spec = this.valueOf(argv, SPEC);
+        const out = this.valueOf(argv, OUT);
+        if (spec === undefined || out === undefined) {
+            throw new DocsSiteError_1.DocsSiteError(`wp-docs-site needs both ${SPEC} and ${OUT}`, 'wp-docs-site', `Run: wp-docs-site ${SPEC} <openapi.json> ${OUT} <dir>`);
+        }
+        const proseDir = this.proseDirOf(argv, cwd);
+        const document = this.specs.load(path.resolve(cwd, spec));
+        const site = this.renderer.render(this.reader.read(document), this.prose.load(proseDir), this.prose.titleOf(proseDir));
+        const outDir = path.resolve(cwd, out);
+        return new CliResult(this.writer.write(outDir, site), site, outDir, argv.includes(SERVE), this.portOf(argv));
+    }
+    wantsHelp(argv) {
+        return argv.includes(HELP);
+    }
+    proseDirOf(argv, cwd) {
+        const declared = this.valueOf(argv, PROSE);
+        return declared === undefined ? undefined : path.resolve(cwd, declared);
+    }
+    portOf(argv) {
+        const declared = this.valueOf(argv, PORT);
+        if (declared === undefined) {
+            return 0;
+        }
+        const port = Number(declared);
+        if (!Number.isInteger(port) || port < 0 || port > 65535) {
+            throw new DocsSiteError_1.DocsSiteError(`${PORT} '${declared}' is not a port number`, 'wp-docs-site', `${PORT} takes a whole number from 0 to 65535. 0 asks the operating system for a free one.`);
+        }
+        return port;
+    }
+    /**
+     * The value after a flag. An UNKNOWN flag is refused rather than ignored: a mistyped `--spce`
+     * 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('--') &&
+                !VALUE_FLAGS.includes(argument) &&
+                !BARE_FLAGS.includes(argument)) {
+                throw new DocsSiteError_1.DocsSiteError(`unknown flag '${argument}'`, 'wp-docs-site', `wp-docs-site takes ${[...VALUE_FLAGS, ...BARE_FLAGS].join(', ')}, and nothing else.`);
+            }
+        }
+        return undefined;
+    }
+}
+exports.DocsSiteCli = DocsSiteCli;
+//# sourceMappingURL=DocsSiteCli.js.map

package/src/cli/DocsSiteCli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocsSiteCli.js","sourceRoot":"","sources":["../../../../../../packages/docs/docs-site/src/cli/DocsSiteCli.ts"],"names":[],"mappings":"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","sourcesContent":["import * as path from 'node:path';\nimport { DocsSiteError } from '../DocsSiteError';\nimport { ProseLoader } from '../manifest/ProseLoader';\nimport { RenderedSite } from '../render/SitePage';\nimport { SiteRenderer } from '../render/SiteRenderer';\nimport { SiteWriter } from '../emit/SiteWriter';\nimport { SpecLoader } from '../spec/SpecLoader';\nimport { SpecReader } from '../spec/SpecReader';\n\nconst SPEC = '--spec';\nconst PROSE = '--prose';\nconst OUT = '--out';\nconst PORT = '--port';\nconst SERVE = '--serve';\nconst HELP = '--help';\n\nconst VALUE_FLAGS = [SPEC, PROSE, OUT, PORT];\nconst BARE_FLAGS = [SERVE, HELP];\n\nexport const USAGE = [\n    'wp-docs-site --spec <openapi.json> [--prose <dir>] --out <dir> [--serve] [--port <n>]',\n    '',\n    'Renders a static, three-pane API reference site: one PRE-RENDERED HTML file per URL, so a deep',\n    'link resolves without JavaScript and the output is a folder any static host serves.',\n    '',\n    '  --spec    an OpenAPI 3.0 or 3.1 JSON document. Any conforming document — this renderer does',\n    '            not require the document to have been generated by webpieces.',\n    '  --prose   a directory holding docs.manifest.json and the markdown it names, in ITS order.',\n    '  --out     where to write the site. Nothing in it is deleted.',\n    '  --serve   after writing, preview the result on 127.0.0.1 and nothing else. It is a PREVIEW:',\n    '            not hardened, not authenticated, and not a way to host the site.',\n    '  --port    the preview port. 0, the default, asks the operating system for a free one.',\n].join('\\n');\n\n/** What one run produced, so a caller can print it or assert on it. */\nexport class CliResult {\n    constructor(\n        readonly written: readonly string[],\n        readonly site: RenderedSite,\n        readonly outDir: string,\n        readonly serve: boolean,\n        readonly port: number,\n    ) {}\n}\n\n/**\n * `wp-docs-site`'s argument parsing and composition, with NO process-level concerns in it — no\n * `process.exit`, no `console` — so the suite exercises the whole command exactly as a user runs it.\n *\n * `--spec` and `--out` are REQUIRED and have no defaults. A defaulted `--out` writes a site\n * somewhere the caller did not name; a defaulted `--spec` documents whichever service the command\n * happened to start in.\n */\nexport class DocsSiteCli {\n    private readonly specs = new SpecLoader();\n    private readonly reader = new SpecReader();\n    private readonly prose = new ProseLoader();\n    private readonly renderer = new SiteRenderer();\n    private readonly writer = new SiteWriter();\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 spec = this.valueOf(argv, SPEC);\n        const out = this.valueOf(argv, OUT);\n        if (spec === undefined || out === undefined) {\n            throw new DocsSiteError(\n                `wp-docs-site needs both ${SPEC} and ${OUT}`,\n                'wp-docs-site',\n                `Run: wp-docs-site ${SPEC} <openapi.json> ${OUT} <dir>`,\n            );\n        }\n        const proseDir = this.proseDirOf(argv, cwd);\n        const document = this.specs.load(path.resolve(cwd, spec));\n        const site = this.renderer.render(\n            this.reader.read(document),\n            this.prose.load(proseDir),\n            this.prose.titleOf(proseDir),\n        );\n        const outDir = path.resolve(cwd, out);\n        return new CliResult(\n            this.writer.write(outDir, site),\n            site,\n            outDir,\n            argv.includes(SERVE),\n            this.portOf(argv),\n        );\n    }\n\n    wantsHelp(argv: readonly string[]): boolean {\n        return argv.includes(HELP);\n    }\n\n    private proseDirOf(argv: readonly string[], cwd: string): string | undefined {\n        const declared = this.valueOf(argv, PROSE);\n        return declared === undefined ? undefined : path.resolve(cwd, declared);\n    }\n\n    private portOf(argv: readonly string[]): number {\n        const declared = this.valueOf(argv, PORT);\n        if (declared === undefined) {\n            return 0;\n        }\n        const port = Number(declared);\n        if (!Number.isInteger(port) || port < 0 || port > 65535) {\n            throw new DocsSiteError(\n                `${PORT} '${declared}' is not a port number`,\n                'wp-docs-site',\n                `${PORT} takes a whole number from 0 to 65535. 0 asks the operating system for a free one.`,\n            );\n        }\n        return port;\n    }\n\n    /**\n     * The value after a flag. An UNKNOWN flag is refused rather than ignored: a mistyped `--spce`\n     * would otherwise fall through to \"needs both flags\", which sends the reader looking at the\n     * wrong 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 (\n                argument.startsWith('--') &&\n                !VALUE_FLAGS.includes(argument) &&\n                !BARE_FLAGS.includes(argument)\n            ) {\n                throw new DocsSiteError(\n                    `unknown flag '${argument}'`,\n                    'wp-docs-site',\n                    `wp-docs-site takes ${[...VALUE_FLAGS, ...BARE_FLAGS].join(', ')}, and nothing else.`,\n                );\n            }\n        }\n        return undefined;\n    }\n}\n"]}

package/src/cli/WpDocsSiteMain.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The body of the `wp-docs-site` 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.
+ *
+ * Everything below here THROWS {@link DocsSiteError} 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 — rather than from a string
+ * somebody baked a cure into, so one audience's formatting never freezes into a thrower.
+ */
+export declare class WpDocsSiteMain {
+    private readonly cli;
+    /** @returns the process exit code. 0 on success, 1 on a stated failure. */
+    run(argv: readonly string[], cwd: string, out: NodeJS.WritableStream): Promise<number>;
+    /**
+     * `--serve` starts the localhost preview and RESOLVES when it is listening, rather than blocking
+     * forever. The bin keeps the process alive because the socket is open, and the suite can start
+     * one, read a page and stop it — a run method that never returned would be untestable.
+     */
+    private preview;
+    private render;
+}