jamdesk 1.0.0

package/vendored/scripts/build-project.cjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * Build Project Script
+ *
+ * Validates a project and provides guidance for the ISR workflow.
+ *
+ * With ISR (Incremental Static Regeneration), pages are compiled on-demand
+ * by Vercel, so local static builds are no longer needed.
+ *
+ * Usage:
+ *   npm run build-project acme               # Validate project
+ *   npm run build-project acme --deploy      # Trigger production deploy
+ *
+ * For local development:
+ *   jamdesk dev <project>                    # Start local dev server
+ *
+ * For production deployment:
+ *   ./jam trigger <project>                  # Trigger Cloud Run build
+ *   Or push to GitHub to trigger automatic deployment
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs-extra');
+const path = require('path');
+
+// Parse arguments
+const args = process.argv.slice(2);
+const projectName = args.find(arg => !arg.startsWith('--'));
+const shouldDeploy = args.includes('--deploy');
+
+if (!projectName) {
+  console.log(`
+╔═══════════════════════════════════════════════════════════════════╗
+║                    Build Project Documentation                      ║
+╚═══════════════════════════════════════════════════════════════════╝
+
+Usage:
+  npm run build-project <project-name> [options]
+
+Options:
+  --deploy         Trigger production deployment
+
+For local preview:
+  jamdesk dev <project>
+
+Available projects:`);
+
+  const projectsDir = process.env.JAMDESK_PROJECTS_DIR || path.join(__dirname, '../projects');
+  if (fs.existsSync(projectsDir)) {
+    const projects = fs.readdirSync(projectsDir)
+      .filter(f => fs.statSync(path.join(projectsDir, f)).isDirectory());
+    if (projects.length > 0) {
+      projects.forEach(t => console.log(`  - ${t}`));
+    } else {
+      console.log('  (no projects found - create directories in /projects/)');
+    }
+  } else {
+    console.log('  (projects directory not found)');
+  }
+  console.log('');
+  process.exit(1);
+}
+
+// Verify project exists
+const projectsDir = process.env.JAMDESK_PROJECTS_DIR || path.join(__dirname, '../projects');
+const projectDir = path.join(projectsDir, projectName);
+if (!fs.existsSync(projectDir)) {
+  console.error(`\n❌ Error: Project directory not found: ${projectDir}`);
+  console.error('\nAvailable projects:');
+  if (fs.existsSync(projectsDir)) {
+    const projects = fs.readdirSync(projectsDir)
+      .filter(f => fs.statSync(path.join(projectsDir, f)).isDirectory());
+    projects.forEach(t => console.error(`  - ${t}`));
+  }
+  process.exit(1);
+}
+
+// Verify required files (flat structure - MDX files directly in project dir)
+const hasDocsJson = fs.existsSync(path.join(projectDir, 'docs.json'));
+
+// Check for at least one MDX file (recursively, skipping images/ and hidden dirs)
+function hasMdxFiles(dir) {
+  const files = fs.readdirSync(dir);
+  for (const file of files) {
+    // Skip hidden files/directories (like .claude, .git, etc.)
+    if (file.startsWith('.')) continue;
+
+    const filePath = path.join(dir, file);
+
+    // Use lstatSync to handle symlinks - if target doesn't exist, skip
+    let stat;
+    try {
+      stat = fs.statSync(filePath);
+    } catch (e) {
+      // Broken symlink or inaccessible file - skip
+      continue;
+    }
+
+    if (stat.isDirectory() && file !== 'images' && file !== 'node_modules') {
+      if (hasMdxFiles(filePath)) return true;
+    } else if (file.endsWith('.mdx')) {
+      return true;
+    }
+  }
+  return false;
+}
+
+const hasMdx = hasMdxFiles(projectDir);
+
+if (!hasDocsJson || !hasMdx) {
+  console.error(`\n❌ Error: Missing required files in project directory:`);
+  if (!hasDocsJson) console.error(`  - docs.json`);
+  if (!hasMdx) console.error(`  - *.mdx files`);
+  console.error(`\nExpected structure (flat):`);
+  console.error(`  projects/${projectName}/`);
+  console.error(`    ├── docs.json`);
+  console.error(`    ├── introduction.mdx`);
+  console.error(`    ├── apis/`);
+  console.error(`    │   └── overview.mdx`);
+  console.error(`    └── images/`);
+  process.exit(1);
+}
+
+// Project validated - show ISR workflow guidance
+const title = `Project: ${projectName}`;
+const titlePadding = 69 - 2 - title.length;
+const titleLeft = Math.floor(titlePadding / 2);
+const titleRight = titlePadding - titleLeft;
+
+console.log(`
+╔═══════════════════════════════════════════════════════════════════╗
+║${' '.repeat(titleLeft)}${title}${' '.repeat(titleRight)}║
+╚═══════════════════════════════════════════════════════════════════╝
+`);
+
+console.log('✅ Project validated successfully\n');
+console.log(`   docs.json: Found`);
+console.log(`   MDX files: Found\n`);
+
+if (shouldDeploy) {
+  // Trigger production deployment
+  console.log('📤 Triggering production deployment...\n');
+
+  try {
+    // Try to trigger via ./jam trigger (requires BUILD_API_KEY)
+    // Note: execSync is safe here - projectName is validated against existing directories
+    execSync(`./jam trigger ${projectName}`, {
+      stdio: 'inherit',
+      cwd: path.join(__dirname, '../..'),
+    });
+  } catch (error) {
+    console.log(`
+To deploy to production, you can:
+
+  1. Push to GitHub (triggers automatic deployment)
+  2. Use the dashboard at https://dashboard.jamdesk.com
+  3. Run: ./jam trigger ${projectName}
+     (requires BUILD_API_KEY in functions/.env.local)
+`);
+  }
+} else {
+  console.log(`ISR Workflow:
+
+  Local preview:
+    jamdesk dev ${projectName}
+
+  Production deployment:
+    ./jam trigger ${projectName}
+    Or push to GitHub for automatic deployment
+
+  Live site:
+    https://${projectName}.jamdesk.app
+`);
+}

