rapidoc 11.0.1 → 12.1.0

package/src/utils/highlighter.js

@@ -0,0 +1,419 @@
+// CSS Custom Highlight API-based Syntax Highlighter using bundled TextMate grammars
+
+import astro from "microlighter/grammars/astro.js";
+import bash from "microlighter/grammars/bash.js";
+import c from "microlighter/grammars/c.js";
+import cpp from "microlighter/grammars/cpp.js";
+import csharp from "microlighter/grammars/csharp.js";
+import cssGrammar from "microlighter/grammars/css.js";
+import go from "microlighter/grammars/go.js";
+import html from "microlighter/grammars/html.js";
+import java from "microlighter/grammars/java.js";
+import javascript from "microlighter/grammars/javascript.js";
+import json from "microlighter/grammars/json.js";
+import kotlin from "microlighter/grammars/kotlin.js";
+import markdown from "microlighter/grammars/markdown.js";
+import objectiveC from "microlighter/grammars/objective-c.js";
+import perl from "microlighter/grammars/perl.js";
+import php from "microlighter/grammars/php.js";
+import powershell from "microlighter/grammars/powershell.js";
+import python from "microlighter/grammars/python.js";
+import r from "microlighter/grammars/r.js";
+import ruby from "microlighter/grammars/ruby.js";
+import rust from "microlighter/grammars/rust.js";
+import svelte from "microlighter/grammars/svelte.js";
+import toml from "microlighter/grammars/toml.js";
+import tsx from "microlighter/grammars/tsx.js";
+import typescript from "microlighter/grammars/typescript.js";
+import vue from "microlighter/grammars/vue.js";
+import yaml from "microlighter/grammars/yaml.js";
+
+const httpGrammar = {
+  scopeName: "source.http",
+  patterns: [
+    {
+      match:
+        "^(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS|TRACE|CONNECT)\\s+([^\\s]+)\\s+(HTTP\\/[0-9.]+)",
+      captures: {
+        1: { name: "keyword.control.http" },
+        2: { name: "string.unquoted.http" },
+        3: { name: "keyword.other.http" },
+      },
+    },
+    {
+      match: "^(HTTP\\/[0-9.]+)\\s+([0-9]{3})(?:\\s+(.*))?",
+      captures: {
+        1: { name: "keyword.other.http" },
+        2: { name: "constant.numeric.http" },
+        3: { name: "string.unquoted.http" },
+      },
+    },
+    {
+      match: "^([a-zA-Z0-9_-]+):\\s*(.*)",
+      captures: {
+        1: { name: "support.type.property-name.http" },
+        2: { name: "string.unquoted.http" },
+      },
+    },
+  ],
+};
+
+const grammars = {
+  astro,
+  bash,
+  c,
+  cpp,
+  csharp,
+  css: cssGrammar,
+  go,
+  html,
+  http: httpGrammar,
+  java,
+  javascript,
+  json,
+  kotlin,
+  markdown,
+  "objective-c": objectiveC,
+  perl,
+  php,
+  powershell,
+  python,
+  r,
+  ruby,
+  rust,
+  svelte,
+  toml,
+  tsx,
+  typescript,
+  vue,
+  yaml,
+};
+
+const scopes = new Map();
+Object.values(grammars).forEach((grammar) => {
+  if (grammar?.scopeName) {
+    scopes.set(grammar.scopeName, grammar);
+  }
+});
+
+const languageAliases = {
+  "c++": "cpp",
+  cs: "csharp",
+  curl: "bash",
+  js: "javascript",
+  jsx: "javascript",
+  markup: "html",
+  md: "markdown",
+  objc: "objective-c",
+  ps1: "powershell",
+  py: "python",
+  rb: "ruby",
+  sh: "bash",
+  shell: "bash",
+  svg: "html",
+  ts: "typescript",
+  xml: "html",
+  yml: "yaml",
+  zsh: "bash",
+};
+
+const noMatch = { indices: [[Infinity, Infinity]] };
+const highlights = new Map();
+
+const getCategory = (scope) => {
+  const parts = scope.split(".");
+  const [first, second, third] = parts;
+  const last = parts.at(-1);
+
+  if (first === "markup" && ["quote", "inserted", "deleted", "raw"].includes(second)) return second;
+  if (first === "entity" && second === "name") return third;
+  if (scope.startsWith("constant.character.entity")) return "character-entity";
+  if (parts.includes("numeric")) return "numeric";
+  if (scope.startsWith("support.type.property-name")) return "property";
+  if (parts.includes("attribute-value")) return "attribute-value";
+  if (scope.startsWith("string.other.link")) return "link";
+
+  if (
+    [
+      "doctype",
+      "at-rule",
+      "important",
+      "regexp",
+      "boolean",
+      "symbol",
+      "operator",
+      "attribute-name",
+    ].includes(last)
+  )
+    return last;
+
+  if (
+    [
+      "comment",
+      "string",
+      "constant",
+      "storage",
+      "keyword",
+      "variable",
+      "punctuation",
+      "entity",
+      "support",
+    ].includes(first)
+  )
+    return first;
+};
+
+const addRange = (node, start, end, scope) => {
+  const category = getCategory(scope);
+  if (!category || start === end) return;
+
+  const range = new Range();
+  range.setStart(node, start);
+  range.setEnd(node, end);
+
+  if (!highlights.has(category)) {
+    highlights.set(category, new Highlight());
+  }
+  highlights.get(category).add(range);
+};
+
+const addCaptures = (node, match, captures = {}) => {
+  Object.entries(captures).forEach(([index, capture]) => {
+    const offsets = match.indices[+index];
+    if (offsets) addRange(node, ...offsets, capture.name);
+  });
+};
+
+const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+const expandEnd = (pattern, beginMatch) =>
+  pattern.replace(/\\(\d+)/g, (reference, index) =>
+    beginMatch[index] === undefined ? reference : escapeRegex(beginMatch[index]),
+  );
+
+const getRules = (rule) => {
+  if (!rule) return [];
+  if (Array.isArray(rule)) return rule;
+  if (rule.match || rule.begin || rule.include) return [rule];
+  return rule.patterns || [];
+};
+
+const resolveInclude = (include, grammar, baseGrammar) => {
+  if (include === "$self") return { grammar, rules: grammar.patterns };
+  if (include === "$base") return { grammar: baseGrammar, rules: baseGrammar.patterns };
+
+  if (include[0] === "#") {
+    return { grammar, rules: getRules(grammar.repository?.[include.slice(1)]) };
+  }
+
+  const [scopeName, repositoryName] = include.split("#");
+  const includedGrammar = scopes.get(scopeName);
+  if (!includedGrammar) return null;
+
+  return {
+    grammar: includedGrammar,
+    rules: repositoryName
+      ? getRules(includedGrammar.repository?.[repositoryName])
+      : includedGrammar.patterns,
+  };
+};
+
+const expandRules = (rules, grammar, baseGrammar, activeIncludes = new Set()) => {
+  const expanded = [];
+  rules.forEach((rule) => {
+    if (rule.include) {
+      const includeKey = `${grammar.scopeName}:${rule.include}`;
+      if (activeIncludes.has(includeKey)) return;
+
+      const included = resolveInclude(rule.include, grammar, baseGrammar);
+      if (!included) return;
+
+      const nestedIncludes = new Set(activeIncludes);
+      nestedIncludes.add(includeKey);
+      expanded.push(...expandRules(included.rules, included.grammar, baseGrammar, nestedIncludes));
+      return;
+    }
+
+    if (rule.match || (rule.begin && rule.end)) expanded.push({ grammar, rule });
+  });
+
+  return expanded;
+};
+
+const regexes = new Map();
+let matches = new Map();
+
+const exec = (pattern, node, start, end) => {
+  let match = matches.get(pattern);
+  if (!match || match.indices[0][0] < start) {
+    if (!regexes.has(pattern)) regexes.set(pattern, new RegExp(pattern, "dgm"));
+    const regex = regexes.get(pattern);
+    regex.lastIndex = start;
+    match = regex.exec(node.data) || noMatch;
+    matches.set(pattern, match);
+  }
+
+  return match.indices[0][0] < end && match.indices[0][1] <= end ? match : null;
+};
+
+const nextRule = (node, contexts, start, end) => {
+  let winner = null;
+  contexts.forEach((context) => {
+    const pattern = context.rule.match || context.rule.begin;
+    const match = exec(pattern, node, start, end);
+    if (!match) return;
+
+    if (!winner || match.indices[0][0] < winner.match.indices[0][0]) {
+      winner = { ...context, match };
+    }
+  });
+
+  return winner;
+};
+
+const scanRegion = (node, rules, start, end, grammar, baseGrammar = grammar, closing = null) => {
+  const contexts = expandRules(rules, grammar, baseGrammar);
+  let cursor = start;
+
+  while (cursor < end) {
+    const candidate = nextRule(node, contexts, cursor, end);
+    const endMatch = closing ? exec(closing.pattern, node, cursor, end) : null;
+    const candidateStart = candidate?.match.indices[0][0] ?? Infinity;
+    const endStart = endMatch?.indices[0][0] ?? Infinity;
+
+    if (
+      endMatch &&
+      (endStart < candidateStart || (endStart === candidateStart && !closing?.applyEndPatternLast))
+    ) {
+      return { contentEnd: endStart, end: endMatch.indices[0][1], match: endMatch };
+    }
+
+    if (!candidate) return { contentEnd: end, end, match: null };
+
+    const { rule, match, grammar: ruleGrammar } = candidate;
+    if (rule.match) {
+      if (rule.name) addRange(node, ...match.indices[0], rule.name);
+      addCaptures(node, match, rule.captures);
+      cursor = match.indices[0][1] > cursor ? match.indices[0][1] : cursor + 1;
+      continue;
+    }
+
+    const nested = scanRegion(
+      node,
+      rule.patterns || [],
+      match.indices[0][1],
+      end,
+      ruleGrammar,
+      baseGrammar,
+      {
+        pattern: expandEnd(rule.end, match),
+        applyEndPatternLast: rule.applyEndPatternLast,
+      },
+    );
+
+    if (rule.name) addRange(node, match.indices[0][0], nested.end, rule.name);
+    if (rule.contentName) addRange(node, match.indices[0][1], nested.contentEnd, rule.contentName);
+    addCaptures(node, match, rule.beginCaptures || rule.captures);
+    if (nested.match) addCaptures(node, nested.match, rule.endCaptures || rule.captures);
+
+    cursor = nested.end > cursor ? nested.end : cursor + 1;
+  }
+
+  return { contentEnd: end, end, match: null };
+};
+
+export const getLanguage = (codeBlock) => {
+  const pre = codeBlock.parentElement;
+  const getLangClass = (el) => {
+    if (!el || !el.classList) return null;
+    return [...el.classList].find((c) => c.startsWith("language-"))?.slice("language-".length);
+  };
+  const lang =
+    getLangClass(codeBlock) ||
+    codeBlock.dataset?.language ||
+    getLangClass(pre) ||
+    pre?.dataset?.language ||
+    pre?.getAttribute?.("lang") ||
+    "";
+  return lang.toLowerCase();
+};
+
+export const normalizeLanguage = (lang) => languageAliases[lang] || lang;
+
+export const getAllCodeBlocks = (rootNode = document) => {
+  const blocks = [];
+  const visitedRoots = new Set();
+
+  const traverse = (node) => {
+    if (!node || visitedRoots.has(node)) return;
+    visitedRoots.add(node);
+
+    if (node.querySelectorAll) {
+      const codeEls = node.querySelectorAll("pre > code");
+      blocks.push(...codeEls);
+
+      const allChildren = node.querySelectorAll("*");
+      for (let i = 0; i < allChildren.length; i++) {
+        const child = allChildren[i];
+        if (child.shadowRoot) {
+          traverse(child.shadowRoot);
+        }
+      }
+    }
+  };
+
+  traverse(rootNode);
+  return blocks;
+};
+
+let highlightScheduled = false;
+
+export const highlightAllCode = (rootNode = document) => {
+  if (typeof window === "undefined" || typeof CSS === "undefined" || !CSS.highlights) {
+    return;
+  }
+
+  // Find all code blocks across the root and any nested shadow roots
+  const codeBlocks = getAllCodeBlocks(rootNode).filter(getLanguage);
+  if (codeBlocks.length === 0) return;
+
+  // Clear previous ranges
+  highlights.forEach((ranges, category) => {
+    if (CSS.highlights.get(category) === ranges) CSS.highlights.delete(category);
+    ranges.clear();
+  });
+
+  codeBlocks.forEach((codeBlock) => {
+    const rawLang = getLanguage(codeBlock);
+    const lang = normalizeLanguage(rawLang);
+    const grammar = grammars[lang];
+    if (!grammar) return;
+
+    // Scan all text nodes without mutating or removing Lit marker comment nodes
+    const textNodes = Array.from(codeBlock.childNodes).filter(
+      (child) => child.nodeType === Node.TEXT_NODE && child.data?.length > 0,
+    );
+    if (textNodes.length === 0) return;
+
+    matches = new Map();
+    textNodes.forEach((node) => {
+      scanRegion(node, grammar.patterns, 0, node.data.length, grammar);
+    });
+  });
+
+  highlights.forEach((ranges, category) => {
+    if (ranges.size) CSS.highlights.set(category, ranges);
+  });
+};
+
+export const scheduleHighlight = (rootNode = document) => {
+  if (typeof window === "undefined" || typeof CSS === "undefined" || !CSS.highlights) {
+    return;
+  }
+  if (highlightScheduled) return;
+  highlightScheduled = true;
+  requestAnimationFrame(() => {
+    highlightScheduled = false;
+    highlightAllCode(rootNode);
+  });
+};

