jamdesk 1.0.0

package/vendored/scripts/dev-project.cjs

@@ -0,0 +1,534 @@
+#!/usr/bin/env node
+/**
+ * Dev Project Script
+ *
+ * Runs the development server for a specific project.
+ * This script sets up the environment and runs Next.js dev with the project's content.
+ *
+ * Usage:
+ *   npm run dev-project acme        # Run dev server with acme project's content
+ *   npm run dev-project demo        # Run dev server with demo project's content
+ *
+ * Access at:
+ *   - Default                  → http://localhost:3000/introduction
+ *   - With --host-at-docs flag → http://localhost:3000/docs/introduction
+ *
+ * The hostAtDocs setting is controlled via CLI flag (mirrors dashboard setting).
+ *
+ * What it does:
+ *   1. Sets PROJECT_NAME environment variable
+ *   2. Copies project's docs.json to public/docs.json
+ *   3. Copies project's images to public/images
+ *   4. Builds search index from project's content
+ *   5. Runs Next.js dev server
+ */
+
+const { execSync, spawn } = require('child_process');
+const fs = require('fs-extra');
+const path = require('path');
+
+// Colors for console output
+const colors = {
+  cyan: '\x1b[36m',
+  yellow: '\x1b[33m',
+  green: '\x1b[32m',
+  red: '\x1b[31m',
+  reset: '\x1b[0m',
+};
+
+/**
+ * Get the first page path from navigation config.
+ * Supports:
+ * - Jamdesk format: navigation.languages[].tabs[].groups[].pages[]
+ * - Mintlify tabs format: navigation.tabs[].groups[].pages[]
+ * - Mintlify flat format: navigation.pages[] with groups
+ */
+function getFirstPage(config) {
+  try {
+    const nav = config.navigation;
+    if (!nav) return 'introduction';
+
+    // Jamdesk format: navigation.languages[].tabs[].groups[].pages[]
+    if (nav.languages && nav.languages.length) {
+      const tabs = nav.languages[0]?.tabs;
+      if (!tabs?.length) return 'introduction';
+
+      const groups = tabs[0]?.groups;
+      if (!groups?.length) return 'introduction';
+
+      const pages = groups[0]?.pages;
+      if (!pages?.length) return 'introduction';
+
+      const firstPage = pages[0];
+      if (typeof firstPage === 'string') return firstPage;
+      return firstPage.page || 'introduction';
+    }
+
+    // Mintlify tabs format: navigation.tabs[].groups[].pages[]
+    if (nav.tabs && nav.tabs.length) {
+      const groups = nav.tabs[0]?.groups;
+      if (groups?.length) {
+        const pages = groups[0]?.pages;
+        if (pages?.length) {
+          const firstPage = pages[0];
+          if (typeof firstPage === 'string') return firstPage;
+          return firstPage.page || 'introduction';
+        }
+      }
+    }
+
+    // Mintlify flat format: navigation.pages[] where each item has group + pages
+    if (nav.pages && nav.pages.length) {
+      const firstGroup = nav.pages[0];
+      // Could be a group object with pages array, or a direct page reference
+      if (typeof firstGroup === 'object' && firstGroup.pages?.length) {
+        const firstPage = firstGroup.pages[0];
+        if (typeof firstPage === 'string') return firstPage;
+        return firstPage.page || 'introduction';
+      }
+      // Direct page reference
+      if (typeof firstGroup === 'string') return firstGroup;
+    }
+
+    return 'introduction';
+  } catch {
+    return 'introduction';
+  }
+}
+
+/**
+ * Clean up dev environment before starting
+ * - Kills processes on the specified port
+ * - Removes Next.js lock file
+ *
+ * Note: This uses execSync with fixed commands and validated port numbers.
+ * The port comes from CLI args and is validated as a number before use.
+ */
+function cleanupDevEnvironment(port, nextDir) {
+  console.log(`${colors.cyan}[CLEANUP]${colors.reset} Checking for existing dev processes...`);
+  let killedAny = false;
+
+  // Validate port is a number to prevent injection
+  const portNum = parseInt(port, 10);
+  if (isNaN(portNum) || portNum < 1 || portNum > 65535) {
+    console.warn(`${colors.yellow}[CLEANUP]${colors.reset} Invalid port number, skipping cleanup`);
+    return;
+  }
+
+  try {
+    // Find processes on the port using lsof
+    // Using string template with validated number is safe
+    const lsofOutput = execSync(`lsof -ti :${portNum} 2>/dev/null || true`, { encoding: 'utf8' }).trim();
+
+    if (lsofOutput) {
+      const pids = lsofOutput.split('\n').filter(Boolean);
+      console.log(`\n${colors.yellow}[CLEANUP]${colors.reset} Found process(es) on port ${portNum}:`);
+
+      for (const pid of pids) {
+        // Validate PID is a number
+        const pidNum = parseInt(pid, 10);
+        if (isNaN(pidNum)) continue;
+
+        try {
+          // Get process details using validated PID
+          const processInfo = execSync(`ps -p ${pidNum} -o comm=,args= 2>/dev/null || echo "unknown"`, { encoding: 'utf8' }).trim();
+          const [cmd, ...argsArr] = processInfo.split(/\s+/);
+          const fullCmd = argsArr.join(' ').substring(0, 60);
+
+          console.log(`         PID ${pidNum}: ${colors.cyan}${cmd}${colors.reset}`);
+          if (fullCmd) {
+            console.log(`         Command: ${fullCmd}`);
+          }
+
+          // Kill the process using Node's process.kill (no shell)
+          console.log(`${colors.yellow}[CLEANUP]${colors.reset} Killing PID ${pidNum}...`);
+          try {
+            process.kill(pidNum, 'SIGTERM');
+            killedAny = true;
+          } catch (killErr) {
+            // Process may have already exited
+          }
+        } catch (psErr) {
+          // Process may have already exited
+        }
+      }
+
+      // Wait a moment and force kill if needed
+      if (killedAny) {
+        // Give processes time to terminate gracefully
+        execSync('sleep 1');
+
+        // Check for remaining processes
+        const remaining = execSync(`lsof -ti :${portNum} 2>/dev/null || true`, { encoding: 'utf8' }).trim();
+        if (remaining) {
+          for (const pid of remaining.split('\n').filter(Boolean)) {
+            const pidNum = parseInt(pid, 10);
+            if (isNaN(pidNum)) continue;
+
+            console.log(`${colors.yellow}[CLEANUP]${colors.reset} Force killing PID ${pidNum}...`);
+            try {
+              process.kill(pidNum, 'SIGKILL');
+            } catch (killErr) {
+              // Process may have already exited
+            }
+          }
+          execSync('sleep 1');
+        }
+      }
+    }
+  } catch (err) {
+    // lsof may fail if no process found, that's OK
+  }
+
+  // Handle Next.js lock file
+  if (nextDir) {
+    const lockFile = path.join(nextDir, 'dev', 'lock');
+    if (fs.existsSync(lockFile)) {
+      console.log(`${colors.yellow}[CLEANUP]${colors.reset} Removing Next.js lock file: ${lockFile}`);
+      try {
+        fs.unlinkSync(lockFile);
+        killedAny = true;
+      } catch (err) {
+        console.warn(`         Could not remove lock file: ${err.message}`);
+      }
+    }
+  }
+
+  // Summary
+  if (killedAny) {
+    console.log(`${colors.green}[CLEANUP]${colors.reset} Cleanup complete - ready to start fresh`);
+  } else {
+    console.log(`${colors.green}[CLEANUP]${colors.reset} No conflicts found - port ${portNum} is available`);
+  }
+  console.log('');
+}
+
+// Project directories - check monorepo first, then local
+const BUILD_SERVICE_PROJECTS_DIR = path.join(__dirname, '../projects');
+const MONOREPO_PROJECTS_DIR = path.join(__dirname, '../../..', 'projects'); // jamdesk/projects/ (submodules)
+
+function getProjectsDir() {
+  // Use explicit env var if set AND path exists with content
+  if (process.env.JAMDESK_PROJECTS_DIR && fs.existsSync(process.env.JAMDESK_PROJECTS_DIR)) {
+    const entries = fs.readdirSync(process.env.JAMDESK_PROJECTS_DIR);
+    if (entries.length > 0) {
+      return process.env.JAMDESK_PROJECTS_DIR;
+    }
+  }
+  // Check monorepo projects/ directory (submodules)
+  if (fs.existsSync(MONOREPO_PROJECTS_DIR)) {
+    return MONOREPO_PROJECTS_DIR;
+  }
+  return BUILD_SERVICE_PROJECTS_DIR;
+}
+
+// Parse arguments
+const args = process.argv.slice(2);
+const projectName = args.find(arg => !arg.startsWith('--'));
+const port = args.includes('--port') ? args[args.indexOf('--port') + 1] : '3000';
+// Monorepo subpath (e.g., --path jamdesk for endgame/jamdesk/)
+const subPath = args.includes('--path') ? args[args.indexOf('--path') + 1] : null;
+// hostAtDocs flag - mirrors the dashboard toggle setting
+const hostAtDocs = args.includes('--host-at-docs');
+
+if (!projectName) {
+  console.log(`
+╔═══════════════════════════════════════════════════════════════════╗
+║                   Dev Server for Project                            ║
+╚═══════════════════════════════════════════════════════════════════╝
+
+Usage:
+  npm run dev-project <project-name> [options]
+
+Options:
+  --port <port>    Port to run dev server on (default: 3000)
+  --path <subdir>  Subdirectory within project (for monorepos)
+  --host-at-docs   Serve docs at /docs/* instead of root (mirrors dashboard toggle)
+
+Examples:
+  npm run dev-project acme                    # Serve at root (localhost:3000/introduction)
+  npm run dev-project acme --host-at-docs     # Serve at /docs (localhost:3000/docs/introduction)
+  npm run dev-project demo --port 3001        # Run on port 3001
+  npm run dev-project endgame --path jamdesk  # Monorepo: endgame/jamdesk/
+
+Available projects:`);
+
+  const projectsDir = getProjectsDir();
+  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 = getProjectsDir();
+const projectBaseDir = path.join(projectsDir, projectName);
+// If subPath specified, use it; otherwise auto-detect common monorepo patterns
+let projectDir = projectBaseDir;
+let effectiveSubPath = subPath;
+
+if (!fs.existsSync(projectBaseDir)) {
+  console.error(`\n❌ Error: Project directory not found: ${projectBaseDir}`);
+  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);
+}
+
+// Handle monorepo subpath
+if (subPath) {
+  projectDir = path.join(projectBaseDir, subPath);
+  if (!fs.existsSync(projectDir)) {
+    console.error(`\n❌ Error: Subpath not found: ${projectDir}`);
+    process.exit(1);
+  }
+} else {
+  // Auto-detect monorepo: if no docs.json at root, check for common subdirs
+  const rootDocsJson = path.join(projectBaseDir, 'docs.json');
+  if (!fs.existsSync(rootDocsJson)) {
+    // Check common monorepo patterns
+    const patterns = ['jamdesk', 'docs', 'documentation'];
+    for (const pattern of patterns) {
+      const subDocsJson = path.join(projectBaseDir, pattern, 'docs.json');
+      if (fs.existsSync(subDocsJson)) {
+        effectiveSubPath = pattern;
+        projectDir = path.join(projectBaseDir, pattern);
+        console.log(`📦 Auto-detected monorepo path: ${projectName}/${pattern}/`);
+        break;
+      }
+    }
+  }
+}
+
+/**
+ * Check if npm dependencies are installed and up-to-date.
+ * Auto-installs if package-lock.json is newer than node_modules.
+ */
+function checkDependencies() {
+  const buildServiceDir = path.join(__dirname, '..');
+  const nodeModulesDir = path.join(buildServiceDir, 'node_modules');
+  const packageLockPath = path.join(buildServiceDir, 'package-lock.json');
+
+  // Check if node_modules exists
+  if (!fs.existsSync(nodeModulesDir)) {
+    console.log(`${colors.yellow}[DEPS]${colors.reset} node_modules not found, installing dependencies...`);
+    const { execFileSync } = require('child_process');
+    execFileSync('npm', ['install'], { stdio: 'inherit', cwd: buildServiceDir });
+    return;
+  }
+
+  // Check if package-lock.json is newer than node_modules
+  // This catches cases where dependencies were added but not installed
+  if (fs.existsSync(packageLockPath)) {
+    const lockMtime = fs.statSync(packageLockPath).mtimeMs;
+    const nodeModulesMtime = fs.statSync(nodeModulesDir).mtimeMs;
+
+    if (lockMtime > nodeModulesMtime) {
+      console.log(`${colors.yellow}[DEPS]${colors.reset} package-lock.json changed, updating dependencies...`);
+      const { execFileSync } = require('child_process');
+      execFileSync('npm', ['install'], { stdio: 'inherit', cwd: buildServiceDir });
+      return;
+    }
+  }
+
+  console.log(`${colors.green}[DEPS]${colors.reset} Dependencies up to date`);
+}
+
+async function runDev() {
+  // For monorepo projects, PROJECT_NAME includes the subpath (e.g., "endgame/jamdesk")
+  const effectiveProjectName = effectiveSubPath ? `${projectName}/${effectiveSubPath}` : projectName;
+  const displayName = effectiveProjectName.padEnd(30);
+
+  // Check dependencies before anything else
+  checkDependencies();
+
+  // Clean up any existing dev processes before starting
+  // This handles port conflicts and Next.js lock file issues
+  const nextDir = path.join(__dirname, '../.next');
+  cleanupDevEnvironment(port, nextDir);
+
+  console.log(`
+╔═══════════════════════════════════════════════════════════════════╗
+║           Dev Server for: ${displayName}          ║
+╚═══════════════════════════════════════════════════════════════════╝
+`);
+
+  // hostAtDocs is controlled via CLI flag (mirrors dashboard toggle)
+  // This determines if docs are served at /docs/* (true) or root /* (false)
+  if (hostAtDocs) {
+    console.log('📍 --host-at-docs: serving docs at /docs/*');
+  } else {
+    console.log('📍 Serving docs at root /*');
+  }
+
+  const env = {
+    ...process.env,
+    PROJECT_NAME: effectiveProjectName,
+    JAMDESK_PROJECTS_DIR: projectsDir,  // Pass the resolved projects directory to child scripts
+    HOST_AT_DOCS: hostAtDocs ? 'true' : 'false',  // Pass to Next.js config
+    NEXT_PUBLIC_BASE_PATH: hostAtDocs ? '/docs' : '',  // Pass to client components for asset URLs
+  };
+
+  try {
+    // Step 0: Validate docs.json configuration
+    const projectDocsJson = path.join(projectDir, 'docs.json');
+    if (fs.existsSync(projectDocsJson)) {
+      console.log('🔍 Validating docs.json...');
+      try {
+        // Use execFileSync to avoid shell injection (path is local filesystem only)
+        // Use npx tsx to run the TypeScript validation module directly
+        const { execFileSync } = require('child_process');
+        execFileSync('npx', ['tsx', 'scripts/validate-config.mjs', projectDocsJson], {
+          stdio: ['pipe', 'pipe', 'pipe'],
+          cwd: path.join(__dirname, '..'),
+          env,
+        });
+        console.log(`✓ docs.json is valid`);
+      } catch (validationError) {
+        const errorOutput = validationError.stderr?.toString() || validationError.message;
+        console.error(`\n${colors.red}❌ Configuration Error${colors.reset}`);
+        console.error(`${colors.red}${errorOutput}${colors.reset}\n`);
+        process.exit(1);
+      }
+    }
+
+    // Step 1: Copy project's docs.json to public/docs.json
+    console.log('📋 Copying project docs.json...');
+    const publicDocsJson = path.join(__dirname, '../public/docs.json');
+    if (fs.existsSync(projectDocsJson)) {
+      await fs.copy(projectDocsJson, publicDocsJson, { overwrite: true });
+      console.log(`✓ Copied docs.json`);
+    } else {
+      console.warn(`Warning: Project docs.json not found: ${projectDocsJson}`);
+    }
+
+    // Step 2: Copy project's images to public/images
+    console.log('📁 Copying assets...');
+    execSync(`node scripts/copy-files.cjs --project ${effectiveProjectName}`, {
+      stdio: 'inherit',
+      cwd: path.join(__dirname, '..'),
+      env,
+    });
+
+    // Step 2.5: Enhance navigation with MDX frontmatter (titles, API methods)
+    console.log('🔧 Enhancing navigation with frontmatter...');
+    execSync(`node scripts/enhance-navigation.cjs --project ${effectiveProjectName}`, {
+      stdio: 'inherit',
+      cwd: path.join(__dirname, '..'),
+      env,
+    });
+
+    // Step 2.6: Compile snippets (if project has snippets folder)
+    const snippetsDir = path.join(projectDir, 'snippets');
+    if (fs.existsSync(snippetsDir)) {
+      console.log('🧩 Compiling snippets...');
+    } else {
+      console.log('🧩 Creating empty snippets module...');
+    }
+    execSync(`node scripts/compile-snippets.cjs --project ${effectiveProjectName}`, {
+      stdio: 'inherit',
+      cwd: path.join(__dirname, '..'),
+      env,
+    });
+
+    // Step 3: Build search index
+    console.log('🔍 Building search index...');
+    execSync(`node scripts/build-search-index.cjs --project ${effectiveProjectName}`, {
+      stdio: 'inherit',
+      cwd: path.join(__dirname, '..'),
+      env,
+    });
+
+    // Step 4: Run Next.js dev server
+    console.log(`\n🚀 Starting dev server on port ${port}...`);
+    // Get first page and OpenAPI config from docs.json (reuse projectDocsJson from step 1)
+    let firstPage = 'introduction';
+    let hasOpenApi = false;
+    try {
+      const docsConfig = JSON.parse(fs.readFileSync(projectDocsJson, 'utf-8'));
+      firstPage = getFirstPage(docsConfig);
+      hasOpenApi = Boolean(docsConfig.api?.openapi);
+    } catch {
+      // Fall back to defaults if docs.json can't be read
+    }
+    // Show correct URL based on --host-at-docs flag
+    const basePath = hostAtDocs ? '/docs' : '';
+    console.log(`\n   Access at: http://localhost:${port}${basePath}/${firstPage}\n`);
+
+    // Use Turbopack by default (~5x faster than webpack)
+    // Fall back to webpack with --webpack flag if needed
+    const forceWebpack = process.argv.includes('--webpack');
+    const nextArgs = forceWebpack
+      ? ['next', 'dev', '--webpack', '-p', port]
+      : ['next', 'dev', '-p', port];
+
+    console.log(`   ${forceWebpack ? '📦 Using Webpack' : '⚡ Using Turbopack'}\n`);
+    const nextDev = spawn('npx', nextArgs, {
+      stdio: ['inherit', 'pipe', 'pipe'],
+      cwd: path.join(__dirname, '..'),
+      env,
+    });
+
+    // Filter Next.js output to suppress noisy/confusing messages
+    const filterNextOutput = (data) => {
+      const lines = data.toString().split('\n');
+      // Regex to strip ANSI escape codes (colors, formatting)
+      const stripAnsi = (str) => str.replace(/\x1b\[[0-9;]*m/g, '');
+
+      return lines
+        .filter(line => {
+          const stripped = stripAnsi(line).trim();
+
+          // Filter out experimental feature status indicators (· enabled, ⨯ disabled)
+          // These appear at startup: "  · optimizePackageImports" and "  ⨯ serverSourceMaps"
+          if (stripped.startsWith('·') || stripped.startsWith('⨯')) return false;
+
+          // Filter out page access logs (e.g., " GET /introduction 200 in 72s")
+          // Keep compilation logs (e.g., "○ Compiling /introduction...")
+          if (/^(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\s+\/\S+\s+\d+\s+in\s+/.test(stripped)) return false;
+
+          return true;
+        })
+        .join('\n');
+    };
+
+    nextDev.stdout.on('data', (data) => {
+      const filtered = filterNextOutput(data);
+      if (filtered.trim()) process.stdout.write(filtered);
+    });
+
+    nextDev.stderr.on('data', (data) => {
+      const filtered = filterNextOutput(data);
+      if (filtered.trim()) process.stderr.write(filtered);
+    });
+
+    nextDev.on('close', (code) => {
+      process.exit(code);
+    });
+
+    // Handle Ctrl+C
+    process.on('SIGINT', () => {
+      nextDev.kill('SIGINT');
+      process.exit(0);
+    });
+
+  } catch (error) {
+    console.error('\n❌ Failed to start dev server:', error.message);
+    process.exit(1);
+  }
+}
+
+runDev();
+