jamdesk 1.0.0

package/vendored/lib/validate-config.ts

@@ -0,0 +1,268 @@
+/**
+ * Configuration Validation
+ * 
+ * Validates docs.json configuration against the JSON schema.
+ * Supports JSON5 format for comments and trailing commas.
+ * 
+ * Note: OpenAPI validation is handled separately by:
+ * - CLI: cli/src/commands/validate.ts
+ * - Build: page.tsx (at render time)
+ */
+
+import AjvModule, { ErrorObject } from 'ajv';
+// ESM compatibility - Ajv exports differently in Node.js ESM
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const Ajv = (AjvModule as any).default || AjvModule;
+import JSON5 from 'json5';
+import fs from 'fs';
+import path from 'path';
+import { LIB_DIR } from './paths.js';
+
+// Types
+export interface DocsConfig {
+  name: string;
+  theme?: 'jam' | 'nebula' | 'pulsar';
+  navigation: NavigationConfig;
+  integrations?: IntegrationsConfig;
+  [key: string]: unknown;
+}
+
+export interface IntegrationsConfig {
+  ga4?: { measurementId: string };
+  gtm?: { tagId: string };
+  [key: string]: unknown;
+}
+
+export interface NavigationConfig {
+  /**
+   * @deprecated Use `tabs` instead. Anchors with content should be converted to tabs.
+   * For external links, use the top-level `anchors` field in DocsConfig.
+   */
+  anchors?: unknown[];
+  tabs?: unknown[];
+  groups?: unknown[];
+  pages?: unknown[];
+  products?: unknown[];
+  dropdowns?: unknown[];
+  versions?: unknown[];
+  languages?: unknown[];
+  [key: string]: unknown;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  config?: DocsConfig;
+  error?: string;
+  errorType?: 'config_error';
+  errorSuggestion?: string;
+}
+
+type Schema = Record<string, unknown>;
+
+// Cache the schema
+let cachedSchema: Schema | null = null;
+
+/**
+ * Get the JSON schema for docs.json validation
+ * First tries to load from local cache, then fetches from jamdesk.com
+ */
+export async function getSchema(): Promise<Schema | null> {
+  if (cachedSchema) {
+    return cachedSchema;
+  }
+  
+  // Try to load bundled schema first
+  const bundledSchemaPath = path.join(LIB_DIR, '../schema/docs-schema.json');
+  if (fs.existsSync(bundledSchemaPath)) {
+    const schemaContent = fs.readFileSync(bundledSchemaPath, 'utf-8');
+    cachedSchema = JSON.parse(schemaContent) as Schema;
+    return cachedSchema;
+  }
+  
+  // Fetch from jamdesk.com as fallback
+  try {
+    const response = await fetch('https://www.jamdesk.com/docs.json');
+    if (response.ok) {
+      cachedSchema = await response.json() as Schema;
+      return cachedSchema;
+    }
+  } catch (err) {
+    const error = err as Error;
+    console.log(JSON.stringify({
+      severity: 'WARNING',
+      message: 'Could not fetch schema from jamdesk.com',
+      error: error.message,
+    }));
+  }
+  
+  // Return null if no schema available (validation will be skipped)
+  return null;
+}
+
+/**
+ * Parse docs.json content (supports both JSON and JSON5)
+ */
+export function parseConfig(content: string): DocsConfig {
+  try {
+    // Try JSON5 first (supports comments, trailing commas)
+    return JSON5.parse(content) as DocsConfig;
+  } catch {
+    // Fallback to standard JSON
+    return JSON.parse(content) as DocsConfig;
+  }
+}
+
+/**
+ * Format validation errors into user-friendly messages
+ */
+export function formatValidationErrors(errors: ErrorObject[] | null | undefined): string {
+  if (!errors || errors.length === 0) {
+    return 'Unknown validation error';
+  }
+  
+  const messages = errors.slice(0, 3).map(err => {
+    const path = err.instancePath || 'root';
+    
+    switch (err.keyword) {
+      case 'required':
+        return `Missing required field "${(err.params as { missingProperty?: string }).missingProperty}" at ${path}`;
+      case 'type':
+        return `Invalid type at ${path}: expected ${(err.params as { type?: string }).type}`;
+      case 'enum':
+        return `Invalid value at ${path}: must be one of ${(err.params as { allowedValues?: string[] }).allowedValues?.join(', ')}`;
+      case 'const':
+        return `Invalid value at ${path}: must be "${(err.params as { allowedValue?: string }).allowedValue}"`;
+      case 'additionalProperties':
+        return `Unknown property "${(err.params as { additionalProperty?: string }).additionalProperty}" at ${path}`;
+      case 'minLength':
+        return `Value at ${path} must not be empty`;
+      case 'pattern':
+        return `Invalid format at ${path}`;
+      case 'anyOf':
+        return `Invalid value at ${path}: does not match any allowed format`;
+      default:
+        return `${err.message} at ${path}`;
+    }
+  });
+  
+  if (errors.length > 3) {
+    messages.push(`...and ${errors.length - 3} more error(s)`);
+  }
+  
+  return messages.join('. ');
+}
+
+/**
+ * Validate docs.json configuration
+ * @param configPath - Full path to docs.json
+ * @param docsPath - Optional monorepo path for better error messages (e.g., "jamdesk")
+ */
+export async function validateConfig(configPath: string, docsPath?: string): Promise<ValidationResult> {
+  // Check file exists
+  if (!fs.existsSync(configPath)) {
+    const pathHint = docsPath
+      ? `Missing docs.json at '${docsPath}/docs.json'. Check that your monorepo path is correct.`
+      : 'Missing docs.json configuration file. Your repository must have a docs.json file in the root directory.';
+    return {
+      valid: false,
+      error: pathHint,
+    };
+  }
+  
+  // Read and parse file
+  let config: DocsConfig;
+  try {
+    const content = fs.readFileSync(configPath, 'utf-8');
+    config = parseConfig(content);
+  } catch (parseErr) {
+    const error = parseErr as Error;
+    return {
+      valid: false,
+      error: `Failed to parse docs.json: ${error.message}. Ensure your JSON is valid (tip: use JSON5 format to allow comments).`,
+    };
+  }
+  
+  // Basic validation (always runs, even without schema)
+  if (!config.name) {
+    return {
+      valid: false,
+      error: 'Invalid docs.json: Missing required "name" field.',
+    };
+  }
+  
+  if (!config.navigation) {
+    return {
+      valid: false,
+      error: 'Invalid docs.json: Missing required "navigation" field.',
+    };
+  }
+  
+  // Reject legacy array format
+  if (Array.isArray(config.navigation)) {
+    return {
+      valid: false,
+      error: 'Invalid docs.json: Array of groups is not supported. Please use a hierarchical object format with groups. See https://www.jamdesk.com/docs/navigation for details.',
+    };
+  }
+  
+  // Validate navigation has content
+  const nav = config.navigation;
+  const hasContent = nav.anchors || nav.tabs || nav.groups || nav.pages || 
+                    nav.products || nav.dropdowns || nav.versions || nav.languages;
+  if (!hasContent) {
+    return {
+      valid: false,
+      error: 'Invalid docs.json: Navigation must have at least one of: anchors, tabs, groups, pages, products, dropdowns, versions, or languages.',
+    };
+  }
+  
+  // Validate theme
+  const validThemes = ['jam', 'nebula', 'pulsar'];
+  if (config.theme && !validThemes.includes(config.theme)) {
+    return {
+      valid: false,
+      error: `Invalid docs.json: Theme "${config.theme}" is not supported. Valid themes are: ${validThemes.join(', ')}.`,
+    };
+  }
+
+  // Build error for navigation.anchors (no longer supported)
+  if (nav.anchors) {
+    return {
+      valid: false,
+      error: 'Invalid docs.json: "anchors" is not supported within "navigation". Use "tabs" instead. Run `jamdesk migrate` to update your docs.json.',
+      errorType: 'config_error',
+    };
+  }
+
+  // Try schema validation if available (non-blocking if schema not available)
+  try {
+    const schema = await getSchema();
+    if (schema) {
+      const ajv = new Ajv({ allErrors: true, strict: false });
+      const validate = ajv.compile(schema);
+      const valid = validate(config);
+      
+      if (!valid) {
+        const errorMessage = formatValidationErrors(validate.errors);
+        return {
+          valid: false,
+          error: `Invalid docs.json: ${errorMessage}`,
+          errorType: 'config_error',
+        };
+      }
+    }
+  } catch (schemaErr) {
+    const error = schemaErr as Error;
+    // Schema validation is best-effort, don't fail the build if it errors
+    console.log(JSON.stringify({
+      severity: 'WARNING',
+      message: 'Schema validation skipped',
+      error: error.message,
+    }));
+  }
+  
+  return {
+    valid: true,
+    config,
+  };
+}

