@docmd/core 0.4.0

package/src/commands/dev.js

@@ -0,0 +1,353 @@
+// Source file from the docmd project — https://github.com/docmd-io/docmd
+
+const http = require('http');
+const WebSocket = require('ws');
+const chokidar = require('chokidar');
+const path = require('path');
+const fs = require('../utils/fs-utils');
+const chalk = require('chalk');
+const os = require('os');
+const readline = require('readline');
+const { buildSite } = require('./build');
+const { loadConfig } = require('../utils/config-loader');
+
+// --- 1. Native Static File Server ---
+const MIME_TYPES = {
+  '.html': 'text/html',
+  '.js': 'text/javascript',
+  '.css': 'text/css',
+  '.json': 'application/json',
+  '.png': 'image/png',
+  '.jpg': 'image/jpg',
+  '.jpeg': 'image/jpg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.woff': 'application/font-woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'application/font-ttf',
+  '.txt': 'text/plain',
+};
+
+async function serveStatic(req, res, rootDir) {
+  // Normalize path and remove query strings
+  let safePath = path.normalize(req.url).replace(/^(\.\.[\/\\])+/, '').split('?')[0].split('#')[0];
+  if (safePath === '/' || safePath === '\\') safePath = 'index.html';
+  
+  let filePath = path.join(rootDir, safePath);
+
+  try {
+    let stats;
+    try {
+      stats = await fs.stat(filePath);
+    } catch (e) {
+      // If direct path fails, try appending .html (clean URLs support)
+      if (path.extname(filePath) === '') {
+        filePath += '.html';
+        stats = await fs.stat(filePath);
+      } else {
+        throw e;
+      }
+    }
+    
+    if (stats.isDirectory()) {
+      filePath = path.join(filePath, 'index.html');
+      await fs.stat(filePath);
+    }
+
+    const ext = path.extname(filePath).toLowerCase();
+    const contentType = MIME_TYPES[ext] || 'application/octet-stream';
+    const content = await fs.readFile(filePath);
+
+    res.writeHead(200, { 'Content-Type': contentType });
+    
+    // Inject Live Reload Script into HTML files only
+    if (contentType === 'text/html') {
+      const htmlStr = content.toString('utf-8');
+      const liveReloadScript = `
+        <script>
+          (function() {
+            let socket;
+            let retryCount = 0;
+            const maxRetries = 50;
+            
+            function connect() {
+              // Avoid connecting if already connected
+              if (socket && (socket.readyState === 0 || socket.readyState === 1)) return;
+
+              socket = new WebSocket('ws://' + window.location.host);
+              
+              socket.onopen = () => {
+                console.log('⚡ docmd connected');
+                retryCount = 0;
+              };
+              
+              socket.onmessage = (e) => { 
+                if(e.data === 'reload') window.location.reload(); 
+              };
+              
+              socket.onclose = () => {
+                // Exponential backoff for reconnection
+                if (retryCount < maxRetries) {
+                    retryCount++;
+                    const delay = Math.min(1000 * (1.5 ** retryCount), 5000);
+                    setTimeout(connect, delay);
+                }
+              };
+              
+              socket.onerror = (err) => {
+                 // Ignore errors, let onclose handle retry
+              };
+            }
+            // Delay initial connection slightly to ensure page load
+            setTimeout(connect, 500);
+          })();
+        </script></body>`;
+      res.end(htmlStr.replace('</body>', liveReloadScript));
+    } else {
+      res.end(content);
+    }
+
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      console.log(chalk.yellow(`⚠️  404 Not Found: ${req.url}`));
+      res.writeHead(404, { 'Content-Type': 'text/html' });
+      res.end('<h1>404 Not Found</h1><p>docmd dev server</p>');
+    } else {
+      res.writeHead(500);
+      res.end(`Server Error: ${err.code}`);
+    }
+  }
+}
+
+// --- 2. Helper Utilities ---
+
+function formatPathForDisplay(absolutePath, cwd) {
+  const relativePath = path.relative(cwd, absolutePath);
+  if (!relativePath.startsWith('..') && !path.isAbsolute(relativePath)) {
+    return `./${relativePath}`;
+  }
+  return relativePath;
+}
+
+function getNetworkIp() {
+  const interfaces = os.networkInterfaces();
+  for (const name of Object.keys(interfaces)) {
+    for (const iface of interfaces[name]) {
+      if (iface.family === 'IPv4' && !iface.internal) {
+        return iface.address;
+      }
+    }
+  }
+  return null;
+}
+
+// --- 3. Main Dev Function ---
+
+async function startDevServer(configPathOption, options = { preserve: false, port: undefined }) {
+  let config = await loadConfig(configPathOption);
+  const CWD = process.cwd();
+
+  // Config Fallback Logic
+  let actualConfigPath = path.resolve(CWD, configPathOption);
+  if (configPathOption === 'docmd.config.js' && !await fs.pathExists(actualConfigPath)) {
+      const legacyPath = path.resolve(CWD, 'config.js');
+      if (await fs.pathExists(legacyPath)) {
+          actualConfigPath = legacyPath;
+      }
+  }
+
+  const resolveConfigPaths = (currentConfig) => {
+    return {
+      outputDir: path.resolve(CWD, currentConfig.outputDir),
+      srcDirToWatch: path.resolve(CWD, currentConfig.srcDir),
+      configFileToWatch: actualConfigPath,
+      userAssetsDir: path.resolve(CWD, 'assets'),
+    };
+  };
+
+  let paths = resolveConfigPaths(config);
+  const DOCMD_ROOT = path.resolve(__dirname, '..');
+  
+  // --- Create Native Server ---
+  const server = http.createServer((req, res) => {
+    serveStatic(req, res, paths.outputDir);
+  });
+  
+  let wss; // WebSocket instance (initialized later)
+
+  function broadcastReload() {
+    if (wss) {
+      wss.clients.forEach((client) => {
+        if (client.readyState === WebSocket.OPEN) {
+          client.send('reload');
+        }
+      });
+    }
+  }
+
+  // --- Initial Build ---
+  console.log(chalk.blue('🚀 Performing initial build...'));
+  try {
+    await buildSite(configPathOption, { isDev: true, preserve: options.preserve, noDoubleProcessing: true });
+  } catch (error) {
+      console.error(chalk.red('❌ Initial build failed:'), error.message);
+  }
+
+  // --- Watcher Setup ---
+  const userAssetsDirExists = await fs.pathExists(paths.userAssetsDir);
+  const watchedPaths = [paths.srcDirToWatch, paths.configFileToWatch];
+  if (userAssetsDirExists) watchedPaths.push(paths.userAssetsDir);
+  
+  if (process.env.DOCMD_DEV === 'true') {
+    watchedPaths.push(
+      path.join(DOCMD_ROOT, 'templates'),
+      path.join(DOCMD_ROOT, 'assets'),
+      path.join(DOCMD_ROOT, 'core'),
+      path.join(DOCMD_ROOT, 'plugins')
+    );
+  }
+  
+  console.log(chalk.dim('\n👀 Watching for changes in:'));
+  console.log(chalk.dim(`   - Source: ${chalk.cyan(formatPathForDisplay(paths.srcDirToWatch, CWD))}`));
+  console.log(chalk.dim(`   - Config: ${chalk.cyan(formatPathForDisplay(paths.configFileToWatch, CWD))}`));
+  if (userAssetsDirExists) {
+    console.log(chalk.dim(`   - Assets: ${chalk.cyan(formatPathForDisplay(paths.userAssetsDir, CWD))}`));
+  }
+  console.log(''); 
+
+  const watcher = chokidar.watch(watchedPaths, {
+    ignored: /(^|[\/\\])\../,
+    persistent: true,
+    ignoreInitial: true,
+    awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 100 }
+  });
+
+  watcher.on('all', async (event, filePath) => {
+    const relativeFilePath = path.relative(CWD, filePath);
+    process.stdout.write(chalk.dim(`↻ Change in ${relativeFilePath}... `));
+    
+    try {
+      if (filePath === paths.configFileToWatch) {
+        config = await loadConfig(configPathOption);
+        // Note: With native server, we don't need to restart middleware, 
+        // serveStatic reads from disk dynamically on every request.
+        paths = resolveConfigPaths(config);
+      }
+
+      await buildSite(configPathOption, { isDev: true, preserve: options.preserve, noDoubleProcessing: true });
+      broadcastReload();
+      process.stdout.write(chalk.green('Done.\n'));
+      
+    } catch (error) {
+      console.error(chalk.red('\n❌ Rebuild failed:'), error.message);
+    }
+  });
+
+  // --- Server Startup Logic (Port Checking) ---
+  const PORT = parseInt(options.port || process.env.PORT || 3000, 10);
+  const MAX_PORT_ATTEMPTS = 10;
+
+  function checkPortInUse(port) {
+    return new Promise((resolve) => {
+      const tester = http.createServer()
+        .once('error', (err) => {
+          if (err.code === 'EADDRINUSE') resolve(true);
+          else resolve(false);
+        })
+        .once('listening', () => {
+          tester.close(() => resolve(false));
+        })
+        .listen(port, '0.0.0.0');
+    });
+  }
+
+  function askUserConfirmation() {
+    return new Promise((resolve) => {
+      const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+      });
+
+      console.log(chalk.yellow(`\n⚠️  Port ${PORT} is already in use.`));
+      console.log(chalk.yellow(`   Another instance of docmd (or another app) might be running.`));
+      
+      rl.question('   Do you want to start another instance on a different port? (Y/n) ', (answer) => {
+        rl.close();
+        const isYes = answer.trim().toLowerCase() === 'y' || answer.trim() === '';
+        resolve(isYes);
+      });
+    });
+  }
+  
+  function tryStartServer(port, attempt = 1) {
+    server.listen(port, '0.0.0.0')
+      .on('listening', async () => {
+        // Initialize WebSocket Server only AFTER successful listen
+        wss = new WebSocket.Server({ server });
+        wss.on('error', (e) => console.error('WebSocket Error:', e.message));
+
+        const indexHtmlPath = path.join(paths.outputDir, 'index.html');
+        const networkIp = getNetworkIp();
+        
+        const localUrl = `http://127.0.0.1:${port}`;
+        const networkUrl = networkIp ? `http://${networkIp}:${port}` : null;
+
+        const border = chalk.gray('────────────────────────────────────────');
+        console.log(border);
+        console.log(`  ${chalk.bold.green('SERVER RUNNING')}  ${chalk.dim(`(v${require('../../package.json').version})`)}`);
+        console.log('');
+        console.log(`  ${chalk.bold('Local:')}    ${chalk.cyan(localUrl)}`);
+        if (networkUrl) {
+            console.log(`  ${chalk.bold('Network:')}  ${chalk.cyan(networkUrl)}`);
+        }
+        console.log('');
+        console.log(`  ${chalk.dim('Serving:')}  ${formatPathForDisplay(paths.outputDir, CWD)}`);
+        console.log(border);
+        console.log('');
+
+        if (!await fs.pathExists(indexHtmlPath)) {
+            console.warn(chalk.yellow(`⚠️  Warning: Root index.html not found.`));
+        }
+      })
+      .on('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+           server.close(); 
+           tryStartServer(port + 1);
+        } else {
+           console.error(chalk.red(`Failed to start server: ${err.message}`));
+           process.exit(1);
+        }
+      });
+  }
+
+  // --- Main Execution Flow ---
+  (async () => {
+    // Skip check if user manually specified port flag
+    if (options.port) {
+      tryStartServer(PORT);
+      return;
+    }
+
+    const isBusy = await checkPortInUse(PORT);
+    
+    if (isBusy) {
+      const shouldProceed = await askUserConfirmation();
+      if (!shouldProceed) {
+        console.log(chalk.dim('Cancelled.'));
+        process.exit(0);
+      }
+      tryStartServer(PORT + 1);
+    } else {
+      tryStartServer(PORT);
+    }
+  })();
+
+  process.on('SIGINT', () => {
+    console.log(chalk.yellow('\n🛑 Shutting down...'));
+    watcher.close();
+    process.exit(0);
+  });
+}
+
+module.exports = { startDevServer };

