docmk 1.0.0

package/src/builder/index.ts

@@ -0,0 +1,189 @@
+import { build } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import path from 'path'
+import fs from 'fs/promises'
+import { DocGenConfig, BuildOptions } from '../types/index.js'
+
+export async function buildSite(options: BuildOptions, config: DocGenConfig) {
+  console.log('🏗️  Building documentation site...')
+  
+  // Ensure output directory exists
+  await fs.mkdir(options.output, { recursive: true })
+  
+  // Write config to a temporary file for the build process
+  const configPath = path.join(process.cwd(), 'temp-config.json')
+  await fs.writeFile(configPath, JSON.stringify(config, null, 2))
+  
+  try {
+    // Build the client application
+    await build({
+      root: path.resolve(process.cwd(), 'src/client'),
+      base: config.siteConfig.baseUrl,
+      build: {
+        outDir: options.output,
+        emptyOutDir: true,
+        rollupOptions: {
+          input: {
+            main: path.resolve(process.cwd(), 'src/client/index.html')
+          }
+        }
+      },
+      plugins: [
+        vue(),
+        // Plugin to inject config during build
+        {
+          name: 'docgen-build',
+          transformIndexHtml: {
+            order: 'pre',
+            handler(html) {
+              // Encode config as base64 with proper UTF-8 handling
+              const configJson = JSON.stringify(config)
+              // Use encodeURIComponent to handle UTF-8 properly before base64
+              const utf8Encoded = unescape(encodeURIComponent(configJson))
+              const configBase64 = Buffer.from(utf8Encoded, 'binary').toString('base64')
+              // Decode: atob -> decodeURIComponent(escape()) to restore UTF-8
+              const configScript = `<script>globalThis.__DOCGEN_CONFIG__=JSON.parse(decodeURIComponent(escape(atob("${configBase64}"))));</script>`
+              return html.replace('</head>', `${configScript}\n</head>`)
+            }
+          }
+        }
+      ],
+      resolve: {
+        alias: {
+          '@': path.resolve(process.cwd(), 'src/client')
+        }
+      },
+      define: {
+        __DOCGEN_CONFIG__: JSON.stringify(config)
+      }
+    })
+    
+    // Generate additional static files
+    await generateSitemap(options.output, config)
+    await generateRobotsTxt(options.output, config)
+    await copyAssets(options.output)
+    
+    console.log('✅ Build completed successfully!')
+    
+  } finally {
+    // Clean up temporary config file
+    try {
+      await fs.unlink(configPath)
+    } catch {
+      // Ignore if file doesn't exist
+    }
+  }
+}
+
+async function generateSitemap(outputDir: string, config: DocGenConfig) {
+  console.log('📄 Generating sitemap...')
+  
+  const baseUrl = config.siteConfig.baseUrl.replace(/\/$/, '')
+  const urls: string[] = []
+  
+  // Add home page
+  urls.push(`${baseUrl}/`)
+  
+  // Add all skill pages
+  for (const file of config.files) {
+    const route = getFileRoute(file.path, config.siteConfig.skillsDir)
+    if (route !== '/') {
+      urls.push(`${baseUrl}${route}`)
+    }
+  }
+  
+  const sitemap = `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urls.map(url => `  <url>
+    <loc>${url}</loc>
+    <lastmod>${new Date().toISOString().split('T')[0]}</lastmod>
+    <changefreq>weekly</changefreq>
+    <priority>0.8</priority>
+  </url>`).join('\\n')}
+</urlset>`
+  
+  await fs.writeFile(path.join(outputDir, 'sitemap.xml'), sitemap)
+}
+
+async function generateRobotsTxt(outputDir: string, config: DocGenConfig) {
+  console.log('🤖 Generating robots.txt...')
+  
+  const baseUrl = config.siteConfig.baseUrl.replace(/\/$/, '')
+  const robotsTxt = `User-agent: *
+Allow: /
+
+Sitemap: ${baseUrl}/sitemap.xml`
+  
+  await fs.writeFile(path.join(outputDir, 'robots.txt'), robotsTxt)
+}
+
+async function copyAssets(outputDir: string) {
+  console.log('📁 Copying static assets...')
+  
+  // Create a simple favicon if it doesn't exist
+  const faviconPath = path.join(outputDir, 'favicon.ico')
+  
+  try {
+    await fs.access(faviconPath)
+  } catch {
+    // Create a simple SVG favicon
+    const faviconSvg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <rect width="32" height="32" rx="4" fill="#3182ce"/>
+  <text x="16" y="22" text-anchor="middle" fill="white" font-family="system-ui" font-size="18" font-weight="bold">D</text>
+</svg>`
+    
+    await fs.writeFile(path.join(outputDir, 'favicon.svg'), faviconSvg)
+  }
+}
+
+function getFileRoute(filePath: string, baseDir: string): string {
+  // Normalize paths for comparison
+  const normalizedFilePath = path.normalize(filePath)
+  const normalizedBaseDir = path.normalize(baseDir)
+  
+  // Check if file is within base directory
+  if (!normalizedFilePath.startsWith(normalizedBaseDir)) {
+    return '/'
+  }
+  
+  // Get relative path from base directory
+  const relativePath = normalizedFilePath.slice(normalizedBaseDir.length)
+  const segments = relativePath.split(path.sep).filter(Boolean)
+  
+  if (segments.length === 0) return '/'
+  
+  const lastSegment = segments[segments.length - 1]
+  if (lastSegment.endsWith('.md')) {
+    segments[segments.length - 1] = lastSegment.slice(0, -3)
+  }
+  
+  // SKILL.md and README.md should map to parent directory route
+  const finalSegment = segments[segments.length - 1]
+  if (finalSegment === 'SKILL' || finalSegment === 'README') {
+    segments.pop()
+  }
+
+  return '/' + segments.join('/')
+}
+
+export async function buildForProduction(sourceDir: string, outputDir: string): Promise<DocGenConfig> {
+  const { scanSkillsDirectory } = await import('../scanner/index.js')
+  const { parseSkillsToConfig } = await import('../parser/index.js')
+  
+  const directories = await scanSkillsDirectory(sourceDir)
+  const config = await parseSkillsToConfig(directories, {
+    title: 'Documentation',
+    description: 'Documentation generated from source directory',
+    baseUrl: '/',
+    skillsDir: sourceDir,
+    outputDir
+  })
+  
+  await buildSite({
+    input: sourceDir,
+    output: outputDir,
+    mode: 'production'
+  }, config)
+  
+  return config
+}

package/src/builder/vite-dev.ts

@@ -0,0 +1,117 @@
+import { createServer, ViteDevServer } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import path from 'path'
+import { DocGenConfig } from '../types/index.js'
+import { scanSkillsDirectory, watchSkillsDirectory } from '../scanner/index.js'
+import { parseSkillsToConfig } from '../parser/index.js'
+
+interface DevServerOptions {
+  port: number
+  skillsDir: string
+  config: DocGenConfig
+}
+
+export async function createViteDevServer(options: DevServerOptions): Promise<ViteDevServer> {
+  let currentConfig = options.config
+
+  const server = await createServer({
+    root: path.resolve(process.cwd(), 'src/client'),
+    server: {
+      port: options.port,
+      host: 'localhost'
+    },
+    plugins: [
+      vue(),
+      // Custom plugin to inject config and handle API routes
+      {
+        name: 'docgen-dev',
+        configureServer(server) {
+          // API endpoint for configuration
+          server.middlewares.use('/api/config', (req, res, next) => {
+            if (req.method === 'GET') {
+              res.setHeader('Content-Type', 'application/json')
+              res.end(JSON.stringify(currentConfig))
+            } else {
+              next()
+            }
+          })
+
+          // Inject config into HTML
+          server.middlewares.use((req, res, next) => {
+            if (req.url === '/' || req.url === '/index.html') {
+              // Let Vite handle the HTML transformation
+              next()
+            } else {
+              next()
+            }
+          })
+        },
+        transformIndexHtml: {
+          order: 'pre',
+          handler(html) {
+            // Inject lightweight config placeholder
+            // Full config will be loaded via API to avoid HTML parsing issues
+            const configScript = `
+              <script>
+                // Config will be loaded from /api/config
+                globalThis.__DOCGEN_CONFIG__ = null;
+              </script>
+            `
+            return html.replace('<head>', `<head>${configScript}`)
+          }
+        }
+      }
+    ],
+    resolve: {
+      alias: {
+        '@': path.resolve(process.cwd(), 'src/client')
+      }
+    },
+    define: {
+      __DOCGEN_CONFIG__: JSON.stringify(currentConfig)
+    }
+  })
+
+  // Watch skills directory for changes
+  const watcher = await watchSkillsDirectory(options.skillsDir, async (directories) => {
+    console.log('📝 Skills directory changed, updating configuration...')
+    
+    try {
+      currentConfig = await parseSkillsToConfig(directories, currentConfig.siteConfig)
+      
+      // Notify all connected clients to reload
+      server.ws.send({
+        type: 'full-reload'
+      })
+      
+      console.log('✅ Configuration updated')
+    } catch (error) {
+      console.error('❌ Failed to update configuration:', error)
+      
+      // Send error to clients
+      server.ws.send({
+        type: 'error',
+        err: {
+          message: `Failed to update configuration: ${error.message}`,
+          stack: error.stack
+        }
+      })
+    }
+  })
+
+  // Start the server
+  await server.listen()
+
+  // Extend server with cleanup method
+  const originalClose = server.close.bind(server)
+  server.close = async () => {
+    await watcher?.close()
+    return originalClose()
+  }
+
+  return server
+}
+
+export async function createProductionBuild() {
+  // This will be implemented in the builder
+}

package/src/cli/commands/build.ts

@@ -0,0 +1,48 @@
+import path from 'path'
+import { buildSite } from '../../builder/index.js'
+import { scanSkillsDirectory } from '../../scanner/index.js'
+import { parseSkillsToConfig } from '../../parser/index.js'
+
+interface BuildOptions {
+  dir: string
+  output: string
+}
+
+export async function buildCommand(options: BuildOptions) {
+  console.log('🏗️  Building DocGen documentation site...')
+  
+  const sourceDir = path.resolve(process.cwd(), options.dir)
+  const outputDir = path.resolve(process.cwd(), options.output)
+  
+  try {
+    // Scan source directory
+    console.log(`📁 Scanning source directory: ${sourceDir}`)
+    const directories = await scanSkillsDirectory(sourceDir)
+    
+    console.log(`✅ Found ${directories.length} directories`)
+    
+    // Parse to config
+    const config = await parseSkillsToConfig(directories, {
+      title: 'Documentation',
+      description: 'Documentation generated from source directory',
+      baseUrl: '/',
+      skillsDir: sourceDir,
+      outputDir
+    })
+    
+    // Build site
+    console.log(`📦 Building to: ${outputDir}`)
+    await buildSite({
+      input: sourceDir,
+      output: outputDir,
+      mode: 'production'
+    }, config)
+    
+    console.log('✅ Build completed successfully!')
+    console.log(`📂 Built files are in: ${outputDir}`)
+    
+  } catch (error) {
+    console.error('❌ Build failed:', error)
+    process.exit(1)
+  }
+}

package/src/cli/commands/dev.ts

@@ -0,0 +1,53 @@
+import path from 'path'
+import { createViteDevServer } from '../../builder/vite-dev.js'
+import { scanSkillsDirectory } from '../../scanner/index.js'
+import { parseSkillsToConfig } from '../../parser/index.js'
+
+interface DevOptions {
+  port: string
+  dir: string
+}
+
+export async function devCommand(options: DevOptions) {
+  console.log('🚀 Starting DocGen development server...')
+  
+  const sourceDir = path.resolve(process.cwd(), options.dir)
+  const port = parseInt(options.port, 10)
+  
+  try {
+    // Check if source directory exists
+    console.log(`📁 Scanning source directory: ${sourceDir}`)
+    const directories = await scanSkillsDirectory(sourceDir)
+    
+    console.log(`✅ Found ${directories.length} directories`)
+    
+    // Parse to config
+    const config = await parseSkillsToConfig(directories, {
+      title: 'Documentation',
+      description: 'Documentation generated from source directory',
+      baseUrl: '/',
+      skillsDir: sourceDir,
+      outputDir: 'dist'
+    })
+    
+    // Start Vite dev server
+    const server = await createViteDevServer({
+      port,
+      skillsDir: sourceDir,
+      config
+    })
+    
+    console.log(`🎉 Dev server running at http://localhost:${port}`)
+    
+    // Handle graceful shutdown
+    process.on('SIGINT', async () => {
+      console.log('\\n👋 Shutting down dev server...')
+      await server.close()
+      process.exit(0)
+    })
+    
+  } catch (error) {
+    console.error('❌ Failed to start dev server:', error)
+    process.exit(1)
+  }
+}

