boltdocs 2.5.5 → 2.5.6

package/src/node/plugin/index.ts

@@ -1,478 +0,0 @@
-import { type Plugin, type ResolvedConfig, loadEnv } from 'vite'
-import { generateRoutes, invalidateRouteCache, invalidateFile } from '../routes'
-import { ViteImageOptimizer } from 'vite-plugin-image-optimizer'
-import { resolveConfig, type BoltdocsConfig, CONFIG_FILES } from '../config'
-import { generateStaticPages } from '../ssg'
-import { normalizePath, isDocFile } from '../utils'
-import path from 'path'
-import type { BoltdocsPluginOptions } from './types'
-import { generateEntryCode } from './entry'
-import { injectHtmlMeta, getHtmlTemplate } from './html'
-import { generateRobotsTxt } from '../ssg/robots'
-import { generateSearchData } from '../search'
-import { SECURITY_HEADERS } from '../security/headers'
-import { getCSPHeader } from '../security/csp'
-import fs from 'fs'
-import {
-  PluginLifecycleManager,
-  validatePlugins,
-  PluginSandbox,
-  type SecureBoltdocsPlugin,
-} from '../plugins'
-
-export * from './types'
-
-/**
- * The core Boltdocs Vite plugin.
- * Handles virtual module resolution, HMR for documentation files,
- * injecting HTML meta tags for SEO, and triggering the SSG process on build.
- *
- * @param options - Optional configuration for the plugin
- * @param passedConfig - Pre-resolved configuration (internal use)
- * @returns An array of Vite plugins
- */
-export function boltdocsPlugin(
-  options: BoltdocsPluginOptions = {},
-  passedConfig?: BoltdocsConfig,
-): Plugin[] {
-  const docsDir = path.resolve(process.cwd(), options.docsDir || 'docs')
-  const normalizedDocsDir = normalizePath(docsDir)
-  let config: BoltdocsConfig = passedConfig!
-  let viteConfig: ResolvedConfig
-  let isBuild = false
-  let lifecycle: PluginLifecycleManager
-
-  // Use a placeholder for extra plugins that will be populated once config is resolved
-  let resolvedExtraVitePlugins: Plugin[] = []
-
-  return [
-    {
-      name: 'vite-plugin-boltdocs',
-      enforce: 'pre',
-
-      async config(userConfig, env) {
-        isBuild = env.command === 'build'
-
-        // Load env variables and inject into process.env so they are available in boltdocs.config.js
-        const envDir = userConfig.envDir || process.cwd()
-        const envs = loadEnv(env.mode, envDir, '')
-        Object.assign(process.env, envs)
-
-        // Resolve config async if not already passed
-        if (!config) {
-          config = await resolveConfig(docsDir)
-        }
-
-        // --- NEW: Secure Plugin Initialization ---
-        const boltdocsVersion = (await import('../../../package.json')).version
-        const validatedPlugins = validatePlugins(
-          (config.plugins || []) as SecureBoltdocsPlugin[],
-          boltdocsVersion,
-        )
-
-        // Replace config plugins with validated ones
-        config.plugins = validatedPlugins as any
-
-        // Initialize lifecycle manager
-        lifecycle = new PluginLifecycleManager(validatedPlugins, config)
-
-        // Populate validated extra Vite plugins
-        resolvedExtraVitePlugins = validatedPlugins.flatMap((p) => {
-          const caps = PluginSandbox.getSanitizedCapabilities(p)
-          return (caps.vitePlugins || []) as Plugin[]
-        })
-
-        // Run beforeBuild if building
-        if (isBuild) {
-          await lifecycle.runHook('beforeBuild')
-        }
-
-        return {
-          resolve: {
-            alias: [
-              {
-                find: /^(.*)\/?use-sync-external-store\/shim(?:.*)$/,
-                replacement: '\0virtual:boltdocs-usesync-shim',
-              },
-              {
-                find: /^(.*)\/?use-sync-external-store$/,
-                replacement: '\0virtual:boltdocs-usesync-shim',
-              },
-            ]
-          },
-          optimizeDeps: {
-            include: ['react', 'react-dom'],
-            exclude: [
-              'boltdocs',
-              'boltdocs/client',
-              'boltdocs/hooks',
-              'boltdocs/primitives',
-              'boltdocs/base-ui',
-              'boltdocs/mdx',
-              'boltdocs/integrations',
-              'boltdocs/client/hooks',
-              'boltdocs/client/primitives',
-            ],
-          },
-        }
-      },
-
-      configResolved(resolved) {
-        viteConfig = resolved
-        lifecycle?.runHook('configResolved', config)
-      },
-
-      async configureServer(server) {
-        await lifecycle?.runHook('beforeDev')
-
-        // Security: Apply hardened headers and CSP
-        server.middlewares.use((_req, res, next) => {
-          const isProd = process.env.NODE_ENV === 'production'
-
-          if (isProd) {
-            Object.entries(SECURITY_HEADERS).forEach(([header, value]) => {
-              res.setHeader(header, value)
-            })
-          }
-
-          // Inject CSP if enabled in configuration
-          if (config.security?.enableCSP) {
-            res.setHeader('Content-Security-Policy', getCSPHeader(config))
-          }
-
-          next()
-        })
-
-        // Serve robots.txt from config
-        server.middlewares.use((req, res, next) => {
-          if (req.url === '/robots.txt') {
-            const robots = generateRobotsTxt(config)
-            res.statusCode = 200
-            res.setHeader('Content-Type', 'text/plain')
-            res.end(robots)
-            return
-          }
-          next()
-        })
-
-        // Serve default HTML for documentation routes or if index.html is missing
-        server.middlewares.use(async (req, res, next) => {
-          const url = req.url?.split('?')[0] || '/'
-          const accept = req.headers.accept || ''
-
-          const isDocRoute =
-            url === '/' ||
-            url.startsWith('/docs') ||
-            (config.i18n &&
-              Object.keys(config.i18n.locales).some(
-                (locale) =>
-                  url.startsWith(`/${locale}/docs`) || url === `/${locale}`,
-              )) ||
-            // Handle any HTML request that isn't a known static file or docs,
-            // as it potentially could be an external page.
-            // (The client-side router will handle 404s if it doesn't match anything)
-            true
-
-          // Improved check: If it's a doc route, serve HTML even if it has a dot (e.g. version 1.1)
-          // We only skip if it has a known asset extension to prevent serving HTML for images/js/etc.
-          const isAsset =
-            /\.(js|css|png|jpe?g|gif|svg|ico|webp|woff2?|ttf|otf|mp4|webm|ogg|mp3|wav|flac|aac|pdf|zip|gz|map|json)$/i.test(
-              url,
-            )
-
-          if (accept.includes('text/html') && !isAsset && isDocRoute) {
-            let html = getHtmlTemplate(config)
-            html = injectHtmlMeta(html, config)
-            html = await server.transformIndexHtml(req.url || '/', html)
-            res.statusCode = 200
-            res.setHeader('Content-Type', 'text/html')
-            res.end(html)
-            return
-          }
-
-          next()
-        })
-
-        // Explicitly watch config files...
-
-        const configPaths = CONFIG_FILES.map((c) =>
-          path.resolve(process.cwd(), c),
-        )
-        const compExtensions = ['tsx', 'jsx']
-        const layoutCompPaths = compExtensions.map((ext) =>
-          path.resolve(docsDir, `layout.${ext}`),
-        )
-        const mdxCompExtensions = ['tsx', 'ts', 'jsx', 'js']
-        const mdxCompPaths = mdxCompExtensions.map((ext) =>
-          path.resolve(docsDir, `mdx-components.${ext}`),
-        )
-        const extPagesPaths = mdxCompExtensions.map((ext) =>
-          path.resolve(docsDir, `pages-external/index.${ext}`),
-        )
-
-        server.watcher.add([
-          ...configPaths,
-          ...mdxCompPaths,
-          ...layoutCompPaths,
-          ...extPagesPaths,
-        ])
-
-        const handleFileEvent = async (
-          file: string,
-          type: 'add' | 'unlink' | 'change',
-        ) => {
-          try {
-            const normalized = normalizePath(file)
-
-            // Restart the Vite server if the Boltdocs config changes
-            if (CONFIG_FILES.some((c) => normalized.endsWith(c))) {
-              server.restart()
-              return
-            }
-
-            // If mdx-components file changes, invalidate the virtual module
-            if (
-              mdxCompExtensions.some((ext) =>
-                normalized.endsWith(`mdx-components.${ext}`),
-              )
-            ) {
-              const mod = server.moduleGraph.getModuleById(
-                '\0virtual:boltdocs-mdx-components',
-              )
-              if (mod) server.moduleGraph.invalidateModule(mod)
-              server.ws.send({ type: 'full-reload' })
-              return
-            }
-
-            // If layout.tsx/jsx file changes, invalidate the virtual module
-            if (
-              compExtensions.some((ext) => normalized.endsWith(`layout.${ext}`))
-            ) {
-              const mod = server.moduleGraph.getModuleById(
-                '\0virtual:boltdocs-layout',
-              )
-              if (mod) server.moduleGraph.invalidateModule(mod)
-              server.ws.send({ type: 'full-reload' })
-              return
-            }
-
-            // If any pages-external file changes, invalidate the entry module
-            if (
-              normalized.includes('/pages-external/') ||
-              normalized.includes('\\pages-external\\')
-            ) {
-              const mod = server.moduleGraph.getModuleById(
-                '\0virtual:boltdocs-entry',
-              )
-              if (mod) server.moduleGraph.invalidateModule(mod)
-              server.ws.send({ type: 'full-reload' })
-              return
-            }
-
-            if (
-              !normalized.startsWith(normalizedDocsDir) ||
-              !isDocFile(normalized)
-            )
-              return
-
-            // Invalidate appropriately
-            if (type === 'add' || type === 'unlink') {
-              invalidateRouteCache()
-              // Re-resolve config as it might affect versions/routes
-              config = await resolveConfig(docsDir)
-
-              const configMod = server.moduleGraph.getModuleById(
-                '\0virtual:boltdocs-config',
-              )
-              if (configMod) server.moduleGraph.invalidateModule(configMod)
-
-              server.ws.send({
-                type: 'custom',
-                event: 'boltdocs:config-update',
-                data: {
-                  theme: config?.theme,
-                  i18n: config?.i18n,
-                  versions: config?.versions,
-                  siteUrl: config?.siteUrl,
-                },
-              })
-            } else {
-              invalidateFile(file)
-            }
-
-            // Regenerate and push to client
-            // Optimization: generateRoutes is mostly incremental thanks to docCache
-            // We only force a full disk scan on add/unlink events
-            const newRoutes = await generateRoutes(
-              docsDir,
-              config,
-              '/docs',
-              type !== 'change',
-            )
-
-            const routesMod = server.moduleGraph.getModuleById(
-              '\0virtual:boltdocs-routes',
-            )
-            if (routesMod) server.moduleGraph.invalidateModule(routesMod)
-
-            server.ws.send({
-              type: 'custom',
-              event: 'boltdocs:routes-update',
-              data: newRoutes,
-            })
-          } catch (e) {
-            console.error(`[boltdocs] HMR error during ${type} event:`, e)
-          }
-        }
-
-        server.watcher.on('add', (f) => handleFileEvent(f, 'add'))
-        server.watcher.on('unlink', (f) => handleFileEvent(f, 'unlink'))
-        server.watcher.on('change', (f) => handleFileEvent(f, 'change'))
-
-        await lifecycle?.runHook('afterDev')
-      },
-
-      resolveId(id) {
-        if (
-          id === 'virtual:boltdocs-routes' ||
-          id === 'virtual:boltdocs-config' ||
-          id === 'virtual:boltdocs-entry' ||
-          id === 'virtual:boltdocs-mdx-components' ||
-          id === 'virtual:boltdocs-layout' ||
-          id === 'virtual:boltdocs-search'
-        ) {
-          return '\0' + id
-        }
-        
-        // --- Intercept use-sync-external-store imports to fix React 19 ESM bugs ---
-        // Exclude with-selector as it's not exported by react directly
-        if ((id.includes('use-sync-external-store/shim') || id === 'use-sync-external-store' || id.endsWith('use-sync-external-store/index.js')) && !id.includes('with-selector')) {
-          return '\0virtual:boltdocs-usesync-shim'
-        }
-      },
-
-      async load(id) {
-        if (id === '\0virtual:boltdocs-usesync-shim') {
-          return `import * as React from 'react';\nexport const useSyncExternalStore = React.useSyncExternalStore;\nexport default React.useSyncExternalStore;`
-        }
-        if (id === '\0virtual:boltdocs-routes') {
-          const routes = await generateRoutes(docsDir, config)
-          return `export default ${JSON.stringify(routes, null, 2)};`
-        }
-        if (id === '\0virtual:boltdocs-config') {
-          const clientConfig = {
-            theme: config?.theme,
-            i18n: config?.i18n,
-            versions: config?.versions,
-            siteUrl: config?.siteUrl,
-            plugins: config?.plugins?.map((p) => ({ name: p.name })),
-          }
-          return `export default ${JSON.stringify(clientConfig, null, 2)};`
-        }
-        if (id === '\0virtual:boltdocs-entry') {
-          const code = generateEntryCode(options, config)
-          return code
-        }
-        if (id === '\0virtual:boltdocs-mdx-components') {
-          const extensions = ['tsx', 'ts', 'jsx', 'js']
-          let userMdxPath = null
-
-          for (const ext of extensions) {
-            const p = path.resolve(docsDir, `mdx-components.${ext}`)
-            if (fs.existsSync(p)) {
-              userMdxPath = p
-              break
-            }
-          }
-
-          if (userMdxPath) {
-            const normalizedPath = normalizePath(userMdxPath)
-            return `import * as components from '${normalizedPath}';
-const mdxComponents = components.default || components;
-export default mdxComponents;
-export * from '${normalizedPath}';`
-          }
-
-          return `export default {};`
-        }
-        if (id === '\0virtual:boltdocs-layout') {
-          const extensions = ['tsx', 'jsx']
-          let userLayoutPath = null
-
-          for (const ext of extensions) {
-            const p = path.resolve(docsDir, `layout.${ext}`)
-            if (fs.existsSync(p)) {
-              userLayoutPath = p
-              break
-            }
-          }
-
-          if (userLayoutPath) {
-            const normalizedPath = normalizePath(userLayoutPath)
-            return `import UserLayout from '${normalizedPath}';
-export default UserLayout;`
-          }
-
-          // No user layout — return the built-in default
-          return `import { DefaultLayout } from 'boltdocs/client';
-export default DefaultLayout;`
-        }
-
-        if (id === '\0virtual:boltdocs-search') {
-          const routes = await generateRoutes(docsDir, config)
-          const searchData = generateSearchData(routes)
-          return `export default ${JSON.stringify(searchData, null, 2)};`
-        }
-      },
-
-      transformIndexHtml: {
-        order: 'pre',
-        handler(html) {
-          return injectHtmlMeta(html, config)
-        },
-      },
-
-      async closeBundle() {
-        if (!isBuild) return
-        const outDir = viteConfig?.build?.outDir
-          ? path.resolve(viteConfig.root, viteConfig.build.outDir)
-          : path.resolve(process.cwd(), 'dist')
-
-        const docsDirName = path.basename(docsDir || 'docs')
-        await generateStaticPages({ docsDir, docsDirName, outDir, config })
-
-        const { flushCache } = await import('../cache')
-        await flushCache()
-
-        await lifecycle?.runHook('afterBuild')
-        await lifecycle?.runHook('buildEnd')
-      },
-    },
-    ViteImageOptimizer({
-      includePublic: true,
-      png: { quality: 80 },
-      jpeg: { quality: 80 },
-      jpg: { quality: 80 },
-      webp: { quality: 80 },
-      avif: { quality: 80 },
-      svg: {
-        multipass: true,
-        plugins: [
-          {
-            name: 'preset-default',
-          },
-        ] as any,
-      },
-    }),
-    // Re-bind to use the lazily populated extra plugins
-    {
-      name: 'vite-plugin-boltdocs-extra-plugins',
-      async configResolved() {
-        // This is a dummy plugin to ensure the extra plugins are integrated
-        // Actually, Vite doesn't support changing the plugin list dynamically easily
-        // but we can return them in the original array if we initialize them early.
-      },
-    },
-    ...(() => resolvedExtraVitePlugins)(),
-  ]
-}