package/vendored/next.config.js

@@ -0,0 +1,45 @@
+/**
+ * CLI-specific Next.js config
+ *
+ * IMPORTANT: Keep this minimal! Adding turbopack.root or complex settings
+ * caused 80s+ compile times. Only include what's necessary.
+ *
+ * Why optimizePackageImports is critical:
+ * - Without it: Turbopack parses ALL exports from heavy packages (shiki 2.5MB, lodash, etc.)
+ * - With it: Only loads what's actually imported
+ * - Result: ~40s compile times vs 75s+ without
+ */
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  // Hide dev indicator (floating icon in bottom-left)
+  devIndicators: false,
+  // Keep swagger-parser external (uses Node.js APIs)
+  serverExternalPackages: ['@apidevtools/swagger-parser'],
+  // Turbopack config - only resolveAlias, NOT root (root causes caching issues)
+  turbopack: {
+    resolveAlias: {
+      // Replace Next.js legacy polyfills with empty module (saves ~14KB)
+      '../build/polyfills/polyfill-module': './lib/empty-polyfill.js',
+      'next/dist/build/polyfills/polyfill-module': './lib/empty-polyfill.js',
+    },
+  },
+  // Critical for fast builds
+  experimental: {
+    optimizePackageImports: [
+      'shiki',
+      '@shikijs/rehype',
+      '@shikijs/transformers',
+      'remark-gfm',
+      'gray-matter',
+      'next-mdx-remote',
+      'flexsearch',
+      'lodash',
+      '@radix-ui/react-slot',
+      '@radix-ui/react-collapsible',
+      '@radix-ui/react-tooltip',
+    ],
+  },
+}
+
+export default nextConfig

package/vendored/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+}
+

package/vendored/schema/README.md

@@ -0,0 +1,28 @@
+# docs-schema.json
+
+This file is **auto-synced from `marketing/public/docs.json`**.
+
+## DO NOT EDIT DIRECTLY
+
+The master copy of the JSON schema is in `marketing/public/docs.json` and is served at:
+- https://www.jamdesk.com/docs.json
+
+## Sync Process
+
+The schema is synced to this location by running `npm run vendor` in the CLI:
+
+```bash
+cd builder/cli
+npm run vendor
+```
+
+This copies:
+1. `marketing/public/docs.json` → `builder/build-service/schema/docs-schema.json`
+2. Then `builder/build-service/schema/` → `builder/cli/vendored/schema/`
+
+## Making Changes
+
+1. Edit `marketing/public/docs.json` (the master)
+2. Run `npm run vendor` in `builder/cli/`
+3. Deploy marketing site to update the public schema
+4. Commit all three repositories