package/src/cli/commands/preview.ts

@@ -0,0 +1,57 @@
+import path from 'path'
+import fs from 'fs/promises'
+import sirv from 'sirv'
+import { createServer } from 'http'
+
+interface PreviewOptions {
+  port: string
+  output: string
+}
+
+export async function previewCommand(options: PreviewOptions) {
+  console.log('👀 Starting DocGen preview server...')
+  
+  const outputDir = path.resolve(process.cwd(), options.output)
+  const port = parseInt(options.port, 10)
+  
+  try {
+    // Check if build directory exists
+    try {
+      await fs.access(outputDir)
+    } catch {
+      console.error(`❌ Build directory not found: ${outputDir}`)
+      console.log('💡 Run "docgen build" first to generate the static site')
+      process.exit(1)
+    }
+    
+    // Create static file server
+    const serve = sirv(outputDir, {
+      single: true, // SPA mode
+      dev: false,
+      setHeaders: (res, pathname) => {
+        if (pathname.endsWith('.html') || pathname === '/') {
+          res.setHeader('Content-Type', 'text/html; charset=utf-8')
+        }
+      }
+    })
+    
+    const server = createServer(serve)
+    
+    server.listen(port, () => {
+      console.log(`🎉 Preview server running at http://localhost:${port}`)
+      console.log(`📂 Serving files from: ${outputDir}`)
+    })
+    
+    // Handle graceful shutdown
+    process.on('SIGINT', () => {
+      console.log('\\n👋 Shutting down preview server...')
+      server.close(() => {
+        process.exit(0)
+      })
+    })
+    
+  } catch (error) {
+    console.error('❌ Failed to start preview server:', error)
+    process.exit(1)
+  }
+}

