oaspect 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 oaspect contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,19 @@
+# oaspect
+
+Interactive API reference for OpenAPI 3.x and Swagger 2.0 documents (JSON or YAML).
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/oaspect" data-spec-url="/openapi.yaml"></script>
+```
+
+```bash
+npx oaspect build openapi.yaml -o docs.html
+npx oaspect serve openapi.yaml
+```
+
+```js
+import { createProxyHandler } from "oaspect/server";
+```
+
+See the [main README](https://github.com/oaspect/oaspect) for the web component,
+React usage, configuration and translations. MIT licensed.

package/bin/oaspect.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+// oaspect CLI: build a self-contained HTML reference or serve a live preview.
+import { readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { renderHtml } from "../src/html.js";
+import { serve } from "../src/serve.js";
+import { isUrl, loadSpec } from "../src/spec.js";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const bundlePath = resolve(root, "dist/oaspect.js");
+
+const HELP = `oaspect — interactive API reference for OpenAPI documents
+
+Usage:
+  oaspect build <spec> [-o docs.html] [options]   Write a self-contained HTML file
+  oaspect serve <spec> [--port 8080] [options]    Live preview with a "Try" proxy
+
+<spec> is a JSON or YAML file path or an http(s) URL (OpenAPI 3.x or Swagger 2.0).
+
+Options:
+  -o, --output <file>       build: output file (default: <spec name>.html)
+      --title <text>        page and header title (default: info.title)
+      --locale <code>       UI language: en, tr, ar… (default: en)
+      --theme <light|dark>  force a theme
+      --logo <url>          header logo image
+      --no-prerender        build: render in the browser only (smaller file, no
+                            content without JavaScript or for search engines)
+      --port <number>       serve: port (default: 8080)
+      --host <address>      serve: bind address (default: 127.0.0.1)
+      --proxy-hosts <list>  serve: hosts the proxy may call (default: any, loopback only)
+      --no-proxy            serve: disable the "Try" proxy
+  -h, --help                show this help
+  -v, --version             show the version
+`;
+
+function fail(message) {
+  console.error(`oaspect: ${message}`);
+  process.exit(1);
+}
+
+const { values, positionals } = (() => {
+  try {
+    return parseArgs({
+      allowPositionals: true,
+      options: {
+        output: { type: "string", short: "o" },
+        title: { type: "string" },
+        locale: { type: "string" },
+        theme: { type: "string" },
+        logo: { type: "string" },
+        port: { type: "string" },
+        host: { type: "string" },
+        "proxy-hosts": { type: "string" },
+        "no-proxy": { type: "boolean" },
+        "no-prerender": { type: "boolean" },
+        help: { type: "boolean", short: "h" },
+        version: { type: "boolean", short: "v" },
+      },
+    });
+  } catch (error) {
+    fail(error.message);
+  }
+})();
+
+if (values.version) {
+  const { version } = JSON.parse(await readFile(resolve(root, "package.json"), "utf8"));
+  console.log(version);
+  process.exit(0);
+}
+
+const [command, source] = positionals;
+if (values.help || !command) {
+  console.log(HELP);
+  process.exit(values.help ? 0 : 1);
+}
+if (!["build", "serve"].includes(command)) fail(`unknown command "${command}". Run oaspect --help.`);
+if (!source) fail(`${command} needs a spec file or URL.`);
+if (values.theme && !["light", "dark"].includes(values.theme)) fail("--theme must be light or dark.");
+
+const config = {
+  ...(values.title ? { title: values.title } : {}),
+  ...(values.locale ? { defaultLocale: values.locale } : {}),
+  ...(values.theme ? { theme: values.theme } : {}),
+  ...(values.logo ? { logo: values.logo } : {}),
+};
+
+try {
+  if (command === "build") {
+    const spec = await loadSpec(source);
+    const output = resolve(values.output ?? `${basename(isUrl(source) ? new URL(source).pathname : source, extname(source)) || "openapi"}.html`);
+    // No "Source" menu or ?url= loading in a static file; there is no proxy
+    // either. Prerendered pages render every section (no lazy placeholders)
+    // so the HTML holds the whole reference.
+    const pageConfig = { ...config, urlParam: null, features: { sourceMenu: false }, ...(values["no-prerender"] ? {} : { lazy: false }) };
+    let prerendered = {};
+    if (!values["no-prerender"]) {
+      const { renderToHtml, css } = await import("../dist/ssr.js");
+      prerendered = { markup: renderToHtml({ ...pageConfig, spec }), css };
+    }
+    const html = renderHtml({
+      title: values.title ?? spec.info?.title ?? "API Reference",
+      config: pageConfig,
+      spec,
+      script: { inline: await readFile(bundlePath, "utf8") },
+      ...prerendered,
+    });
+    await writeFile(output, html);
+    console.log(`Wrote ${output} (${(Buffer.byteLength(html) / 1024).toFixed(0)} KB)`);
+  } else {
+    const proxyHosts = values["proxy-hosts"]?.split(",").map((host) => host.trim()).filter(Boolean);
+    const port = values.port ? Number.parseInt(values.port, 10) : 8080;
+    if (!Number.isInteger(port) || port < 0 || port > 65535) fail("--port must be a number between 0 and 65535.");
+    const { url } = await serve({
+      source,
+      port,
+      host: values.host ?? "127.0.0.1",
+      proxy: values["no-proxy"] ? false : proxyHosts?.length ? proxyHosts : true,
+      bundlePath,
+      config,
+    });
+    console.log(`oaspect serving ${source} at ${url}`);
+  }
+} catch (error) {
+  fail(error.message);
+}