package/src/node/plugin/types.ts

@@ -1,9 +0,0 @@
-/**
- * Configuration options specifically for the Boltdocs Vite plugin.
- */
-export interface BoltdocsPluginOptions {
-  /** The root directory containing markdown files (default: 'docs') */
-  docsDir?: string
-  /** Path to a custom home page component (relative to project root) to render at '/' */
-  homePage?: string
-}

package/src/node/plugins/index.ts

@@ -1,17 +0,0 @@
-export * from './plugin-types'
-export * from './plugin-errors'
-export * from './plugin-store'
-export * from './plugin-validator'
-export * from './plugin-sandbox'
-export * from './plugin-lifecycle'
-
-import type { SecureBoltdocsPlugin } from './plugin-types'
-
-/**
- * Utility to create a Boltdocs plugin with full type safety.
- */
-export function createPlugin(
-  plugin: SecureBoltdocsPlugin,
-): SecureBoltdocsPlugin {
-  return plugin
-}

package/src/node/plugins/plugin-errors.ts

@@ -1,62 +0,0 @@
-/**
- * Base class for all plugin-related errors in Boltdocs.
- */
-export class PluginError extends Error {
-  public readonly pluginName: string
-
-  constructor(pluginName: string, message: string) {
-    super(`[plugin:${pluginName}] ${message}`)
-    this.name = 'PluginError'
-    this.pluginName = pluginName
-    Object.setPrototypeOf(this, PluginError.prototype)
-  }
-}
-
-/**
- * Specifically for schema or structure validation failures.
- */
-export class PluginValidationError extends PluginError {
-  constructor(pluginName: string, message: string) {
-    super(pluginName, `Validation failed: ${message}`)
-    this.name = 'PluginValidationError'
-    Object.setPrototypeOf(this, PluginValidationError.prototype)
-  }
-}
-
-/**
- * Specifically for version mismatch or compatibility issues.
- */
-export class PluginCompatibilityError extends PluginError {
-  constructor(pluginName: string, message: string) {
-    super(pluginName, `Compatibility error: ${message}`)
-    this.name = 'PluginCompatibilityError'
-    Object.setPrototypeOf(this, PluginCompatibilityError.prototype)
-  }
-}
-
-/**
- * Specifically for attempts to use capabilities without proper permissions.
- */
-export class PluginPermissionError extends PluginError {
-  constructor(pluginName: string, permission: string) {
-    super(pluginName, `Missing required permission: '${permission}'`)
-    this.name = 'PluginPermissionError'
-    Object.setPrototypeOf(this, PluginPermissionError.prototype)
-  }
-}
-
-/**
- * Specifically for errors that occur during the execution of a lifecycle hook.
- */
-export class PluginHookError extends PluginError {
-  public readonly hookName: string
-
-  constructor(pluginName: string, hookName: string, originalError: Error) {
-    super(pluginName, `Error in hook '${hookName}': ${originalError.message}`)
-    this.name = 'PluginHookError'
-    this.hookName = hookName
-    // Prepend the hook name to the stack if possible
-    this.stack = originalError.stack
-    Object.setPrototypeOf(this, PluginHookError.prototype)
-  }
-}

