jamdesk 1.1.31 → 1.1.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.31",
+  "version": "1.1.32",
   "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/app/[[...slug]]/page.tsx

@@ -70,10 +70,10 @@ import {
   generateCodeExamples,
   formatOpenApiWarning,
   type OpenApiEndpointData,
-  type OpenApiValidationError,
   type CodeExample,
   type AuthMethod,
 } from '@/lib/openapi';
+import { classifyOpenApiLoadError } from '@/lib/openapi/classify-load-error';
 import { extractLanguageFromPath, isValidLanguageCode } from '@/lib/language-utils';
 import { findFirstNavPage } from '@/lib/find-first-nav-page';
 import { candidateSpecPaths } from '@/lib/openapi/lang-spec-path';
@@ -480,6 +480,7 @@ export default async function DocPage({ params }: PageProps) {
   let openApiError: string | null = null;
 
   // OpenAPI spec parsing - supports both static and ISR modes
+  let lastFailure: { err: unknown; specPath: string } | null = null;
   if (data.openapi && typeof data.openapi === 'string') {
     try {
       // Normalize config to array (handles string, array, or undefined)
@@ -510,8 +511,6 @@ export default async function DocPage({ params }: PageProps) {
         : null;
       const contentDir = useIsr ? null : getContentDir();
 
-      let lastError: unknown = null;
-
       for (let i = 0; i < specsToTry.length; i++) {
         const specPath = specsToTry[i];
         try {
@@ -527,10 +526,10 @@ export default async function DocPage({ params }: PageProps) {
             const { api } = await getCachedSpec(specPath, contentDir!);
             openApiEndpointData = parseEndpoint(api, parsed.method, parsed.path, specPath);
           }
-          lastError = null;
+          lastFailure = null;
           break;
         } catch (err) {
-          lastError = err;
+          lastFailure = { err, specPath };
           const isLast = i === specsToTry.length - 1;
           if (!isLast) {
             // Lang variant (or intermediate candidate) failed — log so we
@@ -542,8 +541,8 @@ export default async function DocPage({ params }: PageProps) {
         }
       }
 
-      if (lastError) {
-        throw lastError;
+      if (lastFailure) {
+        throw lastFailure.err;
       }
 
       // Generate code examples
@@ -553,14 +552,11 @@ export default async function DocPage({ params }: PageProps) {
         openApiCodeExamples = generateCodeExamples(openApiEndpointData, { authMethod, languages });
       }
     } catch (err) {
-      const error = err as Partial<OpenApiValidationError>;
-      if (error.type && error.specPath && error.message) {
-        console.warn(formatOpenApiWarning(error as OpenApiValidationError));
-        openApiError = error.message;
-      } else {
-        console.error(`Failed to parse OpenAPI for ${slug.join('/')}:`, err);
-        openApiError = 'Unexpected error loading OpenAPI specification';
-      }
+      const typed = classifyOpenApiLoadError(err, lastFailure?.specPath ?? null);
+      console.warn(formatOpenApiWarning(typed));
+      openApiError = typed.suggestion
+        ? `${typed.message} — ${typed.suggestion}`
+        : typed.message;
     }
   }
 

package/vendored/components/layout/LayoutWrapper.tsx

@@ -107,7 +107,7 @@ export function LayoutWrapper({ config, children }: LayoutWrapperProps) {
           onClose={closeSidebar}
         />
 
-        <div className="flex-1 lg:ml-[295px] flex flex-col lg:h-screen bg-[var(--color-bg-content,var(--color-bg-primary))]">
+        <div className="flex-1 min-w-0 lg:ml-[295px] flex flex-col lg:h-screen bg-[var(--color-bg-content,var(--color-bg-primary))]">
           <Header
             config={config}
             layout={layout}

package/vendored/lib/isr-build-executor.ts

@@ -10,6 +10,7 @@
 import fs from 'fs';
 import path from 'path';
 import glob from 'fast-glob';
+import { isPathWithinProject } from '../shared/path-security.js';
 import type { DocsConfig } from './docs-types.js';
 
 /**
@@ -95,17 +96,100 @@ export async function collectSnippetFiles(projectDir: string): Promise<string[]>
   return files;
 }
 
-/** Collect OpenAPI spec files from project directory. Returns paths relative to openapi/. */
-export async function collectOpenApiFiles(projectDir: string): Promise<string[]> {
-  const openapiDir = `${projectDir}/openapi`;
-  if (!fs.existsSync(openapiDir)) return [];
+/**
+ * An OpenAPI spec file resolved for upload.
+ *
+ * `key` is the R2 key suffix (after `{slug}/`) — it must match what the ISR
+ * fetcher computes from the docs.json path so upload and fetch stay in sync.
+ * `localPath` is the absolute file path on disk.
+ */
+export interface OpenApiFileRef {
+  key: string;
+  localPath: string;
+}
 
-  const files = await glob('**/*.{yaml,yml,json}', {
-    cwd: openapiDir,
-    ignore: ['node_modules/**'],
-  });
+/**
+ * Collect OpenAPI spec files to upload for a project.
+ *
+ * Resolution strategy (symmetric with the ISR fetcher in `r2-content.ts`):
+ * 1. For each path in `docsConfig.api.openapi`, normalize it (strip leading
+ *    `/`), then look for the file at `projectDir/<normalized>`. If not
+ *    found, fall back to `projectDir/openapi/<normalized>` so short-name
+ *    refs like `"foo.yaml"` keep working. Files are uploaded to R2 at
+ *    `{slug}/<normalized>` regardless of disk location so the fetcher's
+ *    `{slug}/<normalized>` lookup succeeds.
+ * 2. Additionally, scan `projectDir/openapi/**` and upload anything there
+ *    at `{slug}/openapi/<relpath>`. Preserves the legacy convention where
+ *    full-form MDX frontmatter (`/openapi/foo.yaml GET /pet`) works even
+ *    when docs.json omits the ref.
+ *
+ * Missing referenced files are logged via `onMissing` (caller decides how
+ * to surface — build log, warning email, etc.) but never fail the build.
+ * HTTP(S) refs are skipped; they are fetched by the ISR renderer directly.
+ */
+export interface CollectOpenApiFilesOptions {
+  openapiRefs?: readonly string[];
+  onMissing?: (ref: string, searchedPaths: readonly string[]) => void;
+}
 
-  return files;
+export async function collectOpenApiFiles(
+  projectDir: string,
+  options: CollectOpenApiFilesOptions = {}
+): Promise<OpenApiFileRef[]> {
+  const { openapiRefs = [], onMissing } = options;
+  const results: OpenApiFileRef[] = [];
+  const seenKeys = new Set<string>();
+
+  // docs.json is user-authored; `isPathWithinProject` rejects `..` traversal,
+  // null bytes, and URL-encoded separators. Does NOT follow symlinks — any
+  // leak still lands in the customer's own R2 prefix, so blast radius is
+  // self-contained.
+
+  // Resolve refs from docs.json.
+  for (const ref of openapiRefs) {
+    if (!ref) continue;
+    if (/^https?:\/\//i.test(ref)) continue; // URLs are fetched by the renderer.
+
+    const normalized = ref.replace(/^\//, '');
+    if (!normalized) continue;
+
+    const primary = path.join(projectDir, normalized);
+    const legacy = path.join(projectDir, 'openapi', normalized);
+    let localPath: string | null = null;
+    if (isPathWithinProject(primary, projectDir) && fs.existsSync(primary)) {
+      localPath = primary;
+    } else if (isPathWithinProject(legacy, projectDir) && fs.existsSync(legacy)) {
+      localPath = legacy;
+    }
+
+    if (!localPath) {
+      onMissing?.(ref, [primary, legacy]);
+      continue;
+    }
+
+    if (!seenKeys.has(normalized)) {
+      seenKeys.add(normalized);
+      results.push({ key: normalized, localPath });
+    }
+  }
+
+  // Legacy scan: anything under `openapi/` gets uploaded at its relative
+  // path. Preserves full-form MDX refs that don't list the spec in docs.json.
+  const openapiDir = path.join(projectDir, 'openapi');
+  if (fs.existsSync(openapiDir)) {
+    const scanned = await glob('**/*.{yaml,yml,json}', {
+      cwd: openapiDir,
+      ignore: ['node_modules/**'],
+    });
+    for (const rel of scanned) {
+      const key = `openapi/${rel}`;
+      if (seenKeys.has(key)) continue;
+      seenKeys.add(key);
+      results.push({ key, localPath: path.join(openapiDir, rel) });
+    }
+  }
+
+  return results;
 }
 
 /**

package/vendored/lib/openapi/classify-load-error.ts

@@ -0,0 +1,19 @@
+import { isR2NotFound } from '../r2-content';
+import { createFileNotFoundError, formatOpenApiError } from './errors';
+import type { OpenApiValidationError } from './types';
+
+/** Maps a raw load error to a typed OpenApiValidationError for the renderer. */
+export function classifyOpenApiLoadError(
+  err: unknown,
+  specPath: string | null
+): OpenApiValidationError {
+  // `'specPath' in err` not truthiness — createFrontmatterError uses `specPath: ''`.
+  if (err && typeof err === 'object' && 'type' in err && 'message' in err && 'specPath' in err) {
+    return err as OpenApiValidationError;
+  }
+  const fallbackPath = specPath || 'unknown';
+  if (isR2NotFound(err)) {
+    return createFileNotFoundError(fallbackPath);
+  }
+  return formatOpenApiError(err, fallbackPath);
+}

package/vendored/shared/status-reporter.ts

@@ -22,7 +22,7 @@ export interface ProgressUpdate {
 }
 
 /** Warning types that can occur during builds (non-blocking) */
-export type BuildWarningType = 'broken_link' | 'auto_migrate' | 'missing_asset' | 'missing_page';
+export type BuildWarningType = 'broken_link' | 'auto_migrate' | 'missing_asset' | 'missing_page' | 'missing_openapi_ref';
 
 /** Build warning structure */
 export interface BuildWarning {