zudoku 0.74.2 → 0.75.0

package/dist/cli/cli.js

@@ -3813,7 +3813,7 @@ import {
 // package.json
 var package_default = {
   name: "zudoku",
-  version: "0.74.1",
+  version: "0.74.3",
   type: "module",
   sideEffects: [
     "**/*.css",
@@ -3951,7 +3951,7 @@ var package_default = {
     "fast-equals": "6.0.0",
     glob: "13.0.6",
     "glob-parent": "6.0.2",
-    graphql: "16.13.1",
+    graphql: "16.13.2",
     "graphql-type-json": "0.3.2",
     "graphql-yoga": "5.18.0",
     "gray-matter": "4.0.3",
@@ -6730,6 +6730,7 @@ var viteDocsPlugin = () => {
         `  basePath: "${config2.basePath ?? ""}",`,
         `  fileImports,`,
         `  defaultOptions: ${JSON.stringify(docsConfig.defaultOptions)},`,
+        `  publishMarkdown: ${JSON.stringify(docsConfig.publishMarkdown)},`,
         `});`
       );
       await writePluginDebugCode(config2.__meta.rootDir, "docs-plugin", code);
@@ -7774,6 +7775,7 @@ async function writeOutput(dir, {
 // src/vite/prerender/prerender.ts
 init_logger();
 init_file_exists();
+import { readFileSync as readFileSync2 } from "node:fs";
 import { readFile as readFile2, rm } from "node:fs/promises";
 import os from "node:os";
 import path21 from "node:path";
@@ -7944,7 +7946,9 @@ var prerender = async ({
       paths.push(joinUrl(r.from));
     }
   }
-  const maxThreads = buildConfig?.prerender?.workers ?? Math.floor(os.cpus().length * 0.8);
+  const { maxThreads, maxOldGenerationSizeMb } = getWorkerScaling(
+    buildConfig?.prerender?.workers
+  );
   const start = performance.now();
   const LOG_INTERVAL_MS = 3e4;
   let lastLogTime = start;
@@ -7973,7 +7977,11 @@ var prerender = async ({
   const pool = new Piscina({
     filename: new URL("./worker.js", import.meta.url).href,
     idleTimeout: 5e3,
+    minThreads: 1,
     maxThreads,
+    resourceLimits: {
+      maxOldGenerationSizeMb
+    },
     workerData: {
       template: html,
       distDir,
@@ -7985,12 +7993,6 @@ var prerender = async ({
   const workerResults = await Promise.all(
     paths.map(async (urlPath) => {
       const result = await pool.run({ urlPath });
-      if (result.statusCode < 400) {
-        await pagefindIndex?.addHTMLFile({
-          url: urlPath,
-          content: result.html
-        });
-      }
       completedCount++;
       if (isTTY()) {
         writeProgress(completedCount, paths.length, urlPath);
@@ -8008,9 +8010,6 @@ var prerender = async ({
       return result;
     })
   );
-  const pagefindWriteResult = await pagefindIndex?.writeFiles({
-    outputPath: path21.join(distDir, "pagefind")
-  });
   const seconds = ((performance.now() - start) / 1e3).toFixed(1);
   const message = `\u2713 finished prerendering ${paths.length} routes in ${seconds} seconds using ${maxThreads} workers`;
   if (isTTY()) {
@@ -8019,10 +8018,38 @@ var prerender = async ({
   } else {
     logger.info(colors7.blue(message));
   }
-  if (pagefindWriteResult?.outputPath) {
-    logger.info(
-      colors7.blue(`\u2713 pagefind index built: ${pagefindWriteResult.outputPath}`)
+  if (pagefindIndex) {
+    const pagesToIndex = workerResults.flatMap(
+      ({ statusCode, html: html2 }, i) => statusCode < 400 ? { url: paths[i], html: html2 } : []
     );
+    const BATCH_SIZE = 40;
+    const pagefindStart = performance.now();
+    for (let offset = 0; offset < pagesToIndex.length; offset += BATCH_SIZE) {
+      const batch = pagesToIndex.slice(offset, offset + BATCH_SIZE);
+      await Promise.all(
+        batch.map(
+          ({ url, html: html2 }) => pagefindIndex.addHTMLFile({ url, content: html2 })
+        )
+      );
+      if (isTTY()) {
+        const done = offset + batch.length;
+        writeLine(
+          `pagefind indexing (${done}/${pagesToIndex.length}) ${colors7.dim(batch.at(-1)?.url ?? "")}`
+        );
+      }
+    }
+    if (isTTY()) writeLine("");
+    const { outputPath } = await pagefindIndex.writeFiles({
+      outputPath: path21.join(distDir, "pagefind")
+    });
+    if (outputPath) {
+      const duration = (performance.now() - pagefindStart) / 1e3;
+      logger.info(
+        colors7.blue(
+          `\u2713 pagefind index built in ${duration.toFixed(1)} seconds: ${outputPath}`
+        )
+      );
+    }
   }
   const redirectUrls = getRedirectUrls(workerResults, config2.basePath);
   await generateSitemap({
@@ -8073,6 +8100,52 @@ var prerender = async ({
   }
   return { workerResults, rewrites };
 };
+var getWorkerScaling = (workersOverride) => {
+  const PER_WORKER_HEAP_LIMIT_MB = 4096;
+  const MAX_WORKERS = 8;
+  const osTotalMb = Math.floor(os.totalmem() / (1024 * 1024));
+  const cgroupMemMb = getContainerMemoryLimitMb();
+  const totalMemMb = cgroupMemMb !== void 0 ? Math.min(cgroupMemMb, osTotalMb) : osTotalMb;
+  const reservedMb = Math.max(2048, Math.floor(totalMemMb * 0.25));
+  const availableForWorkersMb = totalMemMb - reservedMb;
+  const memBasedWorkers = Math.max(
+    1,
+    Math.floor(availableForWorkersMb / PER_WORKER_HEAP_LIMIT_MB)
+  );
+  const cpuBasedWorkers = Math.max(1, Math.floor(os.cpus().length * 0.5));
+  const defaultWorkers = Math.min(
+    memBasedWorkers,
+    cpuBasedWorkers,
+    MAX_WORKERS
+  );
+  const validOverride = workersOverride && workersOverride > 0 ? workersOverride : void 0;
+  const maxThreads = validOverride ?? defaultWorkers;
+  const maxOldGenerationSizeMb = Math.min(
+    PER_WORKER_HEAP_LIMIT_MB,
+    Math.max(512, Math.floor(availableForWorkersMb / maxThreads))
+  );
+  return { maxThreads, maxOldGenerationSizeMb };
+};
+var getContainerMemoryLimitMb = () => {
+  const CGROUP_PATHS = [
+    "/sys/fs/cgroup/memory.max",
+    // cgroup v2
+    "/sys/fs/cgroup/memory/memory.limit_in_bytes"
+    // cgroup v1
+  ];
+  for (const filePath of CGROUP_PATHS) {
+    try {
+      const raw = readFileSync2(filePath, "utf8").trim();
+      if (raw === "max") return void 0;
+      const bytes = Number(raw);
+      if (!Number.isFinite(bytes) || bytes > 2 ** 50) return void 0;
+      return Math.floor(bytes / (1024 * 1024));
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
+  }
+  return void 0;
+};
 
 // src/vite/build.ts
 var DIST_DIR = "dist";

package/dist/declarations/lib/plugins/markdown/MdxPage.d.ts

@@ -7,8 +7,9 @@ declare global {
         }) => string[] | undefined;
     }
 }
-export declare const MdxPage: ({ mdxComponent: MdxComponent, basePath, frontmatter, defaultOptions, __filepath, tableOfContents, excerpt, }: PropsWithChildren<Omit<MDXImport, "default"> & {
+export declare const MdxPage: ({ mdxComponent: MdxComponent, basePath, frontmatter, defaultOptions, publishMarkdown, __filepath, tableOfContents, excerpt, }: PropsWithChildren<Omit<MDXImport, "default"> & {
     basePath: string;
     mdxComponent: MDXImport["default"];
     defaultOptions?: MarkdownPluginDefaultOptions;
+    publishMarkdown?: boolean;
 }>) => import("react/jsx-runtime").JSX.Element;

package/dist/declarations/lib/plugins/openapi/MCPEndpoint.d.ts

@@ -1,6 +1,7 @@
+import { type McpServerData } from "./mcp-configs.js";
 export declare const MCPEndpoint: ({ serverUrl, operationPath, summary, data, }: {
     serverUrl?: string;
     operationPath?: string;
-    data?: boolean | Record<string, unknown>;
+    data?: McpServerData;
     summary?: string;
 }) => import("react/jsx-runtime").JSX.Element;

package/dist/declarations/lib/plugins/openapi/mcp-configs.d.ts

@@ -0,0 +1,28 @@
+export type McpServerData = boolean | Record<string, unknown>;
+export interface AuthHeader {
+    headerName: string;
+    placeholder: string;
+}
+export type AuthType = "none" | "apiKey" | "oauth";
+export declare const getAuthType: (data?: McpServerData) => AuthType;
+export declare const getAuthHeader: (data?: McpServerData) => AuthHeader | undefined;
+export interface McpSubApp {
+    id: string;
+    label: string;
+    supportedAuth: AuthType[];
+}
+export interface McpApp {
+    id: string;
+    label: string;
+    subApps: McpSubApp[];
+}
+export declare const MCP_APPS: McpApp[];
+export declare const getVisibleApps: (authType: AuthType) => McpApp[];
+export declare const getMcpServerName: (data?: McpServerData, summary?: string) => string;
+export declare const getMcpUrl: (serverUrl?: string, operationPath?: string) => string;
+export declare const getClaudeCodeCommand: (name: string, mcpUrl: string, auth?: AuthHeader) => string;
+export declare const getCodexCliCommand: (name: string, mcpUrl: string, auth?: AuthHeader) => string;
+export declare const getCursorConfig: (name: string, mcpUrl: string, auth?: AuthHeader) => string;
+export declare const getVscodeConfig: (name: string, mcpUrl: string, auth?: AuthHeader) => string;
+export declare const getCodexConfig: (name: string, mcpUrl: string, auth?: AuthHeader) => string;
+export declare const getGenericConfig: (name: string, mcpUrl: string, auth?: AuthHeader) => string;

package/docs/configuration/authentication-auth0.md

@@ -34,7 +34,10 @@ If you don't have an Auth0 account, you can sign up for a
      - Production: `https://your-site.com/oauth/callback`
      - Preview (wildcard): `https://*.your-domain.com/oauth/callback`
      - Local Development: `http://localhost:3000/oauth/callback`
-   - **Allowed Logout URLs**: Same as callback URLs above
+   - **Allowed Logout URLs**:
+     - Production: `https://your-site.com/oauth/logout-callback`
+     - Preview (wildcard): `https://*.your-domain.com/oauth/logout-callback`
+     - Local Development: `http://localhost:3000/oauth/logout-callback`
 
    - **Allowed Web Origins**:
      - Production: `https://your-site.com`
@@ -112,8 +115,8 @@ To enable logout for your Auth0 application:
 
 1. Ensure your **Allowed Logout URLs** are configured in Auth0 (see
    [Configure Auth0 Application](#setup-steps) above)
-2. The logout URL should match your callback URL pattern (e.g., `https://your-site.com/` for
-   production)
+2. The logout URL must use the `/oauth/logout-callback` path (e.g.,
+   `https://your-site.com/oauth/logout-callback` for production)
 
 For older tenants, you may need to enable **RP-Initiated Logout** in your tenant settings. See the
 [Auth0 logout documentation](https://auth0.com/docs/authenticate/login/logout/log-users-out-of-auth0)

package/docs/configuration/authentication-openid.md

@@ -0,0 +1,110 @@
+---
+title: OpenID Connect (OIDC)
+sidebar_label: OpenID Connect
+description:
+  Configure any OpenID Connect compliant identity provider (Okta, Keycloak, Authentik, etc.) as the
+  authentication provider for Zudoku.
+---
+
+Zudoku supports any identity provider that implements the
+[OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) protocol via the generic
+`openid` provider type. This includes Okta, Keycloak, Authentik, Ory, ZITADEL, AWS Cognito, Google
+Identity, and most enterprise IdPs.
+
+## Configuration
+
+Add the `authentication` property to your [Zudoku configuration](./overview.md):
+
+```typescript title="zudoku.config.ts"
+{
+  // ...
+  authentication: {
+    type: "openid",
+    clientId: "<your-client-id>",
+    issuer: "<the-issuer-url>",
+    scopes: ["openid", "profile", "email"], // Optional
+  },
+  // ...
+}
+```
+
+| Option     | Required | Description                                                                                  |
+| ---------- | -------- | -------------------------------------------------------------------------------------------- |
+| `clientId` | Yes      | The OAuth client ID issued by your provider.                                                 |
+| `issuer`   | Yes      | The issuer URL. Zudoku discovers endpoints from `<issuer>/.well-known/openid-configuration`. |
+| `scopes`   | No       | Scopes to request. Defaults to `["openid", "profile", "email"]`.                             |
+
+## Provider Setup
+
+Register Zudoku as a public SPA / single page application client in your identity provider and set:
+
+- Callback / Redirect URI to `https://your-site.com/oauth/callback`
+- For local development, add `http://localhost:3000/oauth/callback`
+- If your provider supports wildcards, add `https://*.your-domain.com/oauth/callback` for preview
+  environments
+- Add your site origin to the list of allowed CORS origins
+- Enable the `Authorization Code` grant with PKCE and the `Refresh Token` grant
+
+### Okta
+
+1. In the Okta admin console go to **Applications** → **Applications** → **Create App Integration**.
+2. Select **OIDC - OpenID Connect** and **Single Page Application**.
+3. Set **Sign-in redirect URIs** to `https://your-site.com/oauth/callback` (add
+   `http://localhost:3000/oauth/callback` for local development).
+4. Under **Assignments**, assign the users or groups that should have access.
+5. After creating the app, copy the **Client ID**. Your issuer is your Okta domain, for example
+   `https://your-tenant.okta.com` or a custom authorization server like
+   `https://your-tenant.okta.com/oauth2/default`.
+6. Under **Security** → **API** → **Trusted Origins**, add your site origin for both CORS and
+   Redirect.
+
+```typescript title="zudoku.config.ts"
+{
+  authentication: {
+    type: "openid",
+    clientId: "<your-okta-client-id>",
+    issuer: "https://your-tenant.okta.com/oauth2/default",
+    scopes: ["openid", "profile", "email"],
+  },
+}
+```
+
+### Keycloak
+
+Use the realm issuer URL:
+
+```typescript title="zudoku.config.ts"
+{
+  authentication: {
+    type: "openid",
+    clientId: "zudoku",
+    issuer: "https://keycloak.example.com/realms/<your-realm>",
+  },
+}
+```
+
+In the realm, create a client with **Client type** `OpenID Connect`, **Access type** `public`, and
+enable **Standard Flow** (Authorization Code).
+
+## Verifying the Issuer
+
+You can confirm your issuer URL is correct by opening `<issuer>/.well-known/openid-configuration` in
+a browser. It should return a JSON document listing `authorization_endpoint`, `token_endpoint`,
+`userinfo_endpoint`, and `jwks_uri`.
+
+## User Profile
+
+After sign-in Zudoku calls the provider's
+[UserInfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) and reads
+`name`, `email`, `picture`, and `email_verified` from the response. Map these claims in your
+provider if they are not emitted by default.
+
+## Troubleshooting
+
+- **Discovery fails**: verify `<issuer>/.well-known/openid-configuration` resolves and matches the
+  `issuer` value in the document.
+- **CORS errors on token / userinfo**: add your site origin to the provider's allowed origins.
+- **Redirect URI mismatch**: the URI registered with the provider must match the Zudoku origin
+  exactly, including protocol and port.
+- **Missing profile fields**: ensure `profile` and `email` scopes are granted and that the provider
+  includes `name`, `email`, and `picture` claims in the UserInfo response.

package/docs/configuration/authentication.md

@@ -15,8 +15,8 @@ authentication provider you use.
 
 ## Authentication Providers
 
-Zudoku supports Clerk, Auth0, Supabase, Firebase, Azure B2C, and any OpenID provider that supports
-the OpenID Connect protocol (including PingFederate).
+Zudoku supports Clerk, Auth0, Supabase, Firebase, Azure B2C, and any OpenID Connect provider
+(including Okta, Keycloak, Authentik, and PingFederate).
 
 Not seeing your authentication provider? [Let us know](https://github.com/zuplo/zudoku/issues)
 
@@ -96,6 +96,9 @@ When configuring your OpenID provider, you will need to set the following:
 By default, the scopes "openid", "profile", and "email" are requested. You can customize these by
 providing your own array of scopes.
 
+For provider-specific guides (Okta, Keycloak, etc.), see the
+[OpenID Connect setup page](./authentication-openid.md).
+
 ### Firebase
 
 For Firebase authentication, you will need your Firebase project configuration. You can find this in

package/docs/openapi-extensions/x-code-samples.md

@@ -0,0 +1,57 @@
+---
+title: x-code-samples
+sidebar_icon: code
+---
+
+Use `x-code-samples` (or `x-codeSamples`) to provide custom code snippets for an API operation. When
+present, these samples appear in the sidecar panel alongside the auto-generated request examples.
+
+## Location
+
+The extension is added at the **Operation Object** level.
+
+| Option           | Type                   | Description                   |
+| ---------------- | ---------------------- | ----------------------------- |
+| `x-code-samples` | `[Code Sample Object]` | Array of custom code samples. |
+| `x-codeSamples`  | `[Code Sample Object]` | Alias for `x-code-samples`.   |
+
+## Code Sample Object
+
+| Property | Type     | Required | Description                                          |
+| -------- | -------- | -------- | ---------------------------------------------------- |
+| `lang`   | `string` | Yes      | Language identifier used for syntax highlighting.    |
+| `label`  | `string` | No       | Display label for the tab. Defaults to `lang` value. |
+| `source` | `string` | Yes      | The code snippet content.                            |
+
+## Example
+
+```yaml
+paths:
+  /users:
+    get:
+      summary: List users
+      x-code-samples:
+        - lang: curl
+          label: cURL
+          source: |
+            curl -X GET https://api.example.com/users \
+              -H "Authorization: Bearer $TOKEN"
+        - lang: python
+          label: Python
+          source: |
+            import requests
+
+            response = requests.get(
+                "https://api.example.com/users",
+                headers={"Authorization": f"Bearer {token}"},
+            )
+        - lang: javascript
+          label: JavaScript
+          source: |
+            const response = await fetch("https://api.example.com/users", {
+              headers: { Authorization: `Bearer ${token}` },
+            });
+      responses:
+        "200":
+          description: Successful response
+```

package/docs/openapi-extensions/x-display-name.md

@@ -0,0 +1,31 @@
+---
+title: x-displayName
+sidebar_icon: tag
+---
+
+Use `x-displayName` to override the display label for a tag in the API navigation and documentation.
+By default, Zudoku uses the tag's `name` field. This extension lets you set a different
+human-friendly label without changing the tag name used for grouping operations.
+
+## Location
+
+The extension is added at the **Tag Object** level.
+
+| Option          | Type     | Description                                            |
+| --------------- | -------- | ------------------------------------------------------ |
+| `x-displayName` | `string` | Custom display name shown in the sidebar and headings. |
+
+## Example
+
+```yaml
+tags:
+  - name: ai-ops
+    description: AI-powered operations
+    x-displayName: AI Operations
+  - name: user-mgmt
+    description: User management endpoints
+    x-displayName: User Management
+```
+
+Without `x-displayName`, the sidebar would show `ai-ops` and `user-mgmt`. With it, the sidebar
+displays `AI Operations` and `User Management` instead.

package/docs/openapi-extensions/x-mcp-server.md

@@ -0,0 +1,104 @@
+---
+title: x-mcp-server
+sidebar_icon: bot
+---
+
+Use `x-mcp-server` to mark an individual OpenAPI operation as an
+[MCP](https://modelcontextprotocol.io/) (Model Context Protocol) endpoint. When Zudoku detects this
+extension, it replaces the standard request/response view with a dedicated MCP card showing the
+endpoint URL, a copy button, and tabbed installation instructions for popular AI clients.
+
+:::note
+
+The `x-mcp-server` extension is applied at the **operation level** to mark specific endpoints. If
+you want to describe an entire MCP server at the root level of your OpenAPI document, see the
+[`x-mcp` extension](./x-mcp).
+
+:::
+
+## Location
+
+The `x-mcp-server` extension is added at the **Operation Object** level.
+
+| Option         | Type                             | Description                                    |
+| -------------- | -------------------------------- | ---------------------------------------------- |
+| `x-mcp-server` | `boolean` or `MCP Server Object` | Marks the operation as an MCP server endpoint. |
+
+## MCP Server Object
+
+When using the object form, the following properties are available:
+
+| Property  | Type            | Required | Description                                                                                                                  |
+| --------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `name`    | `string`        | No       | Display name used in the generated client configuration snippets. Falls back to the operation `summary`, then `"mcp-server"` |
+| `version` | `string`        | No       | Version metadata                                                                                                             |
+| `tools`   | `[Tool Object]` | No       | Array of tools provided by the MCP server                                                                                    |
+
+Each item in the `tools` array:
+
+| Property      | Type     | Required | Description                     |
+| ------------- | -------- | -------- | ------------------------------- |
+| `name`        | `string` | Yes      | Tool name                       |
+| `description` | `string` | No       | Human-readable tool description |
+
+## MCP URL resolution
+
+The displayed MCP URL is constructed from the **server URL** of the API and the **path** of the
+operation. The server URL comes from the OpenAPI `servers` array (or the operation-level `servers`
+override if present).
+
+## Examples
+
+### Boolean shorthand
+
+Use `true` to enable MCP UI without specifying metadata. The operation's `summary` is used as the
+server name.
+
+```yaml
+paths:
+  /mcp:
+    post:
+      summary: My MCP Server
+      x-mcp-server: true
+      responses:
+        "200":
+          description: MCP response
+```
+
+### Object form
+
+```yaml
+paths:
+  /mcp:
+    post:
+      summary: My MCP Server
+      x-mcp-server:
+        name: my-mcp-server
+        version: 1.0.0
+        tools:
+          - name: search_docs
+            description: Search the documentation
+          - name: get_page
+            description: Retrieve a specific documentation page
+      responses:
+        "200":
+          description: MCP response
+```
+
+## Generated UI
+
+When detected, the operation page shows:
+
+- **MCP Endpoint card** with the full URL and a copy button
+- **AI Tool Configuration** tabs with setup instructions for:
+  - **Claude** — add via Connectors UI or `claude mcp add` CLI command
+  - **ChatGPT** — app setup via Settings → Apps → Advanced Settings
+  - **Cursor** — `mcp.json` configuration (global or project-level)
+  - **VS Code** — `.vscode/mcp.json` with native HTTP transport for GitHub Copilot
+  - **Generic** — standard `mcp.json` format compatible with most MCP clients
+
+The standard method badge, request body, parameters, and sidecar panels are hidden for MCP
+endpoints.
+
+For a full walkthrough including Zudoku configuration, see the
+[Documenting MCP Servers guide](/docs/guides/mcp-servers).