jamdesk 1.1.200 → 1.1.201

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.200",
+  "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

@@ -388,9 +388,12 @@ export async function resolveDerivedDescription(
     // 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
+    // `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);

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",