jamdesk 1.1.20 → 1.1.21

package/dist/__tests__/unit/openapi-server-variable-description.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=openapi-server-variable-description.test.d.ts.map

package/dist/__tests__/unit/openapi-server-variable-description.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-server-variable-description.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/unit/openapi-server-variable-description.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/unit/openapi-server-variable-description.test.js

@@ -0,0 +1,55 @@
+/**
+ * Regression guard for the @apidevtools/openapi-schemas@2.1.0 typo in
+ * the OpenAPI 3.1 server-variable schema (`descriptions` instead of
+ * `description`). The patcher at scripts/patch-openapi-schemas.js must
+ * have fixed the installed schema by the time this test runs.
+ *
+ * This test uses the REAL SwaggerParser (not a mock) so it actually
+ * exercises the bundled schema. If the patcher didn't run, or a future
+ * upstream release reintroduces the typo, this test fails.
+ */
+import { describe, it } from 'vitest';
+import SwaggerParser from '@apidevtools/swagger-parser';
+describe('OpenAPI 3.1 server variable description (regression)', () => {
+    it('accepts `description` on a server variable (spec §4.7.10.1)', async () => {
+        const spec = {
+            openapi: '3.1.0',
+            info: { title: 'Regression Test', version: '1.0.0' },
+            servers: [
+                {
+                    url: 'https://{project}.jamdesk.app',
+                    description: 'Production (subdomain)',
+                    variables: {
+                        project: {
+                            default: 'your-project',
+                            description: 'Your Jamdesk project slug',
+                        },
+                    },
+                },
+            ],
+            paths: {},
+        };
+        // Should not throw. If the schema still has `descriptions` (typo), SwaggerParser
+        // rejects `description` as an unevaluated property.
+        await SwaggerParser.validate(spec);
+    });
+    it('accepts a server variable without description (sanity check)', async () => {
+        const spec = {
+            openapi: '3.1.0',
+            info: { title: 'Regression Test', version: '1.0.0' },
+            servers: [
+                {
+                    url: 'https://{project}.jamdesk.app',
+                    variables: {
+                        project: {
+                            default: 'your-project',
+                        },
+                    },
+                },
+            ],
+            paths: {},
+        };
+        await SwaggerParser.validate(spec);
+    });
+});
+//# sourceMappingURL=openapi-server-variable-description.test.js.map

package/dist/__tests__/unit/openapi-server-variable-description.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-server-variable-description.test.js","sourceRoot":"","sources":["../../../src/__tests__/unit/openapi-server-variable-description.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,aAAa,MAAM,6BAA6B,CAAC;AAExD,QAAQ,CAAC,sDAAsD,EAAE,GAAG,EAAE;IACpE,EAAE,CAAC,6DAA6D,EAAE,KAAK,IAAI,EAAE;QAC3E,MAAM,IAAI,GAAG;YACX,OAAO,EAAE,OAAO;YAChB,IAAI,EAAE,EAAE,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,OAAO,EAAE;YACpD,OAAO,EAAE;gBACP;oBACE,GAAG,EAAE,+BAA+B;oBACpC,WAAW,EAAE,wBAAwB;oBACrC,SAAS,EAAE;wBACT,OAAO,EAAE;4BACP,OAAO,EAAE,cAAc;4BACvB,WAAW,EAAE,2BAA2B;yBACzC;qBACF;iBACF;aACF;YACD,KAAK,EAAE,EAAE;SACV,CAAC;QACF,iFAAiF;QACjF,oDAAoD;QACpD,MAAM,aAAa,CAAC,QAAQ,CAAC,IAAa,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8DAA8D,EAAE,KAAK,IAAI,EAAE;QAC5E,MAAM,IAAI,GAAG;YACX,OAAO,EAAE,OAAO;YAChB,IAAI,EAAE,EAAE,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,OAAO,EAAE;YACpD,OAAO,EAAE;gBACP;oBACE,GAAG,EAAE,+BAA+B;oBACpC,SAAS,EAAE;wBACT,OAAO,EAAE;4BACP,OAAO,EAAE,cAAc;yBACxB;qBACF;iBACF;aACF;YACD,KAAK,EAAE,EAAE;SACV,CAAC;QACF,MAAM,aAAa,CAAC,QAAQ,CAAC,IAAa,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.20",
+  "version": "1.1.21",
   "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",
