@aravindc26/velu 0.12.8 → 0.12.10

package/src/engine/lib/preview-config.ts

@@ -0,0 +1,129 @@
+/**
+ * Per-session configuration cache for preview mode.
+ * Reads docs.json from workspace directories and caches the parsed config.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { normalizeConfigNavigation } from './navigation-normalize';
+import type { VeluConfigSource, VeluConfig } from './velu';
+
+const WORKSPACE_DIR = process.env.WORKSPACE_DIR || '/mnt/nfs_share/editor_sessions';
+const PRIMARY_CONFIG_NAME = 'docs.json';
+const LEGACY_CONFIG_NAME = 'velu.json';
+
+interface CachedSession {
+  configSource: VeluConfigSource;
+  loadedAt: number;
+}
+
+const sessionCache = new Map<string, CachedSession>();
+const CACHE_TTL_MS = 60_000; // 1 minute
+
+function resolveWorkspaceConfigPath(sessionId: string): string | null {
+  const wsDir = join(WORKSPACE_DIR, sessionId);
+  const primary = join(wsDir, PRIMARY_CONFIG_NAME);
+  if (existsSync(primary)) return primary;
+  const legacy = join(wsDir, LEGACY_CONFIG_NAME);
+  if (existsSync(legacy)) return legacy;
+  return null;
+}
+
+export function loadSessionConfigSource(sessionId: string): VeluConfigSource | null {
+  const cached = sessionCache.get(sessionId);
+  if (cached && Date.now() - cached.loadedAt < CACHE_TTL_MS) {
+    return cached.configSource;
+  }
+
+  const configPath = resolveWorkspaceConfigPath(sessionId);
+  if (!configPath) return null;
+
+  try {
+    const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
+    const config = normalizeConfigNavigation(raw) as VeluConfig;
+    const rawConfig = raw && typeof raw === 'object' && !Array.isArray(raw)
+      ? raw as Record<string, unknown>
+      : {};
+    const configSource: VeluConfigSource = { config, rawConfig };
+    sessionCache.set(sessionId, {
+      configSource,
+      loadedAt: Date.now(),
+    });
+    return configSource;
+  } catch {
+    return null;
+  }
+}
+
+export function clearSessionCache(sessionId: string): void {
+  sessionCache.delete(sessionId);
+}
+
+export function getWorkspaceDir(sessionId: string): string {
+  return join(WORKSPACE_DIR, sessionId);
+}
+
+// ── Theme color generation ─────────────────────────────────────────────────
+
+function hexToRgb(hex: string): [number, number, number] {
+  const h = hex.replace('#', '');
+  return [
+    parseInt(h.substring(0, 2), 16),
+    parseInt(h.substring(2, 4), 16),
+    parseInt(h.substring(4, 6), 16),
+  ];
+}
+
+function rgbToHex(r: number, g: number, b: number): string {
+  const clamp = (v: number) => Math.round(Math.max(0, Math.min(255, v)));
+  return '#' + [clamp(r), clamp(g), clamp(b)].map((c) => c.toString(16).padStart(2, '0')).join('');
+}
+
+function mixColors(hex1: string, hex2: string, weight: number): string {
+  const [r1, g1, b1] = hexToRgb(hex1);
+  const [r2, g2, b2] = hexToRgb(hex2);
+  return rgbToHex(r1 * weight + r2 * (1 - weight), g1 * weight + g2 * (1 - weight), b1 * weight + b2 * (1 - weight));
+}
+
+function textColorFor(hex: string): string {
+  const [r, g, b] = hexToRgb(hex);
+  const yiq = (r * 299 + g * 587 + b * 114) / 1000;
+  return yiq >= 140 ? '#111111' : '#ffffff';
+}
+
+/**
+ * Generate CSS custom properties for a session's primary color theme.
+ */
+export function getSessionThemeCss(sessionId: string): string | null {
+  const configSource = loadSessionConfigSource(sessionId);
+  const colors = configSource?.config.colors;
+  if (!colors?.primary) return null;
+
+  const { primary, light, dark } = colors;
+  const lightAccent = light || primary;
+  const darkAccent = dark || primary;
+  const lines: string[] = [];
+
+  if (lightAccent) {
+    const accentLow = mixColors(lightAccent, '#ffffff', 0.15);
+    lines.push(':root {');
+    lines.push(`  --color-fd-primary: ${lightAccent};`);
+    lines.push(`  --color-fd-primary-foreground: ${textColorFor(lightAccent)};`);
+    lines.push(`  --color-fd-accent: ${accentLow};`);
+    lines.push(`  --color-fd-accent-foreground: ${textColorFor(accentLow)};`);
+    lines.push(`  --color-fd-ring: ${lightAccent};`);
+    lines.push('}');
+  }
+
+  if (darkAccent) {
+    const accentLow = mixColors(darkAccent, '#000000', 0.3);
+    lines.push('.dark {');
+    lines.push(`  --color-fd-primary: ${darkAccent};`);
+    lines.push(`  --color-fd-primary-foreground: ${textColorFor(darkAccent)};`);
+    lines.push(`  --color-fd-accent: ${accentLow};`);
+    lines.push(`  --color-fd-accent-foreground: ${textColorFor(accentLow)};`);
+    lines.push(`  --color-fd-ring: ${darkAccent};`);
+    lines.push('}');
+  }
+
+  return lines.length > 0 ? lines.join('\n') : null;
+}

