@opensyntaxhq/autodocs 1.0.0

package/README.md

@@ -0,0 +1,15 @@
+# @opensyntaxhq/autodocs
+
+CLI for Autodocs documentation generator.
+
+## Installation
+
+```bash
+npm install -g @opensyntaxhq/autodocs
+```
+
+## Usage
+
+```bash
+autodocs --help
+```

package/dist/index-exports.d.ts

@@ -0,0 +1,57 @@
+interface AutodocsConfig {
+    include: string[];
+    exclude?: string[];
+    entryPoints?: string[];
+    tsconfig?: string;
+    compilerOptions?: Record<string, unknown>;
+    output: OutputConfig;
+    theme?: ThemeConfig;
+    sidebar?: SidebarItem[];
+    features?: FeaturesConfig;
+    plugins?: Array<string | PluginConfig>;
+    ignoreErrors?: boolean;
+    verbose?: boolean;
+    cache?: boolean;
+    cacheDir?: string;
+}
+interface OutputConfig {
+    dir: string;
+    format: 'static' | 'json' | 'markdown';
+    clean?: boolean;
+    publicPath?: string;
+    siteUrl?: string;
+}
+interface ThemeConfig {
+    name: string;
+    primaryColor?: string;
+    secondaryColor?: string;
+    logo?: string;
+    favicon?: string;
+    fonts?: {
+        sans?: string;
+        mono?: string;
+    };
+}
+interface SidebarItem {
+    title: string;
+    path?: string;
+    items?: SidebarItem[];
+    autogenerate?: string;
+    collapsed?: boolean;
+}
+interface FeaturesConfig {
+    search?: boolean;
+    darkMode?: boolean;
+    playground?: boolean;
+    examples?: boolean;
+    download?: boolean;
+    sourceLinks?: boolean;
+}
+interface PluginConfig {
+    name: string;
+    options?: Record<string, unknown>;
+}
+
+declare function defineConfig(config: AutodocsConfig): AutodocsConfig;
+
+export { type AutodocsConfig, type OutputConfig, type ThemeConfig, defineConfig };

package/dist/index-exports.js

