npm - jamdesk - Versions diffs - 1.1.70 → 1.1.72 - Mend

jamdesk 1.1.70 → 1.1.72

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (103) hide show

package/dist/__tests__/integration/validate.integration.test.js +21 -0
package/dist/__tests__/integration/validate.integration.test.js.map +1 -1
package/dist/__tests__/unit/dev-loading-server.test.js +30 -14
package/dist/__tests__/unit/dev-loading-server.test.js.map +1 -1
package/dist/__tests__/unit/extract-hooks.test.js +102 -1
package/dist/__tests__/unit/extract-hooks.test.js.map +1 -1
package/dist/__tests__/unit/mdx-validator.test.js +22 -0
package/dist/__tests__/unit/mdx-validator.test.js.map +1 -1
package/dist/__tests__/unit/migrate-mdx.test.js +121 -1
package/dist/__tests__/unit/migrate-mdx.test.js.map +1 -1
package/dist/__tests__/unit/relative-mdx-imports.test.d.ts +2 -0
package/dist/__tests__/unit/relative-mdx-imports.test.d.ts.map +1 -0
package/dist/__tests__/unit/relative-mdx-imports.test.js +452 -0
package/dist/__tests__/unit/relative-mdx-imports.test.js.map +1 -0
package/dist/__tests__/unit/relocate-snippets.test.d.ts +2 -0
package/dist/__tests__/unit/relocate-snippets.test.d.ts.map +1 -0
package/dist/__tests__/unit/relocate-snippets.test.js +542 -0
package/dist/__tests__/unit/relocate-snippets.test.js.map +1 -0
package/dist/__tests__/unit/run-build-script.test.js +23 -1
package/dist/__tests__/unit/run-build-script.test.js.map +1 -1
package/dist/__tests__/unit/vendored-sync.test.js +5 -0
package/dist/__tests__/unit/vendored-sync.test.js.map +1 -1
package/dist/__tests__/unit/warn-relative-imports.test.d.ts +2 -0
package/dist/__tests__/unit/warn-relative-imports.test.d.ts.map +1 -0
package/dist/__tests__/unit/warn-relative-imports.test.js +44 -0
package/dist/__tests__/unit/warn-relative-imports.test.js.map +1 -0
package/dist/commands/dev.d.ts.map +1 -1
package/dist/commands/dev.js +16 -1
package/dist/commands/dev.js.map +1 -1
package/dist/commands/migrate/convert-mdx.d.ts +5 -1
package/dist/commands/migrate/convert-mdx.d.ts.map +1 -1
package/dist/commands/migrate/convert-mdx.js +19 -6
package/dist/commands/migrate/convert-mdx.js.map +1 -1
package/dist/commands/migrate/extract-hooks.d.ts +26 -0
package/dist/commands/migrate/extract-hooks.d.ts.map +1 -1
package/dist/commands/migrate/extract-hooks.js +71 -12
package/dist/commands/migrate/extract-hooks.js.map +1 -1
package/dist/commands/migrate/fix-mdx-syntax.d.ts +38 -0
package/dist/commands/migrate/fix-mdx-syntax.d.ts.map +1 -0
package/dist/commands/migrate/fix-mdx-syntax.js +80 -0
package/dist/commands/migrate/fix-mdx-syntax.js.map +1 -0
package/dist/commands/migrate/index.d.ts.map +1 -1
package/dist/commands/migrate/index.js +165 -3
package/dist/commands/migrate/index.js.map +1 -1
package/dist/commands/migrate/relocate-snippets.d.ts +30 -0
package/dist/commands/migrate/relocate-snippets.d.ts.map +1 -0
package/dist/commands/migrate/relocate-snippets.js +357 -0
package/dist/commands/migrate/relocate-snippets.js.map +1 -0
package/dist/commands/validate.d.ts.map +1 -1
package/dist/commands/validate.js +31 -1
package/dist/commands/validate.js.map +1 -1
package/dist/lib/deps.d.ts.map +1 -1
package/dist/lib/deps.js +7 -5
package/dist/lib/deps.js.map +1 -1
package/dist/lib/docs-config.d.ts +1 -0
package/dist/lib/docs-config.d.ts.map +1 -1
package/dist/lib/docs-config.js +53 -6
package/dist/lib/docs-config.js.map +1 -1
package/dist/lib/mdx-syntax-fixes.d.ts +14 -0
package/dist/lib/mdx-syntax-fixes.d.ts.map +1 -0
package/dist/lib/mdx-syntax-fixes.js +38 -0
package/dist/lib/mdx-syntax-fixes.js.map +1 -0
package/dist/lib/mdx-validator.d.ts +11 -2
package/dist/lib/mdx-validator.d.ts.map +1 -1
package/dist/lib/mdx-validator.js +41 -4
package/dist/lib/mdx-validator.js.map +1 -1
package/dist/lib/relative-mdx-imports.d.ts +44 -0
package/dist/lib/relative-mdx-imports.d.ts.map +1 -0
package/dist/lib/relative-mdx-imports.js +145 -0
package/dist/lib/relative-mdx-imports.js.map +1 -0
package/dist/lib/run-build-script.d.ts.map +1 -1
package/dist/lib/run-build-script.js +7 -0
package/dist/lib/run-build-script.js.map +1 -1
package/dist/lib/warn-relative-imports.d.ts +2 -0
package/dist/lib/warn-relative-imports.d.ts.map +1 -0
package/dist/lib/warn-relative-imports.js +29 -0
package/dist/lib/warn-relative-imports.js.map +1 -0
package/package.json +2 -2
package/vendored/app/(jd-system)/jd-inactive/BrandedInactive.tsx +118 -0
package/vendored/app/(jd-system)/jd-inactive/layout.tsx +12 -0
package/vendored/app/(jd-system)/jd-inactive/page.tsx +40 -0
package/vendored/app/(unlock)/jd/unlock/page.tsx +32 -0
package/vendored/app/[[...slug]]/page.tsx +63 -15
package/vendored/app/globals.css +5 -0
package/vendored/app/layout.tsx +36 -0
package/vendored/components/navigation/Header.tsx +4 -2
package/vendored/components/navigation/SocialFooter.tsx +4 -18
package/vendored/lib/branding-url.ts +9 -0
package/vendored/lib/build/error-parser.ts +26 -0
package/vendored/lib/docs-isr.ts +33 -19
package/vendored/lib/docs-types.ts +1 -1
package/vendored/lib/email-notifier.ts +1 -1
package/vendored/lib/isr-build-executor.ts +1 -1
package/vendored/lib/layout-helpers.tsx +54 -2
package/vendored/lib/middleware-helpers.ts +46 -8
package/vendored/lib/preprocess-mdx.ts +62 -15
package/vendored/lib/redis.ts +86 -0
package/vendored/lib/revalidation-trigger.ts +29 -15
package/vendored/lib/validate-config.ts +68 -7
package/vendored/schema/docs-schema.json +1 -1
package/vendored/scripts/compile-snippets.cjs +50 -7
package/vendored/themes/index.ts +6 -4
package/vendored/workspace-package-lock.json +118 -133