package/src/{preview-engine/lib/content-generator.ts → engine/lib/preview-content.ts}

@@ -3,11 +3,9 @@
  *
  * Reads a workspace directory (docs.json + MDX source files) and writes
  * processed content to an output directory that fumadocs-mdx scans.
- *
- * This is a simplified version of the build pipeline in build.ts/_server.mjs,
- * focused only on content generation (no engine scaffolding, theme CSS, etc.).
  */
 import {
+  copyFileSync,
   existsSync,
   mkdirSync,
   readFileSync,
@@ -15,7 +13,8 @@ import {
   rmSync,
   writeFileSync,
 } from 'node:fs';
-import { basename, dirname, extname, join, relative } from 'node:path';
+import { basename, dirname, extname, join, relative, resolve } from 'node:path';
+import { normalizeConfigNavigation } from './navigation-normalize';
 
 const PREVIEW_CONTENT_DIR = process.env.PREVIEW_CONTENT_DIR || './content';
 const WORKSPACE_DIR = process.env.WORKSPACE_DIR || '/mnt/nfs_share/editor_sessions';
@@ -23,6 +22,41 @@ const WORKSPACE_DIR = process.env.WORKSPACE_DIR || '/mnt/nfs_share/editor_sessio
 const PRIMARY_CONFIG_NAME = 'docs.json';
 const LEGACY_CONFIG_NAME = 'velu.json';
 
+/**
+ * Copy only spec files (JSON/YAML) from workspace to public/ so the
+ * OpenAPI component can resolve them. Images and other assets are served
+ * on-demand through the session assets API route, so we skip them here
+ * to keep session init fast.
+ */
+const SPEC_EXTENSIONS = new Set(['.json', '.yaml', '.yml']);
+
+function copySpecFiles(docsDir: string): void {
+  const publicDir = resolve('public');
+
+  function walk(dir: string): void {
+    if (!existsSync(dir)) return;
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      if (entry.name === 'node_modules') continue;
+      const srcPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(srcPath);
+        continue;
+      }
+      const ext = extname(entry.name).toLowerCase();
+      if (!SPEC_EXTENSIONS.has(ext)) continue;
+      const rel = relative(docsDir, srcPath);
+      const destPath = join(publicDir, rel);
+      mkdirSync(dirname(destPath), { recursive: true });
+      copyFileSync(srcPath, destPath);
+    }
+  }
+
+  mkdirSync(publicDir, { recursive: true });
+  walk(docsDir);
+}
+
 // ── Types ──────────────────────────────────────────────────────────────────
 
 interface VeluConfig {
@@ -136,7 +170,8 @@ function loadConfig(docsDir: string): {
   if (!configPath) {
     throw new Error(`No docs.json or velu.json found in ${docsDir}`);
   }
-  const raw = JSON.parse(readFileSync(configPath, 'utf-8')) as VeluConfig;
+  const parsed = JSON.parse(readFileSync(configPath, 'utf-8'));
+  const raw = normalizeConfigNavigation(parsed) as VeluConfig;
   const variables = resolveVariables(raw.variables);
   return { config: raw, variables };
 }
@@ -171,12 +206,126 @@ function sanitizeFrontmatterValue(value: string): string {
   return value.replace(/\r?\n+/g, ' ').replace(/"/g, '\\"').trim();
 }
 
+// ── OpenAPI helpers ───────────────────────────────────────────────────────
+
+const OPENAPI_PATH_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'trace']);
+
+function extractOpenApiSource(openapi: unknown): string | string[] | undefined {
+  if (typeof openapi === 'string' || Array.isArray(openapi)) return openapi;
+  if (openapi && typeof openapi === 'object') {
+    const source = (openapi as Record<string, unknown>).source;
+    if (typeof source === 'string' || Array.isArray(source)) return source;
+  }
+  return undefined;
+}
+
+function resolveOpenApiSpecList(openapi: unknown): string[] {
+  const source = extractOpenApiSource(openapi);
+  if (typeof source === 'string') {
+    const trimmed = source.trim();
+    return trimmed ? [trimmed] : [];
+  }
+  if (Array.isArray(source)) {
+    return source.filter((e): e is string => typeof e === 'string' && e.trim().length > 0).map(e => e.trim());
+  }
+  return [];
+}
+
+function normalizeOpenApiSpecForFrontmatter(spec: string | undefined): string | undefined {
+  if (!spec) return undefined;
+  const trimmed = String(spec).trim();
+  if (!trimmed) return undefined;
+  if (/^https?:\/\//i.test(trimmed) || trimmed.startsWith('file://')) return trimmed;
+  if (trimmed.startsWith('/')) return trimmed;
+  return `/${trimmed.replace(/^\.?\/*/, '')}`;
+}
+
+function slugFromOpenApiOperation(method: string, endpoint: string): string {
+  const cleaned = endpoint
+    .toLowerCase()
+    .replace(/^\/+/, '')
+    .replace(/[{}]/g, '')
+    .replace(/[^a-z0-9/._-]+/g, '-')
+    .replace(/\/+/g, '-')
+    .replace(/[-_.]{2,}/g, '-')
+    .replace(/^[-_.]+|[-_.]+$/g, '');
+  return `${method.toLowerCase()}-${cleaned || 'endpoint'}`;
+}
+
+interface OpenApiOperation {
+  spec: string;
+  method: string;
+  endpoint: string;
+  title?: string;
+  description?: string;
+  deprecated?: boolean;
+}
+
+function loadOpenApiOperations(specSource: string, docsDir: string): OpenApiOperation[] {
+  const resolvedPath = /^https?:\/\//i.test(specSource)
+    ? undefined
+    : join(docsDir, specSource.replace(/^\/+/, ''));
+  if (!resolvedPath || !existsSync(resolvedPath)) return [];
+
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(readFileSync(resolvedPath, 'utf-8'));
+  } catch {
+    return [];
+  }
+
+  const output: OpenApiOperation[] = [];
+  const paths = parsed.paths;
+  if (paths && typeof paths === 'object') {
+    for (const [endpoint, methods] of Object.entries(paths as Record<string, unknown>)) {
+      if (!endpoint.startsWith('/') || !methods || typeof methods !== 'object') continue;
+      for (const method of Object.keys(methods as Record<string, unknown>)) {
+        if (!OPENAPI_PATH_METHODS.has(method.toLowerCase())) continue;
+        const operation = (methods as Record<string, unknown>)[method];
+        if (!operation || typeof operation !== 'object') continue;
+        const op = operation as Record<string, unknown>;
+        output.push({
+          spec: specSource,
+          method: method.toUpperCase(),
+          endpoint,
+          title: typeof op.summary === 'string' ? op.summary : undefined,
+          description: typeof op.description === 'string' ? op.description : undefined,
+          deprecated: op.deprecated === true,
+        });
+      }
+    }
+  }
+
+  // Webhooks
+  const webhooks = parsed.webhooks;
+  if (webhooks && typeof webhooks === 'object') {
+    for (const [webhookName, pathItem] of Object.entries(webhooks as Record<string, unknown>)) {
+      if (!pathItem || typeof pathItem !== 'object') continue;
+      // Pick the first valid HTTP method from the webhook path item
+      const pi = pathItem as Record<string, unknown>;
+      const resolvedMethod = Array.from(OPENAPI_PATH_METHODS).find(m => pi[m] && typeof pi[m] === 'object');
+      if (!resolvedMethod) continue;
+      const operation = pi[resolvedMethod] as Record<string, unknown>;
+      output.push({
+        spec: specSource,
+        method: 'WEBHOOK',
+        endpoint: webhookName,
+        title: typeof operation.summary === 'string' ? operation.summary : undefined,
+        description: typeof operation.description === 'string' ? operation.description : undefined,
+        deprecated: operation.deprecated === true,
+      });
+    }
+  }
+
+  return output;
+}
+
 // ── Build artifacts ────────────────────────────────────────────────────────
 