package/vendored/scripts/build-search-index.cjs

@@ -0,0 +1,347 @@
+#!/usr/bin/env node
+/**
+ * Build Search Index Script
+ * 
+ * Generates a search-data.json file from MDX content.
+ * Supports project-specific builds via PROJECT_NAME environment variable.
+ * 
+ * Usage:
+ *   node scripts/build-search-index.js              # Uses default content directory
+ *   PROJECT_NAME=acme node scripts/build-search-index.js  # Uses project's content
+ *   node scripts/build-search-index.js --project acme     # Same as above
+ * 
+ * Search Data Handling:
+ *   - LOCAL DEV: Writes to public/search-data.json (served by Next.js dev server)
+ *   - PRODUCTION BUILD: Writes to public/search-data.json, then included in /out/ static export
+ *   - Each project gets their own search-data.json when deployed to R2
+ */
+
+const fs = require('fs');
+const fsPromises = require('fs/promises');
+const path = require('path');
+const matter = require('gray-matter');
+const os = require('os');
+const { create, insertMultiple } = require('@orama/orama');
+const { persist } = require('@orama/plugin-data-persistence');
+
+// Concurrency control for parallel file processing
+const CONCURRENCY = parseInt(process.env.SEARCH_INDEX_CONCURRENCY || '') || os.cpus().length * 2;
+
+/**
+ * Pre-process frontmatter to handle common YAML issues:
+ * - Colons in unquoted string values (e.g., "description: Follow the workflow: step 1")
+ * - YAML tags like !Jamdesk that should be plain text
+ *
+ * NOTE: This is duplicated from lib/frontmatter-utils.ts for CJS compatibility.
+ */
+function preprocessFrontmatter(content) {
+  if (!content.startsWith('---')) return content;
+
+  const endMatch = content.slice(3).match(/\n---(\r?\n|$)/);
+  if (!endMatch) return content;
+
+  const frontmatterEnd = 3 + endMatch.index + endMatch[0].length;
+  const frontmatter = content.slice(3, frontmatterEnd - endMatch[0].length);
+  const body = content.slice(frontmatterEnd);
+
+  const fixedLines = frontmatter.split('\n').map((line) => {
+    if (!line.trim() || line.trim().startsWith('#')) return line;
+
+    const match = line.match(/^(\s*)([a-zA-Z_][a-zA-Z0-9_]*):\s*(.*)$/);
+    if (!match) return line;
+
+    const [, indent, key, value] = match;
+
+    if (!value || value.startsWith('"') || value.startsWith("'") || /^[|>][-+]?$/.test(value)) {
+      return line;
+    }
+
+    if (value.startsWith('{') || value.startsWith('[')) return line;
+
+    let fixedValue = value.replace(/^![a-zA-Z][a-zA-Z0-9_-]*\s*/, '');
+
+    if (fixedValue.includes(':') && !fixedValue.endsWith(':')) {
+      fixedValue = '"' + fixedValue.replace(/"/g, '\\"') + '"';
+    }
+
+    return `${indent}${key}: ${fixedValue}`;
+  });
+
+  return '---\n' + fixedLines.join('\n') + '\n---' + body;
+}
+
+/**
+ * Parse frontmatter with lenient preprocessing.
+ */
+function parseFrontmatterLenient(content) {
+  const processed = preprocessFrontmatter(content);
+  const { data, content: rawContent } = matter(processed);
+  return { data, content: rawContent };
+}
+
+/**
+ * Infer page type from slug for search result badges.
+ * Returns: 'api' | 'component' | 'guide' | 'help' | 'quickstart'
+ *
+ * NOTE: This logic is duplicated from lib/infer-page-type.ts for CJS compatibility.
+ * If you update the rules here, also update the TypeScript version.
+ * Run `npm run test:run -- infer-page-type` to verify both implementations match.
+ */
+function inferPageType(slug) {
+  const lower = slug.toLowerCase();
+  if (lower.startsWith('apis/') || lower.includes('/api/') || lower.startsWith('api-reference/')) {
+    return 'api';
+  }
+  if (lower.startsWith('components/') || lower.startsWith('component/')) {
+    return 'component';
+  }
+  if (lower.startsWith('help-center/') || lower.startsWith('help/') || lower.startsWith('faq')) {
+    return 'help';
+  }
+  if (lower.includes('quickstart') || lower.includes('getting-started') || lower === 'introduction') {
+    return 'quickstart';
+  }
+  return 'guide';
+}
+
+class Semaphore {
+  constructor(max) {
+    this.max = max;
+    this.current = 0;
+    this.queue = [];
+  }
+
+  async acquire() {
+    if (this.current < this.max) {
+      this.current++;
+      return;
+    }
+    await new Promise(resolve => this.queue.push(resolve));
+    this.current++;
+  }
+
+  release() {
+    this.current--;
+    if (this.queue.length > 0) {
+      const next = this.queue.shift();
+      next();
+    }
+  }
+}
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const projectArgIndex = args.indexOf('--project');
+const projectFromArg = projectArgIndex !== -1 ? args[projectArgIndex + 1] : null;
+const projectName = projectFromArg || process.env.PROJECT_NAME;
+
+// Directories to skip when traversing
+const SKIP_DIRS = ['images', 'node_modules', 'files'];
+
+// Determine paths based on project
+function getContentDir() {
+  if (projectName) {
+    // Use JAMDESK_PROJECTS_DIR if set, otherwise fall back to local projects/
+    const projectsDir = process.env.JAMDESK_PROJECTS_DIR || path.join(__dirname, '../projects');
+    return path.join(projectsDir, projectName);
+  }
+  return path.join(process.cwd(), 'content');
+}
+
+function getOutputPath() {
+  // During build, output goes to public so it's included in the static export
+  return path.join(process.cwd(), 'public', 'search-data.json');
+}
+
+function stripMarkdown(text) {
+  return text
+    .replace(/```[\s\S]*?```/g, '')
+    .replace(/`[^`]+`/g, '')
+    .replace(/#{1,6}\s/g, '')
+    .replace(/\*\*([^*]+)\*\*/g, '$1')
+    .replace(/\*([^*]+)\*/g, '$1')
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+    .replace(/<[^>]+>/g, '')
+    .replace(/!\[([^\]]*)\]\([^)]+\)/g, '')
+    .replace(/\n+/g, ' ')
+    .trim();
+}
+
+function extractSections(content) {
+  const sections = [];
+  const lines = content.split('\n');
+  let currentHeading = '';
+  let currentContent = [];
+
+  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;
+}
+
+async function buildSearchIndex() {
+  const contentDir = getContentDir();
+  const outputPath = getOutputPath();
+
+  if (projectName) {
+    console.log(`Building search index for project: ${projectName}`);
+  }
+  console.log(`Content directory: ${contentDir}`);
+
+  if (!fs.existsSync(contentDir)) {
+    console.error(`Error: Content directory not found: ${contentDir}`);
+    process.exit(1);
+  }
+
+  // First, collect all MDX file paths
+  const mdxFiles = [];
+
+  function collectFiles(dir, basePath = '') {
+    const files = fs.readdirSync(dir);
+
+    for (const file of files) {
+      // Skip hidden files/directories (like .claude, .git, etc.)
+      if (file.startsWith('.')) continue;
+
+      const filePath = path.join(dir, file);
+
+      // Handle broken symlinks gracefully
+      let stat;
+      try {
+        stat = fs.statSync(filePath);
+      } catch (e) {
+        // Broken symlink or inaccessible file - skip
+        continue;
+      }
+
+      if (stat.isDirectory()) {
+        // Skip non-content directories
+        if (SKIP_DIRS.includes(file)) continue;
+        collectFiles(filePath, path.join(basePath, file));
+      } else if (file.endsWith('.mdx')) {
+        const slug = path.join(basePath, file.replace(/\.mdx$/, ''));
+        mdxFiles.push({ filePath, slug });
+      }
+    }
+  }
+
+  collectFiles(contentDir);
+  console.log(`Found ${mdxFiles.length} MDX files, processing with concurrency ${CONCURRENCY}...`);
+
+  // Process files in parallel with semaphore
+  const semaphore = new Semaphore(CONCURRENCY);
+
+  async function processFile({ filePath, slug }) {
+    await semaphore.acquire();
+    try {
+      const fileContents = await fsPromises.readFile(filePath, 'utf8');
+      const { data, content } = parseFrontmatterLenient(fileContents);
+      const sections = extractSections(content);
+
+      const docs = [];
+      const normalizedSlug = slug.replace(/\\/g, '/');
+      const pageType = inferPageType(normalizedSlug);
+      sections.forEach((section, idx) => {
+        const cleanContent = stripMarkdown(section.content);
+        if (cleanContent.trim()) {
+          docs.push({
+            id: `${slug}-${idx}`,
+            title: data.title || slug.split('/').pop() || '',
+            description: data.description,
+            content: cleanContent.substring(0, 300),
+            slug: normalizedSlug,
+            section: section.heading || undefined,
+            type: pageType,
+          });
+        }
+      });
+      return docs;
+    } finally {
+      semaphore.release();
+    }
+  }
+
+  // Process all files in parallel
+  const results = await Promise.all(mdxFiles.map(processFile));
+  const documents = results.flat();
+
+  // Ensure output directory exists
+  const outputDir = path.dirname(outputPath);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  // Write to public directory
+  await fsPromises.writeFile(outputPath, JSON.stringify(documents, null, 2));
+
+  console.log(`✓ Built search index with ${documents.length} documents`);
+  console.log(`✓ Saved to ${outputPath}`);
+
+  // Build pre-built Orama index for MCP server (faster cold starts)
+  await buildOramaIndex(documents, outputDir);
+}
+
+/**
+ * Build and serialize an Orama search index for use by the MCP server.
+ * The pre-built index loads ~4x faster than building from search-data.json.
+ */
+async function buildOramaIndex(searchData, outputDir) {
+  const db = await create({
+    schema: {
+      id: 'string',
+      title: 'string',
+      description: 'string',
+      content: 'string',
+      slug: 'string',
+      section: 'string',
+      type: 'string',
+    },
+  });
+
+  // Normalize data (ensure all fields exist)
+  const normalizedData = searchData.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);
+
+  // Serialize the index using the persistence plugin
+  const serialized = await persist(db, 'json');
+
+  // Write to public directory (will be uploaded to R2)
+  const indexPath = path.join(outputDir, 'search-index.orama.json');
+  await fsPromises.writeFile(indexPath, JSON.stringify(serialized));
+
+  console.log(`✓ Built Orama index for MCP server`);
+}
+
+buildSearchIndex().catch(err => {
+  console.error('Error building search index:', err);
+  process.exit(1);
+});