package/src/commands/init.js

@@ -0,0 +1,277 @@
+// Source file from the docmd project — https://github.com/docmd-io/docmd
+
+const fs = require('../utils/fs-utils');
+const path = require('path');
+const readline = require('readline');
+const { version } = require('../../package.json');
+
+const defaultConfigContent = `// docmd.config.js
+module.exports = {
+  // --- Core Metadata ---
+  siteTitle: 'My Documentation',
+  siteUrl: '', // e.g. https://mysite.com (Critical for SEO/Sitemap)
+
+  // --- Branding ---
+  logo: {
+    light: 'assets/images/docmd-logo-dark.png',
+    dark: 'assets/images/docmd-logo-light.png',
+    alt: 'Logo',
+    href: './',
+  },
+  favicon: 'assets/favicon.ico',
+
+  // --- Source & Output ---
+  srcDir: 'docs',
+  outputDir: 'site',
+
+  // --- Theme & Layout ---
+  theme: {
+    name: 'sky',            // Options: 'default', 'sky', 'ruby', 'retro'
+    defaultMode: 'system',  // 'light', 'dark', or 'system'
+    enableModeToggle: true, // Show mode toggle button
+    positionMode: 'top',    // 'top' or 'bottom'
+    codeHighlight: true,    // Enable Highlight.js
+    customCss: [],          // e.g. ['assets/css/custom.css']
+  },
+
+  // --- Features ---
+  search: true,           // Built-in offline search
+  minify: true,           // Minify HTML/CSS/JS in build
+  autoTitleFromH1: true,  // Auto-generate page title from first H1
+  copyCode: true,         // Show "copy" button on code blocks
+  pageNavigation: true,   // Prev/Next buttons at bottom
+
+  // --- Navigation (Sidebar) ---
+  navigation: [
+    { title: 'Introduction', path: '/', icon: 'home' },
+    {
+      title: 'Guide',
+      icon: 'book-open',
+      collapsible: true,
+      children: [
+        { title: 'Getting Started', path: 'https://docs.docmd.io/getting-started/installation', icon: 'rocket', external: true },
+        { title: 'Configuration', path: 'https://docs.docmd.io/configuration', icon: 'settings', external: true },
+      ],
+    },
+    { title: 'Live Editor', path: 'https://live.docmd.io', icon: 'pencil-ruler', external: true },
+    { title: 'GitHub', path: 'https://github.com/docmd-io/docmd', icon: 'github', external: true },
+  ],
+
+  // --- Plugins ---
+  plugins: {
+    seo: {
+      defaultDescription: 'Documentation built with docmd.',
+      openGraph: {
+        defaultImage: '',   // e.g. 'assets/images/og-image.png'
+      },
+      twitter: {
+        cardType: 'summary_large_image',
+      }
+    },
+    analytics: {
+      googleV4: {
+        measurementId: 'G-X9WTDL262N' // Replace with your Google Analytics Measurement ID
+      }
+    },
+    sitemap: {
+      defaultChangefreq: 'weekly',  // e.g. 'daily', 'weekly', 'monthly'
+      defaultPriority: 0.8          // Priority between 0.0 and 1.0
+    }
+  },
+
+  // --- Footer ---
+  footer: '© ' + new Date().getFullYear() + ' My Project. Built with [docmd](https://docmd.io).',
+  
+  // --- Edit Link ---
+  editLink: {
+    enabled: false,
+    baseUrl: 'https://github.com/USERNAME/REPO/edit/main/docs',
+    text: 'Edit this page'
+  }
+};
+`;
+
+const defaultIndexMdContent = `---
+title: "Welcome"
+description: "Welcome to your new documentation site."
+---
+
+# Welcome to Your Docs
+
+Congratulations! You have successfully initialized a new **docmd** project.
+
+## 🚀 Quick Start
+
+You are currently viewing the content of \`docs/index.md\`.
+
+\`\`\`bash
+npm start   # Start the dev server
+docmd build # Build for production
+\`\`\`
+
+## ✨ Features Demo
+
+docmd comes with built-in components to make your documentation beautiful.
+
+::: callout tip
+**Try this:** Edit this file and save it. The browser will live reload instantly!
+:::
+
+### Container Examples
+
+::: card Flexible Structure
+**Organize your way.**
+Create Markdown files in the \`docs/\` folder and map them in \`docmd.config.js\`.
+:::
+
+::: tabs
+== tab "Simple"
+This is a simple tab content.
+
+== tab "Nested"
+::: callout info
+You can even nest other components inside tabs!
+:::
+:::
+
+## 📚 Next Steps
+
+*   [Check the Official Documentation](https://docs.docmd.io)
+*   [Customize your Theme](https://docs.docmd.io/theming)
+*   [Deploy to GitHub Pages](https://docs.docmd.io/deployment)
+`;
+
+const defaultPackageJson = {
+  name: "my-docs",
+  version: "0.0.1",
+  private: true,
+  scripts: {
+    "dev": "docmd dev",
+    "build": "docmd build",
+    "preview": "npx serve site"
+  },
+  dependencies: {
+    "@docmd/core": `^${version}`
+  }
+};
+
+async function initProject() {
+  const baseDir = process.cwd();
+  const packageJsonFile = path.join(baseDir, 'package.json');
+  const configFile = path.join(baseDir, 'docmd.config.js');
+  const docsDir = path.join(baseDir, 'docs');
+  const indexMdFile = path.join(docsDir, 'index.md');
+  const assetsDir = path.join(baseDir, 'assets');
+  const assetsCssDir = path.join(assetsDir, 'css');
+  const assetsJsDir = path.join(assetsDir, 'js');
+  const assetsImagesDir = path.join(assetsDir, 'images');
+  
+  const existingFiles = [];
+  const dirExists = {
+    docs: false,
+    assets: false
+  };
+  
+  // Check if package.json exists
+  if (!await fs.pathExists(packageJsonFile)) {
+    await fs.writeJson(packageJsonFile, defaultPackageJson, { spaces: 2 });
+    console.log('📦 Created `package.json` (Deployment Ready)');
+  } else {
+    console.log('⏭️  Skipped existing `package.json`');
+  }
+
+  // Check each file individually
+  if (await fs.pathExists(configFile)) {
+    existingFiles.push('docmd.config.js');
+  }
+
+  // Check for the legacy config.js
+  const oldConfigFile = path.join(baseDir, 'config.js');
+  if (await fs.pathExists(oldConfigFile)) {
+    existingFiles.push('config.js');
+  }
+  
+  // Check if docs directory exists
+  if (await fs.pathExists(docsDir)) {
+    dirExists.docs = true;
+    if (await fs.pathExists(indexMdFile)) {
+      existingFiles.push('docs/index.md');
+    }
+  }
+
+  // Check if assets directory exists
+  if (await fs.pathExists(assetsDir)) {
+    dirExists.assets = true;
+  }
+  
+  // Determine if we should override existing files
+  let shouldOverride = false;
+  if (existingFiles.length > 0) {
+    console.warn('⚠️  The following files already exist:');
+    existingFiles.forEach(file => console.warn(`   - ${file}`));
+    
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    
+    const answer = await new Promise(resolve => {
+      rl.question('Do you want to override these files? (y/N): ', resolve);
+    });
+    
+    rl.close();
+    
+    shouldOverride = answer.toLowerCase() === 'y';
+    
+    if (!shouldOverride) {
+      console.log('⏭️  Skipping existing files. Will only create new files.');
+    }
+  }
+  
+  // Create docs directory if it doesn't exist
+  if (!dirExists.docs) {
+    await fs.ensureDir(docsDir);
+    console.log('📁 Created `docs/` directory');
+  } else {
+    console.log('📁 Using existing `docs/` directory');
+  }
+
+  // Create assets directory structure if it doesn't exist
+  if (!dirExists.assets) {
+    await fs.ensureDir(assetsDir);
+    await fs.ensureDir(assetsCssDir);
+    await fs.ensureDir(assetsJsDir);
+    await fs.ensureDir(assetsImagesDir);
+    console.log('📁 Created `assets/` directory with css, js, and images subdirectories');
+  } else {
+    console.log('📁 Using existing `assets/` directory');
+    
+    if (!await fs.pathExists(assetsCssDir)) await fs.ensureDir(assetsCssDir);
+    if (!await fs.pathExists(assetsJsDir)) await fs.ensureDir(assetsJsDir);
+    if (!await fs.pathExists(assetsImagesDir)) await fs.ensureDir(assetsImagesDir);
+  }
+  
+  // Write config file if it doesn't exist or user confirmed override
+  if (!await fs.pathExists(configFile) || shouldOverride) {
+    await fs.writeFile(configFile, defaultConfigContent, 'utf8');
+    console.log(`📄 ${shouldOverride ? 'Updated' : 'Created'} \`docmd.config.js\``);
+  } else {
+    console.log('⏭️  Skipped existing `docmd.config.js`');
+  }
+  
+  // Write index.md file if it doesn't exist or user confirmed override
+  if (!await fs.pathExists(indexMdFile) || shouldOverride) {
+    await fs.writeFile(indexMdFile, defaultIndexMdContent, 'utf8');
+    console.log('📄 Created `docs/index.md`');
+  } else if (shouldOverride) {
+    await fs.writeFile(indexMdFile, defaultIndexMdContent, 'utf8');
+    console.log('📄 Updated `docs/index.md`');
+  } else {
+    console.log('⏭️  Skipped existing `docs/index.md`');
+  }
+  
+  console.log('✅ Project initialization complete!');
+  console.log('👉 Run `npm install` to setup dependencies.');
+}
+
+module.exports = { initProject };