package/src/utils/markdown-utils.js

@@ -0,0 +1,110 @@
+import { marked } from "marked";
+
+let configured = false;
+
+function escapeAttribute(value) {
+  return value
+    .replace(/&/g, "&")
+    .replace(/"/g, """)
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/**
+ * When an HTML `<base>` tag is present in the page, a markdown in-page anchor link (e.g. `#link-to-a-section`) would
+ * resolve against the base URL instead of the current page. This renders such links with an absolute URL
+ * built from the current document location, and tags them with the `anchor-link` CSS class.
+ *
+ * @param {import('marked').Renderer} renderer
+ * @param {import('marked').Tokens.Link} token
+ * @returns {string | false} the rendered link, or `false` when the link is not an in-page anchor (use the default renderer)
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base#in-page_anchors
+ */
+function renderAnchorLink(renderer, { href, title, tokens }) {
+  if (!href?.startsWith("#") || typeof location === "undefined") {
+    return false;
+  }
+  const absoluteHref = `${location.href.replace(/#.*/, "")}${href}`;
+  const titleAttribute = title ? ` title="${escapeAttribute(title)}"` : "";
+  return `<a class="anchor-link" href="${escapeAttribute(absoluteHref)}"${titleAttribute}>${renderer.parser.parseInline(tokens)}</a>`;
+}
+
+/**
+ * Applies the in-page anchor fix to a custom renderer. A renderer passed per call, `marked(text, { renderer })`,
+ * replaces the global one configured by {@link configureMarkdown}, so custom renderers need it too.
+ *
+ * @param {import('marked').Renderer} renderer
+ */
+export function fixRenderedAnchorLinks(renderer) {
+  const defaultLink = renderer.link;
+  renderer.link = function link(token) {
+    const anchorLink = renderAnchorLink(this, token);
+    return anchorLink === false ? defaultLink.call(this, token) : anchorLink;
+  };
+}
+
+/** Inline HTML for the first line of a paragraph-like token (paragraph, heading, list), with line breaks as spaces. */
+export function firstLineHtml(token) {
+  // a list item's own text, without any nested list under it
+  const text =
+    token.type === "list"
+      ? token.items[0]?.tokens?.find((t) => t.type === "text" || t.type === "paragraph")?.text
+      : token.text;
+  return marked.parseInline((text || "").replace(/\s*\n\s*/g, " ").trim());
+}
+
+/**
+ * One-line HTML stand-in for a markdown block that cannot be shown on a single line: a short placeholder
+ * for tables and code blocks, the plain text of an HTML block, and the first line of a blockquote.
+ *
+ * @param {import('marked').Token} token - a block token from `marked.lexer`
+ * @returns {string} HTML for the summary line, or '' when the block can be shown inline as it is
+ */
+export function blockSummary(token) {
+  switch (token?.type) {
+    case "table": {
+      const rows = token.rows.length;
+      return `<span class="descr-placeholder">Table · ${rows} ${rows === 1 ? "row" : "rows"}</span>`;
+    }
+    case "code":
+      return `<span class="descr-placeholder">Code block${token.lang ? ` · ${escapeAttribute(token.lang)}` : ""}</span>`;
+    case "html": {
+      const text = token.text
+        .replace(/<(script|style)\b[\s\S]*?<\/\1>/gi, "")
+        .replace(/<[^>]*>/g, " ")
+        .replace(/[<>]/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+      return text || '<span class="descr-placeholder">HTML content</span>';
+    }
+    case "blockquote": {
+      const first = token.tokens.find((t) => t.type !== "space");
+      if (!first) return "";
+      return ["paragraph", "heading", "list", "text"].includes(first.type)
+        ? firstLineHtml(first)
+        : blockSummary(first);
+    }
+    default:
+      return "";
+  }
+}
+
+/**
+ * Configures the global `marked` instance used by every `marked(...)` call that has no custom renderer.
+ * Idempotent: safe to import and call from several entry points.
+ */
+export function configureMarkdown() {
+  if (configured) {
+    return;
+  }
+  configured = true;
+  marked.use({
+    renderer: {
+      link(token) {
+        return renderAnchorLink(this, token); // `false` falls back to marked's default link renderer
+      },
+    },
+  });
+}
+
+configureMarkdown();

package/src/utils/mcp/README.md

@@ -0,0 +1,155 @@
+# MCP Manifest, Runtime and Export
+
+## Overview
+
+Turns an OpenAPI document into an **MCP manifest** (plain JSON: one tool per operation, with
+JSON Schema arguments and MCP safety annotations) and executes that manifest with `fetch`. The
+exported MCP server is the manifest plus two fixed files: `runtime.js` (this folder's runtime,
+copied verbatim) and `project/server.ts` (a stdio server on `@modelcontextprotocol/sdk` that
+registers the manifest's tools and hands calls to the runtime). The entry point is
+`src/utils/mcp-generator.js`; `<rapi-doc>` (`src/rapidoc.ts`, `src/templates/downloads-template.js`)
+uses it for its Export MCP Server button, and `packages/rapidoc-mcp/src/index.js` re-exports it as `@rapidoc/mcp`
+(a separate package, Node only, no Lit) for the portal build, `@rapidoc/server` and the CLI.
+
+Arazzo workflows become tools too: `workflows.js` compiles a parsed Arazzo document into
+`manifest.workflows` (steps resolved to operations) and one tool per workflow, and
+`workflow-runtime.js` runs them on top of `runtime.js`. The two runtimes are separate files so
+`dist/rapidoc-min.js` (operation tools only) carries no Arazzo runtime, while
+`dist/rapidoc-flow-min.js` and `@rapidoc/mcp` include both. Not owned here: Arazzo parsing and validation (`../arazzo/`), the `<rapi-doc>` attribute and
+methods, and the network calls themselves (the runtime only builds and sends requests).
+
+## Interface
+
+- `compileWorkflows(arazzo, { sources, onProblem }) -> { tools, workflows }` [workflows.js]:
+  `sources` are operation indexes by Arazzo source name (`../arazzo/operations.js`). A workflow the
+  runtime cannot run is reported once through `onProblem` and left out. `buildMcpManifest` calls
+  it for `options.arazzo`, naming the manifest's source after the Arazzo document's first OpenAPI
+  source so steps resolve; `generateMcpServer` collects the problems into its result.
+
+- `buildMcpManifest(spec, options) -> manifest` [manifest.js]: `spec` is a raw OpenAPI 3.x /
+  Swagger 2.0 object or `ProcessSpec`'s result (`tags[].paths[]`). Options: `serverName`,
+  `sourceName` (default `api`), `includeInternal`, `includeDeprecated`, `includeOperations` (`false`:
+  only the Arazzo workflows' tools, for a manifest of workflows). `toJsonSchema(schema,
+  root)` is the schema converter on its own; `MANIFEST_VERSION` is `1`.
+- `createMcpRuntime(manifest, { fetch, credentials, baseUrls, runWorkflow })` [runtime.js]:
+  `listTools()`, `listResources()`, `callTool(name, args, hooks) -> { content, structuredContent?,
+  isError? }`, `execute(operation, args, { headers? })` (one request, for workflow runners; the
+  headers are added to the request). A workflow tool is handed to `runWorkflow`; without it the
+  call is an error result. `callTool`'s hooks reach the workflow runner: `onStepStart`, `onStep`,
+  `sleep`, and `requestHeaders({ workflowId, stepId, attempt, operation })`, whose result is sent
+  with that step's request (how `<rapi-flow>` asks `rapidoc mock` for a status with
+  `Prefer: code=`).
+- `runWorkflow(runtime, tool, args, { onStepStart, onStep, sleep })` and
+  `createMcpWorkflowRuntime(manifest, options)` (createMcpRuntime with `runWorkflow` plugged in;
+  `options.sleep` waits between retries) [workflow-runtime.js], plus `evaluateExpression`,
+  `resolveValue` and `evaluateCondition`. `@rapidoc/mcp` exports `createMcpWorkflowRuntime` as its
+  `createMcpRuntime`.
+  `readResource(uri) -> { contents }`. `buildRequest(manifest, operation, args, options)` returns
+  the request without sending it; `credentialsFromEnv(manifest, env)` and `envNameFor(id)` map
+  security schemes to environment variables.
+- `writeMcpProject(manifest, { serverName, workflowRuntime }) -> { [path]: text }` [project.js]:
+  `manifest.json`, `server.ts`, `runtime.js`, `package.json`, `README.md`,
+  `claude_desktop_config.json`, and `workflow-runtime.js` when the manifest has workflows and
+  `workflowRuntime` (its text) is given: `@rapidoc/mcp` and `<rapi-flow>` supply it,
+  `dist/rapidoc-min.js` does not carry it. `server.ts` imports it dynamically when present.
+- `createZip(files) -> Uint8Array` [zip.js]: a stored (uncompressed) ZIP of text files.
+- `generateMcpServer(spec, options) -> { manifest, files, budget, hostConfig }`
+  [../mcp-generator.js]: the three above in one call.
+- `common.js`: `parseMcpEnabled(val)` (the `mcp` attribute), `toSnakeCase`, `sanitizeDescription`,
+  `deriveToolName`, `AUTH_TRANSPORT_HEADERS`, `estimateTokenCost(manifest)` and
+  `generateHostConfigs(serverName, { schemes })`.
+
+## Invariants
+
+- **Manifest shape.** `{ manifestVersion, server: { name, version, description }, sources:
+  { [name]: { baseUrl, securitySchemes } }, tools, resources, workflows }`. A workflow tool has
+  `workflow` (its id) instead of `operation`; `workflows[id]` is `{ workflowId, summary,
+  description, inputs, steps, outputs }`, each step `{ stepId, operation, parameters, requestBody,
+  successCriteria, onSuccess, onFailure, outputs }` with the operation resolved (source, method,
+  path, params from the step's parameters and body, security from the OpenAPI operation) and
+  values kept as Arazzo expressions. A tool is
+  `{ name, description, inputSchema, annotations, operation }` with `operation = { source, method,
+  path, params: [{ name, in, arg?, contentType? }], security }`; `arg` names the argument when it
+  differs from the wire name, `contentType` is set for `in: "body"`. A resource has `uri`
+  (`reference://...`) and `mimeType` instead of `inputSchema` and `annotations`.
+- **Exclusion** (`[manifest.js:buildMcpManifest]`): an operation is skipped when `x-internal` or
+  `x-hidden` is `true` on it or its path item (unless `includeInternal`), when `deprecated` (unless
+  `includeDeprecated`), or when it is a webhook.
+- **Arguments.** Path, query, header and cookie parameters become properties by name (a clash
+  across locations gets `_<in>`); path parameters are required. The request body is one `body`
+  property with the first JSON content type's schema (else form-urlencoded, multipart, or the first
+  listed). Path-level parameters are merged unless the operation redefines them. Headers in
+  `AUTH_TRANSPORT_HEADERS` and any parameter that matches an `apiKey` scheme's `in` and `name`
+  are never arguments: the runtime sends them.
+- **JSON Schema** (`[manifest.js:toJsonSchema]`): `$ref`s are inlined from the raw document;
+  a schema met again on the same branch is cut to `{ type }`; `nullable` folds into `type`;
+  `readOnly` properties (and their `required` entries) are dropped; OpenAPI 3.0 boolean
+  `exclusiveMinimum/Maximum` become numbers; `example`, `xml`, `x-*` and other non-schema keys
+  are dropped.
+- **Naming**: `toSnakeCase(operationId)`, else `deriveToolName(method, path)`; workflow tools are
+  `toSnakeCase(workflowId)`, after the operations; a repeated name gets `_2`, `_3`, ... in that
+  order. `sanitizeDescription` deletes every `_`.
+- **Annotations**: `readOnlyHint` for GET; `destructiveHint` for PUT, PATCH and DELETE;
+  `idempotentHint` for GET, PUT and DELETE. A workflow tool is read-only when every step is a
+  GET, destructive when any step is PUT, PATCH or DELETE, never idempotent. `estimateTokenCost.consequentialCount` counts tools
+  without `readOnlyHint`.
+- **Resources**: a GET with no required argument whose path contains one of `/reference`,
+  `/currencies`, `/countries`, `/tiers`, `/categories`, `/status`, `/schema`.
+- **Security.** `securitySchemes` keeps `type, description, in, name, scheme, bearerFormat,
+  openIdConnectUrl` and OAuth 2 `flows`; `<rapi-doc>`'s injected `_rapidoc_api_key` scheme is
+  left out. A tool's `security` is the operation's, else the document's. The runtime uses the
+  first alternative all of whose credentials are known; with none, nothing is sent when an
+  alternative is empty, else the first alternative as far as credentials go.
+- **Runtime.** `runtime.js` imports nothing and uses only `fetch`, `URLSearchParams`,
+  `TextEncoder` and `btoa`, and `workflow-runtime.js` imports only `./runtime.js`, because the
+  project writer embeds their text (`?raw` imports, supported by Vite and
+  `scripts/test-loader.mjs`). Path parameters are percent-encoded; array query values
+  repeat the key; objects elsewhere are JSON; `Accept: application/json` unless set; a missing path
+  parameter is an error result, as is a transport failure or a non-2xx status (text `HTTP <status>`
+  plus the body). JSON responses are pretty-printed and, for objects, also `structuredContent`.
+- **Workflows the runtime runs** (`[workflows.js:compileWorkflows]`): steps that name an
+  operation found in the sources, parameters in path, query, header or cookie, a request body
+  with `payload` and `replacements`, simple criteria only (`regex`, `jsonpath` and `xpath` are
+  reported), actions `end`, `goto` to a step and `retry` (`retryLimit` default 1, `retryAfter`
+  seconds) with simple criteria, and `$inputs` / `$steps` expressions. Steps that call another
+  workflow, actions that go to one, and `$workflows` expressions are reported. A step's actions
+  are its own `onSuccess` / `onFailure` followed by the workflow's it does not override by name.
+- **Running a workflow** (`[workflow-runtime.js:runWorkflow]`): required inputs are checked first.
+  Each step's parameters and payload are evaluated against `$inputs` and earlier steps' outputs
+  (`resolveValue`: a whole-string expression keeps its type, `{$expr}` inside text is
+  interpolated), the request is sent, and every criterion must hold (`evaluateCondition`: `==`,
+  `!=`, `<`, `>`, `<=`, `>=`, `&&`, `||`, `!`, parentheses, quoted strings, numbers, `true`,
+  `false`, `null`; `==` compares numbers and strings as text and treats a missing value as
+  `null`). A step without criteria succeeds on a 2xx response. The first action whose criteria all hold runs: on success
+  `end` finishes, `goto` jumps, none falls through; on failure none or `end` fails the workflow
+  (the result names the step, the criterion and the response), `goto` jumps, `retry` re-runs the
+  step (or `stepId`) after `retryAfter` seconds up to `retryLimit` times. A transport error is a
+  failure with no response. More than 1000 step runs is an error. The result is the workflow's
+  `outputs` as `structuredContent`; `onStepStart` gets `{ workflowId, stepId, attempt }` before
+  each request and `onStep` gets `{ workflowId, stepId, attempt, outcome, request, response,
+  outputs, failedCriterion, action }` after it.
+- **Environment.** `envNameFor("petstore_auth")` is `PETSTORE_AUTH`; `API_KEY` is the fallback
+  for every scheme; HTTP Basic reads `<NAME>` as `user:password` or `<NAME>_USERNAME` /
+  `<NAME>_PASSWORD`. `API_BASE_URL` in `server.ts` overrides every source's base URL.
+- **Project.** `server.ts` and `runtime.js` are identical for every API; only `manifest.json`,
+  `package.json`, `README.md` and `claude_desktop_config.json` vary. The zip stores entries
+  uncompressed with a fixed 1980-01-01 timestamp and UTF-8 names.
+
+## Side Effects
+
+- None in this folder: no network, DOM, storage or console. The exported `server.ts` reads
+  `manifest.json`, the environment and stdio, and the runtime it calls makes HTTP requests.
+
+## Verification
+
+- `npm run test:unit` from the repo root. `tests/unit/mcp-generator.test.js` covers the manifest
+  (from `docs/public/specs/petstore.yaml` and small documents), the schema converter, the runtime
+  with a fake `fetch`, credentials from the environment, the project files and the zip.
+  `tests/unit/mcp-workflows.test.js` covers compiling `docs/public/specs/petstore.arazzo.yaml`,
+  expressions, conditions, and runs (outputs between steps, retry, goto, failure) with a fake
+  `fetch`. `tests/unit/mcp-project.test.js` runs the exported project for real: it starts `server.ts`
+  (through `scripts/test-loader.mjs` instead of `tsx`) under `.test-tmp/`, drives it with the MCP
+  SDK's stdio client (`@modelcontextprotocol/sdk`, a root dev dependency) and points
+  `API_BASE_URL` at `@rapidoc/mock` serving the same Petstore spec, workflow tools included.
+- `/examples/mcp-server` on the docs site shows the manifest, `server.ts` and `runtime.js` and
+  downloads the project. After editing, `npm run lint` and `npm run format-fix`.