-function buildArtifacts(config: VeluConfig): BuildArtifacts {
+function buildArtifacts(config: VeluConfig, docsDir?: string): BuildArtifacts {
   const pageMap: PageMapping[] = [];
   const metaFiles: MetaFile[] = [];
-  const rootTabs = (config.navigation.tabs || []).filter((tab) => !tab.href);
+  const rootTabs = (config.navigation?.tabs || []).filter((tab) => !tab.href);
   const rootPages = rootTabs.map((tab) => tab.slug);
   let firstPage = 'quickstart';
   let hasFirstPage = false;
@@ -237,13 +386,47 @@ function buildArtifacts(config: VeluConfig): BuildArtifacts {
       }
     }
 
+    // Auto-generate pages from OpenAPI spec when group has no explicit pages
+    if (group.pages.length === 0 && groupSpec && docsDir) {
+      const specs = resolveOpenApiSpecList(group.openapi ?? groupSpec);
+      if (specs.length === 0 && groupSpec) specs.push(groupSpec);
+      const seen = new Set<string>();
+      for (const spec of specs) {
+        for (const op of loadOpenApiOperations(spec, docsDir)) {
+          const key = `${op.method}::${op.endpoint}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+          const slug = slugFromOpenApiOperation(op.method, op.endpoint);
+          const dest = uniqueDestination(`${groupDir}/${slug}`);
+          pageMap.push({
+            src: `${op.spec} ${op.method} ${op.endpoint}`,
+            dest,
+            kind: 'openapi-operation',
+            openapiSpec: op.spec,
+            openapiMethod: op.method,
+            openapiEndpoint: op.endpoint,
+            title: op.title,
+            description: op.description,
+            deprecated: op.deprecated,
+          });
+          groupMetaPages.push(slug);
+          trackFirstPage(dest);
+        }
+      }
+    }
+
+    const groupMetaData: Record<string, unknown> = {
+      title: group.group,
+      pages: groupMetaPages,
+      defaultOpen: group.expanded !== false,
+    };
+    if (group.description) groupMetaData.description = group.description;
+    if (group.icon) groupMetaData.icon = group.icon;
+    if (group.iconType) groupMetaData.iconType = group.iconType;
+
     metaFiles.push({
       dir: groupDir,
-      data: {
-        title: group.group,
-        ...(group.description ? { description: group.description } : {}),
-        pages: groupMetaPages,
-      },
+      data: groupMetaData,
     });
   }
 
@@ -253,7 +436,6 @@ function buildArtifacts(config: VeluConfig): BuildArtifacts {
     const tabMetaPages: string[] = [];
     const tabSpec = typeof tab.openapi === 'string' ? tab.openapi : undefined;
 
-    // Process top-level pages in this tab
     if (tab.pages) {
       for (const item of tab.pages) {
         if (typeof item === 'string') {
@@ -267,7 +449,6 @@ function buildArtifacts(config: VeluConfig): BuildArtifacts {
       }
     }
 
-    // Process groups
     if (tab.groups) {
       for (const group of tab.groups) {
         const groupSlug = group.slug || pageBasename(group.group).toLowerCase().replace(/[^a-z0-9]+/g, '-');
@@ -276,18 +457,45 @@ function buildArtifacts(config: VeluConfig): BuildArtifacts {
       }
     }
 
+    // Auto-generate pages from OpenAPI spec when tab has no explicit pages/groups
+    if (!tab.pages?.length && !tab.groups?.length && tab.openapi !== undefined && docsDir) {
+      const specs = resolveOpenApiSpecList(tab.openapi);
+      if (specs.length === 0 && tabSpec) specs.push(tabSpec);
+      const seen = new Set<string>();
+      for (const spec of specs) {
+        for (const op of loadOpenApiOperations(spec, docsDir)) {
+          const key = `${op.method}::${op.endpoint}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+          const slug = slugFromOpenApiOperation(op.method, op.endpoint);
+          const dest = uniqueDestination(`${tabDir}/${slug}`);
+          pageMap.push({
+            src: `${op.spec} ${op.method} ${op.endpoint}`,
+            dest,
+            kind: 'openapi-operation',
+            openapiSpec: op.spec,
+            openapiMethod: op.method,
+            openapiEndpoint: op.endpoint,
+            title: op.title,
+            description: op.description,
+            deprecated: op.deprecated,
+          });
+          tabMetaPages.push(slug);
+          trackFirstPage(dest);
+        }
+      }
+    }
+
     metaFiles.push({
       dir: tabDir,
       data: { title: tab.tab, pages: tabMetaPages },
     });
   }
 
