@blaaiz/docs-core 0.1.0

package/package.json

@@ -0,0 +1,145 @@
+{
+  "name": "@blaaiz/docs-core",
+  "version": "0.1.0",
+  "description": "Neutral, self-hostable documentation framework core — navigation parsing, OpenAPI merging, MDX doc components, and a hardened try-it proxy. Config and content live in each consuming site.",
+  "keywords": [
+    "documentation",
+    "docs",
+    "openapi",
+    "api-playground",
+    "mdx",
+    "react",
+    "framework"
+  ],
+  "license": "MIT",
+  "author": "Blaaiz",
+  "homepage": "https://github.com/blaaiz/docs-core#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blaaiz/docs-core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/blaaiz/docs-core/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./ui": {
+      "types": "./dist/ui.d.ts",
+      "import": "./dist/ui.js",
+      "require": "./dist/ui.cjs"
+    },
+    "./ui/copy-page": {
+      "types": "./dist/ui/copy-page.d.ts",
+      "import": "./dist/ui/copy-page.js",
+      "require": "./dist/ui/copy-page.cjs"
+    },
+    "./ui/mermaid": {
+      "types": "./dist/ui/mermaid.d.ts",
+      "import": "./dist/ui/mermaid.js",
+      "require": "./dist/ui/mermaid.cjs"
+    },
+    "./ui/api-try-it": {
+      "types": "./dist/ui/api-try-it.d.ts",
+      "import": "./dist/ui/api-try-it.js",
+      "require": "./dist/ui/api-try-it.cjs"
+    },
+    "./ui/ask-ai": {
+      "types": "./dist/ui/ask-ai.d.ts",
+      "import": "./dist/ui/ask-ai.js",
+      "require": "./dist/ui/ask-ai.cjs"
+    },
+    "./generator": {
+      "types": "./dist/generator.d.ts",
+      "import": "./dist/generator.js",
+      "require": "./dist/generator.cjs"
+    },
+    "./styles/*": {
+      "style": "./styles/*",
+      "default": "./styles/*"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "docs-core": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "styles",
+    "patches",
+    "templates",
+    "skills"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "mermaid": "^11.0.0",
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "mermaid": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.27.11",
+    "@commitlint/cli": "^19.6.1",
+    "@commitlint/config-conventional": "^19.6.0",
+    "@eslint/js": "^9.17.0",
+    "@microsoft/api-extractor": "^7.48.1",
+    "@types/node": "^22.10.5",
+    "@types/react": "^19.0.7",
+    "@types/react-dom": "^19.0.3",
+    "@vitest/coverage-v8": "^2.1.8",
+    "dependency-cruiser": "^16.9.0",
+    "eslint": "^9.17.0",
+    "eslint-config-prettier": "^9.1.0",
+    "lefthook": "^1.10.1",
+    "mermaid": "^11.17.2",
+    "plop": "^4.0.1",
+    "prettier": "^3.4.2",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.19.0",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "arch": "depcruise src",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "api:check": "api-extractor run --verbose && api-extractor run --verbose --config api-extractor.ui.json && api-extractor run --verbose --config api-extractor.generator.json",
+    "api:update": "api-extractor run --local --verbose && api-extractor run --local --verbose --config api-extractor.ui.json && api-extractor run --local --verbose --config api-extractor.generator.json",
+    "gen": "plop",
+    "verify": "pnpm run format:check && pnpm run lint && pnpm run typecheck && pnpm run arch && pnpm run test:coverage && pnpm run build && pnpm run api:check",
+    "release": "changeset publish"
+  }
+}

package/patches/fumadocs-openapi.patch

