jamdesk 1.1.199 → 1.1.201

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.199",
+  "version": "1.1.201",
   "description": "CLI for Jamdesk — build, preview, and deploy documentation sites from MDX. Dev server with hot reload, 50+ components, OpenAPI support, AI search, and Mintlify migration",
   "keywords": [
     "jamdesk",

package/vendored/lib/openapi-isr.ts

@@ -17,32 +17,58 @@ interface OpenApiSpec {
   [key: string]: unknown;
 }
 
-// Cache for OpenAPI specs (longer TTL since specs change infrequently)
-const specCache = new Map<string, { spec: OpenApiSpec; timestamp: number }>();
+// Cache for OpenAPI specs (longer TTL since specs change infrequently).
+//
+// Stores the in-flight PROMISE rather than the resolved value, and stores it
+// BEFORE awaiting. Next.js resolves `generateMetadata` and renders the page
+// component for the same request, and both paths resolve the same spec
+// (render-doc-page.tsx buildDocMetadata + renderDocPage). With a value cache
+// populated only after the await, both missed and both paid a full R2 fetch
+// AND a full SwaggerParser.dereference — the dereference being the expensive
+// half. Caching the promise makes the second caller join the first.
+const specCache = new Map<string, { spec: Promise<OpenApiSpec>; timestamp: number }>();
 const CACHE_TTL = 600_000; // 10 minutes
 
-/** Fetch OpenAPI spec from external URL. */
-export async function fetchOpenApiSpec(url: string): Promise<OpenApiSpec> {
-  // Check cache
-  const cached = specCache.get(url);
+/**
+ * Memoize one spec load on `cacheKey` for CACHE_TTL, de-duplicating concurrent
+ * callers. A rejected load is evicted instead of being served for the rest of
+ * the TTL, so one transient R2 failure cannot pin a project's specs broken for
+ * ten minutes.
+ */
+function cachedSpec(
+  cacheKey: string,
+  produce: () => Promise<OpenApiSpec>,
+): Promise<OpenApiSpec> {
+  const cached = specCache.get(cacheKey);
   if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
     return cached.spec;
   }
 
-  const response = await fetch(url, {
-    headers: { Accept: 'application/json' },
+  const spec = produce();
+  specCache.set(cacheKey, { spec, timestamp: Date.now() });
+  // Evict on failure. The identity check means a later successful entry is
+  // never deleted by an earlier failure resolving after it. Attaching a
+  // handler here also keeps this bookkeeping from surfacing as an unhandled
+  // rejection; the caller still sees the throw from its own await.
+  spec.catch(() => {
+    if (specCache.get(cacheKey)?.spec === spec) specCache.delete(cacheKey);
   });
+  return spec;
+}
 
-  if (!response.ok) {
-    throw new Error(`Failed to fetch OpenAPI spec: ${response.status}`);
-  }
-
-  const spec = (await response.json()) as OpenApiSpec;
-
-  // Cache it
-  specCache.set(url, { spec, timestamp: Date.now() });
+/** Fetch OpenAPI spec from external URL. */
+export function fetchOpenApiSpec(url: string): Promise<OpenApiSpec> {
+  return cachedSpec(url, async () => {
+    const response = await fetch(url, {
+      headers: { Accept: 'application/json' },
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch OpenAPI spec: ${response.status}`);
+    }
 
-  return spec;
+    return (await response.json()) as OpenApiSpec;
+  });
 }
 
 /**
@@ -51,34 +77,23 @@ export async function fetchOpenApiSpec(url: string): Promise<OpenApiSpec> {
  * Handles both YAML and JSON formats, and resolves all internal $ref
  * references (matching the static mode behavior of SwaggerParser.validate).
  */
-export async function fetchOpenApiSpecFromR2(
+export function fetchOpenApiSpecFromR2(
   projectSlug: string,
   specPath: string
 ): Promise<OpenApiSpec> {
-  const cacheKey = `r2:${projectSlug}:${specPath}`;
-
-  // Check cache
-  const cached = specCache.get(cacheKey);
-  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
-    return cached.spec;
-  }
-
-  const content = await fetchOpenApiFile(projectSlug, specPath);
-
-  // Parse YAML or JSON into a plain object
-  const isYaml = /\.ya?ml$/i.test(specPath);
-  const raw = isYaml ? yamlLoad(content) : JSON.parse(content);
-
-  // Dereference all $ref pointers (matching static mode's SwaggerParser.validate behavior).
-  // SwaggerParser.dereference accepts a loose Document type that does not line up with
-  // our internal OpenApiSpec; intermediate `any` cast is required at this library boundary.
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SwaggerParser type interop (see CLAUDE.md memory)
-  const spec = await SwaggerParser.dereference(raw as any) as unknown as OpenApiSpec;
-
-  // Cache it
-  specCache.set(cacheKey, { spec, timestamp: Date.now() });
-
-  return spec;
+  return cachedSpec(`r2:${projectSlug}:${specPath}`, async () => {
+    const content = await fetchOpenApiFile(projectSlug, specPath);
+
+    // Parse YAML or JSON into a plain object
+    const isYaml = /\.ya?ml$/i.test(specPath);
+    const raw = isYaml ? yamlLoad(content) : JSON.parse(content);
+
+    // Dereference all $ref pointers (matching static mode's SwaggerParser.validate behavior).
+    // SwaggerParser.dereference accepts a loose Document type that does not line up with
+    // our internal OpenApiSpec; intermediate `any` cast is required at this library boundary.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SwaggerParser type interop (see CLAUDE.md memory)
+    return await SwaggerParser.dereference(raw as any) as unknown as OpenApiSpec;
+  });
 }
 
 /**

package/vendored/lib/render-doc-page.tsx

@@ -348,6 +348,82 @@ export async function resolveOpenApiMetaDescription(
   return null;
 }
 
+/**
+ * The description used for `<meta>`, the OG/Twitter tags and the OG card
+ * image: authored frontmatter first, then the OpenAPI operation, then the
+ * page's first prose paragraph.
+ *
+ * Shared by `buildDocMetadata` and `renderDocPage` so the meta tags and the
+ * JSON-LD `image` resolve the SAME text. They used to disagree: only the
+ * metadata path resolved a description, so on pages with none authored the
+ * JSON-LD card URL omitted `description=` while og:image carried it, and the
+ * two URLs rendered two genuinely different cards — two OG renders and two CDN
+ * entries per page.
+ *
+ * The gate stays on the RAW value, not frontmatterText(): YAML hands back a
+ * Date for `description: 2026-01-01` and a number for `description: 404`.
+ * Both are truthy and must keep suppressing the fallbacks exactly as before.
+ *
+ * NEVER write the result back onto `data`. `parseFrontmatter` is gray-matter,
+ * whose cache returns a shallow copy that SHARES one `data` object per content
+ * string (gray-matter/index.js:39, `Object.assign({}, cached)`), so an
+ * assignment reached `renderDocPage`'s own parse of the same page and rendered
+ * as the page SUBTITLE: the operation description twice on every spec-backed
+ * page, and the first paragraph twice on every description-less prose page.
+ * The cache is module-global, so it persisted across requests rather than
+ * being a within-request ordering race. (#7 follow-up.)
+ */
+export async function resolveDerivedDescription(
+  config: DocsConfig,
+  data: FrontmatterData,
+  content: string,
+  projectSlug: string | null | undefined,
+): Promise<string | undefined> {
+  let metaDescription: string | undefined = data.description;
+  if (metaDescription) return metaDescription;
+
+  if (typeof data.openapi === 'string' && data.openapi && config.api?.openapi) {
+    // Source the description from the OpenAPI operation before falling back to
+    // first-paragraph extraction (which is empty for prose-less API pages).
+    // The spec loader REUSES the render path's cached loaders — the ISR module
+    // cache (`r2:${slug}:${specPath}`, 10-min TTL) that `renderDocPage`
+    // populates when it renders the page's <ApiEndpoint>, or the static
+    // `getCachedSpec`. That cache stores the in-flight PROMISE, so this lookup
+    // joins the render's load rather than starting a second one — Next.js runs
+    // `generateMetadata` and the page component for the same request, and a
+    // value-cache populated only after the await let BOTH miss and both pay a
+    // full R2 fetch plus a full SwaggerParser.dereference. See openapi-isr.ts
+    // `cachedSpec`. That matters because docs routes are force-dynamic, so this
+    // metadata runs on EVERY page view (every human + crawler). Mirrors the
+    // `useIsr`/`projectDir` derivation in `renderDocPage`'s OpenAPI branch.
+    const specPaths = collectLocalSpecPaths(config.api.openapi);
+    const useIsr = isIsrMode() && !!projectSlug;
+    const projectDir = useIsr ? null : getContentDir();
+    const loadSpecForMeta = async (sp: string): Promise<unknown | null> => {
+      try {
+        if (useIsr && projectSlug) {
+          const { resolveOpenApiSpec } = await import('@/lib/openapi-isr');
+          return await resolveOpenApiSpec(projectSlug, sp);
+        }
+        if (projectDir) {
+          const { api } = await getCachedSpec(sp, projectDir);
+          return api;
+        }
+        return null;
+      } catch {
+        // Any load/parse error degrades to generateAutoDescription below.
+        return null;
+      }
+    };
+    const sourced = await resolveOpenApiMetaDescription(
+      data.openapi, specPaths, loadSpecForMeta,
+    );
+    if (sourced) metaDescription = sourced;
+  }
+
+  return metaDescription || generateAutoDescription(content);
+}
+
 export async function buildDocMetadata(input: RenderInput): Promise<Metadata> {
   const { slug: slugInput, projectSlug, hostAtDocs, docsPrefix, requestHeaders } = input;
   const linkPrefix = docsPrefix ?? (hostAtDocs ? '/docs' : '');
@@ -413,59 +489,9 @@ export async function buildDocMetadata(input: RenderInput): Promise<Metadata> {
   const parsed = parseFrontmatter(fileContents);
   const data = parsed.data as FrontmatterData;
 
-  // DERIVED for <meta>/OG/Twitter/OG-card only — never written back onto
-  // `data`. `parseFrontmatter` is gray-matter, whose cache returns a shallow
-  // copy that SHARES one `data` object per content string, so an assignment
-  // here reached `renderDocPage`'s own parse of the same page and rendered as
-  // the page SUBTITLE: the operation description twice on every spec-backed
-  // page, and the first paragraph twice on every description-less prose page.
-  // The cache is module-global, so it persisted across requests rather than
-  // being a within-request ordering race. (#7 follow-up.)
-  //
-  // The gate stays on the RAW value, not frontmatterText(): YAML hands back a
-  // Date for `description: 2026-01-01` and a number for `description: 404`.
-  // Both are truthy and must keep suppressing the fallbacks exactly as before.
-  let metaDescription: string | undefined = data.description;
-  if (!metaDescription) {
-    if (typeof data.openapi === 'string' && data.openapi && config.api?.openapi) {
-      // Source the description from the OpenAPI operation before falling back to
-      // first-paragraph extraction (which is empty for prose-less API pages).
-      // The spec loader REUSES the render path's cached loaders — the ISR module
-      // cache (`r2:${slug}:${specPath}`, 10-min TTL) that `renderDocPage`
-      // populates when it renders the page's <ApiEndpoint>, or the static
-      // `getCachedSpec`. So the spec is the same warm parse the render already
-      // did: the marginal cost of this lookup is a cache hit, never an uncached
-      // fetch+parse. That matters because docs routes are force-dynamic, so this
-      // metadata runs on EVERY page view (every human + crawler). Mirrors the
-      // `useIsr`/`projectDir` derivation in `renderDocPage`'s OpenAPI branch.
-      const specPaths = collectLocalSpecPaths(config.api.openapi);
-      const useIsr = isIsrMode() && !!projectSlug;
-      const projectDir = useIsr ? null : getContentDir();
-      const loadSpecForMeta = async (sp: string): Promise<unknown | null> => {
-        try {
-          if (useIsr && projectSlug) {
-            const { resolveOpenApiSpec } = await import('@/lib/openapi-isr');
-            return await resolveOpenApiSpec(projectSlug, sp);
-          }
-          if (projectDir) {
-            const { api } = await getCachedSpec(sp, projectDir);
-            return api;
-          }
-          return null;
-        } catch {
-          // Any load/parse error degrades to generateAutoDescription below.
-          return null;
-        }
-      };
-      const sourced = await resolveOpenApiMetaDescription(
-        data.openapi, specPaths, loadSpecForMeta,
-      );
-      if (sourced) metaDescription = sourced;
-    }
-    if (!metaDescription) {
-      metaDescription = generateAutoDescription(parsed.content);
-    }
-  }
+  const metaDescription = await resolveDerivedDescription(
+    config, data, parsed.content, projectSlug,
+  );
 
   // buildSeoMetadata reads `frontmatter.description` for og:, twitter: and the
   // OG card, so it must see the RESOLVED text — via a copy, never by mutating
@@ -611,7 +637,15 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
 
   const baseUrl = resolveBaseUrl(requestHeaders, projectSlug, hostAtDocs);
   const faqPairs = extractFaqPairs(rawContent);
-  const ogImageUrl = buildPageOgImageUrl(config, data, baseUrl, linkPrefix);
+  // The same resolution buildDocMetadata performs, so og:image and the JSON-LD
+  // `image` point at ONE card. Passed as a copy — never a write onto the shared
+  // `data`, which is what caused #7 in the first place.
+  const ogDescription = await resolveDerivedDescription(
+    config, data, rawContent, projectSlug,
+  );
+  const ogImageUrl = buildPageOgImageUrl(
+    config, { ...data, description: ogDescription }, baseUrl, linkPrefix,
+  );
   // See frontmatterText: a YAML Date title throws when React renders it as a
   // child below, so every consumer in this function reads the coerced value.
   const titleText = frontmatterText(data.title);

package/vendored/lib/seo.ts

@@ -879,7 +879,7 @@ const MAX_DESCRIPTION_LENGTH = 155;
 /** Patterns that indicate a paragraph is not prose (headings, components, images, comments, etc). */
 const NON_PROSE_PATTERNS = [
   /^#{1,6}\s/,       // headings
-  /^<[A-Z]/,         // MDX components
+  /^<\/?[A-Z]/,      // MDX components, opening AND closing (`</ResponseExample>`)
   /^!\[/,            // images
   /^<!--/,           // HTML comments
   /^>/,              // blockquotes

package/vendored/workspace-package-lock.json

@@ -68,9 +68,9 @@
       }
     },
     "node_modules/@alloc/quick-lru": {
-      "version": "5.2.0",
-      "resolved": "https://registry.npmjs.org/@alloc/quick-lru/-/quick-lru-5.2.0.tgz",
-      "integrity": "sha512-UrcABB+4bUrFABwbluTIBErXwvbsU/V7TZWfmbgJfbkwiBuziS9gxdODUyuiecfdGQ85jglMW6juS3+z5TsKLw==",
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/@alloc/quick-lru/-/quick-lru-5.3.0.tgz",
+      "integrity": "sha512-U4+70Pc5ZS9osnCBCE5Jha/ciHM+Yp+CNMNC/7HvYbNRk1Ldd+f7qO65W5qfhu/TCv+/ozljlXXe9Nj8419DMA==",
       "license": "MIT",
       "engines": {
         "node": ">=10"
@@ -2290,12 +2290,12 @@
       }
     },
     "node_modules/commander": {
-      "version": "8.3.0",
-      "resolved": "https://registry.npmjs.org/commander/-/commander-8.3.0.tgz",
-      "integrity": "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==",
+      "version": "15.0.0",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-15.0.0.tgz",
+      "integrity": "sha512-z67u4ZhzCL/Tydu1lJARtEZYWbWaN7oYLHbsuzocr6y4N6WZAagG3RQ4FW61V1/0+jImpj293XfrcYnd1qxtPg==",
       "license": "MIT",
       "engines": {
-        "node": ">= 12"
+        "node": ">=22.12.0"
       }
     },
     "node_modules/cose-base": {
@@ -3763,16 +3763,16 @@
       }
     },
     "node_modules/katex": {
-      "version": "0.18.4",
-      "resolved": "https://registry.npmjs.org/katex/-/katex-0.18.4.tgz",
-      "integrity": "sha512-IMPntbRLOU+eu88XDiFKqQ8Akhr9Tv7jDMXqPhjG9SI1JMA4DIgXk4x9k4skJz2NZJXBRbC+2pYBLj9olqcZow==",
+      "version": "0.18.5",
+      "resolved": "https://registry.npmjs.org/katex/-/katex-0.18.5.tgz",
+      "integrity": "sha512-1FU5H3RjGJVj6GT9fMjf2uMIXmPQp232aXS3UEeQzf0dxefHg/CKMvNB3DuOC46LFG/E5PNxrE8dOwB782FDGg==",
       "funding": [
         "https://opencollective.com/katex",
         "https://github.com/sponsors/katex"
       ],
       "license": "MIT",
       "dependencies": {
-        "commander": "^8.3.0"
+        "commander": "^15.0.0"
       },
       "bin": {
         "katex": "cli.js"
@@ -4475,6 +4475,15 @@
         "uuid": "^11.1.0 || ^12 || ^13 || ^14.0.0"
       }
     },
+    "node_modules/mermaid/node_modules/commander": {
+      "version": "8.3.0",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-8.3.0.tgz",
+      "integrity": "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 12"
+      }
+    },
     "node_modules/mermaid/node_modules/katex": {
       "version": "0.16.47",
       "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.47.tgz",
@@ -4700,6 +4709,15 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/micromark-extension-math/node_modules/commander": {
+      "version": "8.3.0",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-8.3.0.tgz",
+      "integrity": "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 12"
+      }
+    },
     "node_modules/micromark-extension-math/node_modules/katex": {
       "version": "0.16.47",
       "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.47.tgz",
@@ -5786,6 +5804,15 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/rehype-katex/node_modules/commander": {
+      "version": "8.3.0",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-8.3.0.tgz",
+      "integrity": "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 12"
+      }
+    },
     "node_modules/rehype-katex/node_modules/katex": {
       "version": "0.16.47",
       "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.47.tgz",