jamdesk 1.1.30 → 1.1.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.30",
+  "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';
@@ -192,6 +192,10 @@ function findFirstPage(config: DocsConfig, lang?: string): string {
   return result ? result.replace(/^\//, '') : 'introduction';
 }
 
+function needsSlugRewrite(slug: string[]): boolean {
+  return slug.length === 0 || (slug.length === 1 && isValidLanguageCode(slug[0]));
+}
+
 function resolveSlug(normalizedSlug: string[], config: DocsConfig): string[] {
   if (normalizedSlug.length === 0) return pathToSlug(findFirstPage(config));
   if (normalizedSlug.length === 1 && isValidLanguageCode(normalizedSlug[0])) {
@@ -264,12 +268,17 @@ export async function generateMetadata({ params }: PageProps) {
   // Normalize slug: strip /docs prefix when hostAtDocs=true.
   // Empty root → resolve to first page (see DocPage for the full rationale).
   const normalizedSlug = normalizeSlugForContent(resolvedParams.slug || [], hostAtDocs);
-  const config = await loader.getConfig();
-  const slug = resolveSlug(normalizedSlug, config);
+  const configP = loader.getConfig();
+  const slug = needsSlugRewrite(normalizedSlug)
+    ? resolveSlug(normalizedSlug, await configP)
+    : normalizedSlug;
   const isRoot = normalizedSlug.length === 0;
   const pagePath = slug.join('/');
 
-  const fileContents = await loader.getContent(pagePath).catch(() => null);
+  const [fileContents, config] = await Promise.all([
+    loader.getContent(pagePath).catch(() => null),
+    configP,
+  ]);
 
   if (!fileContents) {
     return {
@@ -345,11 +354,16 @@ export default async function DocPage({ params }: PageProps) {
   // redirect() emits cache-control: private, blocking CDN caching. Canonical
   // + noindex in generateMetadata prevent duplicate indexing.
   const normalizedSlug = normalizeSlugForContent(resolvedParams.slug || [], hostAtDocs);
-  const config = await loader.getConfig();
-  const slug = resolveSlug(normalizedSlug, config);
+  const configP = loader.getConfig();
+  const slug = needsSlugRewrite(normalizedSlug)
+    ? resolveSlug(normalizedSlug, await configP)
+    : normalizedSlug;
   const pagePath = slug.join('/');
   const currentLang = extractLanguageFromPath(`/${pagePath}`);
-  const fileContents = await loader.getContent(pagePath).catch(() => null);
+  const [fileContents, config] = await Promise.all([
+    loader.getContent(pagePath).catch(() => null),
+    configP,
+  ]);
 
   // Check if content exists (getContent returns null via catch if not found)
   if (!fileContents) {
@@ -466,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)
@@ -496,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 {
@@ -513,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
@@ -528,8 +541,8 @@ export default async function DocPage({ params }: PageProps) {
         }
       }
 
-      if (lastError) {
-        throw lastError;
+      if (lastFailure) {
+        throw lastFailure.err;
       }
 
       // Generate code examples
@@ -539,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/lib/ui-strings.ts

@@ -24,8 +24,7 @@ const ZH: Partial<UiStrings> = {
   selectLanguage: '选择语言',
 };
 
-const STRINGS: Partial<Record<LanguageCode, Partial<UiStrings>>> = {
-  en: EN,
+const OVERRIDES: Partial<Record<LanguageCode, Partial<UiStrings>>> = {
   fr: {
     search: 'Rechercher',
     askAi: "Demander à l'IA",
@@ -44,9 +43,12 @@ const STRINGS: Partial<Record<LanguageCode, Partial<UiStrings>>> = {
   cn: ZH,
 };
 
+// Pre-merge so repeated calls return a stable object reference.
+const MERGED: Partial<Record<LanguageCode, UiStrings>> = {};
+for (const [code, overrides] of Object.entries(OVERRIDES) as [LanguageCode, Partial<UiStrings>][]) {
+  MERGED[code] = { ...EN, ...overrides };
+}
+
 export function getUiStrings(lang: LanguageCode | undefined): UiStrings {
-  if (!lang) return EN;
-  const overrides = STRINGS[lang];
-  if (!overrides) return EN;
-  return { ...EN, ...overrides };
+  return (lang && MERGED[lang]) || EN;
 }

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 {

package/vendored/themes/jam/variables.css

@@ -782,19 +782,19 @@ body[data-theme="jam"] .prose video {
 /* Phase 2: Touch Targets for Sidebar */
 @media (max-width: 1023px) {
   :root {
-    --sidebar-item-spacing: 6px;
+    --sidebar-item-spacing: 3px;
   }
 
   .sidebar-scroll ul li a {
-    padding-top: 10px !important;
-    padding-bottom: 10px !important;
-    min-height: 44px;
+    padding-top: 7px !important;
+    padding-bottom: 7px !important;
+    min-height: 36px;
   }
 
   .sidebar-scroll .nav-group-l1 {
-    padding-top: 10px !important;
-    padding-bottom: 10px !important;
-    min-height: 44px;
+    padding-top: 7px !important;
+    padding-bottom: 7px !important;
+    min-height: 36px;
   }
 }
 

package/vendored/themes/nebula/variables.css

@@ -141,19 +141,19 @@
 /* Phase 2: Touch Targets for Sidebar */
 @media (max-width: 1023px) {
   :root {
-    --sidebar-item-spacing: 6px;
+    --sidebar-item-spacing: 3px;
   }
 
   .sidebar-scroll ul li a {
-    padding-top: 10px !important;
-    padding-bottom: 10px !important;
-    min-height: 44px;
+    padding-top: 7px !important;
+    padding-bottom: 7px !important;
+    min-height: 36px;
   }
 
   .sidebar-scroll .nav-group-l1 {
-    padding-top: 10px !important;
-    padding-bottom: 10px !important;
-    min-height: 44px;
+    padding-top: 7px !important;
+    padding-bottom: 7px !important;
+    min-height: 36px;
   }
 }
 

package/vendored/themes/pulsar/variables.css

@@ -896,19 +896,19 @@ body[data-theme="pulsar"] header [data-theme-toggle] {
 /* Phase 3: Touch Targets for Sidebar */
 @media (max-width: 1023px) {
   :root {
-    --sidebar-item-spacing: 6px;
+    --sidebar-item-spacing: 3px;
   }
 
   .sidebar-scroll ul li a {
-    padding-top: 10px !important;
-    padding-bottom: 10px !important;
-    min-height: 44px;
+    padding-top: 7px !important;
+    padding-bottom: 7px !important;
+    min-height: 36px;
   }
 
   .sidebar-scroll .nav-group-l1 {
-    padding-top: 10px !important;
-    padding-bottom: 10px !important;
-    min-height: 44px;
+    padding-top: 7px !important;
+    padding-bottom: 7px !important;
+    min-height: 36px;
   }
 }