package/vendored/lib/layout-helpers.tsx CHANGED Viewed

@@ -26,6 +26,31 @@ import { LinkPrefixProvider } from '@/lib/link-prefix-context';
 import { ProjectSlugProvider } from '@/lib/project-slug-context';
 import { getAnalyticsScript } from '@/lib/analytics-script';
+const scrollLockBootstrap = `
+(function() {
+  try {
+    if ('scrollRestoration' in history) history.scrollRestoration = 'manual';
+    var unlocked = false;
+    function unlock() {
+      if (unlocked) return;
+      unlocked = true;
+      var el = document.getElementById('content-scroll-container');
+      if (el) el.scrollTop = 0;
+      document.documentElement.removeAttribute('data-scroll-locked');
+    }
+    function ready() {
+      requestAnimationFrame(function() { requestAnimationFrame(unlock); });
+    }
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', ready, { once: true });
+    } else {
+      ready();
+    }
+    setTimeout(unlock, 2000);
+  } catch (e) {}
+})();
+`;
 // Pre-load fonts at module scope — Next.js requires this for static analysis.
 export const inter = Inter({
   subsets: ['latin'],
@@ -216,7 +241,10 @@ export async function DocsChrome({
   customJs,
   children,
 }: DocsChromeProps): Promise<React.ReactElement> {
-  const themeName = config.theme as ThemeName | undefined;
+  // Lowercase to match docs-config canonical case — `data-theme="nebula"` CSS
+  // selectors are case-sensitive, so `theme: "NEBULA"` from disk would silently
+  // skip every theme-scoped rule without this normalization.
+  const themeName = (config.theme?.toLowerCase() as ThemeName | undefined) ?? undefined;
   const themeCss = themeName && themeName !== 'jam' ? getThemeCssContent(themeName) : null;
   const fontClassName = getFontClassName(themeName, config.fonts);
@@ -259,8 +287,32 @@ export async function DocsChrome({
   preload('/_jd/fonts/fontawesome/webfonts/fa-brands-400.woff2', { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' });
   return (
-    <html lang={lang} dir={dir} suppressHydrationWarning data-scroll-behavior="smooth">
+    <html lang={lang} dir={dir} suppressHydrationWarning data-scroll-behavior="smooth" data-scroll-locked="true">
       <head>
+        {/*
+          SSR scroll lock — prevents Chrome's same-tab cross-origin "preserve
+          scroll" heuristic from scrolling #content-scroll-container on first
+          paint. Custom inner-scroll layout (body{overflow:hidden} +
+          #content-scroll-container{overflow-y:auto}) means body.scrollY=0 but
+          the inner container inherits the previous origin's scroll ratio.
+          history.scrollRestoration='manual' doesn't suppress this code path.
+          Solution: ship overflow-y:hidden on the container via a CSS rule
+          gated on html[data-scroll-locked], release it on DOMContentLoaded +
+          2 frames so Chrome's restore attempts hit a structurally
+          non-scrollable element (scrollTop pinned to 0).
+        */}
+        <script
+          dangerouslySetInnerHTML={{
+            __html: scrollLockBootstrap,
+          }}
+        />
+        {/* JS-off fallback — bootstrap can't unlock, so override the rule. */}
+        <noscript
+          dangerouslySetInnerHTML={{
+            __html:
+              '<style>html[data-scroll-locked] #content-scroll-container{overflow-y:auto !important;}</style>',
+          }}
+        />
         <meta name="viewport" content="width=device-width, initial-scale=1" />
         {config.fonts && (
           <>

package/vendored/lib/middleware-helpers.ts CHANGED Viewed

@@ -13,7 +13,7 @@ import {
   getProjectConfig,
   isSubdomain,
 } from './project-resolver';
-import { redis } from './redis';
+import { redis, getProjectInactive } from './redis';
 import { getForwardedHosts, isJamdeskDomain } from './domain-helpers';
 import { getRedirects, matchRedirect, mergeQueryStrings, isInvalidDestination } from './redirect-matcher';
 import { ASSET_PREFIX } from './docs-types';
@@ -46,6 +46,20 @@ export interface ProjectResolutionResult {
   skip?: boolean;
   /** Domain verification status */
   domainStatus?: string;
+  /**
+   * Project owner's subscription is inactive — proxy rewrites to the
+   * `/jd-inactive` placeholder instead of serving real content. Set by
+   * Stripe webhook propagation (canceled/past_due/incomplete_expired)
+   * and cleared on successful payment.
+   */
+  inactive?: boolean;
+  /**
+   * True when the project resolved via the custom-domain branch
+   * (i.e., a user's own domain pointing at our CNAME), vs via the
+   * subdomain branch (slug.jamdesk.app). Used by the branded inactive
+   * page to show owner-sign-in hints only to real customers.
+   */
+  customDomain?: boolean;
 }
 /**
@@ -127,24 +141,33 @@ export async function handleProjectResolution(
       const customForwardedHost = forwardedHosts.find(h => !isJamdeskDomain(h));
       if (customForwardedHost) {
-        // Resolve hostAtDocs from custom domain config
-        const customResolution = await resolveCustomDomain(customForwardedHost);
+        // Resolve hostAtDocs from custom domain config (batched with
+        // inactive flag — both are Redis reads off the resolved slug).
+        const [customResolution, inactive] = await Promise.all([
+          resolveCustomDomain(customForwardedHost),
+          getProjectInactive(projectSlug),
+        ]);
         log('info', 'Project resolved from subdomain with forwarded custom domain', {
           hostname,
           projectSlug,
           forwardedHost: customForwardedHost,
           hostAtDocs: customResolution.hostAtDocs,
+          inactive,
         });
         return {
           projectSlug,
           hostAtDocs: customResolution.hostAtDocs,
+          inactive,
         };
       }
-      // No forwarded custom domain - use project config
-      const config = await getProjectConfig(projectSlug);
-      log('info', 'Project resolved from subdomain', { hostname, projectSlug });
-      return { projectSlug, hostAtDocs: config.hostAtDocs };
+      // No forwarded custom domain — batch config + inactive lookup.
+      const [config, inactive] = await Promise.all([
+        getProjectConfig(projectSlug),
+        getProjectInactive(projectSlug),
+      ]);
+      log('info', 'Project resolved from subdomain', { hostname, projectSlug, inactive });
+      return { projectSlug, hostAtDocs: config.hostAtDocs, inactive };
     }
   }
@@ -171,11 +194,17 @@ export async function handleProjectResolution(
     };
   }
-  log('info', 'Project resolved from custom domain', { hostname, projectSlug: resolution.projectSlug });
+  // Piggyback inactive read on the custom-domain resolution path. Single
+  // extra Redis GET per request; the proxy reads .inactive to rewrite.
+  const inactive = await getProjectInactive(resolution.projectSlug);
+  log('info', 'Project resolved from custom domain', { hostname, projectSlug: resolution.projectSlug, inactive });
   return {
     projectSlug: resolution.projectSlug,
     hostAtDocs: resolution.hostAtDocs,
     domainStatus: resolution.domainStatus,
+    inactive,
+    customDomain: true,
   };
 }
@@ -558,6 +587,15 @@ const TRUSTED_PROXY_HEADERS = [
   'x-host-at-docs',
   'x-jd-language',
   'x-jd-unlock-mode',
+  // Placeholder branch — set by the inactive rewrite. The layout
+  // gate (`x-jd-layout: placeholder`) controls whether the chrome is
+  // skipped, and a forged `x-jd-custom-domain: 1` would let an
+  // attacker on a subdomain ALSO toggle the "owner can sign in"
+  // copy. Strip them all from the inbound request.
+  'x-jd-layout',
+  'x-jd-custom-domain',
+  'x-jd-project-name',
+  'x-jd-project-logo',
 ] as const;
 /**

package/vendored/lib/preprocess-mdx.ts CHANGED Viewed

@@ -39,31 +39,37 @@ const JSX_CONTENT_COMPONENTS = [
   'Visibility',
 ] as const;
+// Match a fenced code block (``` or ~~~), used to mask code-block content
+// before scanning for top-level snippet imports — otherwise import lines
+// inside docs-on-snippets code examples are treated as real imports and
+// trigger 5+ failing R2 fetches per page render.
+const FENCED_CODE_BLOCK_RE =
+  /^( *)(```+|~~~+)[^\n]*\n([\s\S]*?)\n\1\2\s*$/gm;
 /**
  * Strip snippet import statements from MDX content.
  *
- * Removes import statements that reference the /snippets/ directory:
- * - import { Component } from "/snippets/file.mdx"
- * - import { Component } from '../snippets/file.mdx'
- * - import Component from "/snippets/file.mdx"
- *
- * Note: Relative MDX imports (./file.mdx, ../folder/file.mdx) that DON'T
- * reference /snippets/ are NOT stripped. These need to be handled by MDX
- * compiler or will fail at build time with a helpful error.
+ * Imports inside fenced code blocks are preserved (documentation examples).
  *
  * @param content - Raw MDX content
  * @returns MDX content with snippet imports removed
  */
 export function stripSnippetImports(content: string): string {
-  // Only strip imports from /snippets/ directory
   const snippetsPattern = /^import\s+(?:(?:\{[^}]*\}|\*\s+as\s+\w+|\w+)\s+from\s+)?["'](?:\.\.\/)*\/?snippets\/[^"']+["'];?\s*$/gm;
-  return content.replace(snippetsPattern, '');
+  const codeBlocks: string[] = [];
+  const masked = content.replace(FENCED_CODE_BLOCK_RE, (match) => {
+    const idx = codeBlocks.length;
+    codeBlocks.push(match);
+    return '\0CB' + idx + '\0';
+  });
+  const stripped = masked.replace(snippetsPattern, '');
+  return stripped.replace(/\0CB(\d+)\0/g, (_, idx) => codeBlocks[Number(idx)]);
 }
 /**
  * Extract snippet import information from MDX content.
- * Only matches imports from /snippets/ directory.
+ *
+ * Imports inside fenced code blocks are ignored (documentation examples).
  *
  * @param content - Raw MDX content
  * @returns Array of import info objects
@@ -74,12 +80,11 @@ export function extractSnippetImports(content: string): Array<{
   path: string;
 }> {
   const results: Array<{ statement: string; imports: string[]; path: string }> = [];
-  // Match import statements from /snippets/
+  const scanContent = content.replace(FENCED_CODE_BLOCK_RE, '');
   const importPattern = /^(import\s+(?:(?:\{([^}]*)\}|(\w+)|\*\s+as\s+(\w+))\s+from\s+)?["']((?:\.\.\/)*\/?snippets\/[^"']+)["'];?\s*)$/gm;
   let match;
-  while ((match = importPattern.exec(content)) !== null) {
+  while ((match = importPattern.exec(scanContent)) !== null) {
     const [, statement, namedImports, defaultImport, namespaceImport, importPath] = match;
     const imports: string[] = [];
@@ -518,6 +523,42 @@ export function normalizeJsxIndentation(content: string): string {
   return result.join('\n');
 }
+/**
+ * Un-indent a closing JSX tag absorbed into the previous markdown list item.
+ *
+ * Distinct from `unindentJsxAfterListItems` below: that one rewrites indented
+ * *opening* tags inside list context. Here the opening tag is at root level
+ * and only the closing tag is indented after the list — markdown reads it as
+ * listItem continuation, so MDX compiles see the parent component as unclosed
+ * ("Expected the closing tag `</Card>` either after the end of `listItem`...").
+ *
+ * CLI mirror: `builder/cli/src/lib/mdx-syntax-fixes.ts` — keep regex in sync.
+ */
+export function unindentClosingTagAfterList(content: string): string {
+  // Hot-path prefilter — preprocessMdx runs on every page render, and most
+  // MDX has no indented closing tags at all. Skip the split+walk in that case.
+  if (!/^\s+<\/[A-Z]/m.test(content)) return content;
+  const closingTagPattern = /^(\s+)(<\/[A-Z][\w-]*>)\s*$/;
+  const listItemPattern = /^\s*(?:[-*+]\s|\d+\.\s)/;
+  const lines = content.split('\n');
+  const out: string[] = [];
+  let lastNonBlank = '';
+  for (const line of lines) {
+    const closing = line.match(closingTagPattern);
+    if (closing && listItemPattern.test(lastNonBlank)) {
+      out.push(closing[2]);
+      lastNonBlank = closing[2];
+      continue;
+    }
+    out.push(line);
+    if (line.trim() !== '') lastNonBlank = line;
+  }
+  return out.join('\n');
+}
 /**
  * Un-indent JSX blocks that follow markdown list items.
  *
@@ -997,6 +1038,12 @@ export function preprocessMdx(content: string, options?: { assetVersion?: string
   // Convert noStyle to data-no-style for React compatibility
   processed = convertNoStyleToDataAttr(processed);
+  // Un-indent absorbed closing tags FIRST — handles the case where the
+  // opening tag is at root level but the closing tag got indented after a
+  // list. unindentJsxAfterListItems below only catches cases where the
+  // opening tag itself is indented inside list context.
+  processed = unindentClosingTagAfterList(processed);
   // Un-indent JSX blocks that follow list items to prevent
   // "Expected closing tag before end of listItem" errors
   // This must run BEFORE ensureBlankLinesInJsx since it changes block structure

package/vendored/lib/redis.ts CHANGED Viewed

@@ -115,3 +115,89 @@ export async function deleteDomainAuthSecret(
   if (!kvUrl || !kvToken) return;
   await upstashCommand(kvUrl, kvToken, 'DEL', `domainAuthSecret:${hostname}`);
 }
+// ---------------------------------------------------------------------------
+// Project inactive flag.
+// Set when the project owner's subscription is canceled, past_due, or
+// incomplete_expired. Read by builder/proxy middleware to serve the
+// inactive placeholder instead of the real site. No TTL — the flag lives
+// until explicitly cleared by a successful payment webhook.
+// Fails open (returns false) both when Redis is not configured AND when
+// the underlying GET throws (network blip, Upstash outage). Availability
+// wins over the inactive-site gate — a flaky Redis shouldn't 500 every
+// request on every docs site.
+// ---------------------------------------------------------------------------
+const PROJECT_INACTIVE_PREFIX = 'projectInactive:';
+// Key shape: projectInactive:<slug>. The project ID is NOT the edge
+// key — callers with a projectId must resolve via the dashboard's
+// `writeProjectInactiveBySlug` helper first.
+export async function getProjectInactive(slug: string): Promise<boolean> {
+  if (!redis) return false;
+  try {
+    // Upstash SDK auto-parses the body as JSON, so the stored string
+    // "1" comes back as the number 1. Accept either to keep the gate
+    // honest regardless of how the value round-trips.
+    const value = await redis.get<string | number>(
+      `${PROJECT_INACTIVE_PREFIX}${slug}`,
+    );
+    return value === '1' || value === 1;
+  } catch (err) {
+    console.warn('[redis] getProjectInactive failed, failing open:', {
+      slug,
+      error: (err as Error).message,
+    });
+    return false;
+  }
+}
+export async function setProjectInactive(
+  slug: string,
+  inactive: boolean,
+): Promise<void> {
+  if (!redis) return;
+  const key = `${PROJECT_INACTIVE_PREFIX}${slug}`;
+  if (inactive) {
+    await redis.set(key, '1');
+  } else {
+    await redis.del(key);
+  }
+}
+// ---------------------------------------------------------------------------
+// Project meta (display name + logo) for the inactive placeholder.
+// Mirrored to Redis at the same write site as projectInactive so the edge
+// brand mark renders without a Firestore or R2 round trip. Lifecycle is
+// 1:1 with projectInactive — written when the flag is set, deleted when
+// it's cleared. Optional logoUrl tracks docs.json `logo` (single string
+// only; theme-variant maps degrade to the name-only brand mark).
+// ---------------------------------------------------------------------------
+const PROJECT_META_PREFIX = 'projectMeta:';
+export interface ProjectMeta {
+  name: string;
+  logoUrl?: string;
+}
+export async function getProjectMeta(
+  slug: string,
+): Promise<ProjectMeta | null> {
+  if (!redis) return null;
+  try {
+    const value = await redis.get<ProjectMeta>(
+      `${PROJECT_META_PREFIX}${slug}`,
+    );
+    if (!value || typeof value.name !== 'string' || !value.name) {
+      return null;
+    }
+    return value;
+  } catch (err) {
+    console.warn('[redis] getProjectMeta failed, returning null:', {
+      slug,
+      error: (err as Error).message,
+    });
+    return null;
+  }
+}

package/vendored/lib/revalidation-trigger.ts CHANGED Viewed

@@ -19,7 +19,13 @@ export interface RevalidationOptions {
 export async function triggerRevalidation(options: RevalidationOptions): Promise<void> {
   const { projectSlug, changedPaths, all } = options;
-  const isrAppUrl = process.env.ISR_APP_URL || process.env.VERCEL_DEPLOYMENT_URL || 'https://docs.jamdesk.app';
+  // Fail loud if unset — the previous default `https://docs.jamdesk.app` is an
+  // orphan domain whose cert silently expired (May 2026 incident); falling back
+  // to it produced "fetch failed" with no clue to the cause.
+  const isrAppUrl = (process.env.ISR_APP_URL || process.env.VERCEL_DEPLOYMENT_URL || '').trim();
+  if (!isrAppUrl) {
+    throw new Error('Revalidation failed: ISR_APP_URL not configured');
+  }
   const secret = (process.env.REVALIDATE_SECRET || '').trim();
   const body: Record<string, unknown> = {
@@ -55,22 +61,30 @@ async function revalidateIsrApp(
   secret: string,
   body: Record<string, unknown>,
 ): Promise<{ ok: boolean; status?: number; error?: string; revalidated?: string[] }> {
-  const response = await fetch(`${isrAppUrl}/api/revalidate`, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'x-revalidate-secret': secret,
-    },
-    body: JSON.stringify(body),
-  });
+  // Wrap fetch in try/catch so network-level failures (DNS, TLS, ECONNREFUSED)
+  // surface through the same { ok: false } path as HTTP errors. Without this,
+  // a raw `TypeError: fetch failed` escapes to the build error handler with no
+  // hint that revalidation was the failing step (May 2026 incident).
+  try {
+    const response = await fetch(`${isrAppUrl}/api/revalidate`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-revalidate-secret': secret,
+      },
+      body: JSON.stringify(body),
+    });
-  if (!response.ok) {
-    const error = await response.text();
-    return { ok: false, status: response.status, error };
-  }
+    if (!response.ok) {
+      const error = await response.text();
+      return { ok: false, status: response.status, error };
+    }
-  const result = (await response.json()) as { success: boolean; revalidated?: string[] };
-  return { ok: true, revalidated: result.revalidated };
+    const result = (await response.json()) as { success: boolean; revalidated?: string[] };
+    return { ok: true, revalidated: result.revalidated };
+  } catch (err) {
+    return { ok: false, error: `${(err as Error).message} (url=${isrAppUrl})` };
+  }
 }
 /** Purge the proxy's Vercel CDN cache. Non-fatal on failure. */

package/vendored/lib/validate-config.ts CHANGED Viewed

@@ -64,6 +64,44 @@ export interface ValidationResult {
 type Schema = Record<string, unknown>;
+// Migration docs URL — embedded verbatim in every Mintlify-migration error message.
+// error-parser.ts pattern-matches on this string to attach the step-by-step
+// migrate suggestion, so it MUST stay in the user-facing message exactly as below.
+// (Sentinel doubles as the customer-facing link target.)
+export const MIGRATION_DOCS_URL = 'https://jamdesk.com/docs/setup/migration';
+/** Mintlify themes (Mint pre-2.0 + Themes 2.0). Used as a fallback signal when
+ * `$schema` has been stripped during a partial migration attempt. */
+const MINTLIFY_THEMES = [
+  'mint', 'maple', 'palm', 'willow', 'quill', 'aspen', 'linden', 'prism',
+  'almond', 'sequoia', 'luma',
+];
+/** Detect Mintlify by $schema URL — the durable signal Mintlify itself controls. */
+function isMintlifyBySchema(config: unknown): boolean {
+  if (!config || typeof config !== 'object') return false;
+  const schema = (config as Record<string, unknown>).$schema;
+  return typeof schema === 'string' && schema.includes('mintlify.com');
+}
+/** Detect Mintlify by theme name (fallback when $schema is missing). */
+function isMintlifyByThemeName(theme: unknown): boolean {
+  return typeof theme === 'string' && MINTLIFY_THEMES.includes(theme.toLowerCase());
+}
+/** Build the "needs migration" error result. `reason` is interpolated as the
+ * leading sentence so each detection branch can explain *which* signal fired. */
+function mintlifyMigrationError(reason: string): ValidationResult {
+  return {
+    valid: false,
+    error:
+      `Invalid docs.json: ${reason} This project hasn't been migrated to Jamdesk yet ` +
+      '— run `jamdesk migrate` from your project directory to convert your config ' +
+      `(and Mintlify-only MDX components) automatically. See ${MIGRATION_DOCS_URL} for details.`,
+    errorType: 'config_error',
+  };
+}
 // Cache the schema
 let cachedSchema: Schema | null = null;
@@ -267,6 +305,12 @@ export function formatValidationErrors(errors: ErrorObject[] | null | undefined)
 export async function validateConfig(configPath: string, docsPath?: string): Promise<ValidationResult> {
   // Check file exists
   if (!fs.existsSync(configPath)) {
+    // If `mint.json` sits where docs.json should be, the project is mid-migration
+    // (or hasn't started). Give the migrate hint instead of the generic "missing".
+    const mintPath = path.join(path.dirname(configPath), 'mint.json');
+    if (fs.existsSync(mintPath)) {
+      return mintlifyMigrationError('Found `mint.json` but no `docs.json`.');
+    }
     const pathHint = docsPath
       ? `Missing docs.json at '${docsPath}/docs.json'. Check that your monorepo path is correct.`
       : 'Missing docs.json configuration file. Your repository must have a docs.json file in the root directory.';
@@ -288,7 +332,15 @@ export async function validateConfig(configPath: string, docsPath?: string): Pro
       error: `Failed to parse docs.json: ${error.message}. Ensure your JSON is valid (tip: use JSON5 format to allow comments).`,
     };
   }
+  // Mintlify-shaped configs trip every structural rule below (their
+  // `navigation` is an array, anchors are required keys, etc.). Detect via
+  // $schema BEFORE structural validation so customers see "run jamdesk migrate"
+  // instead of "Array of groups is not supported".
+  if (isMintlifyBySchema(config)) {
+    return mintlifyMigrationError('Mintlify `$schema` detected.');
+  }
   // Basic validation (always runs, even without schema)
   if (!config.name) {
     return {
@@ -327,13 +379,22 @@ export async function validateConfig(configPath: string, docsPath?: string): Pro
     };
   }
-  // Validate theme
+  // Validate theme (case-insensitive — "MINT" still falls through to the Mintlify branch below).
   const validThemes = ['jam', 'nebula', 'pulsar'];
-  if (config.theme && !validThemes.includes(config.theme)) {
-    return {
-      valid: false,
-      error: `Invalid docs.json: Theme "${config.theme}" is not supported. Valid themes are: ${validThemes.join(', ')}.`,
-    };
+  if (typeof config.theme === 'string') {
+    const themeLower = config.theme.toLowerCase();
+    if (!validThemes.includes(themeLower)) {
+      if (isMintlifyByThemeName(config.theme)) {
+        return mintlifyMigrationError(`Theme "${config.theme}" looks like a Mintlify theme.`);
+      }
+      return {
+        valid: false,
+        error: `Invalid docs.json: Theme "${config.theme}" is not supported. Valid themes are: ${validThemes.join(', ')}.`,
+        errorType: 'config_error',
+      };
+    }
+    // Normalize so downstream Ajv schema (lowercase enum) accepts it.
+    config.theme = themeLower as 'jam' | 'nebula' | 'pulsar';
   }
   if (legacyAnchors) {

package/vendored/schema/docs-schema.json CHANGED Viewed

@@ -1577,7 +1577,7 @@
                                 },
                                 "hint": {
                                     "type": "string",
-                                    "description": "Optional hint shown on the unlock page (e.g., \"Ask your account manager\"). Plain text, no HTML.",
+                                    "description": "Optional hint shown on the unlock page (e.g., \"Ask #docs-access on Slack\"). Plain text, no HTML.",
                                     "maxLength": 200
                                 },
                                 "public": {

package/vendored/scripts/compile-snippets.cjs CHANGED Viewed

@@ -321,6 +321,22 @@ export const SnippetComponents: Record<string, React.ComponentType<any>> = {};
   const snippetFiles = findSnippetFiles(snippetsDir);
+  // Deterministic order: within a (dir, baseName) collision, process .mdx
+  // first so the .tsx/.jsx code file overwrites the wrapped-MDX output on
+  // disk. Without this, fs.readdir order varies by platform and the
+  // surviving file content is non-deterministic. Outside of collisions,
+  // the order doesn't matter — sort makes it stable.
+  const EXT_PRIORITY = { '.mdx': 0, '.md': 1, '.ts': 2, '.js': 3, '.tsx': 4, '.jsx': 5 };
+  snippetFiles.sort((a, b) => {
+    const aDir = path.join(a.dir, '');
+    const bDir = path.join(b.dir, '');
+    if (aDir !== bDir) return aDir < bDir ? -1 : 1;
+    const aBase = a.file.replace(/\.[^.]+$/, '');
+    const bBase = b.file.replace(/\.[^.]+$/, '');
+    if (aBase !== bBase) return aBase < bBase ? -1 : 1;
+    return (EXT_PRIORITY[path.extname(a.file)] ?? 99) - (EXT_PRIORITY[path.extname(b.file)] ?? 99);
+  });
   if (snippetFiles.length === 0) {
     console.log('   No snippet files found');
@@ -376,7 +392,8 @@ export const SnippetComponents: Record<string, React.ComponentType<any>> = {};
           name: exportName,
           dir: dir,
           fileName,
-          needsClient
+          needsClient,
+          sourceFile: dir ? path.join(dir, file) : file,
         });
         const status = written ? '(updated)' : '(unchanged)';
@@ -399,7 +416,8 @@ export const SnippetComponents: Record<string, React.ComponentType<any>> = {};
         name: baseName,
         dir: dir,
         fileName,
-        needsClient
+        needsClient,
+        sourceFile: dir ? path.join(dir, file) : file,
       });
       const status = written ? '(updated)' : '(unchanged)';
@@ -414,8 +432,33 @@ export const SnippetComponents: Record<string, React.ComponentType<any>> = {};
   // For locale-specific snippets (e.g., es/Counter), we export under prefixed name (EsCounter).
   // The buildSnippetAliasMap function handles mapping import aliases to the correct component.
+  // Dedupe by (dir, name): two source files with the same base name (e.g.
+  // `vercel-json-generator.mdx` + `vercel-json-generator.tsx`) compile to the
+  // same generated fileName. The on-disk file is correctly overwritten by
+  // the last writer (sorted above so code files win), but componentInfo
+  // would otherwise carry both entries and produce duplicate import/export
+  // lines in ProjectSnippets.tsx. Keep the last (= the code file).
+  const seenComponentKeys = new Map();
+  for (const c of componentInfo) {
+    const key = `${c.dir}|${c.name}`;
+    if (seenComponentKeys.has(key)) {
+      const prior = seenComponentKeys.get(key);
+      // stderr (not stdout) so `runBuildScript` surfaces this in non-verbose
+      // mode — without it, the `jamdesk dev` user sees the collision is
+      // silently resolved and the next collision (a different name) crashes
+      // Turbopack with no breadcrumb.
+      console.warn(
+        `   ⚠ Snippet name collision: "${c.name}" defined in both ` +
+        `${prior.sourceFile} and ${c.sourceFile} — using ${c.sourceFile}. ` +
+        `Remove or rename one of these files to clear this warning.`,
+      );
+    }
+    seenComponentKeys.set(key, c);
+  }
+  const dedupedComponentInfo = [...seenComponentKeys.values()];
   // Build unique import names for each component (prefixed with dir if needed)
-  const importInfo = componentInfo.map(c => {
+  const importInfo = dedupedComponentInfo.map(c => {
     const prefix = c.dir ? toPascalCase(c.dir.replace(/\//g, '-')) : '';
     const uniqueName = prefix + c.name.charAt(0).toUpperCase() + c.name.slice(1);
     // Strip the .tsx extension from fileName to get the import path
@@ -468,17 +511,17 @@ ${importInfo.map(c => `  ${c.uniqueName},`).join('\n')}
     }
   }
-  const clientCount = componentInfo.filter(c => c.needsClient).length;
-  const serverCount = componentInfo.length - clientCount;
+  const clientCount = dedupedComponentInfo.filter(c => c.needsClient).length;
+  const serverCount = dedupedComponentInfo.length - clientCount;
   console.log(`\n✅ Generated snippets:`);
   console.log(`   Index: ${outputPath} ${indexWritten ? '(updated)' : '(unchanged)'}`);
-  console.log(`   Components: ${generatedDir}/ (${componentInfo.length} files)`);
+  console.log(`   Components: ${generatedDir}/ (${dedupedComponentInfo.length} files)`);
   if (removedCount > 0) {
     console.log(`   Removed: ${removedCount} stale file(s)`);
   }
   console.log(`   Client components: ${clientCount}, Server components: ${serverCount}`);
-  console.log(`   Exports: ${componentInfo.map(c => c.name).join(', ')}\n`);
+  console.log(`   Exports: ${dedupedComponentInfo.map(c => c.name).join(', ')}\n`);
 }
 // Run the compilation