@@ -0,0 +1,39 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index-exports.ts
+var index_exports_exports = {};
+__export(index_exports_exports, {
+  defineConfig: () => defineConfig
+});
+module.exports = __toCommonJS(index_exports_exports);
+
+// src/config/loader.ts
+var import_cosmiconfig = require("cosmiconfig");
+var import_jiti = require("jiti");
+var jiti = (0, import_jiti.createJiti)(__filename);
+
+// src/config/index.ts
+function defineConfig(config) {
+  return config;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  defineConfig
+});

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,1060 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/index.ts
+var import_commander = require("commander");
+
+// src/commands/init.ts
+var import_promises = __toESM(require("fs/promises"));
+var import_path = __toESM(require("path"));
+var import_chalk = __toESM(require("chalk"));
+var import_inquirer = __toESM(require("inquirer"));
+function registerInit(program2) {
+  program2.command("init").description("Initialize autodocs configuration").option("-f, --force", "Overwrite existing config").option("--typescript", "Use TypeScript config (default)", true).option("--javascript", "Use JavaScript config").option("--json", "Use JSON config").action(async (options) => {
+    try {
+      const opts = options;
+      const configType = opts.json ? "json" : opts.javascript ? "js" : "ts";
+      const configFile = `autodocs.config.${configType}`;
+      const configPath = import_path.default.join(process.cwd(), configFile);
+      const exists = await fileExists(configPath);
+      if (exists && !opts.force) {
+        console.log(import_chalk.default.yellow(`Config file already exists: ${configFile}`));
+        console.log(import_chalk.default.yellow("Use --force to overwrite"));
+        return;
+      }
+      const answers = await import_inquirer.default.prompt([
+        {
+          type: "input",
+          name: "include",
+          message: "Source files to document:",
+          default: "src/**/*.ts"
+        },
+        {
+          type: "input",
+          name: "outputDir",
+          message: "Output directory:",
+          default: "./docs-dist"
+        },
+        {
+          type: "list",
+          name: "format",
+          message: "Output format:",
+          choices: ["static", "json", "markdown"],
+          default: "static"
+        },
+        {
+          type: "input",
+          name: "primaryColor",
+          message: "Primary color (hex):",
+          default: "#6366f1",
+          validate: (input) => {
+            return /^#[0-9A-F]{6}$/i.test(input) || "Invalid hex color";
+          }
+        },
+        {
+          type: "confirm",
+          name: "darkMode",
+          message: "Enable dark mode?",
+          default: true
+        },
+        {
+          type: "confirm",
+          name: "search",
+          message: "Enable search?",
+          default: true
+        }
+      ]);
+      const content = generateConfigContent(answers, configType);
+      await import_promises.default.writeFile(configPath, content, "utf-8");
+      console.log(import_chalk.default.green(`\u2713 Created ${configFile}`));
+      await addToGitignore(answers.outputDir);
+      console.log(import_chalk.default.cyan("\nNext steps:"));
+      console.log(import_chalk.default.cyan("  1. Review the configuration file"));
+      console.log(import_chalk.default.cyan("  2. Run: autodocs build"));
+      console.log(import_chalk.default.cyan("  3. Run: autodocs serve"));
+    } catch (error) {
+      console.error(import_chalk.default.red("Error initializing config:"), error);
+      process.exit(1);
+    }
+  });
+}
+function generateConfigContent(answers, type) {
+  const include = answers.include;
+  const outputDir = answers.outputDir;
+  const format = answers.format;
+  const primaryColor = answers.primaryColor;
+  const search = answers.search;
+  const darkMode = answers.darkMode;
+  const config = {
+    include: [include],
+    exclude: ["**/*.test.ts", "**/*.spec.ts"],
+    output: {
+      dir: outputDir,
+      format,
+      clean: true
+    },
+    theme: {
+      name: "default",
+      primaryColor
+    },
+    features: {
+      search,
+      darkMode,
+      examples: true
+    }
+  };
+  if (type === "json") {
+    return JSON.stringify(config, null, 2);
+  }
+  const importLine = type === "ts" ? "import { defineConfig } from '@opensyntaxhq/autodocs';" : "const { defineConfig } = require('@opensyntaxhq/autodocs');";
+  const exportLine = type === "ts" ? "export default" : "module.exports =";
+  return `${importLine}
+
+${exportLine} defineConfig(${JSON.stringify(config, null, 2)});
+`;
+}
+async function fileExists(path7) {
+  try {
+    await import_promises.default.access(path7);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function addToGitignore(outputDir) {
+  const gitignorePath = import_path.default.join(process.cwd(), ".gitignore");
+  try {
+    let content = "";
+    try {
+      content = await import_promises.default.readFile(gitignorePath, "utf-8");
+    } catch {
+    }
+    if (!content.includes(outputDir)) {
+      content += `
+# Autodocs
+${outputDir}
+.autodocs-cache
+`;
+      await import_promises.default.writeFile(gitignorePath, content, "utf-8");
+      console.log(import_chalk.default.green(`\u2713 Added ${outputDir} to .gitignore`));
+    }
+  } catch {
+    console.warn(import_chalk.default.yellow("Could not update .gitignore"));
+  }
+}
+
+// src/commands/build.ts
+var import_path3 = __toESM(require("path"));
+var import_url = require("url");
+var import_chalk2 = __toESM(require("chalk"));
+var import_ora = __toESM(require("ora"));
+var import_glob = require("glob");
+var import_child_process = require("child_process");
+var import_util = require("util");
+var import_promises2 = __toESM(require("fs/promises"));
+
+// src/config/defaults.ts
+var DEFAULT_CONFIG = {
+  include: ["src/**/*.ts", "src/**/*.tsx"],
+  exclude: [
+    "**/*.test.ts",
+    "**/*.spec.ts",
+    "**/*.test.tsx",
+    "**/*.spec.tsx",
+    "**/node_modules/**",
+    "**/*.d.ts"
+  ],
+  output: {
+    dir: "./docs-dist",
+    format: "static",
+    clean: true
+  },
+  theme: {
+    name: "default",
+    primaryColor: "#6366f1",
+    secondaryColor: "#8b5cf6"
+  },
+  features: {
+    search: true,
+    darkMode: true,
+    playground: false,
+    examples: true,
+    download: true,
+    sourceLinks: true
+  },
+  cache: true,
+  cacheDir: ".autodocs-cache",
+  verbose: false,
+  ignoreErrors: false
+};
+
+// src/config/loader.ts
+var import_cosmiconfig = require("cosmiconfig");
+var import_fs = __toESM(require("fs"));
+var import_path2 = __toESM(require("path"));
+var import_jiti = require("jiti");
+var jiti = (0, import_jiti.createJiti)(__filename);
+async function loadConfig(searchFrom) {
+  const explorer = (0, import_cosmiconfig.cosmiconfig)("autodocs", {
+    searchPlaces: [
+      "autodocs.config.ts",
+      "autodocs.config.js",
+      "autodocs.config.mjs",
+      "autodocs.config.cjs",
+      "autodocs.config.json",
+      "package.json"
+    ],
+    loaders: {
+      ".ts": (filepath) => jiti.import(filepath, { default: true })
+    }
+  });
+  try {
+    const resolvedPath = searchFrom ? import_path2.default.resolve(searchFrom) : void 0;
+    const hasExplicitConfig = resolvedPath && import_path2.default.extname(resolvedPath) && import_fs.default.existsSync(resolvedPath);
+    const result = hasExplicitConfig ? await explorer.load(resolvedPath) : await explorer.search(searchFrom);
+    if (!result || result.isEmpty) {
+      if (hasExplicitConfig && resolvedPath) {
+        const ext = import_path2.default.extname(resolvedPath);
+        if (ext === ".json") {
+          const raw = await import_fs.default.promises.readFile(resolvedPath, "utf-8");
+          return mergeConfig(DEFAULT_CONFIG, JSON.parse(raw));
+        }
+        if ([".ts", ".js", ".mjs", ".cjs"].includes(ext)) {
+          const loaded = await jiti.import(resolvedPath, { default: true });
+          const config2 = loaded.default || loaded;
+          return mergeConfig(DEFAULT_CONFIG, config2);
+        }
+      }
+      return null;
+    }
+    const rawConfig = result.config;
+    const hasDefaultExport = typeof rawConfig === "object" && rawConfig !== null && "default" in rawConfig;
+    const config = hasDefaultExport ? rawConfig.default ?? rawConfig : rawConfig;
+    return mergeConfig(DEFAULT_CONFIG, config);
+  } catch (error) {
+    throw new Error(`Failed to load config: ${error.message}`);
+  }
+}
+function mergeConfig(base, override) {
+  return {
+    ...base,
+    ...override,
+    output: {
+      ...base.output,
+      ...override.output
+    },
+    theme: {
+      ...base.theme,
+      ...override.theme || {}
+    },
+    features: {
+      ...base.features,
+      ...override.features
+    }
+  };
+}
+function resolveConfigPaths(config, configDir) {
+  const resolveAssetPath = (value) => {
+    if (!value) {
+      return value;
+    }
+    if (/^(https?:|data:)/.test(value) || value.startsWith("/")) {
+      return value;
+    }
+    return import_path2.default.resolve(configDir, value);
+  };
+  return {
+    ...config,
+    include: config.include.map((p) => import_path2.default.resolve(configDir, p)),
+    exclude: config.exclude?.map((p) => import_path2.default.resolve(configDir, p)),
+    output: {
+      ...config.output,
+      dir: import_path2.default.resolve(configDir, config.output.dir)
+    },
+    tsconfig: config.tsconfig ? import_path2.default.resolve(configDir, config.tsconfig) : void 0,
+    cacheDir: config.cacheDir ? import_path2.default.resolve(configDir, config.cacheDir) : config.cacheDir,
+    theme: config.theme ? {
+      ...config.theme,
+      logo: resolveAssetPath(config.theme.logo),
+      favicon: resolveAssetPath(config.theme.favicon)
+    } : config.theme
+  };
+}
+
+// src/utils/configHash.ts
+var import_crypto = __toESM(require("crypto"));
+function computeConfigHash(config) {
+  const relevant = {
+    tsconfig: config.tsconfig,
+    compilerOptions: config.compilerOptions,
+    include: config.include,
+    exclude: config.exclude ?? [],
+    plugins: normalizePlugins(config.plugins ?? [])
+  };
+  const payload = stableStringify(relevant);
+  return import_crypto.default.createHash("sha256").update(payload).digest("hex");
+}
+function normalizePlugins(plugins) {
+  return plugins.map((plugin) => {
+    if (typeof plugin === "string") {
+      return plugin;
+    }
+    return {
+      name: plugin.name,
+      options: plugin.options ?? {}
+    };
+  });
+}
+function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value).sort(
+      ([a], [b]) => a.localeCompare(b)
+    );
+    return `{${entries.map(([key, val]) => `${JSON.stringify(key)}:${stableStringify(val)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+// src/commands/build.ts
+var import_autodocs_core = require("@opensyntaxhq/autodocs-core");
+var execAsync = (0, import_util.promisify)(import_child_process.exec);
+var ASSET_MIME_TYPES = {
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".ico": "image/x-icon"
+};
+async function assetToDataUrl(value) {
+  if (!value) {
+    return void 0;
+  }
+  if (/^(https?:|data:)/.test(value)) {
+    return value;
+  }
+  if (!import_path3.default.isAbsolute(value)) {
+    return value;
+  }
+  try {
+    const buffer = await import_promises2.default.readFile(value);
+    const ext = import_path3.default.extname(value).toLowerCase();
+    const mime = ASSET_MIME_TYPES[ext] || "application/octet-stream";
+    return `data:${mime};base64,${buffer.toString("base64")}`;
+  } catch {
+    return void 0;
+  }
+}
+function isPathLike(value) {
+  return value.startsWith(".") || value.startsWith("/") || value.startsWith("file:");
+}
+async function loadPluginModule(name, configDir) {
+  if (name.startsWith("file:")) {
+    return import(name);
+  }
+  if (isPathLike(name)) {
+    const resolvedPath = import_path3.default.resolve(configDir, name);
+    return import((0, import_url.pathToFileURL)(resolvedPath).href);
+  }
+  return import(name);
+}
+function resolvePluginExport(exported, options) {
+  if (typeof exported === "function") {
+    return exported(options);
+  }
+  return exported;
+}
+async function loadPlugins(pluginManager, plugins, configDir) {
+  if (!plugins || plugins.length === 0) {
+    return;
+  }
+  for (const plugin of plugins) {
+    if (typeof plugin === "string") {
+      if (isPathLike(plugin)) {
+        const module3 = await loadPluginModule(plugin, configDir);
+        const exported2 = module3.default ?? module3;
+        const instance2 = resolvePluginExport(exported2);
+        await pluginManager.loadPlugin(instance2);
+      } else {
+        await pluginManager.loadPlugin(plugin);
+      }
+      continue;
+    }
+    const module2 = await loadPluginModule(plugin.name, configDir);
+    const exported = module2.default ?? module2;
+    const instance = resolvePluginExport(exported, plugin.options ?? {});
+    await pluginManager.loadPlugin(instance);
+  }
+}
+async function copySidebarFiles(sidebar, outputDir, configDir) {
+  if (!sidebar || !configDir) {
+    return;
+  }
+  for (const item of sidebar) {
+    if (item.items && item.items.length > 0) {
+      await copySidebarFiles(item.items, outputDir, configDir);
+    }
+    if (!item.path || !item.path.endsWith(".md")) {
+      continue;
+    }
+    if (/^(https?:|data:)/.test(item.path)) {
+      continue;
+    }
+    const relativePath = item.path.startsWith("/") ? item.path.slice(1) : item.path;
+    const sourcePath = import_path3.default.resolve(configDir, relativePath);
+    try {
+      await import_promises2.default.access(sourcePath);
+    } catch {
+      continue;
+    }
+    const destinationPath = import_path3.default.join(outputDir, relativePath);
+    await import_promises2.default.mkdir(import_path3.default.dirname(destinationPath), { recursive: true });
+    await import_promises2.default.copyFile(sourcePath, destinationPath);
+  }
+}
+async function copyDirectory(src, dest) {
+  await import_promises2.default.mkdir(dest, { recursive: true });
+  const entries = await import_promises2.default.readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = import_path3.default.join(src, entry.name);
+    const destPath = import_path3.default.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      await copyDirectory(srcPath, destPath);
+    } else {
+      await import_promises2.default.copyFile(srcPath, destPath);
+    }
+  }
+}
+async function buildUiConfigPayload(uiConfig) {
+  const theme = uiConfig.theme ? {
+    ...uiConfig.theme,
+    logo: await assetToDataUrl(uiConfig.theme.logo),
+    favicon: await assetToDataUrl(uiConfig.theme.favicon)
+  } : void 0;
+  return {
+    version: import_autodocs_core.VERSION,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    theme,
+    features: uiConfig.features,
+    sidebar: uiConfig.sidebar
+  };
+}
+async function writeStaticDocs(docs, outputDir, options) {
+  await import_promises2.default.mkdir(outputDir, { recursive: true });
+  await copySidebarFiles(options.uiConfig.sidebar, outputDir, options.configDir);
+  const { generateJson } = await import("@opensyntaxhq/autodocs-core");
+  await generateJson(docs, outputDir, { pretty: true, rootDir: options.rootDir });
+  const configData = await buildUiConfigPayload(options.uiConfig);
+  await import_promises2.default.writeFile(
+    import_path3.default.join(outputDir, "config.json"),
+    JSON.stringify(configData, null, 2),
+    "utf-8"
+  );
+  await (0, import_autodocs_core.generateStaticSite)({
+    outputDir,
+    siteUrl: options.siteUrl,
+    siteName: options.siteName ?? "Autodocs"
+  });
+}
+async function buildReactUI(docs, outputDir, spinner, options) {
+  let uiDir;
+  let uiDistDir;
+  if (options.uiDir) {
+    uiDir = options.uiDir;
+    uiDistDir = import_path3.default.join(uiDir, "dist");
+  } else {
+    try {
+      const uiPackageJson = require.resolve("@opensyntaxhq/autodocs-ui/package.json");
+      uiDir = import_path3.default.dirname(uiPackageJson);
+      uiDistDir = import_path3.default.join(uiDir, "dist");
+    } catch {
+      uiDir = import_path3.default.resolve(__dirname, "../../ui");
+      uiDistDir = import_path3.default.join(uiDir, "dist");
+    }
+  }
+  try {
+    await import_promises2.default.access(uiDir);
+  } catch {
+    spinner.text = "React UI not found, using basic HTML generator...";
+    const { generateHtml } = await import("@opensyntaxhq/autodocs-core");
+    await generateHtml(docs, outputDir);
+    return;
+  }
+  spinner.text = "Building React UI...";
+  try {
+    await execAsync("npm run build", { cwd: uiDir });
+  } catch {
+    spinner.fail(import_chalk2.default.red("Failed to build React UI, falling back to basic HTML"));
+    const { generateHtml } = await import("@opensyntaxhq/autodocs-core");
+    await generateHtml(docs, outputDir);
+    return;
+  }
+  spinner.succeed(import_chalk2.default.green("React UI built"));
+  spinner.start("Preparing output directory...");
+  await import_promises2.default.rm(outputDir, { recursive: true, force: true });
+  await import_promises2.default.mkdir(outputDir, { recursive: true });
+  spinner.text = "Copying UI assets...";
+  await copyDirectory(uiDistDir, outputDir);
+  spinner.succeed(import_chalk2.default.green("UI assets copied"));
+  spinner.start("Generating docs data...");
+  await writeStaticDocs(docs, outputDir, {
+    rootDir: options.rootDir,
+    configDir: options.configDir,
+    uiConfig: options.uiConfig,
+    siteUrl: options.siteUrl,
+    siteName: options.siteName
+  });
+  spinner.succeed(import_chalk2.default.green("Documentation data generated"));
+}
+function registerBuild(program2) {
+  program2.command("build").description("Build documentation").option("-c, --config <path>", "Config file path").option("-o, --output <dir>", "Output directory (overrides config)").option("--format <format>", "Output format (overrides config)").option("--clean", "Clean output directory first").option("-v, --verbose", "Verbose logging").option("--no-cache", "Disable caching").action(async (options) => {
+    const spinner = (0, import_ora.default)("Loading configuration...").start();
+    let pluginManager = null;
+    try {
+      const opts = options;
+      let config = await loadConfig(opts.config);
+      if (!config) {
+        spinner.fail("No configuration found");
+        console.log(import_chalk2.default.yellow("\nRun: autodocs init"));
+        process.exit(1);
+      }
+      const configDir = opts.config ? import_path3.default.dirname(opts.config) : process.cwd();
+      config = resolveConfigPaths(config, configDir);
+      if (opts.output) {
+        config.output.dir = import_path3.default.resolve(opts.output);
+      }
+      if (opts.format) {
+        config.output.format = opts.format;
+      }
+      if (opts.clean !== void 0) {
+        config.output.clean = opts.clean;
+      }
+      if (opts.verbose) {
+        config.verbose = true;
+      }
+      if (opts.cache === false) {
+        config.cache = false;
+      }
+      const siteUrl = config.output.siteUrl ?? process.env.SITE_URL;
+      const siteName = config.theme?.name && config.theme.name !== "default" ? config.theme.name : "Autodocs";
+      spinner.text = "Loading plugins...";
+      pluginManager = new import_autodocs_core.PluginManager(config);
+      const manager = pluginManager;
+      await loadPlugins(manager, config.plugins, configDir);
+      spinner.text = "Finding source files...";
+      let files = await (0, import_glob.glob)(config.include, {
+        ignore: config.exclude || [],
+        absolute: true
+      });
+      files = await manager.runHook("beforeParse", files);
+      if (files.length === 0) {
+        spinner.fail("No files found matching include patterns");
+        console.log(import_chalk2.default.yellow("\nInclude patterns:"));
+        config.include.forEach((p) => {
+          console.log(import_chalk2.default.yellow(`  ${p}`));
+        });
+        process.exit(1);
+      }
+      spinner.succeed(import_chalk2.default.green(`Found ${files.length.toString()} files`));
+      const configHash = computeConfigHash(config);
+      let docs = [];
+      let rootDir = process.cwd();
+      let diagnostics = [];
+      spinner.start("Parsing TypeScript...");
+      if (config.cache !== false) {
+        const cache = new import_autodocs_core.FileCache({
+          cacheDir: config.cacheDir || import_path3.default.join(configDir, ".autodocs-cache"),
+          enabled: true
+        });
+        const result = await (0, import_autodocs_core.incrementalBuild)({
+          files,
+          cache,
+          tsconfig: config.tsconfig,
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment
+          compilerOptions: config.compilerOptions,
+          configHash,
+          onProgram: async (program3, parsedSourceFiles) => {
+            await manager.runHook("afterParse", program3);
+            await manager.runHook("beforeExtract", parsedSourceFiles);
+          }
+        });
+        docs = result.docs;
+        rootDir = result.rootDir;
+        diagnostics = result.diagnostics;
+        spinner.succeed(
+          import_chalk2.default.green(
+            `Processed ${result.changedFiles.length.toString()} changed files (${result.fromCache.toString()} from cache)`
+          )
+        );
+      } else {
+        const parseResult = (0, import_autodocs_core.createProgram)(files, {
+          configFile: config.tsconfig,
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment
+          compilerOptions: config.compilerOptions,
+          skipLibCheck: true
+        });
+        await manager.runHook("afterParse", parseResult.program);
+        await manager.runHook("beforeExtract", parseResult.sourceFiles);
+        docs = (0, import_autodocs_core.extractDocs)(parseResult.program, { rootDir: parseResult.rootDir });
+        rootDir = parseResult.rootDir;
+        diagnostics = parseResult.diagnostics;
+        spinner.succeed(import_chalk2.default.green("TypeScript parsed"));
+      }
+      if (config.verbose && diagnostics.length > 0) {
+        spinner.info("TypeScript diagnostics:");
+        diagnostics.forEach((d) => {
+          const message = typeof d.messageText === "string" ? d.messageText : d.messageText.messageText;
+          console.log(import_chalk2.default.gray(`  ${message}`));
+        });
+      }
+      spinner.start("Extracting documentation...");
+      docs = await manager.runHook("afterExtract", docs);
+      if (docs.length === 0) {
+        spinner.warn("No exported symbols found to document");
+        console.log(
+          import_chalk2.default.yellow("\nMake sure your code exports interfaces, types, or functions")
+        );
+        process.exit(0);
+      }
+      spinner.succeed(import_chalk2.default.green(`Extracted ${docs.length.toString()} entries`));
+      docs = await manager.runHook("beforeGenerate", docs);
+      spinner.start("Generating documentation...");
+      switch (config.output.format) {
+        case "json": {
+          const { generateJson } = await import("@opensyntaxhq/autodocs-core");
+          await generateJson(docs, config.output.dir, {
+            pretty: true,
+            rootDir
+          });
+          break;
+        }
+        case "markdown": {
+          const { generateMarkdown } = await import("@opensyntaxhq/autodocs-core");
+          await generateMarkdown(docs, config.output.dir);
+          break;
+        }
+        case "static":
+        default: {
+          await buildReactUI(docs, config.output.dir, spinner, {
+            rootDir,
+            configDir,
+            uiConfig: {
+              theme: config.theme,
+              features: config.features,
+              sidebar: config.sidebar
+            },
+            siteUrl,
+            siteName
+          });
+          break;
+        }
+      }
+      await manager.runHook("afterGenerate", config.output.dir);
+      await manager.cleanup();
+      spinner.succeed(import_chalk2.default.green("Documentation generated!"));
+      console.log(import_chalk2.default.cyan("\nStatistics:"));
+      console.log(`  Files processed: ${files.length.toString()}`);
+      console.log(`  Entries generated: ${docs.length.toString()}`);
+      console.log(`  Output: ${config.output.dir}`);
+      const kindCounts = {};
+      docs.forEach((d) => {
+        kindCounts[d.kind] = (kindCounts[d.kind] || 0) + 1;
+      });
+      console.log(import_chalk2.default.cyan("\nBy kind:"));
+      Object.entries(kindCounts).forEach(([kind, count]) => {
+        console.log(`  ${kind}: ${count.toString()}`);
+      });
+    } catch (error) {
+      spinner.fail(import_chalk2.default.red("Build failed"));
+      console.error(error);
+      if (pluginManager) {
+        await pluginManager.cleanup();
+      }
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/check.ts
+var import_chalk3 = __toESM(require("chalk"));
+var import_ora2 = __toESM(require("ora"));
+var import_path4 = __toESM(require("path"));
+var import_promises3 = __toESM(require("fs/promises"));
+var import_glob2 = require("glob");
+function registerCheck(program2) {
+  program2.command("check").description("Validate configuration and check for issues").option("-c, --config <path>", "Config file path").action(async (options) => {
+    const spinner = (0, import_ora2.default)("Checking configuration...").start();
+    try {
+      const opts = options;
+      let config = await loadConfig(opts.config);
+      if (!config) {
+        spinner.fail("No configuration found");
+        console.log(import_chalk3.default.yellow("\nRun: autodocs init"));
+        process.exit(1);
+      }
+      const configDir = opts.config ? import_path4.default.dirname(opts.config) : process.cwd();
+      config = resolveConfigPaths(config, configDir);
+      spinner.succeed(import_chalk3.default.green("Configuration loaded"));
+      const issues = [];
+      const warnings = [];
+      spinner.start("Checking source files...");
+      const files = await (0, import_glob2.glob)(config.include, {
+        ignore: config.exclude || [],
+        absolute: true
+      });
+      if (files.length === 0) {
+        issues.push("No files found matching include patterns");
+      } else {
+        spinner.succeed(import_chalk3.default.green(`Found ${files.length.toString()} source files`));
+      }
+      if (config.tsconfig) {
+        spinner.start("Checking tsconfig...");
+        try {
+          await import_promises3.default.access(config.tsconfig);
+          spinner.succeed(import_chalk3.default.green("tsconfig.json found"));
+        } catch {
+          warnings.push(`tsconfig.json not found: ${config.tsconfig}`);
+          spinner.warn(import_chalk3.default.yellow("tsconfig.json not found"));
+        }
+      }
+      spinner.start("Checking output directory...");
+      try {
+        const stat = await import_promises3.default.stat(config.output.dir);
+        if (!stat.isDirectory()) {
+          issues.push(`Output path exists but is not a directory: ${config.output.dir}`);
+        }
+        spinner.succeed(import_chalk3.default.green("Output directory exists"));
+      } catch {
+        spinner.info("Output directory will be created");
+      }
+      console.log(import_chalk3.default.cyan("\n=== Summary ==="));
+      if (issues.length === 0 && warnings.length === 0) {
+        console.log(import_chalk3.default.green("\u2713 No issues found"));
+      } else {
+        if (issues.length > 0) {
+          console.log(import_chalk3.default.red("\nErrors:"));
+          issues.forEach((issue) => {
+            console.log(import_chalk3.default.red(`  \u2717 ${issue}`));
+          });
+        }
+        if (warnings.length > 0) {
+          console.log(import_chalk3.default.yellow("\nWarnings:"));
+          warnings.forEach((warn) => {
+            console.log(import_chalk3.default.yellow(`  \u26A0 ${warn}`));
+          });
+        }
+      }
+      if (issues.length > 0) {
+        process.exit(1);
+      }
+    } catch (error) {
+      spinner.fail("Check failed");
+      console.error(error);
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/serve.ts
+var import_chalk4 = __toESM(require("chalk"));
+var import_path5 = __toESM(require("path"));
+var import_fs2 = __toESM(require("fs"));
+function registerServe(program2) {
+  program2.command("serve").description("Serve documentation locally").option("-p, --port <port>", "Port number", "3000").option("--host <host>", "Host address", "localhost").option("-o, --open", "Open browser automatically").option("--docs <dir>", "Docs directory to serve", "./docs-dist").action(async (options) => {
+    try {
+      const opts = options;
+      const express = await import("express");
+      const open = opts.open ? await import("open") : null;
+      const app = express.default();
+      const docsDir = import_path5.default.resolve(opts.docs);
+      if (!import_fs2.default.existsSync(docsDir)) {
+        console.error(import_chalk4.default.red("Error: Docs directory not found:", docsDir));
+        console.log(import_chalk4.default.yellow("Run: autodocs build"));
+        process.exit(1);
+      }
+      app.use(express.default.static(docsDir));
+      app.get(/(.*)/, (_req, res) => {
+        res.sendFile(import_path5.default.join(docsDir, "index.html"), (err) => {
+          if (err) {
+            res.status(404).send("Documentation not found. Run: autodocs build");
+          }
+        });
+      });
+      app.listen(parseInt(opts.port), opts.host, () => {
+        const url = `http://${opts.host}:${opts.port}`;
+        console.log(import_chalk4.default.green("\u2713 Server running at:"), import_chalk4.default.cyan(url));
+        console.log(import_chalk4.default.gray("\nPress Ctrl+C to stop"));
+        if (open) {
+          open.default(url);
+        }
+      });
+    } catch (error) {
+      console.error(import_chalk4.default.red("Error starting server:"), error);
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/watch.ts
+var import_path6 = __toESM(require("path"));
+var import_chalk5 = __toESM(require("chalk"));
+var import_ora3 = __toESM(require("ora"));
+var import_glob3 = require("glob");
+
+// src/utils/watcher.ts
+var import_chokidar = require("chokidar");
+var import_events = require("events");
+var FileWatcher = class extends import_events.EventEmitter {
+  watcher = null;
+  debounceTimer = null;
+  options;
+  constructor(options) {
+    super();
+    this.options = {
+      paths: options.paths,
+      ignored: options.ignored || ["**/node_modules/**", "**/.git/**", "**/dist/**"],
+      debounce: options.debounce || 300
+    };
+  }
+  start() {
+    const watcher = (0, import_chokidar.watch)(this.options.paths, {
+      ignored: this.options.ignored,
+      persistent: true,
+      ignoreInitial: true,
+      awaitWriteFinish: {
+        stabilityThreshold: 100,
+        pollInterval: 100
+      }
+    });
+    this.watcher = watcher;
+    watcher.on("change", (path7) => {
+      this.handleChange(path7);
+    });
+    watcher.on("add", (path7) => {
+      this.handleChange(path7);
+    });
+    watcher.on("unlink", (path7) => {
+      this.handleChange(path7);
+    });
+    this.emit("ready");
+  }
+  async stop() {
+    if (this.watcher) {
+      await this.watcher.close();
+      this.watcher = null;
+    }
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+  }
+  handleChange(path7) {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+    this.debounceTimer = setTimeout(() => {
+      this.emit("change", path7);
+    }, this.options.debounce);
+  }
+};
+
+// src/commands/watch.ts
+var import_autodocs_core2 = require("@opensyntaxhq/autodocs-core");
+async function runBuild({ config, configDir, mode }) {
+  const spinner = (0, import_ora3.default)("Loading plugins...").start();
+  let pluginManager = null;
+  try {
+    const siteUrl = config.output.siteUrl ?? process.env.SITE_URL;
+    const siteName = config.theme?.name && config.theme.name !== "default" ? config.theme.name : "Autodocs";
+    pluginManager = new import_autodocs_core2.PluginManager(config);
+    const manager = pluginManager;
+    await loadPlugins(manager, config.plugins, configDir);
+    spinner.text = "Finding source files...";
+    let files = await (0, import_glob3.glob)(config.include, {
+      ignore: config.exclude || [],
+      absolute: true
+    });
+    files = await manager.runHook("beforeParse", files);
+    if (files.length === 0) {
+      spinner.fail("No files found matching include patterns");
+      return;
+    }
+    const configHash = computeConfigHash(config);
+    let docs = [];
+    let rootDir = process.cwd();
+    spinner.start("Parsing TypeScript...");
+    if (config.cache !== false) {
+      const cache = new import_autodocs_core2.FileCache({
+        cacheDir: config.cacheDir || import_path6.default.join(configDir, ".autodocs-cache"),
+        enabled: true
+      });
+      const result = await (0, import_autodocs_core2.incrementalBuild)({
+        files,
+        cache,
+        tsconfig: config.tsconfig,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment
+        compilerOptions: config.compilerOptions,
+        configHash,
+        onProgram: async (program2, sourceFiles) => {
+          await manager.runHook("afterParse", program2);
+          await manager.runHook("beforeExtract", sourceFiles);
+        }
+      });
+      docs = result.docs;
+      rootDir = result.rootDir;
+      spinner.succeed(
+        import_chalk5.default.green(
+          `Processed ${result.changedFiles.length.toString()} changed files (${result.fromCache.toString()} from cache)`
+        )
+      );
+    } else {
+      const parseResult = (0, import_autodocs_core2.createProgram)(files, {
+        configFile: config.tsconfig,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment
+        compilerOptions: config.compilerOptions,
+        skipLibCheck: true
+      });
+      await manager.runHook("afterParse", parseResult.program);
+      await manager.runHook("beforeExtract", parseResult.sourceFiles);
+      docs = (0, import_autodocs_core2.extractDocs)(parseResult.program, { rootDir: parseResult.rootDir });
+      rootDir = parseResult.rootDir;
+      spinner.succeed(import_chalk5.default.green("TypeScript parsed"));
+    }
+    spinner.start("Extracting documentation...");
+    docs = await manager.runHook("afterExtract", docs);
+    docs = await manager.runHook("beforeGenerate", docs);
+    spinner.start("Generating documentation...");
+    switch (config.output.format) {
+      case "json": {
+        const { generateJson } = await import("@opensyntaxhq/autodocs-core");
+        await generateJson(docs, config.output.dir, { pretty: true, rootDir });
+        break;
+      }
+      case "markdown": {
+        const { generateMarkdown } = await import("@opensyntaxhq/autodocs-core");
+        await generateMarkdown(docs, config.output.dir);
+        break;
+      }
+      case "static":
+      default: {
+        if (mode === "full") {
+          await buildReactUI(docs, config.output.dir, spinner, {
+            rootDir,
+            configDir,
+            uiConfig: {
+              theme: config.theme,
+              features: config.features,
+              sidebar: config.sidebar
+            },
+            siteUrl,
+            siteName
+          });
+        } else {
+          await writeStaticDocs(docs, config.output.dir, {
+            rootDir,
+            configDir,
+            uiConfig: {
+              theme: config.theme,
+              features: config.features,
+              sidebar: config.sidebar
+            },
+            siteUrl,
+            siteName
+          });
+        }
+        break;
+      }
+    }
+    await manager.runHook("afterGenerate", config.output.dir);
+    await manager.cleanup();
+    spinner.succeed(import_chalk5.default.green("Documentation generated"));
+  } catch (error) {
+    spinner.fail("Build failed");
+    console.error(error);
+    if (pluginManager) {
+      await pluginManager.cleanup();
+    }
+  }
+}
+function registerWatch(program2) {
+  program2.command("watch").description("Watch files and rebuild on changes").option("-c, --config <path>", "Config file path").action(async (options) => {
+    const spinner = (0, import_ora3.default)("Loading configuration...").start();
+    try {
+      let config = await loadConfig(options.config);
+      if (!config) {
+        spinner.fail("No configuration found");
+        return;
+      }
+      const configDir = options.config ? import_path6.default.dirname(options.config) : process.cwd();
+      config = resolveConfigPaths(config, configDir);
+      spinner.succeed("Configuration loaded");
+      console.log(import_chalk5.default.cyan("\nBuilding initial docs..."));
+      await runBuild({ config, configDir, mode: "full" });
+      const watcher = new FileWatcher({
+        paths: config.include,
+        ignored: config.exclude
+      });
+      watcher.on("ready", () => {
+        console.log(import_chalk5.default.green("\n\u2713 Watching for changes..."));
+        console.log(import_chalk5.default.gray("Press Ctrl+C to stop\n"));
+      });
+      watcher.on("change", (changedPath) => {
+        console.log(import_chalk5.default.cyan(`
+File changed: ${changedPath}`));
+        console.log(import_chalk5.default.cyan("Rebuilding docs...\n"));
+        void runBuild({ config, configDir, mode: "docs-only" }).then(() => {
+          console.log(import_chalk5.default.green("\u2713 Docs updated\n"));
+        });
+      });
+      watcher.start();
+      process.on("SIGINT", () => {
+        console.log(import_chalk5.default.yellow("\nStopping watcher..."));
+        void watcher.stop().then(() => process.exit(0));
+      });
+    } catch (error) {
+      spinner.fail("Watch failed");
+      console.error(error);
+      process.exit(1);
+    }
+  });
+}
+
+// src/index.ts
+var import_autodocs_core3 = require("@opensyntaxhq/autodocs-core");
+var program = new import_commander.Command();
+program.name("autodocs").description("Engineer-first documentation generator").version(import_autodocs_core3.VERSION);
+registerInit(program);
+registerBuild(program);
+registerCheck(program);
+registerServe(program);
+registerWatch(program);
+program.parse(process.argv);
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@opensyntaxhq/autodocs",
+  "version": "1.0.0",
+  "description": "CLI for Autodocs documentation generator",
+  "bin": {
+    "autodocs": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts src/index-exports.ts --format cjs --dts --no-splitting",
+    "dev": "tsup src/index.ts --format cjs --watch",
+    "lint": "eslint .",
+    "test": "jest",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index-exports.d.ts",
+      "default": "./dist/index-exports.js"
+    },
+    "./config": {
+      "types": "./dist/index-exports.d.ts",
+      "default": "./dist/index-exports.js"
+    }
+  },
+  "dependencies": {
+    "@opensyntaxhq/autodocs-core": "^1.0.0",
+    "chalk": "^5.6.2",
+    "chokidar": "^5.0.0",
+    "commander": "^14.0.3",
+    "cosmiconfig": "^9.0.0",
+    "express": "^5.2.1",
+    "glob": "^13.0.1",
+    "inquirer": "^13.2.2",
+    "jiti": "^2.6.1",
+    "open": "^11.0.0",
+    "ora": "^9.3.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/inquirer": "^8.2.10",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.2.1",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6",
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.0"
+  },
+  "main": "./dist/index-exports.js",
+  "types": "./dist/index-exports.d.ts",
+  "directories": {
+    "test": "tests"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OpenSyntaxHQ/autodocs.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/OpenSyntaxHQ/autodocs/issues"
+  },
+  "homepage": "https://github.com/OpenSyntaxHQ/autodocs",
+  "keywords": [
+    "documentation",
+    "typescript",
+    "cli",
+    "api-docs",
+    "jsdoc"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "",
+  "license": "Apache-2.0",
+  "type": "commonjs"
+}