@@ -0,0 +1,173 @@
+diff --git a/dist/playground/components/oauth-dialog.js b/dist/playground/components/oauth-dialog.js
+index 38925fd7df86dd837fca419161772a5b41070b2d..cf453defa42b08b9ca76fc0b73c8d325165f9817 100644
+--- a/dist/playground/components/oauth-dialog.js
++++ b/dist/playground/components/oauth-dialog.js
+@@ -1,4 +1,5 @@
+-import { useRenderContext } from "../../ui/contexts/api.js";
++import { useRenderContext, useServerContext } from "../../ui/contexts/api.js";
++import { joinURL, resolveServerUrl } from "@fumadocs/api-docs/utils/url";
+ import { cn } from "../../utils/cn.js";
+ import { useQuery } from "../../utils/use-query.js";
+ import { useAuth } from "../auth.js";
+@@ -10,6 +11,28 @@ import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@
+ import { Input, labelVariants } from "@fumadocs/api-docs/components/input";
+ import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, DialogTrigger } from "@fumadocs/api-docs/components/dialog";
+ //#region src/playground/components/oauth-dialog.tsx
++
++// Blaaiz: OpenAPI allows a relative `tokenUrl` (resolved against the server),
++// but the dialog fetched it verbatim, so it hit the docs origin instead of the
++// API. Resolve it the same way the playground resolves a request URL.
++function blaaizResolveTokenUrl(tokenUrl, server) {
++	if (/^[a-z][a-z0-9+.-]*:\/\//i.test(tokenUrl)) return tokenUrl;
++	const base = new URL(server ? resolveServerUrl(server.url, server.variables) : "/", window.location.origin).href;
++	return joinURL(base, tokenUrl);
++}
++// Blaaiz: a failed exchange threw the raw response body, so an HTML error page
++// flooded the dialog. Prefer the OAuth error fields, else a short summary.
++async function blaaizTokenError(res) {
++	const raw = (await res.text()).trim();
++	let message;
++	try {
++		const parsed = JSON.parse(raw);
++		message = parsed.error_description ?? parsed.error ?? parsed.message;
++	} catch {}
++	if (!message) message = raw.startsWith("<") || raw.length > 300 ? `${res.status} ${res.statusText || "error"} from the token endpoint.` : raw;
++	return new Error(`Token request failed: ${message}`);
++}
++
+ const OAuthDialog = Dialog;
+ function OAuthDialogContent(props) {
+ 	const t = useTranslations({ note: "OAuth dialog" });
+@@ -17,6 +40,9 @@ function OAuthDialogContent(props) {
+ }
+ function Content({ schemeId, scopes, setToken, setOpen }) {
+ 	const { dereferenced, resolve } = useRenderContext().schema;
++	// Blaaiz: the selected server, so a relative tokenUrl resolves against the
++	// API rather than the docs origin.
++	const { server: blaaizServer } = useServerContext();
+ 	const schemes = dereferenced.components?.securitySchemes;
+ 	const tokenInfo = useAuth().store[schemeId];
+ 	const scheme = resolve(schemes?.[schemeId]);
+@@ -118,7 +144,7 @@ function Content({ schemeId, scopes, setToken, setOpen }) {
+ 				if (values.clientId) body.set("client_id", values.clientId);
+ 				if (values.clientSecret) body.set("client_secret", values.clientSecret);
+ 			}
+-			res = await fetch(value.tokenUrl, {
++			res = await fetch(blaaizResolveTokenUrl(value.tokenUrl, blaaizServer), {
+ 				method: "POST",
+ 				headers,
+ 				body
+@@ -126,7 +152,7 @@ function Content({ schemeId, scopes, setToken, setOpen }) {
+ 		}
+ 		if (type === "clientCredentials") {
+ 			const value = scheme.flows[type];
+-			res = await fetch(value.tokenUrl, {
++			res = await fetch(blaaizResolveTokenUrl(value.tokenUrl, blaaizServer), {
+ 				method: "POST",
+ 				headers: { "Content-Type": "application/x-www-form-urlencoded" },
+ 				body: new URLSearchParams({
+@@ -138,7 +164,7 @@ function Content({ schemeId, scopes, setToken, setOpen }) {
+ 			});
+ 		}
+ 		if (res) {
+-			if (!res.ok) throw new Error(await res.text());
++			if (!res.ok) throw await blaaizTokenError(res);
+ 			const { access_token, token_type = "Bearer" } = await res.json();
+ 			setToken(`${token_type} ${access_token}`);
+ 			setOpen(false);
+diff --git a/dist/ui/index.d.ts b/dist/ui/index.d.ts
+index d9d78c8e161189b998c56441787f243e5f3bdc4d..ac3230e5574c12afc0864a57591c529653328b32 100644
+--- a/dist/ui/index.d.ts
++++ b/dist/ui/index.d.ts
+@@ -204,3 +204,10 @@ declare function createOpenAPIPage(options?: CreateOpenAPIPageOptions): FC<OpenA
+ type ApiPageProps = OpenAPIPageProps;
+ //#endregion
+ export { APIPlaygroundProps, ApiPageProps, CreateOpenAPIPageOptions, GenerateTypeScriptDefinitionsContext, OpenAPIPageProps, OpenAPIPageProps_Preloaded, OpenAPIPageProps_Spec, type OperationItem, type WebhookItem, createOpenAPIPage };
++// Blaaiz: server context, for a site-owned server switcher.
++export declare function useServerContext(): {
++  servers?: { url: string; description?: string; name?: string }[];
++  server?: { url: string; name?: string; variables: Record<string, string> } | null;
++  setServer(url: string): void;
++  setServerVariables(variables: Record<string, string>): void;
++};
+diff --git a/dist/ui/index.js b/dist/ui/index.js
+index 79678f643989b2ec048c18cc9a6dc83bf701154a..17cd7595ea2c79b2b3119b0abb43cb7e679ada1c 100644
+--- a/dist/ui/index.js
++++ b/dist/ui/index.js
+@@ -12,4 +12,7 @@ function createOpenAPIPage(options = {}) {
+ 	});
+ }
+ //#endregion
++// Blaaiz: expose the server context so a site can build its own server
++// switcher (the built-in one is a full dialog).
++export { useServerContext } from "./contexts/api.js";
+ export { createOpenAPIPage };
+diff --git a/dist/ui/operation/usage-tabs.js b/dist/ui/operation/usage-tabs.js
+index c26343b90b81499835392af83df7600373cea057..edb31d8efcb74c5ed90ad64cc71a97f43cc391d0 100644
+--- a/dist/ui/operation/usage-tabs.js
++++ b/dist/ui/operation/usage-tabs.js
+@@ -10,6 +10,42 @@ import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@
+ import { joinURL, resolveServerUrl } from "@fumadocs/api-docs/utils/url";
+ import { CodeBlockTab, CodeBlockTabs, CodeBlockTabsList, CodeBlockTabsTrigger } from "fumadocs-ui/components/codeblock";
+ //#region src/ui/operation/usage-tabs.tsx
++// Blaaiz: render the code-sample languages as a Select dropdown floated to the
++// right, with the endpoint name as the panel title — matching Mintlify.
++function BlaaizUsageDropdown({ map, title }) {
++	const [id, setId] = useState(map[0][0]);
++	const active = map.find(([key]) => key === id) ?? map[0];
++	const items = map.map(([key, item]) => ({ value: key, label: item.label ?? item.lang }));
++	return /* @__PURE__ */ jsxs("div", {
++		className: "not-prose openapi-usage",
++		children: [
++			/* @__PURE__ */ jsxs("div", {
++				className: "openapi-usage-header",
++				children: [
++					/* @__PURE__ */ jsx("span", { className: "openapi-usage-title", children: title ?? "" }),
++					/* @__PURE__ */ jsxs(Select, {
++						items,
++						value: id,
++						onValueChange: (v) => v !== null && setId(v),
++						children: [
++							/* @__PURE__ */ jsx(SelectTrigger, {
++								className: "openapi-usage-lang",
++								children: /* @__PURE__ */ jsx(SelectValue, {})
++							}),
++							/* @__PURE__ */ jsx(SelectContent, {
++								children: items.map((it) => /* @__PURE__ */ jsx(SelectItem, {
++									value: it.value,
++									children: it.label
++								}, it.value))
++							})
++						]
++					})
++				]
++			}),
++			/* @__PURE__ */ jsx(UsageTab, { id, lang: active[1].lang })
++		]
++	});
++}
+ function UsageTabs({ method, operation, pathItem }) {
+ 	const ctx = useRenderContext();
+ 	let { renderAPIExampleUsageTabs, renderAPIExampleLayout } = ctx.content ?? {};
+@@ -26,20 +62,7 @@ function UsageTabs({ method, operation, pathItem }) {
+ 	renderAPIExampleUsageTabs ??= (registry) => {
+ 		const map = Array.from(registry.map().entries());
+ 		if (map.length === 0) return null;
+-		return /* @__PURE__ */ jsxs(CodeBlockTabs, {
+-			groupId: "fumadocs_openapi_requests",
+-			defaultValue: map[0][0],
+-			children: [/* @__PURE__ */ jsx(CodeBlockTabsList, { children: map.map(([id, item]) => /* @__PURE__ */ jsx(CodeBlockTabsTrigger, {
+-				value: id,
+-				children: item.label ?? item.lang
+-			}, id)) }), map.map(([id, item]) => /* @__PURE__ */ jsx(CodeBlockTab, {
+-				value: id,
+-				children: /* @__PURE__ */ jsx(UsageTab, {
+-					id,
+-					lang: item.lang
+-				})
+-			}, id))]
+-		});
++		return /* @__PURE__ */ jsx(BlaaizUsageDropdown, { map, title: operation.summary });
+ 	};
+ 	const registry = useMemo(() => {
+ 		const registry = createCodeUsageGeneratorRegistry(ctx.codeUsages);

package/skills/AGENTS-section.md

@@ -0,0 +1,36 @@
+## Documentation site — @blaaiz/docs-core
+
+This project's documentation site is built with `@blaaiz/docs-core`. The package
+owns the logic; this repository owns config and content. Rules that always apply:
+
+- **Never edit `node_modules/@blaaiz/docs-core`.** Every behaviour change comes
+  from `docs.config.ts`, `content/docs.json`, or a content file. If a change
+  seems to need a package edit, it belongs in the `docs-core` repository — say so
+  instead of patching the install.
+- **`docs.config.ts` is the only place for site-specific values**: the brand, the
+  access mode, the try-it proxy allow-list, the opt-in features, SEO, and Ask AI.
+  A secret never goes in it. Config names an environment variable; the server
+  reads the value at runtime.
+- **`content/docs.json` is the single source of truth for navigation.** Tabs,
+  groups, page order, and which API endpoints are published all live there.
+  Never reorganize the sidebar by moving files.
+- **Generated files are outputs, not sources.** On a site that runs
+  `@blaaiz/docs-core/generator`, `content/docs/api/**`, `content/nav.json`,
+  `content/api-methods.json`, and every `meta.json` are rewritten from
+  `docs.json` on each run. Hand edits are lost. Change `docs.json` and re-run the
+  generator.
+- **`proxy.allowedOrigins` is security-critical.** It is the exhaustive list of
+  upstream origins the try-it playground may reach. Add an origin only when the
+  site really must call it.
+- **Verify before you finish**: run the project's `typecheck` and `build`, and
+  check the affected pages at `/docs` in the browser.
+
+The full skill — the complete config schema, the `docs.json` shape, task recipes,
+and every error the framework raises with its fix — is installed for both agents:
+
+- Claude Code: `.claude/skills/docs-core/SKILL.md`
+- Codex: `.agents/skills/docs-core/SKILL.md`
+
+Refresh them after a `docs-core` upgrade with `npx docs-core agents --force`.
+That command rewrites only the block between its own two markers in this file,
+so anything you add outside them is safe.