-  // Process all tabs
   for (const tab of rootTabs) {
     processTab(tab);
   }
 
-  // Root meta.json lists the tab slugs
   metaFiles.push({
     dir: '',
     data: { pages: rootPages.filter((p): p is string => typeof p === 'string') },
@@ -333,7 +541,6 @@ function writeLangContent(
 ) {
   const storagePrefix = useLangFolders ? langCode : (isDefault ? '' : langCode);
 
-  // Write meta files
   const metas = storagePrefix
     ? artifacts.metaFiles.map((m) => ({
         dir: m.dir ? `${storagePrefix}/${m.dir}` : storagePrefix,
@@ -347,7 +554,6 @@ function writeLangContent(
     writeFileSync(metaPath, JSON.stringify(meta.data, null, 2) + '\n', 'utf-8');
   }
 
-  // Copy and process pages
   for (const mapping of artifacts.pageMap) {
     const destPath = join(
       contentDir,
@@ -357,14 +563,19 @@ function writeLangContent(
     if (mapping.kind === 'openapi-operation') {
       mkdirSync(dirname(destPath), { recursive: true });
       const operationLabel = `${mapping.openapiMethod ?? 'GET'} ${mapping.openapiEndpoint ?? '/'}`;
+      const normalizedSpec = normalizeOpenApiSpecForFrontmatter(mapping.openapiSpec);
+      const openapiValue = normalizedSpec
+        ? `${normalizedSpec} ${operationLabel}`
+        : operationLabel;
       const title = sanitizeFrontmatterValue(mapping.title ?? operationLabel);
-      const openapi = operationLabel.replace(/"/g, '\\"');
+      const openapi = openapiValue.replace(/"/g, '\\"');
       const descriptionLine = mapping.description
         ? `\ndescription: "${sanitizeFrontmatterValue(mapping.description)}"`
         : '';
+      const deprecatedLine = mapping.deprecated === true ? `\ndeprecated: true` : '';
       writeFileSync(
         destPath,
-        `---\ntitle: "${title}"${descriptionLine}\nopenapi: "${openapi}"\n---\n`,
+        `---\ntitle: "${title}"${descriptionLine}${deprecatedLine}\nopenapi: "${openapi}"\n---\n`,
         'utf-8',
       );
       continue;
@@ -380,11 +591,6 @@ function writeLangContent(
     processPage(srcPath, destPath, src, variables);
   }
 
-  // Index page redirect
-  const urlPrefix = isDefault ? '' : langCode;
-  const href = urlPrefix
-    ? `/${urlPrefix}/${artifacts.firstPage}/`
-    : `/${artifacts.firstPage}/`;
   const indexPath = storagePrefix
     ? join(contentDir, storagePrefix, 'index.mdx')
     : join(contentDir, 'index.mdx');
@@ -399,8 +605,6 @@ function writeLangContent(
 
 /**
  * Generate all content for a session from its workspace.
- * Reads from workspaceDir (docs.json + MDX sources) and writes
- * processed content to outputDir.
  */
 export function generateSessionContent(sessionId: string): {
   firstPage: string;
@@ -409,18 +613,19 @@ export function generateSessionContent(sessionId: string): {
   const workspaceDir = join(WORKSPACE_DIR, sessionId);
   const outputDir = join(PREVIEW_CONTENT_DIR, sessionId);
 
-  // Clean previous content
   if (existsSync(outputDir)) {
     rmSync(outputDir, { recursive: true, force: true });
   }
   mkdirSync(outputDir, { recursive: true });
 
+  // Copy spec files (JSON/YAML) to public/ so the OpenAPI component can resolve them
+  copySpecFiles(workspaceDir);
+
   const { config, variables } = loadConfig(workspaceDir);
-  const navLanguages = config.navigation.languages;
+  const navLanguages = config.navigation?.languages;
   const simpleLanguages = config.languages || [];
 
   if (navLanguages && navLanguages.length > 0) {
-    // Per-language navigation
     const rootPages: string[] = [];
     let totalPages = 0;
     let firstPage = 'quickstart';
@@ -432,7 +637,7 @@ export function generateSessionContent(sessionId: string): {
         ...config,
         navigation: { ...config.navigation, tabs: langEntry.tabs },
       } as VeluConfig;
-      const artifacts = buildArtifacts(langConfig);
+      const artifacts = buildArtifacts(langConfig, workspaceDir);
       writeLangContent(workspaceDir, outputDir, langEntry.language, artifacts, variables, isDefault, true);
       totalPages += artifacts.pageMap.length;
       if (i === 0) firstPage = artifacts.firstPage;
@@ -448,8 +653,7 @@ export function generateSessionContent(sessionId: string): {
     return { firstPage, pageCount: totalPages };
   }
 
-  // Simple (single-lang or same-nav multi-lang)
-  const artifacts = buildArtifacts(config);
+  const artifacts = buildArtifacts(config, workspaceDir);
   const useLangFolders = simpleLanguages.length > 1;
   writeLangContent(
     workspaceDir, outputDir,
@@ -478,8 +682,6 @@ export function generateSessionContent(sessionId: string): {
 
 /**
  * Sync a single file after an edit in the workspace.
- * Re-reads the file from the workspace and writes the processed
- * version to the preview content directory.
  */
 export function syncSessionFile(
   sessionId: string,
@@ -488,13 +690,11 @@ export function syncSessionFile(
   const workspaceDir = join(WORKSPACE_DIR, sessionId);
   const outputDir = join(PREVIEW_CONTENT_DIR, sessionId);
 
-  // If this is a config file change, do a full regeneration
   if (filePath === PRIMARY_CONFIG_NAME || filePath === LEGACY_CONFIG_NAME) {
     generateSessionContent(sessionId);
     return { synced: true };
   }
 
-  // Load config for variable substitution
   let variables: Record<string, string> = {};
   try {
     const result = loadConfig(workspaceDir);
@@ -503,7 +703,6 @@ export function syncSessionFile(
     // Config might not exist yet
   }
 
-  // Find the source file
   const stripped = filePath.replace(/\.(mdx?|md)$/, '');
   let srcPath = join(workspaceDir, filePath);
   if (!existsSync(srcPath)) {
@@ -516,11 +715,9 @@ export function syncSessionFile(
     return { synced: false };
   }
 
-  // We need to figure out where this file maps in the output.
-  // Rebuild from config to get the page map, then find the mapping for this file.
   try {
     const { config } = loadConfig(workspaceDir);
-    const artifacts = buildArtifacts(config);
+    const artifacts = buildArtifacts(config, workspaceDir);
     const mapping = artifacts.pageMap.find((m) => {
       return m.src === stripped || m.src === filePath;
     });
@@ -534,7 +731,6 @@ export function syncSessionFile(
     // Fall through to direct copy
   }
 
-  // Fallback: try to process the file directly
   const destPath = join(outputDir, `${stripped}.mdx`);
   processPage(srcPath, destPath, stripped, variables);
   return { synced: true };