@litodocs/cli 0.5.2 → 0.7.0

package/lito-manifest.schema.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Lito Template Manifest",
+  "description": "Configuration schema for Lito documentation templates",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Template name"
+    },
+    "version": {
+      "type": "string",
+      "description": "Template version (semver)"
+    },
+    "framework": {
+      "type": "string",
+      "enum": ["astro", "react", "next", "vue", "nuxt", "svelte"],
+      "description": "The framework this template uses"
+    },
+    "frameworkConfig": {
+      "type": "object",
+      "description": "Custom framework configuration overrides",
+      "properties": {
+        "contentDir": {
+          "type": "string",
+          "description": "Directory where documentation content is placed"
+        },
+        "publicDir": {
+          "type": "string",
+          "description": "Directory for static public assets"
+        },
+        "configFile": {
+          "type": "string",
+          "description": "Main framework config file name"
+        },
+        "layoutInjection": {
+          "type": "boolean",
+          "description": "Whether to inject layout frontmatter into markdown files"
+        },
+        "layoutPath": {
+          "type": "string",
+          "description": "Path to the markdown layout component"
+        },
+        "useMDX": {
+          "type": "boolean",
+          "description": "Whether the template uses MDX for markdown processing"
+        }
+      }
+    },
+    "commands": {
+      "type": "object",
+      "description": "Custom build/dev commands",
+      "properties": {
+        "dev": {
+          "type": "array",
+          "items": [
+            { "type": "string", "description": "Binary name" },
+            { "type": "array", "items": { "type": "string" }, "description": "Arguments" }
+          ],
+          "description": "Dev server command [binary, [args]]"
+        },
+        "build": {
+          "type": "array",
+          "items": [
+            { "type": "string", "description": "Binary name" },
+            { "type": "array", "items": { "type": "string" }, "description": "Arguments" }
+          ],
+          "description": "Build command [binary, [args]]"
+        }
+      }
+    },
+    "features": {
+      "type": "object",
+      "description": "Template feature flags",
+      "properties": {
+        "search": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether template supports search"
+        },
+        "i18n": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether template supports internationalization"
+        },
+        "versioning": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether template supports doc versioning"
+        },
+        "darkMode": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether template supports dark mode"
+        },
+        "apiDocs": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether template supports OpenAPI documentation"
+        }
+      }
+    },
+    "requiredFiles": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of files required for this template to work"
+    },
+    "author": {
+      "type": "string",
+      "description": "Template author"
+    },
+    "repository": {
+      "type": "string",
+      "description": "Git repository URL"
+    }
+  },
+  "required": ["framework"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litodocs/cli",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "Beautiful documentation sites from Markdown. Fast, simple, and open-source.",
   "main": "src/index.js",
   "type": "module",

package/src/cli.js

@@ -3,6 +3,11 @@ import pc from "picocolors";
 import { buildCommand } from "./commands/build.js";
 import { devCommand } from "./commands/dev.js";
 import { ejectCommand } from "./commands/eject.js";
+import { initCommand } from "./commands/init.js";
+import { validateCommand } from "./commands/validate.js";
+import { previewCommand } from "./commands/preview.js";
+import { doctorCommand } from "./commands/doctor.js";
+import { infoCommand } from "./commands/info.js";
 import {
   templateListCommand,
   templateCacheCommand,
@@ -20,7 +25,7 @@ export async function cli() {
     .description(
       "Beautiful documentation sites from Markdown. Fast, simple, and open-source."
     )
-    .version("0.5.2");
+    .version("0.6.0");
 
   program
     .command("build")
@@ -95,6 +100,49 @@ export async function cli() {
     .option("--refresh", "Force re-download template (bypass cache)", false)
     .action(ejectCommand);
 
+  // Initialize a new project
+  program
+    .command("init")
+    .description("Initialize a new documentation project")
+    .option("-o, --output <path>", "Output directory for the project")
+    .option("-n, --name <name>", "Project name")
+    .option("-t, --template <name>", "Template to use", "default")
+    .option("--sample", "Create sample documentation pages", true)
+    .action(initCommand);
+
+  // Validate configuration
+  program
+    .command("validate")
+    .description("Validate docs-config.json configuration")
+    .option("-i, --input <path>", "Path to the docs folder")
+    .option("-q, --quiet", "Quiet mode for CI (exit code only)")
+    .action(validateCommand);
+
+  // Preview production build
+  program
+    .command("preview")
+    .description("Preview production build locally")
+    .option("-i, --input <path>", "Path to docs folder (will build if no dist exists)")
+    .option("-o, --output <path>", "Path to built site", "./dist")
+    .option("-t, --template <name>", "Template to use if building", "default")
+    .option("-b, --base-url <url>", "Base URL for the site", "/")
+    .option("-p, --port <number>", "Port for preview server", "4321")
+    .action(previewCommand);
+
+  // Doctor - diagnose issues
+  program
+    .command("doctor")
+    .description("Diagnose common issues with your docs project")
+    .option("-i, --input <path>", "Path to the docs folder")
+    .action(doctorCommand);
+
+  // Info - show project information
+  program
+    .command("info")
+    .description("Show project information and statistics")
+    .option("-i, --input <path>", "Path to the docs folder")
+    .action(infoCommand);
+
   // Template management commands
   const templateCmd = program
     .command("template")

package/src/commands/build.js

@@ -5,10 +5,10 @@ import pc from 'picocolors';
 import { scaffoldProject, cleanupProject } from '../core/scaffold.js';
 import { syncDocs } from '../core/sync.js';
 import { generateConfig } from '../core/config.js';
-import { runAstroBuild } from '../core/astro.js';
 import { syncDocsConfig } from '../core/config-sync.js';
 import { copyOutput } from '../core/output.js';
 import { getTemplatePath } from '../core/template-fetcher.js';
+import { detectFramework, runFrameworkBuild, getOutputDir, needsSearchIndex } from '../core/framework-runner.js';
 
 export async function buildCommand(options) {
   try {
@@ -29,28 +29,33 @@ export async function buildCommand(options) {
     const templatePath = await getTemplatePath(options.template, options.refresh);
     s.stop(templatePath ? `Using template: ${pc.cyan(templatePath)}` : 'Using bundled template');
 
-    // Step 1: Scaffold temporary Astro project
-    s.start('Setting up Astro project...');
+    // Step 1: Scaffold temporary project
+    s.start('Setting up project...');
     const projectDir = await scaffoldProject(templatePath);
-    s.stop('Astro project scaffolded');
+    s.stop('Project scaffolded');
+
+    // Step 1.5: Detect framework
+    s.start('Detecting framework...');
+    const frameworkConfig = await detectFramework(projectDir);
+    s.stop(`Using framework: ${pc.cyan(frameworkConfig.name)}`);
 
     // Step 2: Prepare project (Install dependencies, Sync docs, Generate navigation)
     const { installDependencies, runBinary } = await import('../core/package-manager.js');
     s.start('Preparing project (installing dependencies, syncing files)...');
-    
+
     const userConfigPath = resolve(options.input, 'docs-config.json');
 
     await Promise.all([
       installDependencies(projectDir, { silent: true }),
-      syncDocs(inputPath, projectDir),
+      syncDocs(inputPath, projectDir, frameworkConfig),
       syncDocsConfig(projectDir, inputPath, userConfigPath)
     ]);
 
     s.stop('Project prepared (dependencies installed, docs synced, navigation generated)');
 
-    // Step 4: Generate config
-    s.start('Generating Astro configuration...');
-    await generateConfig(projectDir, options);
+    // Step 4: Generate config (framework-aware)
+    s.start(`Generating ${frameworkConfig.name} configuration...`);
+    await generateConfig(projectDir, options, frameworkConfig);
     s.stop('Configuration generated');
 
     // Step 4.5: Configure for provider
@@ -61,20 +66,24 @@ export async function buildCommand(options) {
       s.stop(`Configured for ${options.provider}`);
     }
 
-    // Step 5: Build with Astro
-    s.start('Building site with Astro...');
-    await runAstroBuild(projectDir);
+    // Step 5: Build with framework
+    s.start(`Building site with ${frameworkConfig.name}...`);
+    await runFrameworkBuild(projectDir, frameworkConfig);
     s.stop('Site built successfully');
 
-    // Step 5.5: Generate Pagefind search index
-    s.start('Generating search index...');
-    await runBinary(projectDir, 'pagefind', ['--site', 'dist']);
-    s.stop('Search index generated');
+    // Step 5.5: Generate Pagefind search index (only for static frameworks)
+    if (needsSearchIndex(frameworkConfig)) {
+      const outputDir = getOutputDir(frameworkConfig);
+      s.start('Generating search index...');
+      await runBinary(projectDir, 'pagefind', ['--site', outputDir]);
+      s.stop('Search index generated');
+    }
 
     // Step 6: Copy output
     const outputPath = resolve(options.output);
+    const frameworkOutputDir = getOutputDir(frameworkConfig);
     s.start(`Copying output to ${pc.cyan(outputPath)}...`);
-    await copyOutput(projectDir, outputPath);
+    await copyOutput(projectDir, outputPath, frameworkOutputDir);
     s.stop('Output copied');
 
     // Cleanup temp directory

package/src/commands/dev.js

@@ -6,9 +6,9 @@ import chokidar from 'chokidar';
 import { scaffoldProject, cleanupProject } from '../core/scaffold.js';
 import { syncDocs } from '../core/sync.js';
 import { generateConfig } from '../core/config.js';
-import { runAstroDev } from '../core/astro.js';
 import { syncDocsConfig } from '../core/config-sync.js';
 import { getTemplatePath } from '../core/template-fetcher.js';
+import { detectFramework, runFrameworkDev } from '../core/framework-runner.js';
 
 export async function devCommand(options) {
   try {
@@ -29,10 +29,15 @@ export async function devCommand(options) {
     const templatePath = await getTemplatePath(options.template, options.refresh);
     s.stop(templatePath ? `Using template: ${pc.cyan(templatePath)}` : 'Using bundled template');
 
-    // Step 1: Scaffold temporary Astro project
-    s.start('Setting up Astro project...');
+    // Step 1: Scaffold temporary project
+    s.start('Setting up project...');
     const projectDir = await scaffoldProject(templatePath);
-    s.stop('Astro project scaffolded');
+    s.stop('Project scaffolded');
+
+    // Step 1.5: Detect framework
+    s.start('Detecting framework...');
+    const frameworkConfig = await detectFramework(projectDir);
+    s.stop(`Using framework: ${pc.cyan(frameworkConfig.name)}`);
 
     // Register cleanup handlers
     const cleanup = async () => {
@@ -52,15 +57,15 @@ export async function devCommand(options) {
 
     await Promise.all([
       installDependencies(projectDir, { silent: true }),
-      syncDocs(inputPath, projectDir),
+      syncDocs(inputPath, projectDir, frameworkConfig),
       syncDocsConfig(projectDir, inputPath, userConfigPath)
     ]);
 
     s.stop('Project prepared (dependencies installed, docs synced, navigation generated)');
 
-    // Step 4: Generate config
-    s.start('Generating Astro configuration...');
-    await generateConfig(projectDir, options);
+    // Step 4: Generate config (framework-aware)
+    s.start(`Generating ${frameworkConfig.name} configuration...`);
+    await generateConfig(projectDir, options, frameworkConfig);
     s.stop('Configuration generated');
 
     // Step 4: Setup file watcher with debouncing
@@ -82,7 +87,7 @@ export async function devCommand(options) {
 
         try {
           await Promise.all([
-            syncDocs(inputPath, projectDir),
+            syncDocs(inputPath, projectDir, frameworkConfig),
             syncDocsConfig(projectDir, inputPath, userConfigPath)
           ]);
           log.success('Documentation and config re-synced');
@@ -115,9 +120,9 @@ export async function devCommand(options) {
       debouncedSync();
     });
 
-    // Step 5: Start Astro dev server
-    note(`Starting Astro dev server at http://localhost:${options.port}`, 'Dev Server');
-    await runAstroDev(projectDir, options.port);
+    // Step 5: Start framework dev server
+    note(`Starting ${frameworkConfig.name} dev server at http://localhost:${options.port}`, 'Dev Server');
+    await runFrameworkDev(projectDir, frameworkConfig, options.port);
 
   } catch (error) {
     if (isCancel(error)) {

package/src/commands/doctor.js

@@ -0,0 +1,311 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { resolve, join, extname } from 'path';
+import { intro, outro, log, spinner } from '@clack/prompts';
+import pc from 'picocolors';
+import { validateConfig } from '../core/config-validator.js';
+import { TEMPLATE_REGISTRY } from '../core/template-registry.js';
+
+/**
+ * Check result types
+ */
+const CHECK_PASS = 'pass';
+const CHECK_WARN = 'warn';
+const CHECK_FAIL = 'fail';
+
+/**
+ * Doctor command - Diagnose common issues
+ */
+export async function doctorCommand(options) {
+  try {
+    const inputPath = options.input ? resolve(options.input) : process.cwd();
+
+    console.clear();
+    intro(pc.inverse(pc.cyan(' Lito - Doctor ')));
+
+    log.message(pc.dim(`Checking: ${inputPath}`));
+    log.message('');
+
+    const checks = [];
+
+    // Check 1: Directory exists
+    checks.push(await checkDirectoryExists(inputPath));
+
+    // Check 2: docs-config.json exists
+    checks.push(await checkConfigExists(inputPath));
+
+    // Check 3: Config is valid JSON
+    const configCheck = await checkConfigValid(inputPath);
+    checks.push(configCheck);
+
+    // Check 4: Config passes validation
+    if (configCheck.status === CHECK_PASS) {
+      checks.push(await checkConfigSchema(inputPath));
+    }
+
+    // Check 5: Content files exist
+    checks.push(await checkContentFiles(inputPath));
+
+    // Check 6: Check for common issues
+    checks.push(await checkCommonIssues(inputPath));
+
+    // Check 7: Template cache
+    checks.push(await checkTemplateCache());
+
+    // Check 8: Node.js version
+    checks.push(await checkNodeVersion());
+
+    // Print results
+    log.message('');
+    log.message(pc.bold('Diagnostic Results:'));
+    log.message('');
+
+    let hasErrors = false;
+    let hasWarnings = false;
+
+    for (const check of checks) {
+      const icon =
+        check.status === CHECK_PASS
+          ? pc.green('✓')
+          : check.status === CHECK_WARN
+          ? pc.yellow('!')
+          : pc.red('✗');
+
+      log.message(`  ${icon} ${check.name}`);
+
+      if (check.message) {
+        log.message(`    ${pc.dim(check.message)}`);
+      }
+
+      if (check.status === CHECK_FAIL) hasErrors = true;
+      if (check.status === CHECK_WARN) hasWarnings = true;
+    }
+
+    log.message('');
+
+    // Summary
+    if (hasErrors) {
+      log.error(pc.red('Some checks failed. Please fix the issues above.'));
+      process.exit(1);
+    } else if (hasWarnings) {
+      log.warn(pc.yellow('Some warnings found. Your project should still work.'));
+      outro(pc.yellow('Doctor completed with warnings'));
+    } else {
+      log.success(pc.green('All checks passed!'));
+      outro(pc.green('Your project looks healthy! 🎉'));
+    }
+  } catch (error) {
+    log.error(pc.red(error.message));
+    process.exit(1);
+  }
+}
+
+async function checkDirectoryExists(inputPath) {
+  if (!existsSync(inputPath)) {
+    return {
+      name: 'Directory exists',
+      status: CHECK_FAIL,
+      message: `Directory not found: ${inputPath}`,
+    };
+  }
+
+  const stat = statSync(inputPath);
+  if (!stat.isDirectory()) {
+    return {
+      name: 'Directory exists',
+      status: CHECK_FAIL,
+      message: `Path is not a directory: ${inputPath}`,
+    };
+  }
+
+  return {
+    name: 'Directory exists',
+    status: CHECK_PASS,
+  };
+}
+
+async function checkConfigExists(inputPath) {
+  const configPath = join(inputPath, 'docs-config.json');
+
+  if (!existsSync(configPath)) {
+    return {
+      name: 'docs-config.json exists',
+      status: CHECK_FAIL,
+      message: `Run 'lito init' to create a configuration file`,
+    };
+  }
+
+  return {
+    name: 'docs-config.json exists',
+    status: CHECK_PASS,
+  };
+}
+
+async function checkConfigValid(inputPath) {
+  const configPath = join(inputPath, 'docs-config.json');
+
+  if (!existsSync(configPath)) {
+    return {
+      name: 'Config is valid JSON',
+      status: CHECK_WARN,
+      message: 'Skipped (no config file)',
+    };
+  }
+
+  try {
+    JSON.parse(readFileSync(configPath, 'utf-8'));
+    return {
+      name: 'Config is valid JSON',
+      status: CHECK_PASS,
+    };
+  } catch (e) {
+    return {
+      name: 'Config is valid JSON',
+      status: CHECK_FAIL,
+      message: e.message,
+    };
+  }
+}
+
+async function checkConfigSchema(inputPath) {
+  const configPath = join(inputPath, 'docs-config.json');
+
+  try {
+    const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    const result = validateConfig(config, inputPath, { silent: true });
+
+    if (!result.valid) {
+      return {
+        name: 'Config passes validation',
+        status: CHECK_FAIL,
+        message: result.errors.map((e) => e.message).join('; '),
+      };
+    }
+
+    return {
+      name: 'Config passes validation',
+      status: CHECK_PASS,
+    };
+  } catch (e) {
+    return {
+      name: 'Config passes validation',
+      status: CHECK_WARN,
+      message: 'Could not validate',
+    };
+  }
+}
+
+async function checkContentFiles(inputPath) {
+  try {
+    const files = readdirSync(inputPath);
+    const contentFiles = files.filter((f) => {
+      const ext = extname(f).toLowerCase();
+      return ['.md', '.mdx'].includes(ext);
+    });
+
+    if (contentFiles.length === 0) {
+      return {
+        name: 'Content files exist',
+        status: CHECK_WARN,
+        message: 'No .md or .mdx files found in root directory',
+      };
+    }
+
+    return {
+      name: 'Content files exist',
+      status: CHECK_PASS,
+      message: `Found ${contentFiles.length} content file(s)`,
+    };
+  } catch (e) {
+    return {
+      name: 'Content files exist',
+      status: CHECK_WARN,
+      message: 'Could not read directory',
+    };
+  }
+}
+
+async function checkCommonIssues(inputPath) {
+  const issues = [];
+
+  // Check for node_modules in docs folder (shouldn't be there)
+  if (existsSync(join(inputPath, 'node_modules'))) {
+    issues.push('node_modules folder found in docs (should be removed)');
+  }
+
+  // Check for package.json in docs folder (might cause conflicts)
+  if (existsSync(join(inputPath, 'package.json'))) {
+    issues.push('package.json in docs folder (may cause conflicts)');
+  }
+
+  // Check for .git in docs folder
+  if (existsSync(join(inputPath, '.git'))) {
+    issues.push('.git folder in docs (unusual structure)');
+  }
+
+  if (issues.length > 0) {
+    return {
+      name: 'No common issues',
+      status: CHECK_WARN,
+      message: issues.join('; '),
+    };
+  }
+
+  return {
+    name: 'No common issues',
+    status: CHECK_PASS,
+  };
+}
+
+async function checkTemplateCache() {
+  const cacheDir = join(process.env.HOME || '~', '.lito', 'templates');
+
+  if (!existsSync(cacheDir)) {
+    return {
+      name: 'Template cache',
+      status: CHECK_PASS,
+      message: 'No cached templates',
+    };
+  }
+
+  try {
+    const cached = readdirSync(cacheDir);
+    return {
+      name: 'Template cache',
+      status: CHECK_PASS,
+      message: `${cached.length} template(s) cached`,
+    };
+  } catch (e) {
+    return {
+      name: 'Template cache',
+      status: CHECK_WARN,
+      message: 'Could not read cache directory',
+    };
+  }
+}
+
+async function checkNodeVersion() {
+  const version = process.version;
+  const major = parseInt(version.slice(1).split('.')[0], 10);
+
+  if (major < 18) {
+    return {
+      name: 'Node.js version',
+      status: CHECK_FAIL,
+      message: `Node.js 18+ required (found ${version})`,
+    };
+  }
+
+  if (major < 20) {
+    return {
+      name: 'Node.js version',
+      status: CHECK_WARN,
+      message: `Node.js 20+ recommended (found ${version})`,
+    };
+  }
+
+  return {
+    name: 'Node.js version',
+    status: CHECK_PASS,
+    message: version,
+  };
+}