package/src/commands/live.js

@@ -0,0 +1,15 @@
+async function buildLive(options = {}) {
+  // Delegate to the standalone package
+  const livePkg = require('@docmd/live');
+  
+  // If explicitly asked NOT to serve (for testing), just build
+  if (options.serve === false) {
+      console.log('🔨 Building Live Editor ...');
+      await livePkg.build();
+  } else {
+      // Default behavior: Build + Serve
+      await livePkg.start();
+  }
+}
+
+module.exports = { buildLive };

package/src/utils/config-loader.js

@@ -0,0 +1,38 @@
+const path = require('path');
+const fs = require('fs');
+const { validateConfig } = require('@docmd/parser'); 
+
+async function loadConfig(configPath) {
+  const cwd = process.cwd();
+  let absoluteConfigPath = path.resolve(cwd, configPath);
+
+  // Fallback for default filename
+  if (!fs.existsSync(absoluteConfigPath) && configPath === 'docmd.config.js') {
+    const legacyPath = path.resolve(cwd, 'config.js');
+    if (fs.existsSync(legacyPath)) absoluteConfigPath = legacyPath;
+    else throw new Error(`Configuration file not found at: ${absoluteConfigPath}\nRun "docmd init" to create one.`);
+  }
+
+  try {
+    delete require.cache[require.resolve(absoluteConfigPath)];
+    const config = require(absoluteConfigPath);
+    
+    // Validate using Parser
+    validateConfig(config);
+
+    // Apply Defaults
+    return {
+      base: '/',
+      srcDir: 'docs',
+      outputDir: 'site',
+      ...config,
+      theme: { defaultMode: 'light', ...config.theme },
+      navigation: config.navigation || [{ title: 'Home', path: '/' }]
+    };
+  } catch (e) {
+    if (e.message === 'Invalid configuration file.') throw e;
+    throw new Error(`Error parsing config file: ${e.message}`);
+  }
+}
+
+module.exports = { loadConfig };