@@ -59,6 +59,7 @@
   "files": [
     "bin/",
     "dist/",
+    "scripts/patch-openapi-schemas.js",
     "templates/",
     "vendored/components/",
     "vendored/contexts/",
@@ -91,7 +92,8 @@
     "test": "vitest",
     "test:local": "node scripts/test-local.js",
     "lint": "eslint src/",
-    "dev": "tsc --watch"
+    "dev": "tsc --watch",
+    "postinstall": "node scripts/patch-openapi-schemas.js"
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^12.1.0",

package/scripts/patch-openapi-schemas.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * Patch a typo in @apidevtools/openapi-schemas@2.1.0.
+ *
+ * The bundled OpenAPI 3.1 meta-schema defines `server-variable.properties`
+ * as `{ enum, default, descriptions }` — but the OpenAPI 3.1 spec says the
+ * third property is `description` (singular). Combined with
+ * `unevaluatedProperties: false` on the same definition, any spec-valid
+ * `description` field on a server variable is rejected with:
+ *
+ *   #/servers/0/variables/<name> must NOT have unevaluated properties
+ *
+ * We swap the typo at install time so swagger-parser accepts the spec.
+ * Idempotent — safe to run multiple times. Deletes itself cleanly once
+ * upstream ships a fix:
+ *
+ *   https://github.com/APIDevTools/openapi-schemas
+ *
+ * This file runs as an npm `postinstall` script in the package root, so
+ * `__dirname` is always `<package>/scripts/` and `node_modules` resolves
+ * one level up.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const schemaPath = path.join(
+  __dirname,
+  '..',
+  'node_modules',
+  '@apidevtools',
+  'openapi-schemas',
+  'schemas',
+  'v3.1',
+  'schema.json'
+);
+
+// If the dep isn't installed (e.g., production install with --omit=dev and
+// swagger-parser moved to devDependencies), silently no-op.
+if (!fs.existsSync(schemaPath)) {
+  process.exit(0);
+}
+
+let schema;
+try {
+  schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+} catch (err) {
+  console.warn(
+    '[jamdesk] patch-openapi-schemas: failed to parse schema, skipping:',
+    err.message
+  );
+  process.exit(0);
+}
+
+const defs = schema && schema.$defs;
+const serverVariable = defs && defs['server-variable'];
+const props = serverVariable && serverVariable.properties;
+
+if (!props) {
+  // Schema shape changed upstream — bail out quietly.
+  process.exit(0);
+}
+
+if (props.description) {
+  // Already patched (or upstream fixed it). Either way, no work to do.
+  process.exit(0);
+}
+
+if (!props.descriptions) {
+  // No typo to fix. Quietly no-op.
+  process.exit(0);
+}
+
+props.description = props.descriptions;
+delete props.descriptions;
+
+try {
+  fs.writeFileSync(schemaPath, JSON.stringify(schema, null, 2));
+} catch (err) {
+  console.warn(
+    '[jamdesk] patch-openapi-schemas: failed to write patch, skipping:',
+    err.message
+  );
+  process.exit(0);
+}
+console.log(
+  '[jamdesk] patched openapi-schemas 3.1 server-variable typo (descriptions → description)'
+);

package/vendored/app/[[...slug]]/page.tsx

@@ -47,7 +47,8 @@ import { mdxSecurityOptions } from '@/lib/mdx-security-options';
 import fs from 'fs';
 import path from 'path';
 import matter from 'gray-matter';
-import { getDocsConfig, getContentDir } from '@/lib/docs';
+import { getContentDir } from '@/lib/docs';
+import type { DocsConfig } from '@/lib/docs-types';
 import { buildSeoMetadata, generateAutoDescription, buildSiteTitle } from '@/lib/seo';
 import { buildJsonLd } from '@/lib/json-ld';
 import {
@@ -182,7 +183,7 @@ function getAllDocPaths(): string[] {
 /**
  * Find the first page in navigation (used to resolve empty root slug in place).
  */
-function findFirstPage(config: ReturnType<typeof getDocsConfig>): string {
+function findFirstPage(config: DocsConfig): string {
   const navigation = config.navigation;
 
   // Helper to extract page path from a page entry
@@ -339,9 +340,10 @@ 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 slug = normalizedSlug.length > 0
-    ? normalizedSlug
-    : pathToSlug(findFirstPage(await loader.getConfig()));
+  const isRoot = normalizedSlug.length === 0;
+  const slug = isRoot
+    ? pathToSlug(findFirstPage(await loader.getConfig()))
+    : normalizedSlug;
   const pagePath = slug.join('/');
 
   // Fetch content and config in parallel
@@ -381,7 +383,7 @@ export async function generateMetadata({ params }: PageProps) {
     ...seoMetadata,
     // Root serves first-page content but canonical points at /{firstPage};
     // noindex as a second dedup signal alongside the canonical tag.
-    ...(normalizedSlug.length === 0 && { robots: { index: false, follow: true } }),
+    ...(isRoot && { robots: { index: false, follow: true } }),
     ...(data.rss ? {
       alternates: {
         ...seoMetadata.alternates,
@@ -420,15 +422,13 @@ export default async function DocPage({ params }: PageProps) {
   const loader = getContentLoader(projectSlug ?? undefined);
 
   // Normalize slug: strip /docs prefix when hostAtDocs=true.
-  // Empty root request → render the first page in place instead of 307'ing
-  // to /{firstPage} (Lighthouse flagged ~1.5s mobile; Next's redirect() emits
-  // cache-control: private so CDNs can't absorb it). Canonical URL still
-  // points at /{firstPage} via buildSeoMetadata, and generateMetadata
-  // noindexes the root to prevent duplicate indexing.
+  // Empty root renders the first page in place rather than 307'ing — Next's
+  // redirect() emits cache-control: private, blocking CDN caching. Canonical
+  // + noindex in generateMetadata prevent duplicate indexing.
   const normalizedSlug = normalizeSlugForContent(resolvedParams.slug || [], hostAtDocs);
-  const slug = normalizedSlug.length > 0
-    ? normalizedSlug
-    : pathToSlug(findFirstPage(await loader.getConfig()));
+  const slug = normalizedSlug.length === 0
+    ? pathToSlug(findFirstPage(await loader.getConfig()))
+    : normalizedSlug;
   const pagePath = slug.join('/');
   const [fileContents, config] = await Promise.all([
     loader.getContent(pagePath).catch(() => null),

package/vendored/components/search/SearchModal.tsx

@@ -10,9 +10,6 @@ import { trackSearch } from '@/lib/analytics-client';
 import { useLinkPrefix } from '@/lib/link-prefix-context';
 import { useProjectSlug } from '@/lib/project-slug-context';
 
-// Build-time env var for client-side configuration
-const projectSlug = process.env.NEXT_PUBLIC_PROJECT_SLUG || 'default';
-
 interface SearchResult {
   id: string;
   title: string;
@@ -104,7 +101,7 @@ function NoResultsState({ query, onSuggestionClick }: { query: string; onSuggest
 
 export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: SearchModalProps) {
   const linkPrefix = useLinkPrefix();
-  const analyticsProjectSlug = useProjectSlug();
+  const projectSlug = useProjectSlug();
   const [query, setQuery] = useState('');
   const [results, setResults] = useState<SearchResult[]>([]);
   const [selectedIndex, setSelectedIndex] = useState(0);
@@ -144,7 +141,7 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
   useEffect(() => {
     if (!isOpen && lastSearchRef.current && !hasTrackedRef.current) {
       // Modal closed with an untracked search - track it now
-      trackSearch(analyticsProjectSlug, {
+      trackSearch(projectSlug, {
         type: 'search_query',
         query: lastSearchRef.current.query,
         resultsCount: lastSearchRef.current.resultsCount,
@@ -155,15 +152,19 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
       hasTrackedRef.current = false;
       lastSearchRef.current = null;
     }
-  }, [isOpen, analyticsProjectSlug]);
+  }, [isOpen, projectSlug]);
 
-  // Load search data and recent searches on mount
+  // Load recent searches (depends on projectSlug from context, kept separate
+  // so search-data init doesn't re-fetch when the slug would hypothetically change)
   useEffect(() => {
     if (isOpen) {
-      // Load recent searches
       setRecentSearches(getRecentSearches(projectSlug));
+    }
+  }, [isOpen, projectSlug]);
 
-      // Initialize search
+  // Load search data on mount
+  useEffect(() => {
+    if (isOpen) {
       setIsInitializing(true);
       setInitError(null);
 
@@ -265,7 +266,7 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
       else if (query.trim() && results.length === 0 && !isSearching && e.key === 'Enter') {
         e.preventDefault();
         // Track this as a committed search with zero results
-        trackSearch(analyticsProjectSlug, {
+        trackSearch(projectSlug, {
           type: 'search_query',
           query: query.trim(),
           resultsCount: 0,
@@ -303,19 +304,19 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
 
     document.addEventListener('keydown', handleKeyDown);
     return () => document.removeEventListener('keydown', handleKeyDown);
-  }, [isOpen, query, recentSearches, results, selectedIndex, effectivePopularPages, popularIndex, router, onClose, onNavigate, analyticsProjectSlug]);
+  }, [isOpen, query, recentSearches, results, selectedIndex, effectivePopularPages, popularIndex, router, onClose, onNavigate, projectSlug]);
 
   const handleResultClick = (result: SearchResult, index: number) => {
     if (query.trim()) {
       // Track search_query event (the search itself)
-      trackSearch(analyticsProjectSlug, {
+      trackSearch(projectSlug, {
         type: 'search_query',
         query: query.trim(),
         resultsCount: results.length,
       });
 
       // Track search_click event (the result they clicked)
-      trackSearch(analyticsProjectSlug, {
+      trackSearch(projectSlug, {
         type: 'search_click',
         query: query.trim(),
         resultsCount: results.length,

package/vendored/lib/analytics-client.ts

@@ -1,14 +1,9 @@
-// Search Analytics Client
-// Tracks search queries and clicks for analytics dashboard.
-//
-// Endpoint is /_jd/search-ev (not /api/search-ev) so that sites fronted by
-// the jamdesk.com Cloudflare Worker — which only proxies /_jd/* — route the
-// request to the ISR app. Middleware rewrites /_jd/search-ev to /api/search-ev.
+// Endpoint is /_jd/search-ev (not /api/search-ev) so sites fronted by the
+// jamdesk.com Cloudflare Worker — which only proxies /_jd/* — reach the ISR
+// app. Middleware rewrites /_jd/search-ev to /api/search-ev.
 
 const ANALYTICS_URL = '/_jd/search-ev';
 
-// Reuse the same session ID as the pageview tracking script (localStorage with 30-min inactivity timeout).
-// Every call refreshes the timestamp, so active users keep the same session.
 const SESSION_TIMEOUT_MS = 1800000; // 30 minutes
 
 function getSessionId(): string {
@@ -29,7 +24,6 @@ function getSessionId(): string {
   return sessionId;
 }
 
-// Use separate event types to avoid double-counting
 interface SearchQueryEvent {
   type: 'search_query';
   query: string;
@@ -50,20 +44,11 @@ interface SearchClickEvent {
 type SearchEvent = SearchQueryEvent | SearchClickEvent;
 
 /**
- * Track a search analytics event.
- *
- * The project slug MUST be supplied at runtime (typically via `useProjectSlug()`
- * from `lib/project-slug-context`). Build-time env vars are not usable because
- * the ISR deployment is multi-tenant and NEXT_PUBLIC_* vars are baked per-build.
- *
- * Fire-and-forget: returns immediately. The fetch runs in the background with
- * `keepalive: true` so it survives page navigation. Errors are silently ignored.
+ * Fire-and-forget. The slug must be supplied at runtime (via `useProjectSlug()`)
+ * because `NEXT_PUBLIC_*` vars are baked per-build and the ISR app is multi-tenant.
  */
 export function trackSearch(projectSlug: string, event: SearchEvent): void {
-  // Don't track in development
   if (process.env.NODE_ENV === 'development') return;
-
-  // Empty slug means we couldn't resolve the project (e.g., non-ISR fallback) — no-op
   if (!projectSlug) return;
 
   try {
@@ -79,10 +64,6 @@ export function trackSearch(projectSlug: string, event: SearchEvent): void {
       headers: { 'Content-Type': 'application/json' },
       body: payload,
       keepalive: true,
-    }).catch(() => {
-      // Silent fail - analytics should never break the app
-    });
-  } catch {
-    // Silent fail - analytics should never break the app
-  }
+    }).catch(() => {});
+  } catch {}
 }

package/vendored/lib/project-slug-context.tsx

@@ -2,16 +2,10 @@
 
 import { createContext, useContext, type ReactNode } from 'react';
 
-/**
- * Context for exposing the resolved project slug to client components.
- *
- * The value is populated in `app/layout.tsx` from the `x-project-slug`
- * request header (set by middleware). Empty string means "unknown" — clients
- * should treat this as a signal to no-op (e.g. skip analytics).
- *
- * Why this exists: `NEXT_PUBLIC_PROJECT_SLUG` is inlined at build time and is
- * unset in the multi-tenant ISR deployment, so client code cannot read it.
- */
+// `NEXT_PUBLIC_PROJECT_SLUG` is inlined at build time and unset in the
+// multi-tenant ISR deployment, so the slug has to flow through context.
+// `layout.tsx` seeds the value from the `x-project-slug` header set by
+// middleware. Empty string means "unknown" — consumers should no-op.
 const ProjectSlugContext = createContext<string>('');
 
 export function ProjectSlugProvider({
@@ -28,9 +22,6 @@ export function ProjectSlugProvider({
   );
 }
 
-/**
- * Hook returning the resolved project slug, or '' when unavailable.
- */
 export function useProjectSlug(): string {
   return useContext(ProjectSlugContext);
 }