@kong/spec-renderer 1.111.3 → 1.111.4-pr.942.12e41ef.0

package/README.md

@@ -15,6 +15,7 @@ An online API specification editor is available at [api-documentation.dev](https
     - [Example for html/script](#-example-for-htmlscript)
   - [Props](#props)
     - [v-model](#v-model)
+- [CLI](#cli)
 - [Contributing & Local Development](#contributing--local-development)
   - [Development Sandbox](#development-sandbox)
     - [Build and Preview the Development Sandbox](#build-and-preview-the-development-sandbox)
@@ -23,6 +24,7 @@ An online API specification editor is available at [api-documentation.dev](https
   - [Build for production](#build-for-production)
   - [Committing Changes](#committing-changes)
     - [Enforcing Commit Format](#enforcing-commit-format)
+    - [Agentic Reviewer](#agentic-reviewer)
   - [Approvals](#approvals)
   - [Package Publishing](#package-publishing)
 - [Third-party packages and Thank You](#third-party-packages-and-thank-you)
@@ -225,6 +227,27 @@ As of now only `SpecRenderer` as single component is supported for this. Let us
 
 [Check out the `SpecRendererProps` interface](./src/types/spec-renderer.ts) for all props valid for the `SpecRenderer` component.
 
+## CLI
+
+Preview an OpenAPI or AsyncAPI spec (from a local file or remote URL), rendered with this package's own UI, right on your machine - no host app or project setup required. The preview reloads automatically when you save changes to the spec file.
+
+### Via `npx` or `pnpm dlx`
+
+```sh
+npx @kong/spec-renderer preview ./openapi.yaml
+```
+
+### Via kongctl Extension
+
+The CLI is also available as a [kongctl](https://github.com/Kong/kongctl) extension:
+
+```sh
+kongctl install extension kong/spec-renderer
+kongctl preview spec ./openapi.yaml
+```
+
+See the [CLI docs](./cli/README.md) for full usage, flags, and troubleshooting.
+
 ## Contributing & Local Development
 
 To get started, install the package dependencies
@@ -306,6 +329,10 @@ This will trigger the Commitizen interactive prompt for building your commit mes
 
 Additionally, CI will use `commitlint` to validate the commits associated with a PR in the `Lint and Validate` job.
 
+### Agentic reviewer
+
+[View the reference for the `/muthur` agentic reviewer](./docs/agentic-reviewer.md)
+
 ### Approvals
 
 - All pull requests require review and approval from authorized team members.

package/dist/cli/commands/preview.js

@@ -0,0 +1,134 @@
+import { readFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+import { watch } from 'chokidar';
+import open from 'open';
+import { loadSpecSource } from '../spec-source.js';
+import { resolveRenderOptions } from '../resolve-render-options.js';
+import { findOpenPort } from '../find-open-port.js';
+import { startPreviewServer } from '../server.js';
+import { hyperlink, info, pc, printPreviewBanner } from '../ui.js';
+const DEFAULT_PORT = 4757;
+/**
+ * Runs the `preview` command: loads the spec, starts the local preview
+ * server, watches the spec file for changes (when it's a local file), and
+ * opens the browser.
+ *
+ * Resolves once the server is up; the process is kept alive by the running
+ * server and, when applicable, the file watcher.
+ */
+export async function runPreviewCommand(specArg, flags) {
+    const source = await loadSpecSource(specArg);
+    let specText = source.text;
+    const requestedPort = await findOpenPort(flags.port ?? DEFAULT_PORT);
+    const previewServer = await startPreviewServer({
+        port: requestedPort,
+        getSpecText: () => specText,
+        config: resolveRenderOptions(flags),
+    });
+    // Use the port the server actually bound to, not the requested one - they
+    // differ when the requested port is `0` (OS picks any free port).
+    const url = `http://localhost:${previewServer.port}`;
+    const isWatching = source.watch && !!source.watchPath;
+    // A local file gets a `file://` link target; a remote spec's URL is
+    // already one, so it can link to itself.
+    const specLinkTarget = source.watchPath ? pathToFileURL(source.watchPath).href : specArg;
+    printPreviewBanner([
+        { label: 'Spec', value: pc.bold(pc.underline(hyperlink(specArg, specLinkTarget))) },
+        { label: 'URL', value: pc.bold(pc.underline(hyperlink(url, url))) },
+        { label: 'Reload', value: isWatching ? pc.green('watching for changes') : pc.yellow('not available (remote URL)') },
+    ]);
+    console.log();
+    info('Press Ctrl+C to stop');
+    let watcher;
+    if (source.watch && source.watchPath) {
+        const watchPath = source.watchPath;
+        // Guards against a slower, now-stale read completing after a newer one -
+        // e.g. two rapid saves in quick succession - and clobbering fresher content.
+        let latestChangeToken = 0;
+        watcher = watch(watchPath, {
+            // Without this, chokidar's initial scan on startup fires an `add` event
+            // for the already-existing watched file - which our `add` handler below
+            // (added to handle editors that recreate the file in place) would
+            // otherwise mistake for a real change and reload immediately on launch.
+            ignoreInitial: true,
+            // Some editors/tools write a file's contents in multiple chunks before
+            // the save is complete; without this, a `change` event can fire mid-write
+            // and be read as truncated/invalid content, surfacing a bogus parse error
+            // for what was actually a valid save.
+            awaitWriteFinish: {
+                stabilityThreshold: 200,
+                pollInterval: 20,
+            },
+        });
+        // Some editors (e.g. Vim's default writebackup save) rename the original
+        // file away and create a brand-new file at the same path, rather than
+        // writing in place. When the gap between that rename and the new file's
+        // creation exceeds chokidar's atomic-write dedup window, this surfaces as
+        // a genuine `unlink` followed by a separate `add`, instead of a single
+        // `change` - so both are treated as reload triggers, and a pending
+        // "file deleted" warning is held briefly to give a same-path `add` a
+        // chance to arrive first before assuming the file is actually gone.
+        let pendingUnlinkWarning;
+        const reloadFromDisk = () => {
+            const changeToken = ++latestChangeToken;
+            readFile(watchPath, 'utf-8')
+                .then((text) => {
+                if (changeToken !== latestChangeToken) {
+                    return;
+                }
+                specText = text;
+                previewServer.broadcastReload();
+                console.log(`${pc.magenta('↻')} Spec changed, reloading preview...`);
+            })
+                .catch((readError) => {
+                console.error(`${pc.red('✖')} Failed to reload spec: ${readError instanceof Error ? readError.message : String(readError)}`);
+            });
+        };
+        watcher.on('change', reloadFromDisk);
+        watcher.on('add', () => {
+            if (pendingUnlinkWarning) {
+                clearTimeout(pendingUnlinkWarning);
+                pendingUnlinkWarning = undefined;
+            }
+            reloadFromDisk();
+        });
+        watcher.on('unlink', () => {
+            pendingUnlinkWarning = setTimeout(() => {
+                pendingUnlinkWarning = undefined;
+                console.error(`${pc.red('✖')} Spec file was deleted or moved - live reload has stopped. The preview will keep showing its last-known content.`);
+            }, 500);
+        });
+        watcher.on('error', (watchError) => {
+            console.error(`${pc.red('✖')} File watcher error: ${watchError instanceof Error ? watchError.message : String(watchError)}`);
+        });
+    }
+    let isShuttingDown = false;
+    const shutdown = () => {
+        if (isShuttingDown) {
+            return;
+        }
+        isShuttingDown = true;
+        void Promise.resolve(watcher?.close())
+            .then(() => previewServer.close())
+            .catch((shutdownError) => {
+            console.error(`${pc.red('✖')} Error during shutdown: ${shutdownError instanceof Error ? shutdownError.message : String(shutdownError)}`);
+        })
+            .finally(() => process.exit(0));
+    };
+    // Registered before opening the browser so the server/watcher always have a
+    // clean shutdown path via Ctrl+C, even if the browser launch below fails.
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    if (flags.open !== false) {
+        try {
+            await open(url);
+        }
+        catch (openError) {
+            // Opening the browser is a convenience, not essential to the preview
+            // working - warn and keep the server/watcher running rather than
+            // failing the whole command.
+            console.error(`${pc.red('✖')} Failed to open the browser automatically: ${openError instanceof Error ? openError.message : String(openError)}`);
+        }
+    }
+}
+//# sourceMappingURL=preview.js.map

package/dist/cli/commands/preview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.js","sourceRoot":"","sources":["../../../cli/commands/preview.ts"],"names":[],"mappings":"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"}

package/dist/cli/find-open-port.js

@@ -0,0 +1,27 @@
+import { createServer } from 'node:net';
+/**
+ * Checks whether a port is free to bind on the local host by briefly binding
+ * to it and releasing it.
+ */
+export function isPortFree(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once('error', () => resolve(false));
+        server.once('listening', () => server.close(() => resolve(true)));
+        server.listen(port);
+    });
+}
+/**
+ * Finds the first free port starting at `startPort`, checking up to
+ * `maxAttempts` consecutive ports.
+ */
+export async function findOpenPort(startPort, checkIsPortFree = isPortFree, maxAttempts = 10) {
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        const candidate = startPort + attempt;
+        if (await checkIsPortFree(candidate)) {
+            return candidate;
+        }
+    }
+    throw new Error(`Could not find an open port after checking ${maxAttempts} ports starting at ${startPort}`);
+}
+//# sourceMappingURL=find-open-port.js.map

package/dist/cli/find-open-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-open-port.js","sourceRoot":"","sources":["../../cli/find-open-port.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAEvC;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG,YAAY,EAAE,CAAA;QAE7B,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAA;QAC1C,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACjE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IACrB,CAAC,CAAC,CAAA;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,SAAiB,EACjB,kBAAsD,UAAU,EAChE,WAAW,GAAG,EAAE;IAEhB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QACvD,MAAM,SAAS,GAAG,SAAS,GAAG,OAAO,CAAA;QAErC,IAAI,MAAM,eAAe,CAAC,SAAS,CAAC,EAAE,CAAC;YACrC,OAAO,SAAS,CAAA;QAClB,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,8CAA8C,WAAW,sBAAsB,SAAS,EAAE,CAAC,CAAA;AAC7G,CAAC"}

package/dist/cli/index.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { createProgram } from './program.js';
+import { error as printError } from './ui.js';
+try {
+    await createProgram().parseAsync(process.argv);
+}
+catch (error) {
+    printError(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../cli/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,EAAE,KAAK,IAAI,UAAU,EAAE,MAAM,SAAS,CAAA;AAE7C,IAAI,CAAC;IACH,MAAM,aAAa,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;AAChD,CAAC;AAAC,OAAO,KAAK,EAAE,CAAC;IACf,UAAU,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;IAClE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAA;AACtB,CAAC"}

package/dist/cli/parse-int-flag.js

@@ -0,0 +1,28 @@
+import { InvalidArgumentError } from 'commander';
+/**
+ * Builds a commander option parser for a non-negative integer flag.
+ *
+ * Throws a commander `InvalidArgumentError` for non-numeric or out-of-range
+ * input, which commander turns into a clean CLI error - rather than letting
+ * `Number.parseInt` silently produce `NaN` (which `??` does not treat as
+ * nullish, and which `JSON.stringify` silently serializes to `null`).
+ */
+export function parseIntFlag(flagName, options = {}) {
+    return (value) => {
+        // `Number.parseInt` stops at the first non-digit rather than requiring
+        // the whole string to be numeric (e.g. `parseInt('5000abc', 10) === 5000`,
+        // `parseInt('2.9', 10) === 2`) - reject anything that isn't purely
+        // digits up front so trailing garbage or a decimal point can't silently
+        // produce a value the user never typed.
+        if (!/^\d+$/.test(value.trim())) {
+            const bound = options.max === undefined ? '' : ` up to ${options.max}`;
+            throw new InvalidArgumentError(`${flagName} must be a non-negative integer${bound}.`);
+        }
+        const parsed = Number.parseInt(value, 10);
+        if (options.max !== undefined && parsed > options.max) {
+            throw new InvalidArgumentError(`${flagName} must be a non-negative integer up to ${options.max}.`);
+        }
+        return parsed;
+    };
+}
+//# sourceMappingURL=parse-int-flag.js.map

package/dist/cli/parse-int-flag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-int-flag.js","sourceRoot":"","sources":["../../cli/parse-int-flag.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAOhD;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,UAA+B,EAAE;IAC9E,OAAO,CAAC,KAAa,EAAU,EAAE;QAC/B,uEAAuE;QACvE,2EAA2E;QAC3E,mEAAmE;QACnE,wEAAwE;QACxE,wCAAwC;QACxC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YAChC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,OAAO,CAAC,GAAG,EAAE,CAAA;YAEtE,MAAM,IAAI,oBAAoB,CAAC,GAAG,QAAQ,kCAAkC,KAAK,GAAG,CAAC,CAAA;QACvF,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;QAEzC,IAAI,OAAO,CAAC,GAAG,KAAK,SAAS,IAAI,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;YACtD,MAAM,IAAI,oBAAoB,CAAC,GAAG,QAAQ,yCAAyC,OAAO,CAAC,GAAG,GAAG,CAAC,CAAA;QACpG,CAAC;QAED,OAAO,MAAM,CAAA;IACf,CAAC,CAAA;AACH,CAAC"}

package/dist/cli/preview-page/client.js

@@ -0,0 +1,89 @@
+/**
+ * Fetches the spec/config and assigns them onto the `<kong-spec-renderer>`
+ * element, then registers (and upgrades) the custom element - deliberately
+ * in that order.
+ *
+ * Vue's `defineCustomElement` reads any already-present own properties on the
+ * element as its *initial* prop values at construction/upgrade time; props
+ * assigned afterwards (e.g. `currentPath`) reach the underlying component
+ * reactively for props it actively watches, but some - like `currentPath` -
+ * are only snapshotted into local refs once at setup and never re-synced.
+ * Registering the element only after every property (spec, config, including
+ * `currentPath`) is already set ensures the initial render picks up the
+ * right values, rather than defaults, the first and only time it matters.
+ */
+async function loadAndApply() {
+    const el = document.getElementById('preview');
+    if (!el) {
+        return;
+    }
+    const [specResponse, configResponse] = await Promise.all([fetch('/spec'), fetch('/config')]);
+    const spec = await specResponse.text();
+    const config = await configResponse.json();
+    el.spec = spec;
+    for (const [key, value] of Object.entries(config)) {
+        el[key] = value;
+    }
+    const requestedPath = typeof config.currentPath === 'string' ? config.currentPath : undefined;
+    // Matches how the component's own click-driven navigation builds the URL
+    // for each `navigationType` (there's no `basePath` here - the CLI's preview
+    // page is always served from `/`).
+    const toAddressBarUrl = (path) => config.navigationType === 'hash' ? `#${path}` : path;
+    if (requestedPath && requestedPath !== '/') {
+        // The component only pushes address-bar updates from its own click-driven
+        // navigation, not for an initial `currentPath` prop supplied externally -
+        // reflect the requested deep link ourselves so the URL matches what's
+        // actually rendered. Optimistic: rolled back below if the path turns out
+        // to be invalid.
+        history.replaceState({}, '', toAddressBarUrl(requestedPath));
+        // `--path` has to match this library's internal node URI scheme
+        // (`/operations/{operationId}`, `/schemas/{SchemaName}`), not the raw OAS
+        // path - there's no other feedback if it doesn't match anything, so warn
+        // loudly rather than silently rendering a blank document pane.
+        el.addEventListener('path-not-found', ((event) => {
+            console.warn(`[kong-spec-renderer] --path "${String(event.detail?.[0] ?? requestedPath)}" doesn't match any operation or schema in this spec. ` +
+                'Expected format: "/operations/{operationId}" or "/schemas/{SchemaName}" - check the spec\'s operationId/schema names, not its raw OAS paths. ' +
+                'Falling back to the overview.');
+            history.replaceState({}, '', '/');
+            // `currentPath` is only read once, at the component's initial setup -
+            // an invalid path can't be corrected by reassigning the property on
+            // the existing element, so replace it with a fresh one instead.
+            const fallback = document.createElement(el.tagName);
+            fallback.id = el.id;
+            fallback.spec = spec;
+            for (const [key, value] of Object.entries(config)) {
+                fallback[key] = key === 'currentPath' ? '/' : value;
+            }
+            el.replaceWith(fallback);
+        }));
+    }
+    // A variable (rather than a string literal) module specifier so TypeScript
+    // treats this as an untyped dynamic import instead of trying to resolve
+    // `/assets/...` at typecheck time - it only exists once the CLI serves it.
+    const bundlePath = '/assets/kong-spec-renderer.web-component.es.js';
+    const { registerKongSpecRenderer } = await import(bundlePath);
+    registerKongSpecRenderer();
+}
+void loadAndApply();
+const RECONNECT_DELAY_MS = 1000;
+/**
+ * Connects the reload-signal WebSocket, reconnecting after a delay if the
+ * connection drops (e.g. the CLI process restarted, or the machine slept)
+ * so live-reload keeps working without requiring a manual page refresh.
+ */
+function connect() {
+    const protocol = location.protocol === 'https:' ? 'wss' : 'ws';
+    const socket = new WebSocket(`${protocol}://${location.host}`);
+    socket.addEventListener('message', (event) => {
+        const message = JSON.parse(event.data);
+        if (message.type === 'reload') {
+            location.reload();
+        }
+    });
+    socket.addEventListener('close', () => {
+        setTimeout(connect, RECONNECT_DELAY_MS);
+    });
+}
+connect();
+export {};
+//# sourceMappingURL=client.js.map

package/dist/cli/preview-page/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../cli/preview-page/client.ts"],"names":[],"mappings":"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"}

package/dist/cli/preview-page/index.html

@@ -0,0 +1,34 @@
+<!doctype html>
+<html lang="en">
+
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Spec Preview - @kong/spec-renderer</title>
+    <link rel="stylesheet" href="/assets/spec-renderer.css" />
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link
+      href="https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&family=JetBrains+Mono:ital,wght@0,100..800;1,100..800&display=swap"
+      rel="stylesheet">
+    <style>
+      html,
+      body {
+        margin: 0;
+        height: 100%;
+        font-family: 'Inter', Roboto, Helvetica, sans-serif;
+      }
+
+      kong-spec-renderer {
+        display: block;
+        height: 100dvh;
+      }
+    </style>
+  </head>
+
+  <body>
+    <kong-spec-renderer id="preview"></kong-spec-renderer>
+    <script type="module" src="/client.js"></script>
+  </body>
+
+</html>

package/dist/cli/program.js

@@ -0,0 +1,105 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Command, Option } from 'commander';
+import { runPreviewCommand } from './commands/preview.js';
+import { error as printError } from './ui.js';
+import { parseIntFlag } from './parse-int-flag.js';
+/**
+ * Walks up from `startDir` to find the nearest `package.json` belonging to
+ * `@kong/spec-renderer` itself, rather than assuming a fixed directory depth
+ * - this module runs both compiled (`dist/cli/program.js`, two levels below
+ * the repo root) and directly from source (`cli/program.ts`, one level
+ * below), so a hardcoded `join(dir, '..', '..')` is only correct for one of
+ * those and silently resolves to the wrong file (or throws ENOENT) for the
+ * other. Candidates are validated (not just checked for existence) since a
+ * marker `package.json` with no `version` field (e.g. a `{"type": "module"}`
+ * dual-package hazard file, a pattern some build tools drop into `dist/`)
+ * could otherwise be accepted, breaking `program.version(undefined, ...)`.
+ */
+function findPackageVersion(startDir) {
+    let dir = startDir;
+    for (;;) {
+        const candidate = join(dir, 'package.json');
+        if (existsSync(candidate)) {
+            const parsed = JSON.parse(readFileSync(candidate, 'utf-8'));
+            if (typeof parsed === 'object' && parsed !== null
+                && 'name' in parsed && parsed.name === '@kong/spec-renderer'
+                && 'version' in parsed && typeof parsed.version === 'string') {
+                return parsed.version;
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            throw new Error(`Could not find @kong/spec-renderer's package.json walking up from ${startDir}`);
+        }
+        dir = parent;
+    }
+}
+const DOCS_URL = 'https://github.com/Kong/spec-renderer/blob/main/cli/README.md';
+/**
+ * Builds the commander program without parsing `process.argv`, so it can be
+ * imported and introspected (e.g. by the kongctl extension manifest
+ * generator) without invoking the CLI.
+ */
+export function createProgram() {
+    // The CLI isn't versioned independently - it always reports the package's
+    // own version, which is what actually gets published/installed.
+    const currentDir = dirname(fileURLToPath(import.meta.url));
+    const version = findPackageVersion(currentDir);
+    const program = new Command();
+    // Flags are registered in the order that groups them logically for readers
+    // of this file, not alphabetically - sort them for `--help` output instead so
+    // they're easy to scan regardless of definition order. `showGlobalOptions`
+    // surfaces `-V/--version` (registered on the top-level program, not the
+    // `preview` subcommand) in `preview --help` too - otherwise it's easy to
+    // assume it doesn't exist, since usage is always through the subcommand.
+    program.configureHelp({ sortOptions: true, showGlobalOptions: true });
+    program
+        .name('kong-spec-renderer')
+        .description('Preview an OpenAPI/AsyncAPI spec (local file or remote URL) using @kong/spec-renderer')
+        .version(version, '-V, --version', 'output the current version')
+        .addHelpText('after', `\nDocs: ${DOCS_URL}`);
+    program
+        .command('preview')
+        .description('Preview a local spec file or remote spec URL using the spec renderer.')
+        .argument('<spec>', 'path to a local spec file, or a URL to a remote spec')
+        .option('--port <port>', 'port to run the preview server on', parseIntFlag('--port', { max: 65535 }))
+        .option('--no-open', 'do not automatically open the preview in a browser')
+        .option('--hide-internal', 'hide internal operations from the table of contents')
+        .option('--hide-deprecated', 'hide deprecated operations from the table of contents')
+        .option('--hide-schemas', 'hide schemas (models) from the table of contents')
+        .option('--hide-try-it', 'hide the "Try it" UI')
+        .option('--hide-insomnia-try-it', 'hide the "Insomnia" option within the "Try it" UI')
+        .option('--with-credentials', 'send credentials when resolving external (http) $refs within the spec')
+        .option('--max-expanded-depth <depth>', 'maximum depth to expand nested schema properties by default', parseIntFlag('--max-expanded-depth'))
+        .option('--verbose', 'log spec parsing stages to the browser console, for troubleshooting (alias: --trace-parsing)')
+        .addOption(new Option('--trace-parsing', 'alias for --verbose').hideHelp())
+        .option('--no-content-scrolling', 'navigate between operations/schemas one at a time instead of scrolling through them continuously (has no effect above 1200 combined operations/schemas, where this is always enforced)')
+        .option('--no-custom-server-url', 'do not let the preview add a custom server URL to the servers list')
+        .option('--show-navigation-buttons', 'show prev/next buttons at the bottom of each operation - useful with --no-content-scrolling')
+        .option('--hide-download-button', 'hide the spec download button')
+        .option('--enable-operation-links', 'show a permalink icon on each operation that copies its URL to the clipboard')
+        .option('--hide-powered-by', 'hide the "Powered by" branding in the table of contents')
+        .option('--path <path>', 'open the preview at a specific operation/schema, e.g. /operations/getPets or /schemas/Pet (not the raw OAS path)')
+        .addOption(new Option('--navigation-type <type>', 'how the current operation/schema is tracked in the URL - "path" breaks a browser refresh at a deep link, since the server has no route fallback for it')
+        .choices(['path', 'hash'])
+        .default('hash'))
+        .addHelpText('after', `\nDocs: ${DOCS_URL}`)
+        .action(async (spec, raw) => {
+        const flags = {
+            ...raw,
+            allowContentScrolling: raw.contentScrolling,
+            currentPath: raw.path,
+        };
+        try {
+            await runPreviewCommand(spec, flags);
+        }
+        catch (error) {
+            printError(error instanceof Error ? error.message : String(error));
+            process.exitCode = 1;
+        }
+    });
+    return program;
+}
+//# sourceMappingURL=program.js.map

package/dist/cli/program.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.js","sourceRoot":"","sources":["../../cli/program.ts"],"names":[],"mappings":"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"}

package/dist/cli/resolve-render-options.js

@@ -0,0 +1,41 @@
+/**
+ * Maps parsed `preview` CLI flags to the `SpecRendererProps` subset the preview
+ * page renders with.
+ *
+ * `controlAddressBar` is always hardcoded true - the CLI, not the user, owns
+ * the single-page preview environment that prop governs. `navigationType`
+ * defaults to `'hash'` rather than the component's own `'path'` default -
+ * with `'path'`, the CLI's server would need to fall back to the preview page
+ * for arbitrary unmatched routes to support a browser refresh at a deep link,
+ * which it doesn't do, so refreshing 404s; `'hash'` keeps the path client-side
+ * only, so a refresh always hits `/`. `showPoweredBy` defaults to `true` here
+ * even though the component prop itself defaults to `false` - the CLI wants
+ * branding visible unless a user opts out with `--hide-powered-by`.
+ * `hideNavigationButtons` defaults to `true` (hidden), matching the
+ * component's own default, and only flips to `false` when
+ * `--show-navigation-buttons` is explicitly passed - mainly useful alongside
+ * `--no-content-scrolling`, where the prev/next buttons are otherwise the
+ * only in-page way to move between operations.
+ */
+export function resolveRenderOptions(flags) {
+    return {
+        hideInternal: flags.hideInternal ?? false,
+        hideDeprecated: flags.hideDeprecated ?? false,
+        hideSchemas: flags.hideSchemas ?? false,
+        hideTryIt: flags.hideTryIt ?? false,
+        hideInsomniaTryIt: flags.hideInsomniaTryIt ?? false,
+        ...(flags.maxExpandedDepth === undefined ? {} : { maxExpandedDepth: flags.maxExpandedDepth }),
+        traceParsing: (flags.verbose ?? false) || (flags.traceParsing ?? false),
+        withCredentials: flags.withCredentials ?? false,
+        allowContentScrolling: flags.allowContentScrolling ?? true,
+        allowCustomServerUrl: flags.customServerUrl ?? true,
+        hideNavigationButtons: !(flags.showNavigationButtons ?? false),
+        hideDownloadButton: flags.hideDownloadButton ?? false,
+        enableOperationLinks: flags.enableOperationLinks ?? false,
+        showPoweredBy: !flags.hidePoweredBy,
+        navigationType: flags.navigationType ?? 'hash',
+        controlAddressBar: true,
+        ...(flags.currentPath === undefined ? {} : { currentPath: flags.currentPath }),
+    };
+}
+//# sourceMappingURL=resolve-render-options.js.map

package/dist/cli/resolve-render-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-render-options.js","sourceRoot":"","sources":["../../cli/resolve-render-options.ts"],"names":[],"mappings":"AA2DA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAsB;IACzD,OAAO;QACL,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,KAAK;QACzC,cAAc,EAAE,KAAK,CAAC,cAAc,IAAI,KAAK;QAC7C,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,KAAK;QACvC,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,KAAK;QACnC,iBAAiB,EAAE,KAAK,CAAC,iBAAiB,IAAI,KAAK;QACnD,GAAG,CAAC,KAAK,CAAC,gBAAgB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,KAAK,CAAC,gBAAgB,EAAE,CAAC;QAC7F,YAAY,EAAE,CAAC,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,IAAI,KAAK,CAAC;QACvE,eAAe,EAAE,KAAK,CAAC,eAAe,IAAI,KAAK;QAC/C,qBAAqB,EAAE,KAAK,CAAC,qBAAqB,IAAI,IAAI;QAC1D,oBAAoB,EAAE,KAAK,CAAC,eAAe,IAAI,IAAI;QACnD,qBAAqB,EAAE,CAAC,CAAC,KAAK,CAAC,qBAAqB,IAAI,KAAK,CAAC;QAC9D,kBAAkB,EAAE,KAAK,CAAC,kBAAkB,IAAI,KAAK;QACrD,oBAAoB,EAAE,KAAK,CAAC,oBAAoB,IAAI,KAAK;QACzD,aAAa,EAAE,CAAC,KAAK,CAAC,aAAa;QACnC,cAAc,EAAE,KAAK,CAAC,cAAc,IAAI,MAAM;QAC9C,iBAAiB,EAAE,IAAI;QACvB,GAAG,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC;KAC/E,CAAA;AACH,CAAC"}

package/dist/cli/resolve-spec-source.js

@@ -0,0 +1,20 @@
+/**
+ * Classifies a CLI spec argument as a local file path or a remote URL.
+ *
+ * Only `http:`/`https:` URLs are treated as remote sources; anything else
+ * (including a value that isn't a valid URL at all) is treated as a local
+ * file path.
+ */
+export function resolveSpecSource(arg) {
+    try {
+        const url = new URL(arg);
+        if (url.protocol === 'http:' || url.protocol === 'https:') {
+            return { kind: 'url', value: arg };
+        }
+    }
+    catch {
+        // Not a parseable URL - fall through to treating it as a file path.
+    }
+    return { kind: 'file', value: arg };
+}
+//# sourceMappingURL=resolve-spec-source.js.map

package/dist/cli/resolve-spec-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-spec-source.js","sourceRoot":"","sources":["../../cli/resolve-spec-source.ts"],"names":[],"mappings":"AAMA;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAA;QACxB,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC1D,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAA;QACpC,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,oEAAoE;IACtE,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,CAAA;AACrC,CAAC"}

package/dist/cli/server.js

@@ -0,0 +1,137 @@
+import { createServer as createHttpServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { dirname, extname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { WebSocketServer } from 'ws';
+const currentDir = dirname(fileURLToPath(import.meta.url));
+// The preview server ships inside the package's own dist/ output (dist/cli/server.js),
+// so the already-built web-component bundle sits one directory up.
+const DEFAULT_DIST_DIR = dirname(currentDir);
+const DEFAULT_PREVIEW_PAGE_DIR = join(currentDir, 'preview-page');
+const CONTENT_TYPES = {
+    '.js': 'text/javascript',
+    '.mjs': 'text/javascript',
+    '.css': 'text/css',
+    '.map': 'application/json',
+    '.wasm': 'application/wasm',
+    '.json': 'application/json',
+};
+/**
+ * Resolves an `/assets/*` request path against `distDir`, returning
+ * `undefined` if the path would escape it.
+ *
+ * The web-component bundle is code-split (syntax-highlighting language
+ * grammars/themes, etc.), so the browser fetches an open-ended set of
+ * relatively-imported chunk files from `dist/` at runtime - not just the
+ * entry bundle and its stylesheet.
+ */
+function resolveDistAsset(distDir, requestPath) {
+    const candidate = join(distDir, requestPath);
+    if (relative(distDir, candidate).startsWith('..')) {
+        return undefined;
+    }
+    return candidate;
+}
+/**
+ * Starts the CLI's local preview server: a minimal static file server for the
+ * preview page and the package's own built web-component assets, plus a
+ * WebSocket channel used to tell the page to reload when the watched spec
+ * file changes.
+ */
+export async function startPreviewServer(options) {
+    const distDir = options.distDir ?? DEFAULT_DIST_DIR;
+    const previewPageDir = options.previewPageDir ?? DEFAULT_PREVIEW_PAGE_DIR;
+    const server = createHttpServer((req, res) => {
+        void handleRequest(req.url, options, distDir, previewPageDir).then(({ status, body, contentType }) => {
+            res.writeHead(status, contentType ? { 'content-type': contentType } : undefined);
+            res.end(body);
+        }).catch((error) => {
+            res.writeHead(500, { 'content-type': 'text/plain' });
+            res.end(`Internal server error: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    });
+    const wss = new WebSocketServer({ server });
+    // Without an 'error' listener, a failed listen() (e.g. EADDRINUSE from a
+    // TOCTOU race against find-open-port.ts's earlier probe) throws and crashes
+    // the process instead of rejecting cleanly through the CLI's own error path.
+    // `ws`'s WebSocketServer re-emits the underlying http.Server's 'error' event
+    // on itself, so the listener has to guard `wss`, not just `server` - an
+    // unhandled 'error' on the WebSocketServer instance crashes just the same.
+    await new Promise((resolve, reject) => {
+        const onListenError = (error) => reject(error);
+        server.once('error', onListenError);
+        wss.once('error', onListenError);
+        server.listen(options.port, () => {
+            server.off('error', onListenError);
+            wss.off('error', onListenError);
+            resolve();
+        });
+    });
+    // A runtime error after startup (e.g. a transient socket error) should be
+    // logged, not left to crash the process as an unhandled 'error' event.
+    server.on('error', (error) => {
+        console.error(`Preview server error: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    wss.on('error', (error) => {
+        console.error(`Preview server error: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    const address = server.address();
+    // `address()` returns a string for a Unix socket/pipe, never the case here
+    // since we always listen on a numeric port - but guard rather than assume.
+    const port = typeof address === 'object' && address !== null ? address.port : options.port;
+    return {
+        server,
+        port,
+        broadcastReload: () => {
+            const message = JSON.stringify({ type: 'reload' });
+            for (const client of wss.clients) {
+                if (client.readyState === client.OPEN) {
+                    client.send(message);
+                }
+            }
+        },
+        close: () => new Promise((resolve, reject) => {
+            // wss.close()/server.close() only invoke their callback once every
+            // connection has ended on its own - with a preview tab left open,
+            // that never happens. Force-terminate everything so shutdown is prompt
+            // regardless of what's still connected.
+            for (const client of wss.clients) {
+                client.terminate();
+            }
+            server.closeAllConnections();
+            wss.close(() => {
+                server.close((error) => error ? reject(error) : resolve());
+            });
+        }),
+    };
+}
+async function handleRequest(url, options, distDir, previewPageDir) {
+    if (url === '/spec') {
+        return { status: 200, body: options.getSpecText(), contentType: 'text/plain; charset=utf-8' };
+    }
+    if (url === '/config') {
+        return { status: 200, body: JSON.stringify(options.config), contentType: 'application/json' };
+    }
+    if (url === '/' || url === '/index.html') {
+        const body = await readFile(join(previewPageDir, 'index.html'), 'utf-8');
+        return { status: 200, body, contentType: 'text/html; charset=utf-8' };
+    }
+    if (url === '/client.js') {
+        const body = await readFile(join(previewPageDir, 'client.js'));
+        return { status: 200, body, contentType: 'text/javascript' };
+    }
+    if (url?.startsWith('/assets/')) {
+        const assetPath = resolveDistAsset(distDir, url.slice('/assets/'.length));
+        if (assetPath) {
+            try {
+                const body = await readFile(assetPath);
+                return { status: 200, body, contentType: CONTENT_TYPES[extname(assetPath)] ?? 'application/octet-stream' };
+            }
+            catch {
+                // Fall through to 404 below - e.g. the file doesn't exist.
+            }
+        }
+    }
+    return { status: 404, body: 'Not found', contentType: 'text/plain' };
+}
+//# sourceMappingURL=server.js.map

package/dist/cli/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../cli/server.ts"],"names":[],"mappings":"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"}

package/dist/cli/spec-source.js

@@ -0,0 +1,23 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { resolveSpecSource } from './resolve-spec-source.js';
+/**
+ * Reads a spec's text from either a local file or a remote URL.
+ *
+ * Local files are watchable for live-reload; remote URLs are fetched once
+ * and are not watched (there is no local file to observe for changes).
+ */
+export async function loadSpecSource(arg) {
+    const source = resolveSpecSource(arg);
+    if (source.kind === 'file') {
+        const watchPath = resolve(source.value);
+        const text = await readFile(watchPath, 'utf-8');
+        return { text, watch: true, watchPath };
+    }
+    const response = await fetch(source.value);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch spec from ${source.value}: ${response.status} ${response.statusText}`);
+    }
+    return { text: await response.text(), watch: false };
+}
+//# sourceMappingURL=spec-source.js.map

package/dist/cli/spec-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-source.js","sourceRoot":"","sources":["../../cli/spec-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAU5D;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,GAAW;IAC9C,MAAM,MAAM,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAA;IAErC,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC3B,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACvC,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;QAE/C,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,CAAA;IACzC,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAE1C,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,6BAA6B,MAAM,CAAC,KAAK,KAAK,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAA;IACzG,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAA;AACtD,CAAC"}

package/dist/cli/ui.js

@@ -0,0 +1,107 @@
+import { createColors } from 'picocolors';
+// picocolors' default export auto-detects color support and disables it for
+// a non-TTY stdout (e.g. output piped to a file or another process) - the
+// preview banner/log lines are always meant to be colored when read in a
+// terminal, so force it on regardless of how stdout is connected. `NO_COLOR`
+// is still honored, since it's the standard explicit user opt-out. Exported
+// so other CLI modules (e.g. `commands/preview.ts`) share the same forced
+// instance rather than importing picocolors' auto-detecting default directly.
+export const pc = createColors(!process.env.NO_COLOR);
+const BOX_TITLE = 'Kong Spec Renderer - Preview';
+// Caps the box at a width that fits comfortably in a typical terminal - a
+// long spec path/URL wraps onto continuation lines instead of pushing the
+// box wider than the terminal, which breaks the border rendering.
+const MAX_CONTENT_WIDTH = 96;
+// eslint-disable-next-line no-control-regex -- matches ANSI SGR escape codes and OSC 8 hyperlink wrappers, which are control characters by definition
+const ANSI_PATTERN = /\x1B\[[0-9;]*m|\x1B\]8;[^\x07]*\x07/g;
+/** Visible length of a string, ignoring ANSI color escape codes and OSC 8 hyperlink wrappers. */
+export function visibleLength(text) {
+    return text.replace(ANSI_PATTERN, '').length;
+}
+/**
+ * Wraps `text` in an OSC 8 terminal hyperlink pointing at `url`, so it's
+ * clickable in terminals that support it (iTerm2, Kitty, Windows Terminal,
+ * VS Code's integrated terminal, etc.) - falls back to plain, unlinked text
+ * everywhere else with no visible difference.
+ */
+export function hyperlink(text, url) {
+    return `\x1B]8;;${url}\x07${text}\x1B]8;;\x07`;
+}
+/** Strips ANSI color escape codes from a string. */
+function stripAnsi(text) {
+    return text.replace(ANSI_PATTERN, '');
+}
+/** Hard-wraps plain text into chunks of at most `width` characters. */
+function wrapPlain(text, width) {
+    if (text.length <= width) {
+        return [text];
+    }
+    const chunks = [];
+    for (let i = 0; i < text.length; i += width) {
+        chunks.push(text.slice(i, i + width));
+    }
+    return chunks;
+}
+/**
+ * Builds the lines of a bordered summary box (spec source, URL, live-reload
+ * status), aligned by visible length.
+ *
+ * `value` may contain ANSI color codes - widths are computed from visible
+ * length so colored values don't throw off the box's alignment. A value
+ * longer than fits within `maxContentWidth` wraps onto continuation lines;
+ * since wrapping a colored value risks splitting mid-escape-sequence, an
+ * over-long value wraps as plain text instead (long values are spec paths/
+ * URLs, which aren't colored today anyway). Split out from
+ * `printPreviewBanner` so the alignment math is unit-testable without
+ * capturing console output or mocking terminal width.
+ */
+export function buildBannerLines(rows, maxContentWidth = MAX_CONTENT_WIDTH) {
+    const labelWidth = Math.max(...rows.map((row) => row.label.length));
+    const valueWidth = Math.max(20, maxContentWidth - labelWidth - 2);
+    const wrappedRows = rows.map((row) => ({
+        label: row.label,
+        valueLines: visibleLength(row.value) <= valueWidth
+            ? [row.value]
+            : wrapPlain(stripAnsi(row.value), valueWidth),
+    }));
+    const contentWidth = Math.max(BOX_TITLE.length, ...wrappedRows.flatMap((row) => row.valueLines.map((line) => labelWidth + 2 + visibleLength(line))));
+    const horizontal = '─'.repeat(contentWidth + 2);
+    const lines = [
+        pc.cyan(`┌${horizontal}┐`),
+        `${pc.cyan('│')} ${pc.bold(BOX_TITLE.padEnd(contentWidth))} ${pc.cyan('│')}`,
+        pc.cyan(`├${horizontal}┤`),
+    ];
+    for (const row of wrappedRows) {
+        row.valueLines.forEach((line, index) => {
+            const label = index === 0 ? row.label.padEnd(labelWidth) : ' '.repeat(labelWidth);
+            const padding = ' '.repeat(contentWidth - labelWidth - 2 - visibleLength(line));
+            lines.push(`${pc.cyan('│')} ${pc.dim(label)}  ${line}${padding} ${pc.cyan('│')}`);
+        });
+    }
+    lines.push(pc.cyan(`└${horizontal}┘`));
+    return lines;
+}
+/**
+ * The box's content width, capped to the actual terminal width when known
+ * (interactive terminals report `process.stdout.columns`; piped/non-TTY
+ * output does not, so `MAX_CONTENT_WIDTH` is used as a sane default).
+ */
+function terminalAwareMaxWidth() {
+    const terminalWidth = process.stdout.columns;
+    if (!terminalWidth) {
+        return MAX_CONTENT_WIDTH;
+    }
+    // Leave room for the box's own border/padding characters (`│ ` + ` │`).
+    return Math.max(20, Math.min(MAX_CONTENT_WIDTH, terminalWidth - 4));
+}
+/** Prints a bordered summary box for the running preview server. */
+export function printPreviewBanner(rows) {
+    for (const line of buildBannerLines(rows, terminalAwareMaxWidth())) {
+        console.log(line);
+    }
+}
+export const success = (message) => console.log(`${pc.green('✔')} ${message}`);
+export const info = (message) => console.log(`${pc.cyan('i')} ${message}`);
+export const warn = (message) => console.log(`${pc.yellow('⚠')} ${pc.yellow(message)}`);
+export const error = (message) => console.error(`${pc.red('✖')} ${pc.red(message)}`);
+//# sourceMappingURL=ui.js.map

package/dist/cli/ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.js","sourceRoot":"","sources":["../../cli/ui.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@kong/spec-renderer",
-  "version": "1.111.3",
+  "version": "1.111.4-pr.942.12e41ef.0",
   "description": "Kong's open-source spec renderer",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/kong-spec-renderer.cjs",
   "module": "./dist/kong-spec-renderer.es.js",
+  "bin": {
+    "kong-spec-renderer": "./dist/cli/index.js"
+  },
   "files": [
     "dist"
   ],
@@ -29,26 +32,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "dev": "cross-env USE_SANDBOX=true vite",
-    "build": "pnpm run typecheck && pnpm run build:package && pnpm run build:webcomponent && pnpm run build:types && pnpm run build:aliases",
-    "build:package": "vite build -m production",
-    "build:webcomponent": "cross-env VITE_AS_WEB_COMPONENT='true' vite build -m production",
-    "build:types": "vue-tsc -p './tsconfig.build.json' --emitDeclarationOnly",
-    "build:aliases": "tsc-alias -p './tsconfig.build.json'",
-    "build:analyzer": "BUILD_VISUALIZER='true' vite build -m production",
-    "build:sandbox": "cross-env USE_SANDBOX=true vite build -m production",
-    "preview": "pnpm run build:sandbox && cross-env USE_SANDBOX=true vite preview",
-    "typecheck": "vue-tsc -p './tsconfig.build.json' --noEmit",
-    "stylelint": "stylelint --allow-empty-input './src/**/*.{css,scss,vue}'",
-    "stylelint:fix": "stylelint --allow-empty-input './src/**/*.{css,scss,sass,vue}' --fix",
-    "lint": "eslint",
-    "lint:fix": "eslint --fix",
-    "test": "cross-env FORCE_COLOR=1 vitest run",
-    "test:open": "cross-env FORCE_COLOR=1 vitest --ui",
-    "semantic-release": "semantic-release",
-    "commit": "cz"
-  },
   "peerDependencies": {
     "vue": ">= 3.3.13 < 4"
   },
@@ -65,13 +48,18 @@
     "@stoplight/yaml": "^4.3.0",
     "@vueuse/core": "^14.3.0",
     "allof-merge": "^0.6.8",
+    "chokidar": "^5.0.0",
+    "commander": "^15.0.0",
     "flatted": "^3.4.2",
     "form-urlencoded": "^6.1.7",
     "httpsnippet": "^3.0.10",
     "lodash-es": "^4.18.1",
     "markdown-it": "^14.3.0",
+    "open": "^11.0.0",
+    "picocolors": "^1.1.1",
     "sanitize-html": "^2.17.6",
-    "shiki": "^3.23.0"
+    "shiki": "^3.23.0",
+    "ws": "^8.21.1"
   },
   "resolutions": {
     "openapi3-ts": "4.6.0"
@@ -86,6 +74,7 @@
     "@kong/eslint-config-kong-ui": "1.7.1",
     "@kong/stylelint-plugin-design-tokens": "1.0.1",
     "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/exec": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@stylistic/stylelint-plugin": "^5.2.1",
     "@types/jsdom": "^28.0.3",
@@ -93,6 +82,7 @@
     "@types/markdown-it": "^14.1.2",
     "@types/node": "^24.13.3",
     "@types/sanitize-html": "^2.16.1",
+    "@types/ws": "^8.18.1",
     "@vitejs/plugin-vue": "^6.0.8",
     "@vitest/ui": "^3.2.7",
     "@vue/test-utils": "^2.4.11",
@@ -128,62 +118,8 @@
     "vitest": "4.1.10",
     "vue": "^3.5.39",
     "vue-router": "^4.6.4",
-    "vue-tsc": "^3.3.7"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "@evilmartians/lefthook",
-      "@parcel/watcher",
-      "esbuild",
-      "vue-demi"
-    ],
-    "overrides": {
-      "openapi3-ts": "4.6.0",
-      "jsonpath-plus@<10.3.0": ">=10.4.0",
-      "elliptic@<=6.6.0": ">=6.6.1",
-      "@babel/helpers@<8.0.0": ">=8.0.0",
-      "cross-spawn@>=7.0.0 <7.0.5": ">=7.0.6",
-      "brace-expansion@<=5.0.7": ">=5.0.9",
-      "pbkdf2@<=3.1.2": ">=3.1.6",
-      "sha.js@<=2.4.11": ">=2.4.12",
-      "cipher-base@<=1.0.4": ">=1.0.7",
-      "glob@>=10.2.0 <10.5.0": ">=13.0.6",
-      "diff@>=4.0.0 <4.0.4": ">=4.0.4",
-      "@isaacs/brace-expansion@<=5.0.0": ">=5.0.1",
-      "mdast-util-to-hast@>=13.0.0 <13.2.1": ">=13.2.1",
-      "qs@>=6.7.0 <=6.15.1": ">=6.15.3",
-      "bn.js@>=5.0.0 <5.2.3": ">=5.2.5",
-      "bn.js@<4.12.3": ">=5.2.5",
-      "rollup@>=4.0.0 <4.59.0": ">=4.62.2",
-      "minimatch@<10.2.3": ">=10.2.5",
-      "ajv@<6.14.0": "^6.15.0",
-      "immutable@>=5.0.0 <5.1.8": ">=5.1.9",
-      "flatted@<=3.4.1": ">=3.4.2",
-      "undici@<6.24.0": ">=8.5.0",
-      "undici@>=7.0.0 <7.29.0": "7.29.0",
-      "undici@>=8.0.0 <8.9.0": ">=8.9.0",
-      "handlebars@>=4.0.0 <4.7.9": ">=4.7.9",
-      "picomatch@<2.3.2": ">=4.0.5",
-      "lodash-es@<=4.17.23": ">=4.18.0",
-      "lodash@<=4.17.23": ">=4.18.0",
-      "yaml@>=2.0.0 <2.8.3": ">=2.9.0",
-      "fast-uri@<=3.1.1": ">=3.1.4",
-      "fast-uri@>=4.0.0 <4.1.2": ">=4.1.2",
-      "uuid@<11.1.1": ">=11.1.1",
-      "vitest@<3.2.6": ">=3.2.7",
-      "js-cookie@<=3.0.5": ">=3.0.8",
-      "tmp@<0.2.6": ">=0.2.7",
-      "esbuild@>=0.27.3 <0.28.1": ">=0.28.1",
-      "sanitize-html@=2.17.3": ">=2.17.6",
-      "ws@>=8.0.0 <8.21.0": ">=8.21.1",
-      "form-data@>=4.0.0 <4.0.6": ">=4.0.6",
-      "vite@>=7.0.0 <=7.3.4": ">=7.3.6",
-      "@babel/core@<8.0.0": ">=8.0.1",
-      "markdown-it@<=14.1.1": ">=14.2.0",
-      "linkify-it@<=5.0.0": ">=5.0.2",
-      "js-yaml@>=4.0.0 <=4.1.1": ">=4.3.0",
-      "js-yaml@>=5.0.0 <=5.2.1": ">=5.2.2"
-    }
+    "vue-tsc": "^3.3.7",
+    "yaml": "^2.9.0"
   },
   "repository": {
     "type": "git",
@@ -231,7 +167,23 @@
           ]
         }
       ],
-      "@semantic-release/github"
+      [
+        "@semantic-release/exec",
+        {
+          "prepareCmd": "scripts/build-kongctl-extension.sh ${nextRelease.version}"
+        }
+      ],
+      [
+        "@semantic-release/github",
+        {
+          "assets": [
+            {
+              "path": "dist/kongctl-ext-spec-preview-universal.tar.gz",
+              "label": "kongctl-ext-spec-preview (universal, requires Node.js)"
+            }
+          ]
+        }
+      ]
     ]
   },
   "engines": {
@@ -251,5 +203,28 @@
       "jiraAppend": "]"
     }
   },
-  "packageManager": "pnpm@10.33.4"
-}
+  "scripts": {
+    "dev": "cross-env USE_SANDBOX=true vite",
+    "build": "pnpm run typecheck && pnpm run build:package && pnpm run build:webcomponent && pnpm run build:types && pnpm run build:aliases && pnpm run build:cli",
+    "build:package": "vite build -m production",
+    "build:webcomponent": "cross-env VITE_AS_WEB_COMPONENT='true' vite build -m production",
+    "build:types": "vue-tsc -p './tsconfig.build.json' --emitDeclarationOnly",
+    "build:aliases": "tsc-alias -p './tsconfig.build.json'",
+    "build:cli": "tsc -p './tsconfig.cli.build.json' && node ./scripts/build-cli-assets.js && node ./scripts/generate-kongctl-manifest.mjs",
+    "generate:kongctl-manifest": "pnpm run build:cli",
+    "build:analyzer": "BUILD_VISUALIZER='true' vite build -m production",
+    "build:sandbox": "cross-env USE_SANDBOX=true vite build -m production",
+    "preview": "pnpm run build:sandbox && cross-env USE_SANDBOX=true vite preview",
+    "typecheck": "vue-tsc -p './tsconfig.build.json' --noEmit && pnpm run typecheck:cli && pnpm run typecheck:scripts",
+    "typecheck:cli": "tsc -p './tsconfig.cli.json' --noEmit",
+    "typecheck:scripts": "tsc -p './tsconfig.scripts.json' --noEmit",
+    "stylelint": "stylelint --allow-empty-input './src/**/*.{css,scss,vue}'",
+    "stylelint:fix": "stylelint --allow-empty-input './src/**/*.{css,scss,sass,vue}' --fix",
+    "lint": "eslint",
+    "lint:fix": "eslint --fix",
+    "test": "cross-env FORCE_COLOR=1 vitest run",
+    "test:open": "cross-env FORCE_COLOR=1 vitest --ui",
+    "semantic-release": "semantic-release",
+    "commit": "cz"
+  }
+}