@litodocs/cli 0.5.2 → 0.7.0

package/src/core/config-sync.js

@@ -2,6 +2,7 @@ import pkg from 'fs-extra';
 const { readFile, writeFile, pathExists } = pkg;
 import { join } from 'path';
 import { readdir } from 'fs/promises';
+import { validateConfig } from './config-validator.js';
 
 /**
  * Auto-generates navigation structure from docs folder
@@ -70,8 +71,11 @@ export async function generateNavigationFromDocs(docsPath) {
 
 /**
  * Merges user config with auto-generated navigation
+ * @param {object} options - Sync options
+ * @param {boolean} options.validate - Whether to validate the config (default: true)
  */
-export async function syncDocsConfig(projectDir, docsPath, userConfigPath) {
+export async function syncDocsConfig(projectDir, docsPath, userConfigPath, options = {}) {
+  const { validate = true } = options;
   const configPath = join(projectDir, 'docs-config.json');
 
   // Read base config from template
@@ -80,6 +84,16 @@ export async function syncDocsConfig(projectDir, docsPath, userConfigPath) {
   // If user has a custom config, merge it
   if (userConfigPath && await pathExists(userConfigPath)) {
     const userConfig = JSON.parse(await readFile(userConfigPath, 'utf-8'));
+
+    // Validate user config before merging (only core config is validated)
+    if (validate) {
+      const validationResult = validateConfig(userConfig, projectDir);
+      if (!validationResult.valid) {
+        const errorMessages = validationResult.errors.map(e => `${e.path}: ${e.message}`).join('\n  ');
+        throw new Error(`Configuration validation failed:\n  ${errorMessages}`);
+      }
+    }
+
     config = deepMerge(config, userConfig);
   }
 
@@ -90,6 +104,8 @@ export async function syncDocsConfig(projectDir, docsPath, userConfigPath) {
 
   // Write merged config
   await writeFile(configPath, JSON.stringify(config, null, 2), 'utf-8');
+
+  return { config };
 }
 
 function formatLabel(str) {

package/src/core/config-validator.js

@@ -0,0 +1,229 @@
+/**
+ * Configuration Validator
+ *
+ * Validates user docs-config.json against the core schema.
+ * Core config is strictly validated - extensions are always allowed
+ * (templates simply ignore what they don't support).
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import pc from 'picocolors';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Core schema defines portable config across all templates
+const CORE_SCHEMA_PATH = join(__dirname, '../schema/core-schema.json');
+
+// Core config keys that all templates must support
+const CORE_CONFIG_KEYS = [
+  'metadata',
+  'branding',
+  'navigation',
+  'search',
+  'seo',
+  'i18n',
+  'assets'
+];
+
+// Extension keys that are template-specific (optional, never cause errors)
+const EXTENSION_KEYS = [
+  'footer',
+  'theme',
+  'landing',
+  'integrations',
+  'versioning'
+];
+
+/**
+ * Load the core schema
+ */
+function loadCoreSchema() {
+  if (!existsSync(CORE_SCHEMA_PATH)) {
+    return null;
+  }
+  return JSON.parse(readFileSync(CORE_SCHEMA_PATH, 'utf-8'));
+}
+
+/**
+ * Load template manifest from project directory
+ */
+export function loadTemplateManifest(projectDir) {
+  const manifestPath = join(projectDir, 'template.json');
+  if (!existsSync(manifestPath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(manifestPath, 'utf-8'));
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Validate configuration against core schema (basic validation)
+ * Only validates REQUIRED fields and types - extensions are always allowed.
+ */
+function validateCoreConfig(config, schema) {
+  const errors = [];
+
+  // Check required fields
+  if (schema.required) {
+    for (const field of schema.required) {
+      if (!(field in config)) {
+        errors.push({
+          path: field,
+          message: `Required field '${field}' is missing`
+        });
+      }
+    }
+  }
+
+  // Check metadata.name is required
+  if (config.metadata && !config.metadata.name) {
+    errors.push({
+      path: 'metadata.name',
+      message: "Required field 'metadata.name' is missing"
+    });
+  }
+
+  // Validate types for core fields
+  if (config.metadata && typeof config.metadata !== 'object') {
+    errors.push({
+      path: 'metadata',
+      message: "'metadata' must be an object"
+    });
+  }
+
+  if (config.navigation?.sidebar && !Array.isArray(config.navigation.sidebar)) {
+    errors.push({
+      path: 'navigation.sidebar',
+      message: "'navigation.sidebar' must be an array"
+    });
+  }
+
+  if (config.navigation?.navbar?.links && !Array.isArray(config.navigation.navbar.links)) {
+    errors.push({
+      path: 'navigation.navbar.links',
+      message: "'navigation.navbar.links' must be an array"
+    });
+  }
+
+  // Validate sidebar items structure
+  if (config.navigation?.sidebar && Array.isArray(config.navigation.sidebar)) {
+    config.navigation.sidebar.forEach((group, i) => {
+      if (!group.label) {
+        errors.push({
+          path: `navigation.sidebar[${i}].label`,
+          message: `Sidebar group at index ${i} is missing required 'label' field`
+        });
+      }
+      if (group.items && !Array.isArray(group.items)) {
+        errors.push({
+          path: `navigation.sidebar[${i}].items`,
+          message: `Sidebar group '${group.label}' items must be an array`
+        });
+      }
+    });
+  }
+
+  return errors;
+}
+
+/**
+ * Validate user configuration
+ *
+ * Only validates core config structure. Extensions are always allowed -
+ * templates simply ignore what they don't support.
+ *
+ * @param {object} config - User's docs-config.json content
+ * @param {string} projectDir - Path to the project directory
+ * @param {object} options - Validation options
+ * @param {boolean} options.silent - If true, don't print anything
+ * @returns {{ valid: boolean, errors: Array }}
+ */
+export function validateConfig(config, projectDir, options = {}) {
+  const { silent = false } = options;
+
+  const coreSchema = loadCoreSchema();
+
+  // Only validate core config - extensions are always allowed
+  const coreErrors = coreSchema ? validateCoreConfig(config, coreSchema) : [];
+
+  const result = {
+    valid: coreErrors.length === 0,
+    errors: coreErrors,
+    manifest: loadTemplateManifest(projectDir)
+  };
+
+  if (!silent && coreErrors.length > 0) {
+    printValidationErrors(coreErrors);
+  }
+
+  return result;
+}
+
+/**
+ * Print validation errors to console
+ */
+function printValidationErrors(errors) {
+  console.log(pc.red('\n✗ Configuration validation failed:\n'));
+  for (const error of errors) {
+    console.log(pc.red(`  • ${error.path}: ${error.message}`));
+  }
+  console.log('');
+}
+
+/**
+ * Get list of portable (core) config keys
+ */
+export function getCoreConfigKeys() {
+  return [...CORE_CONFIG_KEYS];
+}
+
+/**
+ * Get list of extension config keys
+ */
+export function getExtensionKeys() {
+  return [...EXTENSION_KEYS];
+}
+
+/**
+ * Extract only core config from a full config object
+ */
+export function extractCoreConfig(config) {
+  const coreConfig = {};
+  for (const key of CORE_CONFIG_KEYS) {
+    if (key in config) {
+      coreConfig[key] = config[key];
+    }
+  }
+  return coreConfig;
+}
+
+/**
+ * Extract only extension config from a full config object
+ */
+export function extractExtensionConfig(config) {
+  const extensionConfig = {};
+  for (const key of EXTENSION_KEYS) {
+    if (key in config) {
+      extensionConfig[key] = config[key];
+    }
+  }
+  return extensionConfig;
+}
+
+/**
+ * Check if config is portable (uses only core config)
+ * Useful for users who want to ensure their config works with any template.
+ */
+export function isPortableConfig(config) {
+  for (const key of EXTENSION_KEYS) {
+    if (key in config) {
+      return false;
+    }
+  }
+  return true;
+}

package/src/core/config.js

@@ -1,9 +1,15 @@
 import pkg from "fs-extra";
-const { readFile, writeFile, ensureDir } = pkg;
+const { readFile, writeFile, ensureDir, pathExists } = pkg;
 import { join } from "path";
 import { generateThemeStyles } from "./colors.js";
 
-export async function generateConfig(projectDir, options) {
+/**
+ * Generate configuration for the project
+ * @param {string} projectDir - The scaffolded project directory
+ * @param {object} options - CLI options
+ * @param {object|null} frameworkConfig - Framework configuration (optional)
+ */
+export async function generateConfig(projectDir, options, frameworkConfig = null) {
   const {
     baseUrl,
     name,
@@ -68,27 +74,65 @@ export async function generateConfig(projectDir, options) {
     await writeFile(join(stylesDir, "generated-theme.css"), "/* No generated theme styles */", "utf-8");
   }
 
-  // Update astro.config.mjs with base URL and site URL
-  if ((baseUrl && baseUrl !== "/") || config.metadata?.url) {
+  // Update astro.config.mjs with base URL and site URL (only for Astro)
+  const frameworkName = frameworkConfig?.name || 'astro';
+
+  if (frameworkName === 'astro' && ((baseUrl && baseUrl !== "/") || config.metadata?.url)) {
     const astroConfigPath = join(projectDir, "astro.config.mjs");
-    let content = await readFile(astroConfigPath, "utf-8");
+    if (await pathExists(astroConfigPath)) {
+      let content = await readFile(astroConfigPath, "utf-8");
+
+      let injection = "export default defineConfig({\n";
+
+      if (baseUrl && baseUrl !== "/") {
+        injection += `  base: '${baseUrl}',\n`;
+      }
+
+      if (config.metadata?.url) {
+        injection += `  site: '${config.metadata.url}',\n`;
+      }
+
+      // Add base/site option to defineConfig
+      content = content.replace(
+        "export default defineConfig({",
+        injection
+      );
 
-    let injection = "export default defineConfig({\n";
-    
-    if (baseUrl && baseUrl !== "/") {
-      injection += `  base: '${baseUrl}',\n`;
+      await writeFile(astroConfigPath, content, "utf-8");
     }
-    
-    if (config.metadata?.url) {
-      injection += `  site: '${config.metadata.url}',\n`;
+  }
+
+  // Update vite.config.js for React/Vue frameworks
+  if (['react', 'vue'].includes(frameworkName) && baseUrl && baseUrl !== "/") {
+    const viteConfigPath = join(projectDir, "vite.config.js");
+    if (await pathExists(viteConfigPath)) {
+      let content = await readFile(viteConfigPath, "utf-8");
+
+      // Add base option to defineConfig
+      if (content.includes("defineConfig({")) {
+        content = content.replace(
+          "defineConfig({",
+          `defineConfig({\n  base: '${baseUrl}',`
+        );
+        await writeFile(viteConfigPath, content, "utf-8");
+      }
     }
+  }
 
-    // Add base/site option to defineConfig
-    content = content.replace(
-      "export default defineConfig({",
-      injection
-    );
+  // Update next.config.js for Next.js
+  if (frameworkName === 'next' && baseUrl && baseUrl !== "/") {
+    const nextConfigPath = join(projectDir, "next.config.js");
+    if (await pathExists(nextConfigPath)) {
+      let content = await readFile(nextConfigPath, "utf-8");
 
-    await writeFile(astroConfigPath, content, "utf-8");
+      // Add basePath to Next.js config
+      if (!content.includes("basePath")) {
+        content = content.replace(
+          "module.exports = {",
+          `module.exports = {\n  basePath: '${baseUrl}',`
+        );
+        await writeFile(nextConfigPath, content, "utf-8");
+      }
+    }
   }
 }

package/src/core/framework-runner.js

@@ -0,0 +1,208 @@
+import { runBinary } from './package-manager.js';
+import { join } from 'path';
+import pkg from 'fs-extra';
+const { pathExists, readJson } = pkg;
+
+/**
+ * Framework configuration schema
+ * Templates can define their framework in lito-manifest.json or template-manifest.json
+ */
+const DEFAULT_FRAMEWORK_CONFIGS = {
+  astro: {
+    name: 'astro',
+    commands: {
+      dev: ['astro', ['dev']],
+      build: ['astro', ['build']],
+    },
+    contentDir: 'src/pages',
+    publicDir: 'public',
+    configFile: 'astro.config.mjs',
+    layoutInjection: true,
+    layoutPath: 'layouts/MarkdownLayout.astro',
+    apiLayoutPath: 'layouts/APILayout.astro',
+  },
+  react: {
+    name: 'react',
+    commands: {
+      dev: ['vite', ['--host']],
+      build: ['vite', ['build']],
+    },
+    contentDir: 'src/content',
+    publicDir: 'public',
+    configFile: 'vite.config.js',
+    layoutInjection: false,
+    useMDX: true,
+    // HMR trigger file that will be updated when content changes
+    hmrTriggerFile: 'src/.lito-hmr-trigger.js',
+  },
+  next: {
+    name: 'next',
+    commands: {
+      dev: ['next', ['dev']],
+      build: ['next', ['build']],
+    },
+    contentDir: 'content',
+    publicDir: 'public',
+    configFile: 'next.config.js',
+    layoutInjection: false,
+    useMDX: true,
+  },
+  vue: {
+    name: 'vue',
+    commands: {
+      dev: ['vite', ['--host']],
+      build: ['vite', ['build']],
+    },
+    contentDir: 'src/content',
+    publicDir: 'public',
+    configFile: 'vite.config.js',
+    layoutInjection: false,
+    // HMR trigger file that will be updated when content changes
+    hmrTriggerFile: 'src/.lito-hmr-trigger.js',
+  },
+};
+
+/**
+ * Detect framework from template directory
+ * Checks for lito-manifest.json, template-manifest.json, or infers from config files
+ */
+export async function detectFramework(projectDir) {
+  // Check for lito-manifest.json first (preferred)
+  const litoManifestPath = join(projectDir, 'lito-manifest.json');
+  if (await pathExists(litoManifestPath)) {
+    try {
+      const manifest = await readJson(litoManifestPath);
+      if (manifest.framework) {
+        return mergeFrameworkConfig(manifest.framework, manifest);
+      }
+    } catch {
+      // Fall through to other detection methods
+    }
+  }
+
+  // Check for template-manifest.json (legacy)
+  const templateManifestPath = join(projectDir, 'template-manifest.json');
+  if (await pathExists(templateManifestPath)) {
+    try {
+      const manifest = await readJson(templateManifestPath);
+      if (manifest.framework) {
+        return mergeFrameworkConfig(manifest.framework, manifest);
+      }
+    } catch {
+      // Fall through to inference
+    }
+  }
+
+  // Infer from config files
+  if (await pathExists(join(projectDir, 'astro.config.mjs')) ||
+      await pathExists(join(projectDir, 'astro.config.js'))) {
+    return DEFAULT_FRAMEWORK_CONFIGS.astro;
+  }
+
+  if (await pathExists(join(projectDir, 'next.config.js')) ||
+      await pathExists(join(projectDir, 'next.config.mjs')) ||
+      await pathExists(join(projectDir, 'next.config.ts'))) {
+    return DEFAULT_FRAMEWORK_CONFIGS.next;
+  }
+
+  // Check package.json for framework hints
+  const packageJsonPath = join(projectDir, 'package.json');
+  if (await pathExists(packageJsonPath)) {
+    try {
+      const packageJson = await readJson(packageJsonPath);
+      const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
+
+      if (deps['next']) return DEFAULT_FRAMEWORK_CONFIGS.next;
+      if (deps['astro']) return DEFAULT_FRAMEWORK_CONFIGS.astro;
+      if (deps['vue'] && deps['vite']) return DEFAULT_FRAMEWORK_CONFIGS.vue;
+      if (deps['react'] && deps['vite']) return DEFAULT_FRAMEWORK_CONFIGS.react;
+    } catch {
+      // Fall through to default
+    }
+  }
+
+  // Default to Astro (backward compatible)
+  return DEFAULT_FRAMEWORK_CONFIGS.astro;
+}
+
+/**
+ * Merge custom framework config with defaults
+ */
+function mergeFrameworkConfig(frameworkName, manifest) {
+  const baseConfig = DEFAULT_FRAMEWORK_CONFIGS[frameworkName] || {
+    name: frameworkName,
+    contentDir: 'src/content',
+    publicDir: 'public',
+    layoutInjection: false,
+  };
+
+  return {
+    ...baseConfig,
+    ...manifest.frameworkConfig,
+    name: frameworkName,
+    // Allow manifest to override commands
+    commands: {
+      ...baseConfig.commands,
+      ...manifest.commands,
+    },
+  };
+}
+
+/**
+ * Run the framework's dev server
+ */
+export async function runFrameworkDev(projectDir, frameworkConfig, port = '4321') {
+  const { commands } = frameworkConfig;
+  const [binary, args] = commands.dev;
+
+  const devArgs = [...args];
+
+  // Add port based on framework
+  if (frameworkConfig.name === 'astro') {
+    devArgs.push('--port', port);
+  } else if (frameworkConfig.name === 'next') {
+    devArgs.push('-p', port);
+  } else {
+    // Vite-based frameworks
+    devArgs.push('--port', port);
+  }
+
+  await runBinary(projectDir, binary, devArgs);
+}
+
+/**
+ * Run the framework's build command
+ */
+export async function runFrameworkBuild(projectDir, frameworkConfig) {
+  const { commands } = frameworkConfig;
+  const [binary, args] = commands.build;
+
+  await runBinary(projectDir, binary, args);
+}
+
+/**
+ * Get the output directory for the built site
+ */
+export function getOutputDir(frameworkConfig) {
+  switch (frameworkConfig.name) {
+    case 'astro':
+      return 'dist';
+    case 'next':
+      return '.next';
+    case 'react':
+    case 'vue':
+      return 'dist';
+    default:
+      return 'dist';
+  }
+}
+
+/**
+ * Check if framework needs search indexing (pagefind)
+ */
+export function needsSearchIndex(frameworkConfig) {
+  // Only static-output frameworks need pagefind
+  return ['astro', 'react', 'vue'].includes(frameworkConfig.name);
+}
+
+export { DEFAULT_FRAMEWORK_CONFIGS };