package/src/cli/index.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander'
+import { devCommand } from './commands/dev.js'
+import { buildCommand } from './commands/build.js'
+import { previewCommand } from './commands/preview.js'
+
+const program = new Command()
+
+program
+  .name('docmk')
+  .description('CLI tool for generating documentation from any directory')
+  .version('1.0.0')
+  .argument('[directory]', 'Source directory path (starts dev server)', './docs')
+  .option('-p, --port <port>', 'Port to run dev server on', '3000')
+  .action((directory, options) => {
+    // Default action: start dev server
+    devCommand({ dir: directory, port: options.port })
+  })
+
+program
+  .command('dev')
+  .description('Start development server')
+  .option('-p, --port <port>', 'Port to run dev server on', '3000')
+  .option('-d, --dir <directory>', 'Source directory path', './docs')
+  .action(devCommand)
+
+program
+  .command('build')
+  .description('Build static documentation site')
+  .option('-d, --dir <directory>', 'Source directory path', './docs')
+  .option('-o, --output <directory>', 'Output directory', 'dist')
+  .action(buildCommand)
+
+program
+  .command('preview')
+  .description('Preview built documentation site')
+  .option('-p, --port <port>', 'Port to run preview server on', '4173')
+  .option('-o, --output <directory>', 'Built site directory', 'dist')
+  .action(previewCommand)
+
+program.parse()

package/src/client/App.vue

@@ -0,0 +1,15 @@
+<template>
+  <div id="app">
+    <AppLayout />
+  </div>
+</template>
+
+<script setup lang="ts">
+import AppLayout from './layouts/AppLayout.vue'
+</script>
+
+<style scoped>
+#app {
+  min-height: 100vh;
+}
+</style>