fix(cli): bundle ui-dist and prefer it at runtime

prepare ui-dist during prepack and include it in published files
remove runtime UI build dependency from static generation path
prefer bundled assets in buildReactUI and keep HTML fallback safety
update CLI tests for bundled-asset resolution behavior

Signed-off-by: night-slayer18 <samanuaia257@gmail.com>

Author: night-slayer18

.gitignore

@@ -55,3 +55,4 @@ Thumbs.db
 # Autodocs
 docs-dist
 .autodocs-cache
+packages/cli/ui-dist

packages/cli/package.json

@@ -6,15 +6,18 @@
     "autodocs": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "ui-dist"
   ],
   "scripts": {
     "build": "tsup src/index.ts src/index-exports.ts --format cjs --dts --no-splitting",
+    "prepare:ui-dist": "node scripts/prepare-ui-dist.js",
+    "prepack": "npm run prepare:ui-dist",
     "dev": "tsup src/index.ts --format cjs --watch",
     "lint": "eslint .",
     "test": "jest",
     "type-check": "tsc --noEmit",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist ui-dist"
   },
   "exports": {
     ".": {

packages/cli/scripts/prepare-ui-dist.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+const fs = require('fs/promises');
+const path = require('path');
+
+async function pathExists(target) {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function main() {
+  const cliDir = path.resolve(__dirname, '..');
+  const defaultUiDistDir = path.resolve(cliDir, '../ui/dist');
+  const sourceUiDistDir = process.env.AUTODOCS_UI_DIST_SOURCE
+    ? path.resolve(process.env.AUTODOCS_UI_DIST_SOURCE)
+    : defaultUiDistDir;
+  const targetUiDistDir = path.resolve(cliDir, 'ui-dist');
+
+  if (!(await pathExists(sourceUiDistDir))) {
+    console.error(
+      `[prepare-ui-dist] Missing UI build at ${sourceUiDistDir}. Run "npm -w packages/ui run build" first.`
+    );
+    process.exit(1);
+  }
+
+  await fs.rm(targetUiDistDir, { recursive: true, force: true });
+  await fs.cp(sourceUiDistDir, targetUiDistDir, { recursive: true });
+
+  console.log(`[prepare-ui-dist] Copied ${sourceUiDistDir} -> ${targetUiDistDir}`);
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`[prepare-ui-dist] Failed: ${message}`);
+  process.exit(1);
+});

packages/cli/src/commands/build.ts

@@ -4,8 +4,6 @@ import chalk from 'chalk';
 import ora from 'ora';
 import { Command } from 'commander';
 import { glob } from 'glob';
-import { exec } from 'child_process';
-import { promisify } from 'util';
 import fsPromises from 'fs/promises';
 import type { CompilerOptions, Diagnostic } from 'typescript';
 import { loadConfig, resolveConfigPaths } from '../config';
@@ -22,12 +20,24 @@ import {
   VERSION,
 } from '@opensyntaxhq/autodocs-core';
 
-const execAsync = promisify(exec);
-
 function toCompilerOptions(options?: Record<string, unknown>): CompilerOptions | undefined {
   return options ? (options as unknown as CompilerOptions) : undefined;
 }
 
+interface UiSourceCandidate {
+  label: string;
+  distDir: string;
+}
+
+async function pathExists(target: string): Promise<boolean> {
+  try {
+    await fsPromises.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 interface BuildOptions {
   config?: string;
   output?: string;
@@ -258,50 +268,49 @@ export async function buildReactUI(
     siteName?: string;
   }
 ): Promise<void> {
-  // Find the UI package using require.resolve - works in monorepo
-  let uiDir: string;
-  let uiDistDir: string;
+  const candidates: UiSourceCandidate[] = [];
+  const candidateDistDirs = new Set<string>();
+  const addCandidate = (candidate: UiSourceCandidate): void => {
+    if (candidateDistDirs.has(candidate.distDir)) {
+      return;
+    }
+    candidateDistDirs.add(candidate.distDir);
+    candidates.push(candidate);
+  };
 
   if (options.uiDir) {
-    uiDir = options.uiDir;
-    uiDistDir = path.join(uiDir, 'dist');
+    addCandidate({
+      label: `custom uiDir (${options.uiDir})`,
+      distDir: path.join(options.uiDir, 'dist'),
+    });
   } else {
-    try {
-      // Try to resolve the UI package from the monorepo
-      const uiPackageJson = require.resolve('@opensyntaxhq/autodocs-ui/package.json');
-      uiDir = path.dirname(uiPackageJson);
-      uiDistDir = path.join(uiDir, 'dist');
-    } catch {
-      // Fallback: resolve relative to CLI package in monorepo
-      uiDir = path.resolve(__dirname, '../../ui');
-      uiDistDir = path.join(uiDir, 'dist');
-    }
+    // Bundled UI assets are the primary source for published CLI packages.
+    addCandidate({
+      label: 'bundled CLI assets',
+      distDir: path.resolve(__dirname, '../ui-dist'),
+    });
+    addCandidate({
+      label: 'bundled CLI assets',
+      distDir: path.resolve(__dirname, '../../ui-dist'),
+    });
   }
 
-  // Check if UI package exists
-  try {
-    await fsPromises.access(uiDir);
-  } catch {
-    // UI package not found, fall back to basic HTML
-    spinner.text = 'React UI not found, using basic HTML generator...';
-    const { generateHtml } = await import('@opensyntaxhq/autodocs-core');
-    await generateHtml(docs, outputDir);
-    return;
+  let selectedSource: UiSourceCandidate | null = null;
+  for (const candidate of candidates) {
+    if (await pathExists(candidate.distDir)) {
+      selectedSource = candidate;
+      break;
+    }
   }
 
-  // Step 1: Build the React UI
-  spinner.text = 'Building React UI...';
-
-  try {
-    await execAsync('npm run build', { cwd: uiDir });
-  } catch {
-    spinner.fail(chalk.red('Failed to build React UI, falling back to basic HTML'));
+  if (!selectedSource) {
+    spinner.text = 'React UI not found, using basic HTML generator...';
     const { generateHtml } = await import('@opensyntaxhq/autodocs-core');
     await generateHtml(docs, outputDir);
     return;
   }
 
-  spinner.succeed(chalk.green('React UI built'));
+  spinner.succeed(chalk.green(`React UI ready (${selectedSource.label})`));
 
   // Step 2: Clean and create output directory
   spinner.start('Preparing output directory...');
@@ -310,9 +319,9 @@ export async function buildReactUI(
   await fsPromises.mkdir(outputDir, { recursive: true });
 
   // Step 3: Copy React UI assets
-  spinner.text = 'Copying UI assets...';
+  spinner.text = `Copying UI assets (${selectedSource.label})...`;
 
-  await copyDirectory(uiDistDir, outputDir);
+  await copyDirectory(selectedSource.distDir, outputDir);
 
   spinner.succeed(chalk.green('UI assets copied'));
 

packages/cli/tests/build-helpers.test.ts

@@ -27,10 +27,6 @@ jest.mock('../src/config', () => ({
   resolveConfigPaths: jest.fn(),
 }));
 
-jest.mock('child_process', () => ({
-  exec: jest.fn(),
-}));
-
 const pluginManagerInstances: Array<{ cleanup: jest.Mock; runHook: jest.Mock }> = [];
 
 jest.mock('@opensyntaxhq/autodocs-core', () => ({
@@ -53,7 +49,6 @@ jest.mock('@opensyntaxhq/autodocs-core', () => ({
 }));
 
 import { glob } from 'glob';
-import { ChildProcess, exec } from 'child_process';
 import { loadConfig, resolveConfigPaths } from '../src/config';
 import {
   createProgram,
@@ -66,8 +61,6 @@ import {
 import { loadPlugins, writeStaticDocs, buildReactUI, registerBuild } from '../src/commands/build';
 
 const globMock = glob as unknown as jest.MockedFunction<typeof glob>;
-const execMock = exec as unknown as jest.MockedFunction<typeof exec>;
-const createChildProcess = (): ChildProcess => ({ pid: 0 }) as ChildProcess;
 
 describe('build helpers', () => {
   beforeEach(() => {
@@ -253,17 +246,10 @@ describe('build helpers', () => {
     expect(generateHtml).toHaveBeenCalled();
   });
 
-  it('falls back to HTML generator when UI build fails', async () => {
+  it('falls back to HTML generator when custom uiDir has no dist folder', async () => {
     const tempDir = await createTempDir('autodocs-build-');
     const uiDir = path.join(tempDir, 'ui');
     await fs.mkdir(uiDir, { recursive: true });
-    execMock.mockImplementation((...args: Parameters<typeof exec>) => {
-      const cb = typeof args[1] === 'function' ? args[1] : args[2];
-      if (cb) {
-        cb(new Error('build failed'), '', '');
-      }
-      return createChildProcess();
-    });
 
     await buildReactUI(
       [

packages/cli/tests/build.test.ts

@@ -3,18 +3,6 @@ import path from 'path';
 import type { DocEntry } from '@opensyntaxhq/autodocs-core';
 import { createTempDir } from './helpers/temp';
 
-jest.mock('child_process', () => ({
-  exec: jest.fn(
-    (
-      _command: string,
-      _options: unknown,
-      callback: (error: Error | null, stdout: string, stderr: string) => void
-    ) => {
-      callback(null, '', '');
-    }
-  ),
-}));
-
 import { buildReactUI } from '../src/commands/build';
 
 import type { Ora } from 'ora';