package/src/node/plugins/plugin-lifecycle.ts

@@ -1,117 +0,0 @@
-import type { BoltdocsConfig } from '../config'
-import { PluginHookError } from './plugin-errors'
-import {
-  PluginLifecycleHooks,
-  SecureBoltdocsPlugin,
-  PluginContext,
-  PluginLogger,
-} from './plugin-types'
-import { BoltdocsPluginStore } from './plugin-store'
-import { PluginSandbox } from './plugin-sandbox'
-
-/**
- * Manages the lifecycle of all loaded plugins, ensuring hooks are executed
- * in the correct order with proper error isolation and context.
- */
-export class PluginLifecycleManager {
-  private plugins: SecureBoltdocsPlugin[]
-  private config: BoltdocsConfig
-  private store: BoltdocsPluginStore
-
-  constructor(plugins: SecureBoltdocsPlugin[], config: BoltdocsConfig) {
-    this.plugins = plugins
-    this.config = config
-    this.store = new BoltdocsPluginStore()
-  }
-
-  /**
-   * Runs a specific hook for all plugins that implement it.
-   */
-  public async runHook(
-    hookName: keyof PluginLifecycleHooks,
-    ...args: any[]
-  ): Promise<void> {
-    const sortedPlugins = this.getSortedPlugins()
-
-    for (const plugin of sortedPlugins) {
-      if (!plugin.hooks?.[hookName]) continue
-
-      const context = this.createContext(plugin)
-      const isBuildHook = hookName.toLowerCase().includes('build')
-      const isDevHook = hookName.toLowerCase().includes('dev')
-      const permission = isBuildHook
-        ? 'hooks:build'
-        : isDevHook
-          ? 'hooks:dev'
-          : undefined
-
-      try {
-        if (permission) {
-          await PluginSandbox.executeWithIsolation(
-            plugin,
-            permission,
-            hookName,
-            () => (plugin.hooks![hookName] as any)(context, ...args),
-          )
-        } else {
-          // Hooks like configResolved might not require specific permissions or are always allowed
-          await (plugin.hooks![hookName] as any)(context, ...args)
-        }
-      } catch (error) {
-        // Isolate error: logging it but allowing other plugins to continue
-        const hookError = new PluginHookError(
-          plugin.name,
-          hookName,
-          error instanceof Error ? error : new Error(String(error)),
-        )
-        context.logger.error(hookError)
-      }
-    }
-  }
-
-  /**
-   * Sorts plugins based on their 'enforce' property (pre -> normal -> post).
-   */
-  private getSortedPlugins(): SecureBoltdocsPlugin[] {
-    const pre = this.plugins.filter((p) => p.enforce === 'pre')
-    const normal = this.plugins.filter((p) => !p.enforce)
-    const post = this.plugins.filter((p) => p.enforce === 'post')
-    return [...pre, ...normal, ...post]
-  }
-
-  /**
-   * Creates a specialized context for a plugin.
-   */
-  private createContext(plugin: SecureBoltdocsPlugin): PluginContext {
-    return {
-      config: Object.freeze({ ...this.config }),
-      meta: {
-        name: plugin.name,
-        version: plugin.version,
-        boltdocsVersion: plugin.boltdocsVersion,
-      },
-      store: {
-        get: (p, k) => this.store.get(p, k),
-        set: (p, k, v) => this.store.set(p, k, v),
-        has: (p, k) => this.store.has(p, k),
-      },
-      logger: this.createLogger(plugin.name),
-    }
-  }
-
-  /**
-   * Creates a namespaced logger for a plugin.
-   */
-  private createLogger(pluginName: string): PluginLogger {
-    const prefix = `[plugin:${pluginName}]`
-    return {
-      info: (msg) => console.log(`${prefix} INFO: ${msg}`),
-      warn: (msg) => console.warn(`${prefix} WARN: ${msg}`),
-      error: (msg) => {
-        const message = msg instanceof Error ? msg.message : msg
-        console.error(`${prefix} ERROR: ${message}`)
-      },
-      debug: (msg) => console.debug(`${prefix} DEBUG: ${msg}`),
-    }
-  }
-}