jamdesk 1.0.19 → 1.0.21

package/vendored/lib/search-client.ts

@@ -11,8 +11,7 @@ export interface SearchResult {
   type?: 'api' | 'component' | 'guide' | 'help' | 'quickstart';
 }
 
-// Orama database instance
-let db: Orama<{
+type OramaDb = Orama<{
   id: 'string';
   title: 'string';
   description: 'string';
@@ -20,47 +19,91 @@ let db: Orama<{
   slug: 'string';
   section: 'string';
   type: 'string';
-}> | null = null;
+}>;
 
+// Orama database instance
+let db: OramaDb | null = null;
+// Fingerprint of the data that is currently indexed (committed) or null if not yet built
+let committedFingerprint: string | null = null;
+// Fingerprint of the data currently being built (in-flight), to deduplicate concurrent calls
+let buildingFingerprint: string | null = null;
 let initPromise: Promise<void> | null = null;
+// ETag of the last fetched search-data.json and the parsed data it produced.
+// Lets the modal skip response.json() when the CDN returns the same ETag.
+let lastEtag = '';
+let lastParsedData: SearchResult[] | null = null;
+
+/**
+ * Cheap fingerprint: count + first/last IDs + a sample of content lengths.
+ * Detects new/removed pages AND content edits (which change content length).
+ */
+function fingerprint(data: SearchResult[]): string {
+  if (data.length === 0) return '0';
+  const first = data[0].id;
+  const last = data[data.length - 1].id;
+  const step = Math.max(1, Math.floor(data.length / 8));
+  let contentSig = '';
+  // Sample up to 8 evenly-spaced items' content lengths to detect edits
+  for (let i = 0; i < data.length; i += step) {
+    contentSig += data[i].content.length + ',';
+  }
+  return `${data.length}:${first}:${last}:${contentSig}`;
+}
+
+async function buildIndex(data: SearchResult[], etag: string): Promise<void> {
+  db = await create({
+    schema: {
+      id: 'string',
+      title: 'string',
+      description: 'string',
+      content: 'string',
+      slug: 'string',
+      section: 'string',
+      type: 'string',
+    },
+  });
 
-export async function initializeSearch(data: SearchResult[]): Promise<void> {
-  // Only initialize once
-  if (db) return;
-
-  // Return existing promise if already initializing
-  if (initPromise) return initPromise;
-
-  initPromise = (async () => {
-    db = await create({
-      schema: {
-        id: 'string',
-        title: 'string',
-        description: 'string',
-        content: 'string',
-        slug: 'string',
-        section: 'string',
-        type: 'string',
-      },
-    });
-
-    // Normalize data - ensure all fields are strings
-    const normalizedData = data.map(item => ({
-      id: item.id,
-      title: item.title,
-      description: item.description || '',
-      content: item.content,
-      slug: item.slug,
-      section: item.section || '',
-      type: item.type || 'guide',
-    }));
-
-    await insertMultiple(db, normalizedData);
-  })();
+  const normalizedData = data.map(item => ({
+    id: item.id,
+    title: item.title,
+    description: item.description || '',
+    content: item.content,
+    slug: item.slug,
+    section: item.section || '',
+    type: item.type || 'guide',
+  }));
 
+  await insertMultiple(db, normalizedData);
+  committedFingerprint = buildingFingerprint;
+  lastParsedData = data;
+  lastEtag = etag;
+}
+
+export async function initializeSearch(data: SearchResult[], etag = ''): Promise<void> {
+  const fp = fingerprint(data);
+
+  // Skip rebuild if the committed index already matches
+  if (fp === committedFingerprint) return;
+
+  // If a build with this exact data is already in flight, wait on it
+  if (initPromise && fp === buildingFingerprint) return initPromise;
+
+  // New data available (or first init) — rebuild the index
+  buildingFingerprint = fp;
+  initPromise = buildIndex(data, etag);
   return initPromise;
 }
 
+/**
+ * Returns the previously parsed search data if the given ETag matches the
+ * last successful fetch, so the modal can skip response.json() on unchanged data.
+ * Returns null when the ETag is empty, unknown, or has changed.
+ */
+export function getLastData(etag: string | null): SearchResult[] | null {
+  if (!etag || etag !== lastEtag || !lastParsedData) return null;
+  return lastParsedData;
+}
+
 export async function search(query: string, limit = 10): Promise<SearchResult[]> {
   if (!db) {
     console.warn('Search database not initialized');
@@ -86,6 +129,8 @@ export async function search(query: string, limit = 10): Promise<SearchResult[]>
   return results.hits.map(hit => hit.document as unknown as SearchResult);
 }
 
+/** @internal Used by tests only */
 export function isInitialized(): boolean {
   return db !== null;
 }
+

package/vendored/lib/seo.ts

@@ -11,6 +11,18 @@ import type { Metadata } from 'next';
 import type { DocsConfig, Logo, LogoConfig, Favicon, FaviconConfig, LanguageConfig, LanguageCode } from './docs-types';
 import { transformLanguagePath, extractLanguageFromPath, isValidLanguageCode } from './language-utils';
 
+const HAS_DOCS_SUFFIX = /\b(?:Documentation|Docs)\s*$/i;
+
+/**
+ * Build a display title for the site, appending "Documentation" only when
+ * config.name doesn't already end with a docs-related word.
+ */
+export function buildSiteTitle(configName: string): string {
+  return HAS_DOCS_SUFFIX.test(configName)
+    ? configName
+    : `${configName} Documentation`;
+}
+
 /**
  * Build the OG image URL for a page using the proxy's /api/og endpoint.
  * Returns undefined if og:image is explicitly set in metatags.
@@ -288,3 +300,68 @@ export function buildSeoMetadata(
 
   return metadata;
 }
+
+const MAX_DESCRIPTION_LENGTH = 155;
+
+/** Patterns that indicate a paragraph is not prose (headings, components, images, comments, etc). */
+const NON_PROSE_PATTERNS = [
+  /^#{1,6}\s/,       // headings
+  /^<[A-Z]/,         // MDX components
+  /^!\[/,            // images
+  /^<!--/,           // HTML comments
+  /^>/,              // blockquotes
+  /^[-*_]{3,}\s*$/,  // horizontal rules (---, ***, ___)
+];
+
+function isNonProseParagraph(text: string): boolean {
+  return NON_PROSE_PATTERNS.some((pattern) => pattern.test(text));
+}
+
+/** Strip inline markdown formatting, preserving text content. */
+function stripInlineMarkdown(text: string): string {
+  return text
+    .replace(/!\[([^\]]*)\]\([^)]+\)/g, '')    // inline images
+    .replace(/`[^`]+`/g, '')                    // inline code
+    .replace(/~~(.+?)~~/g, '$1')               // strikethrough
+    .replace(/\*\*(.+?)\*\*/g, '$1')           // bold (non-greedy to handle nested *italic*)
+    .replace(/\*([^*]+)\*/g, '$1')             // italic
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')   // links (keep text)
+    .replace(/<[^>]+>/g, '')                    // HTML tags
+    .replace(/\n/g, ' ')                        // join multi-line paragraph
+    .replace(/\s+/g, ' ')                       // collapse whitespace
+    .trim();
+}
+
+/**
+ * Extract first prose paragraph from MDX content for auto-description.
+ * Skips non-prose blocks (headings, components, code), strips markdown
+ * formatting, and truncates to 155 chars on a word boundary.
+ */
+export function generateAutoDescription(rawContent: string): string {
+  if (!rawContent?.trim()) return '';
+
+  // Strip frontmatter, import/export statements, and code blocks
+  const content = rawContent
+    .replace(/^---[\s\S]*?---\n*/m, '')
+    .replace(/^(import|export)\s+.*$/gm, '')
+    .replace(/```[\s\S]*?```/g, '');
+
+  const paragraphs = content.split(/\n\s*\n/);
+
+  for (const para of paragraphs) {
+    const trimmed = para.trim();
+    if (!trimmed || isNonProseParagraph(trimmed)) continue;
+
+    const stripped = stripInlineMarkdown(trimmed);
+    if (!stripped) continue;
+
+    if (stripped.length <= MAX_DESCRIPTION_LENGTH) return stripped;
+
+    // Truncate on word boundary
+    const truncated = stripped.slice(0, MAX_DESCRIPTION_LENGTH);
+    const lastSpace = truncated.lastIndexOf(' ');
+    return truncated.slice(0, lastSpace > 0 ? lastSpace : MAX_DESCRIPTION_LENGTH) + '...';
+  }
+
+  return '';
+}

package/vendored/lib/static-artifacts.ts

@@ -1,8 +1,8 @@
 /**
  * Static Artifact Generator for ISR Mode
  *
- * Generates sitemap.xml, llms.txt, and robots.txt for ISR projects.
- * These are uploaded to R2 alongside the MDX content.
+ * Generates sitemap.xml, llms.txt, robots.txt, feed.xml, and search-data.json
+ * for ISR projects. These are uploaded to R2 alongside the MDX content.
  */
 
 /**
@@ -178,6 +178,7 @@ export interface RawPageInfo {
     noindex?: boolean;
     hidden?: boolean;
     lastModified?: string;
+    rss?: boolean;
     seo?: {
       noindex?: boolean;
     };
@@ -223,6 +224,8 @@ export interface GenerateAllOptions {
   hostAtDocs?: boolean;
   /** Block all crawlers (seo.metatags.robots: "noindex") */
   noindex?: boolean;
+  /** Pages with rss: true frontmatter (for RSS feed generation) */
+  rssPages?: RssPageInfo[];
 }
 
 /**
@@ -232,6 +235,7 @@ export interface GeneratedArtifacts {
   sitemap: string;
   llmsTxt: string;
   robotsTxt: string;
+  rssFeed: string | null;
 }
 
 /**
@@ -241,15 +245,210 @@ export interface GeneratedArtifacts {
  * @returns Object with all generated artifacts
  */
 export function generateAllArtifacts(options: GenerateAllOptions): GeneratedArtifacts {
-  const { baseUrl, name, description, pages, hostAtDocs, noindex } = options;
+  const {
+    baseUrl, name, description, pages, hostAtDocs, noindex, rssPages,
+  } = options;
 
   const sitemap = generateSitemap({ baseUrl, pages, hostAtDocs, noindex });
-  const llmsTxt = generateLlmsTxt({ name, description, baseUrl, pages, hostAtDocs, noindex });
+  const llmsTxt = generateLlmsTxt({
+    name, description, baseUrl, pages, hostAtDocs, noindex,
+  });
   const robotsTxt = generateRobotsTxt({ baseUrl, hostAtDocs, noindex });
 
-  return { sitemap, llmsTxt, robotsTxt };
+  // Generate RSS feed if any pages have rss: true
+  let rssFeed: string | null = null;
+  if (rssPages && rssPages.length > 0) {
+    const updates = extractUpdatesFromPages(rssPages);
+    if (updates.length > 0) {
+      rssFeed = generateRssFeed({
+        name, description, baseUrl, hostAtDocs, updates,
+      });
+    }
+  }
+
+  return { sitemap, llmsTxt, robotsTxt, rssFeed };
+}
+
+// =============================================================================
+// RSS FEED GENERATION
+// =============================================================================
+
+/**
+ * A single update entry extracted from an MDX page.
+ */
+export interface UpdateEntry {
+  label: string;
+  description?: string;
+  tags?: string[];
+  date?: string;
+  content: string;
+  pagePath: string;
+  pageTitle: string;
+}
+
+/**
+ * Options for generating an RSS feed.
+ */
+export interface RssFeedOptions {
+  name: string;
+  description?: string;
+  baseUrl: string;
+  hostAtDocs?: boolean;
+  updates: UpdateEntry[];
+}
+
+/**
+ * Raw page info with content for RSS extraction.
+ */
+export interface RssPageInfo {
+  path: string;
+  content: string;
+  frontmatter: {
+    title?: string;
+    rss?: boolean;
+  };
 }
 
+/**
+ * Escape XML special characters.
+ */
+function escapeXml(text: string): string {
+  return text
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * Generate a URL-friendly slug from a label string.
+ * Same algorithm as generateUpdateId in Update.tsx.
+ */
+function labelToSlug(label: string): string {
+  return label
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Extract Update component entries from MDX pages with rss: true.
+ */
+export function extractUpdatesFromPages(pages: RssPageInfo[]): UpdateEntry[] {
+  const updates: UpdateEntry[] = [];
+
+  for (const page of pages) {
+    if (!page.frontmatter.rss) continue;
+
+    const pagePath = page.path.replace(/\.mdx?$/, '');
+    const pageTitle = page.frontmatter.title || pagePath;
+
+    // Match <Update ...props>content</Update>
+    // Quoted strings come first in alternation so > inside quotes is consumed correctly
+    const updateRegex = /<Update\s+((?:"[^"]*"|'[^']*'|[^>])*?)>([\s\S]*?)<\/Update>/g;
+    let match;
+
+    while ((match = updateRegex.exec(page.content)) !== null) {
+      const attrsStr = match[1];
+      const content = match[2].trim();
+
+      // Parse label
+      const labelMatch = attrsStr.match(/label=["']([^"']+)["']/);
+      if (!labelMatch) continue; // Skip updates without label
+
+      const label = labelMatch[1];
+
+      // Parse description
+      const descMatch = attrsStr.match(/description=["']([^"']+)["']/);
+      const description = descMatch ? descMatch[1] : undefined;
+
+      // Parse date
+      const dateMatch = attrsStr.match(/date=["']([^"']+)["']/);
+      const date = dateMatch ? dateMatch[1] : undefined;
+
+      // Parse tags - handles tags={["feature", "breaking"]}
+      let tags: string[] | undefined;
+      const tagsMatch = attrsStr.match(/tags=\{(\[[\s\S]*?\])}/);
+      if (tagsMatch) {
+        try {
+          tags = JSON.parse(tagsMatch[1].replace(/'/g, '"'));
+        } catch {
+          // Ignore malformed tags
+        }
+      }
+
+      updates.push({
+        label, description, tags, date, content, pagePath, pageTitle,
+      });
+    }
+  }
+
+  return updates;
+}
+
+/**
+ * Generate RSS 2.0 XML feed from update entries.
+ */
+export function generateRssFeed(options: RssFeedOptions): string {
+  const {
+    name, description, baseUrl, hostAtDocs = false, updates,
+  } = options;
+
+  const urlPrefix = hostAtDocs ? '/docs' : '';
+  const feedUrl = `${baseUrl}${urlPrefix}/feed.xml`;
+  const siteLink = `${baseUrl}${urlPrefix}`;
+  const channelTitle = `${escapeXml(name)} Changelog`;
+  const channelDesc = description
+    ? escapeXml(description)
+    : `Updates and changelog for ${escapeXml(name)}`;
+
+  const items = updates.map(update => {
+    const slug = labelToSlug(update.label);
+    const link = `${baseUrl}${urlPrefix}/${update.pagePath}#${slug}`;
+    const title = update.description
+      ? `${escapeXml(update.label)} \u2014 ${escapeXml(update.description)}`
+      : escapeXml(update.label);
+
+    // Strip markdown and truncate content for description
+    let desc = stripMarkdown(update.content);
+    if (desc.length > 500) {
+      desc = desc.substring(0, 497) + '...';
+    }
+
+    let pubDateLine = '';
+    if (update.date) {
+      const d = new Date(update.date + 'T00:00:00Z');
+      if (!isNaN(d.getTime())) {
+        pubDateLine =
+          `      <pubDate>${d.toUTCString()}</pubDate>\n`;
+      }
+    }
+
+    return `    <item>
+      <title>${title}</title>
+      <link>${link}</link>
+      <guid isPermaLink="true">${link}</guid>
+      <description>${escapeXml(desc)}</description>
+${pubDateLine}    </item>`;
+  });
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+  <channel>
+    <title>${channelTitle}</title>
+    <link>${siteLink}</link>
+    <description>${channelDesc}</description>
+    <atom:link href="${feedUrl}" rel="self" type="application/rss+xml" />
+${items.join('\n')}
+  </channel>
+</rss>`;
+}
+
+// =============================================================================
+// SEARCH INDEX
+// =============================================================================
+
 /**
  * Search document entry.
  */

package/vendored/lib/static-file-route.ts

@@ -1,9 +1,9 @@
 /**
- * Shared handler for static file routes (sitemap.xml, robots.txt, llms.txt, search-data.json).
+ * Shared handler for static file routes (sitemap.xml, robots.txt, llms.txt, search-data.json, feed.xml).
  *
  * All static file routes follow the same pattern: check ISR mode, extract project slug,
  * fetch from R2, and return with appropriate headers. This helper eliminates the
- * duplication across 8 route files (4 at root + 4 at /docs).
+ * duplication across 10 route files (5 at root + 5 at /docs).
  */
 
 import { NextRequest, NextResponse } from 'next/server';
@@ -31,12 +31,17 @@ function getContentType(filename: string): string {
  *
  * @param filename - The R2 filename (e.g., 'sitemap.xml', 'search-data.json')
  * @param label - Human-readable label for log messages (e.g., 'Sitemap', 'Search data')
+ * @param contentTypeOverride - Override the inferred content type (e.g., 'application/rss+xml')
+ * @param cacheControlOverride - Override the default Cache-Control header
  */
 export function createStaticFileHandler(
   filename: string,
-  label: string
+  label: string,
+  contentTypeOverride?: string,
+  cacheControlOverride?: string
 ): (request: NextRequest) => Promise<NextResponse> {
-  const contentType = getContentType(filename);
+  const contentType = contentTypeOverride || getContentType(filename);
+  const cacheControl = cacheControlOverride || 'public, max-age=3600, s-maxage=86400';
 
   return async function GET(request: NextRequest): Promise<NextResponse> {
     if (!isIsrMode()) {
@@ -61,7 +66,7 @@ export function createStaticFileHandler(
       return new NextResponse(content, {
         headers: {
           'Content-Type': contentType,
-          'Cache-Control': 'public, max-age=3600, s-maxage=86400',
+          'Cache-Control': cacheControl,
         },
       });
     } catch (error) {

package/vendored/lib/validate-config.ts

@@ -31,6 +31,7 @@ export interface DocsConfig {
 export interface IntegrationsConfig {
   ga4?: { measurementId: string };
   gtm?: { tagId: string };
+  plausible?: { domain?: string; server?: string; scriptUrl?: string };
   [key: string]: unknown;
 }