jamdesk 1.0.0

package/vendored/lib/static-artifacts.ts

@@ -0,0 +1,375 @@
+/**
+ * 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.
+ */
+
+/**
+ * Page metadata for artifact generation.
+ */
+export interface PageMetadata {
+  /** Page path without extension (e.g., 'introduction', 'api/auth') */
+  path: string;
+  /** Page title */
+  title: string;
+  /** Page description */
+  description?: string;
+  /** Exclude from sitemap/llms.txt */
+  noindex?: boolean;
+  /** Hidden page (also excluded) */
+  hidden?: boolean;
+  /** Last modified date (ISO string or YYYY-MM-DD) */
+  lastModified?: string;
+}
+
+/**
+ * Options for generating sitemap.
+ */
+export interface SitemapOptions {
+  /** Base URL for the site (e.g., 'https://acme.jamdesk.app') */
+  baseUrl: string;
+  /** Array of page metadata */
+  pages: PageMetadata[];
+  /** Whether docs are hosted at /docs path */
+  hostAtDocs?: boolean;
+  /** Block all crawlers - generates empty sitemap */
+  noindex?: boolean;
+}
+
+/**
+ * Generate sitemap.xml from page metadata.
+ *
+ * @param options - Sitemap options
+ * @returns XML string
+ */
+export function generateSitemap(options: SitemapOptions): string {
+  const { baseUrl, pages, hostAtDocs = false, noindex = false } = options;
+
+  if (noindex) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+</urlset>`;
+  }
+
+  const urlPrefix = hostAtDocs ? '/docs' : '';
+
+  const entries = pages
+    .filter(p => !p.noindex && !p.hidden)
+    .map(p => {
+      const url = `${baseUrl}${urlPrefix}/${p.path}`;
+      const lastmod = p.lastModified || new Date().toISOString().split('T')[0];
+      const priority = p.path === 'introduction' ? '1.0' : '0.8';
+
+      return `  <url>
+    <loc>${url}</loc>
+    <lastmod>${lastmod}</lastmod>
+    <changefreq>weekly</changefreq>
+    <priority>${priority}</priority>
+  </url>`;
+    });
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${entries.join('\n')}
+</urlset>`;
+}
+
+/**
+ * Options for generating llms.txt.
+ */
+export interface LlmsTxtOptions {
+  /** Documentation name */
+  name: string;
+  /** Documentation description */
+  description?: string;
+  /** Base URL for the site */
+  baseUrl: string;
+  /** Array of page metadata */
+  pages: PageMetadata[];
+  /** Whether docs are hosted at /docs path */
+  hostAtDocs?: boolean;
+  /** Block all crawlers - generates empty llms.txt */
+  noindex?: boolean;
+}
+
+/**
+ * Generate llms.txt following https://llmstxt.org/ spec.
+ *
+ * @param options - LLMs.txt options
+ * @returns Plain text string
+ */
+export function generateLlmsTxt(options: LlmsTxtOptions): string {
+  const { name, description, baseUrl, pages, hostAtDocs = false, noindex = false } = options;
+
+  if (noindex) {
+    return '';
+  }
+
+  const urlPrefix = hostAtDocs ? '/docs' : '';
+
+  let output = `# ${name}\n\n`;
+
+  if (description) {
+    output += `> ${description}\n\n`;
+  }
+
+  for (const page of pages) {
+    if (page.noindex || page.hidden) continue;
+
+    const url = `${baseUrl}${urlPrefix}/${page.path}.md`;
+    const desc = page.description ? `: ${page.description}` : '';
+    output += `- [${page.title}](${url})${desc}\n`;
+  }
+
+  return output.trim();
+}
+
+/**
+ * Options for generating robots.txt.
+ */
+export interface RobotsTxtOptions {
+  /** Base URL for the site */
+  baseUrl: string;
+  /** Custom sitemap URL (defaults to {baseUrl}/sitemap.xml) */
+  sitemapUrl?: string;
+  /** Whether docs are hosted at /docs path */
+  hostAtDocs?: boolean;
+  /** Block all crawlers (seo.metatags.robots: "noindex") */
+  noindex?: boolean;
+}
+
+/**
+ * Generate robots.txt.
+ *
+ * @param options - Robots.txt options
+ * @returns Plain text string
+ */
+export function generateRobotsTxt(options: RobotsTxtOptions): string {
+  const { baseUrl, sitemapUrl, hostAtDocs = false, noindex = false } = options;
+
+  if (noindex) {
+    return `User-agent: *
+Disallow: /
+`;
+  }
+
+  const defaultSitemapUrl = hostAtDocs
+    ? `${baseUrl}/docs/sitemap.xml`
+    : `${baseUrl}/sitemap.xml`;
+
+  return `User-agent: *
+Allow: /
+
+Sitemap: ${sitemapUrl || defaultSitemapUrl}
+`;
+}
+
+/**
+ * Raw page info from file system or R2.
+ */
+export interface RawPageInfo {
+  /** File path with extension */
+  path: string;
+  /** Frontmatter from MDX file */
+  frontmatter: {
+    title?: string;
+    description?: string;
+    noindex?: boolean;
+    hidden?: boolean;
+    lastModified?: string;
+    seo?: {
+      noindex?: boolean;
+    };
+  };
+}
+
+/**
+ * Extract page metadata from raw page info.
+ *
+ * @param pages - Array of raw page info
+ * @returns Array of page metadata
+ */
+export function extractPageMetadata(pages: RawPageInfo[]): PageMetadata[] {
+  return pages.map(page => {
+    const pathWithoutExt = page.path.replace(/\.mdx?$/, '');
+
+    return {
+      path: pathWithoutExt,
+      title: page.frontmatter.title || pathWithoutExt,
+      description: page.frontmatter.description,
+      noindex: page.frontmatter.noindex || page.frontmatter.seo?.noindex,
+      hidden: page.frontmatter.hidden,
+      lastModified: page.frontmatter.lastModified,
+    };
+  });
+}
+
+/**
+ * Options for generating all artifacts.
+ */
+export interface GenerateAllOptions {
+  /** Project slug */
+  projectSlug: string;
+  /** Base URL for the site */
+  baseUrl: string;
+  /** Documentation name */
+  name: string;
+  /** Documentation description */
+  description?: string;
+  /** Array of page metadata */
+  pages: PageMetadata[];
+  /** Whether docs are hosted at /docs path */
+  hostAtDocs?: boolean;
+  /** Block all crawlers (seo.metatags.robots: "noindex") */
+  noindex?: boolean;
+}
+
+/**
+ * Generated artifacts.
+ */
+export interface GeneratedArtifacts {
+  sitemap: string;
+  llmsTxt: string;
+  robotsTxt: string;
+}
+
+/**
+ * Generate all static artifacts for a project.
+ *
+ * @param options - Generation options
+ * @returns Object with all generated artifacts
+ */
+export function generateAllArtifacts(options: GenerateAllOptions): GeneratedArtifacts {
+  const { baseUrl, name, description, pages, hostAtDocs, noindex } = options;
+
+  const sitemap = generateSitemap({ baseUrl, pages, hostAtDocs, noindex });
+  const llmsTxt = generateLlmsTxt({ name, description, baseUrl, pages, hostAtDocs, noindex });
+  const robotsTxt = generateRobotsTxt({ baseUrl, hostAtDocs, noindex });
+
+  return { sitemap, llmsTxt, robotsTxt };
+}
+
+/**
+ * Search document entry.
+ */
+export interface SearchDocument {
+  id: string;
+  title: string;
+  description?: string;
+  content: string;
+  slug: string;
+  section?: string;
+  type: string;
+}
+
+/**
+ * Raw page info with content for search index generation.
+ */
+export interface SearchPageInfo {
+  /** File path with extension */
+  path: string;
+  /** Raw MDX content */
+  content: string;
+  /** Frontmatter from MDX file */
+  frontmatter: {
+    title?: string;
+    description?: string;
+  };
+}
+
+/**
+ * Infer page type from slug path.
+ */
+function inferPageType(slug: string): string {
+  if (slug.startsWith('api/') || slug.startsWith('api-reference/')) return 'api';
+  if (slug.includes('changelog')) return 'changelog';
+  if (slug.includes('quickstart') || slug.includes('getting-started')) return 'quickstart';
+  return 'guide';
+}
+
+/**
+ * Strip markdown formatting from text.
+ */
+function stripMarkdown(text: string): string {
+  return text
+    .replace(/```[\s\S]*?```/g, '')    // code blocks
+    .replace(/`[^`]+`/g, '')           // inline code
+    .replace(/#{1,6}\s/g, '')          // headings
+    .replace(/\*\*([^*]+)\*\*/g, '$1') // bold
+    .replace(/\*([^*]+)\*/g, '$1')     // italic
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') // links
+    .replace(/<[^>]+>/g, '')           // HTML tags
+    .replace(/!\[([^\]]*)\]\([^)]+\)/g, '') // images
+    .replace(/\n+/g, ' ')              // newlines
+    .trim();
+}
+
+/**
+ * Extract sections from MDX content.
+ */
+function extractSections(content: string): Array<{ heading: string; content: string }> {
+  const sections: Array<{ heading: string; content: string }> = [];
+  const lines = content.split('\n');
+  let currentHeading = '';
+  let currentContent: string[] = [];
+
+  for (const line of lines) {
+    const headingMatch = line.match(/^#{1,6}\s+(.+)$/);
+    if (headingMatch) {
+      if (currentHeading || currentContent.length > 0) {
+        sections.push({
+          heading: currentHeading,
+          content: currentContent.join('\n'),
+        });
+      }
+      currentHeading = headingMatch[1];
+      currentContent = [];
+    } else {
+      currentContent.push(line);
+    }
+  }
+
+  if (currentHeading || currentContent.length > 0) {
+    sections.push({
+      heading: currentHeading,
+      content: currentContent.join('\n'),
+    });
+  }
+
+  return sections;
+}
+
+/**
+ * Generate search data from page content.
+ *
+ * @param pages - Array of page info with content
+ * @returns JSON string of search documents
+ */
+export function generateSearchData(pages: SearchPageInfo[]): string {
+  const documents: SearchDocument[] = [];
+
+  for (const page of pages) {
+    const pathWithoutExt = page.path.replace(/\.mdx?$/, '');
+    const slug = pathWithoutExt.replace(/\\/g, '/');
+    const pageType = inferPageType(slug);
+    const sections = extractSections(page.content);
+
+    sections.forEach((section, idx) => {
+      const cleanContent = stripMarkdown(section.content);
+      if (cleanContent.trim()) {
+        documents.push({
+          id: `${slug}-${idx}`,
+          title: page.frontmatter.title || slug.split('/').pop() || '',
+          description: page.frontmatter.description,
+          content: cleanContent.substring(0, 300),
+          slug,
+          section: section.heading || undefined,
+          type: pageType,
+        });
+      }
+    });
+  }
+
+  return JSON.stringify(documents);
+}

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

@@ -0,0 +1,72 @@
+/**
+ * Shared handler for static file routes (sitemap.xml, robots.txt, llms.txt, search-data.json).
+ *
+ * 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).
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+
+import { log } from '@/lib/logger';
+import { isIsrMode } from '@/lib/page-isr-helpers';
+import { fetchStaticFile } from '@/lib/r2-content';
+
+const CONTENT_TYPES: Record<string, string> = {
+  '.xml': 'application/xml',
+  '.json': 'application/json',
+  '.txt': 'text/plain',
+};
+
+/**
+ * Infer content type from filename extension.
+ */
+function getContentType(filename: string): string {
+  const ext = filename.slice(filename.lastIndexOf('.'));
+  return CONTENT_TYPES[ext] || 'application/octet-stream';
+}
+
+/**
+ * Create a GET handler that serves a static file from R2.
+ *
+ * @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')
+ */
+export function createStaticFileHandler(
+  filename: string,
+  label: string
+): (request: NextRequest) => Promise<NextResponse> {
+  const contentType = getContentType(filename);
+
+  return async function GET(request: NextRequest): Promise<NextResponse> {
+    if (!isIsrMode()) {
+      return new NextResponse('Not found', { status: 404 });
+    }
+
+    const projectSlug = request.headers.get('x-project-slug');
+
+    if (!projectSlug) {
+      log('warn', `${label} request missing project slug`);
+      return new NextResponse('Project not found', { status: 404 });
+    }
+
+    try {
+      const content = await fetchStaticFile(projectSlug, filename);
+
+      if (!content) {
+        log('warn', `${label} not found in R2`, { projectSlug });
+        return new NextResponse(`${label} not found`, { status: 404 });
+      }
+
+      return new NextResponse(content, {
+        headers: {
+          'Content-Type': contentType,
+          'Cache-Control': 'public, max-age=3600, s-maxage=86400',
+        },
+      });
+    } catch (error) {
+      log('error', `Error serving ${label.toLowerCase()}`, { projectSlug, error: String(error) });
+      return new NextResponse(`Error serving ${label.toLowerCase()}`, { status: 500 });
+    }
+  };
+}

package/vendored/lib/tracking-script.ts

@@ -0,0 +1,19 @@
+/**
+ * Minified tracking script for analytics injection
+ *
+ * This script is injected into HTML pages to track page views.
+ * Source: see route.ts injectTrackingScript for readable version (git history)
+ *
+ * Features:
+ * - Session ID generation using crypto API
+ * - SPA navigation tracking (pushState, replaceState, popstate)
+ * - Referrer extraction (filters self-referrals)
+ * - Timezone detection for country fallback
+ * - Debouncing to prevent duplicate events
+ * - sendBeacon with fetch fallback
+ */
+export const TRACKING_SCRIPT = `<script>(function(){function e(){let e=sessionStorage.getItem("jamdesk_session_id");if(!e){const t=new Uint8Array(16);crypto.getRandomValues(t),e=Array.from(t,e=>e.toString(16).padStart(2,"0")).join("")+Date.now().toString(36),sessionStorage.setItem("jamdesk_session_id",e)}return e}let t="",n=0;function a(a){const i=Date.now(),s=window.location.pathname;if(s===t&&i-n<500)return;t=s,n=i;const o=e();let r=null;if(document.referrer)try{const e=new URL(document.referrer);e.hostname!==window.location.hostname&&(r=e.hostname)}catch(e){}let c=null;try{c=Intl.DateTimeFormat().resolvedOptions().timeZone}catch(e){}const d={projectSlug:"__PROJECT__",path:a||s,referrer:r,userAgent:navigator.userAgent,sessionId:o,type:"pageview",eventId:o+":"+i.toString(36),timezone:c},l=JSON.stringify(d);navigator.sendBeacon?navigator.sendBeacon("/_jd/ev",new Blob([l],{type:"application/json"})):fetch("/_jd/ev",{method:"POST",headers:{"Content-Type":"application/json"},body:l,keepalive:!0}).catch(()=>{})}"loading"===document.readyState?document.addEventListener("DOMContentLoaded",()=>{a()}):a();const i=history.pushState,s=history.replaceState;history.pushState=function(){i.apply(this,arguments),a()},history.replaceState=function(){s.apply(this,arguments),a()},window.addEventListener("popstate",()=>{a()})})();</script>`;
+
+export function getTrackingScript(projectSlug: string): string {
+  return TRACKING_SCRIPT.replace('__PROJECT__', projectSlug);
+}

package/vendored/lib/typography-config.ts

@@ -0,0 +1,42 @@
+/**
+ * Typography Configuration Utilities
+ *
+ * Provides helper functions to conditionally include typography plugins
+ * in the MDX processing pipeline based on docs.json configuration.
+ *
+ * Typography is enabled via: styling.typography: true in docs.json
+ */
+
+import type { DocsConfig } from './docs-types';
+import remarkSmartypants from 'remark-smartypants';
+import type { PluggableList } from 'unified';
+
+/**
+ * Check if typography enhancements are enabled in the docs config.
+ *
+ * @param config - The docs.json configuration
+ * @returns true if styling.typography is explicitly set to true
+ */
+export function isTypographyEnabled(config?: DocsConfig): boolean {
+  return config?.styling?.typography === true;
+}
+
+/**
+ * Get remark plugins for typography processing.
+ * Returns remark-smartypants if typography is enabled, otherwise empty array.
+ *
+ * remark-smartypants converts:
+ * - "quotes" to "curly quotes"
+ * - -- to en-dash (–)
+ * - --- to em-dash (—)
+ * - ... to ellipsis (…)
+ *
+ * @param config - The docs.json configuration
+ * @returns Array of remark plugins
+ */
+export function getTypographyRemarkPlugins(config?: DocsConfig): PluggableList {
+  if (!isTypographyEnabled(config)) {
+    return [];
+  }
+  return [remarkSmartypants];
+}