@knowcode/doc-builder 1.0.0

package/cli.js

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const chalk = require('chalk');
+const prompts = require('prompts');
+const ora = require('ora');
+const fs = require('fs-extra');
+const path = require('path');
+const { build } = require('./lib/builder');
+const { startDevServer } = require('./lib/dev-server');
+const { deployToVercel, setupVercelProject } = require('./lib/deploy');
+const { loadConfig, createDefaultConfig } = require('./lib/config');
+const { execSync } = require('child_process');
+
+// Package info
+const packageJson = require('./package.json');
+
+// Default to build command if no args provided
+if (process.argv.length === 2) {
+  process.argv.push('build');
+}
+
+program
+  .name('doc-builder')
+  .description(packageJson.description)
+  .version(packageJson.version)
+  .addHelpText('before', `
+${chalk.cyan('🚀 @juno/doc-builder')} - Transform your markdown into beautiful documentation sites
+
+${chalk.yellow('What it does:')}
+  • Converts markdown files to static HTML with a beautiful Notion-inspired theme
+  • Automatically generates navigation from your folder structure
+  • Supports mermaid diagrams, syntax highlighting, and dark mode
+  • Deploys to Vercel with one command (zero configuration)
+  • Optional authentication to protect private documentation
+
+${chalk.yellow('Quick Start:')}
+  ${chalk.gray('$')} npx @juno/doc-builder              ${chalk.gray('# Build and deploy to Vercel')}
+  ${chalk.gray('$')} npx @juno/doc-builder build        ${chalk.gray('# Build HTML files only')}
+  ${chalk.gray('$')} npx @juno/doc-builder dev          ${chalk.gray('# Start development server')}
+  `);
+
+// Build command
+program
+  .command('build')
+  .description('Build the documentation site to static HTML')
+  .option('-c, --config <path>', 'path to config file (default: doc-builder.config.js)')
+  .option('-i, --input <dir>', 'input directory containing markdown files (default: docs)')
+  .option('-o, --output <dir>', 'output directory for HTML files (default: html)')
+  .option('--preset <preset>', 'use a preset configuration (available: cybersolstice)')
+  .option('--legacy', 'use legacy mode for backward compatibility')
+  .option('--no-auth', 'disable authentication even if configured')
+  .option('--no-changelog', 'disable automatic changelog generation')
+  .addHelpText('after', `
+${chalk.yellow('Examples:')}
+  ${chalk.gray('$')} doc-builder build                        ${chalk.gray('# Build with defaults')}
+  ${chalk.gray('$')} doc-builder build --input docs --output dist
+  ${chalk.gray('$')} doc-builder build --preset cybersolstice ${chalk.gray('# Use JUNO platform preset')}
+  ${chalk.gray('$')} doc-builder build --config my-config.js  ${chalk.gray('# Use custom config')}
+`)
+  .action(async (options) => {
+    const spinner = ora('Building documentation...').start();
+    
+    try {
+      const config = await loadConfig(options.config || 'doc-builder.config.js', options);
+      await build(config);
+      spinner.succeed('Documentation built successfully!');
+    } catch (error) {
+      spinner.fail('Build failed');
+      console.error(chalk.red(error.message));
+      if (error.stack) {
+        console.error(chalk.gray(error.stack));
+      }
+      process.exit(1);
+    }
+  });
+
+// Dev server command
+program
+  .command('dev')
+  .description('Start development server with live reload')
+  .option('-c, --config <path>', 'path to config file (default: doc-builder.config.js)')
+  .option('-p, --port <port>', 'port to run dev server on (default: 3000)')
+  .option('-h, --host <host>', 'host to bind to (default: localhost)')
+  .option('--no-open', 'don\'t open browser automatically')
+  .addHelpText('after', `
+${chalk.yellow('Examples:')}
+  ${chalk.gray('$')} doc-builder dev                    ${chalk.gray('# Start on http://localhost:3000')}
+  ${chalk.gray('$')} doc-builder dev --port 8080        ${chalk.gray('# Use custom port')}
+  ${chalk.gray('$')} doc-builder dev --host 0.0.0.0     ${chalk.gray('# Allow external connections')}
+`)
+  .action(async (options) => {
+    try {
+      const config = await loadConfig(options.config, options);
+      await startDevServer(config, options.port);
+    } catch (error) {
+      console.error(chalk.red(error.message));
+      process.exit(1);
+    }
+  });
+
+// Deploy command
+program
+  .command('deploy')
+  .description('Deploy documentation to Vercel (requires Vercel CLI)')
+  .option('-c, --config <path>', 'path to config file (default: doc-builder.config.js)')
+  .option('--prod', 'deploy to production (default: preview deployment)')
+  .option('--no-build', 'skip building before deployment')
+  .option('--force', 'force deployment without confirmation')
+  .addHelpText('after', `
+${chalk.yellow('Examples:')}
+  ${chalk.gray('$')} doc-builder deploy                 ${chalk.gray('# Deploy preview to Vercel')}
+  ${chalk.gray('$')} doc-builder deploy --prod          ${chalk.gray('# Deploy to production')}
+  ${chalk.gray('$')} doc-builder deploy --no-build      ${chalk.gray('# Deploy existing build')}
+
+${chalk.yellow('First-time setup:')}
+  The tool will guide you through:
+  1. Installing Vercel CLI (if needed)
+  2. Creating a new Vercel project
+  3. Configuring deployment settings
+  
+${chalk.yellow('Important:')} After deployment, disable Vercel Authentication in project settings for public docs.
+`)
+  .action(async (options) => {
+    const spinner = ora('Deploying to Vercel...').start();
+    
+    try {
+      const config = await loadConfig(options.config, options);
+      
+      // Check if this is the first deployment
+      const vercelConfigPath = path.join(process.cwd(), '.vercel', 'project.json');
+      if (!fs.existsSync(vercelConfigPath)) {
+        spinner.stop();
+        console.log(chalk.yellow('\n🚀 First time deploying to Vercel!\n'));
+        
+        const setupConfirm = await prompts({
+          type: 'confirm',
+          name: 'value',
+          message: 'Would you like to set up a new Vercel project?',
+          initial: true
+        });
+        
+        if (setupConfirm.value) {
+          await setupVercelProject(config);
+        } else {
+          console.log(chalk.gray('Run `vercel` manually to set up your project.'));
+          process.exit(0);
+        }
+      }
+      
+      spinner.start('Deploying to Vercel...');
+      const url = await deployToVercel(config, options.prod);
+      spinner.succeed(`Deployed successfully! ${chalk.cyan(url)}`);
+      
+    } catch (error) {
+      spinner.fail('Deployment failed');
+      console.error(chalk.red(error.message));
+      process.exit(1);
+    }
+  });
+
+// Init command
+program
+  .command('init')
+  .description('Initialize doc-builder in your project')
+  .option('--config', 'create configuration file')
+  .option('--example', 'create example documentation structure')
+  .addHelpText('after', `
+${chalk.yellow('Examples:')}
+  ${chalk.gray('$')} doc-builder init --config          ${chalk.gray('# Create doc-builder.config.js')}
+  ${chalk.gray('$')} doc-builder init --example         ${chalk.gray('# Create example docs folder')}
+`)
+  .action(async (options) => {
+    if (options.config) {
+      const configPath = path.join(process.cwd(), 'doc-builder.config.js');
+      
+      if (fs.existsSync(configPath)) {
+        const overwrite = await prompts({
+          type: 'confirm',
+          name: 'value',
+          message: 'Config file already exists. Overwrite?',
+          initial: false
+        });
+        
+        if (!overwrite.value) {
+          console.log(chalk.gray('Cancelled.'));
+          process.exit(0);
+        }
+      }
+      
+      const config = await createDefaultConfig();
+      fs.writeFileSync(configPath, `module.exports = ${JSON.stringify(config, null, 2)};`);
+      console.log(chalk.green('✅ Created doc-builder.config.js'));
+    }
+    
+    if (options.example) {
+      const docsDir = path.join(process.cwd(), 'docs');
+      
+      if (!fs.existsSync(docsDir)) {
+        fs.mkdirSync(docsDir, { recursive: true });
+        
+        // Create example files
+        const exampleFiles = {
+          'README.md': `# Welcome to Your Documentation\n\nThis is an example documentation site created with @knowcode/doc-builder.\n\n## Features\n\n- 📝 Write in Markdown\n- 🎨 Beautiful Notion-inspired design\n- 📊 Mermaid diagram support\n- 🌙 Dark mode\n- 🚀 Deploy to Vercel\n\n## Getting Started\n\n1. Edit this file and add your content\n2. Create new markdown files\n3. Run \`npx @knowcode/doc-builder\` to build and deploy\n\n## Example Diagram\n\n\`\`\`mermaid\ngraph TD\n    A[Write Docs] --> B[Build]\n    B --> C[Deploy]\n    C --> D[Share]\n\`\`\`\n`,
+          'getting-started.md': `# Getting Started\n\n**Generated**: ${new Date().toISOString().split('T')[0]}\n**Status**: Draft\n**Verified**: ❓\n\n## Overview\n\nThis guide will help you get started with your documentation.\n\n## Installation\n\nNo installation required! Just use:\n\n\`\`\`bash\nnpx @knowcode/doc-builder\n\`\`\`\n\n## Writing Documentation\n\n1. Create markdown files in the \`docs\` folder\n2. Use folders to organize your content\n3. Add front matter for metadata\n\n## Building\n\nTo build your documentation:\n\n\`\`\`bash\nnpx @knowcode/doc-builder build\n\`\`\`\n\n## Deployment\n\nDeploy to Vercel:\n\n\`\`\`bash\nnpx @knowcode/doc-builder deploy --prod\n\`\`\`\n`,
+          'guides/configuration.md': `# Configuration Guide\n\n**Generated**: ${new Date().toISOString().split('T')[0]}\n**Status**: Draft\n**Verified**: ❓\n\n## Overview\n\n@knowcode/doc-builder works with zero configuration, but you can customize it.\n\n## Configuration File\n\nCreate \`doc-builder.config.js\`:\n\n\`\`\`javascript\nmodule.exports = {\n  siteName: 'My Documentation',\n  siteDescription: 'Documentation for my project',\n  \n  features: {\n    authentication: false,\n    changelog: true,\n    mermaid: true,\n    darkMode: true\n  }\n};\n\`\`\`\n\n## Options\n\n### Site Information\n\n- \`siteName\`: Your documentation site name\n- \`siteDescription\`: Brief description\n\n### Directories\n\n- \`docsDir\`: Input directory (default: 'docs')\n- \`outputDir\`: Output directory (default: 'html')\n\n### Features\n\n- \`authentication\`: Enable password protection\n- \`changelog\`: Generate changelog automatically\n- \`mermaid\`: Support for diagrams\n- \`darkMode\`: Dark theme support\n`
+        };
+        
+        // Create example files
+        for (const [filePath, content] of Object.entries(exampleFiles)) {
+          const fullPath = path.join(docsDir, filePath);
+          const dir = path.dirname(fullPath);
+          
+          if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+          }
+          
+          fs.writeFileSync(fullPath, content);
+          console.log(chalk.green(`✅ Created ${filePath}`));
+        }
+        
+        console.log(chalk.cyan('\\n📚 Example documentation created in docs/ folder'));
+        console.log(chalk.gray('\\nNext steps:'));
+        console.log(chalk.gray('1. Edit the example files to add your content'));
+        console.log(chalk.gray('2. Run `npx @knowcode/doc-builder` to build and deploy'));
+      } else {
+        console.log(chalk.yellow('⚠️  docs/ directory already exists'));
+      }
+    }
+  });
+
+// Add a default command handler for when doc-builder is run without arguments
+program
+  .action(async () => {
+    // Default action is build + deploy
+    console.log(chalk.cyan('\n🚀 Building and deploying your documentation...\n'));
+    
+    try {
+      // Build first
+      const config = await loadConfig('doc-builder.config.js', { legacy: true });
+      const buildSpinner = ora('Building documentation...').start();
+      await build(config);
+      buildSpinner.succeed('Documentation built successfully!');
+      
+      // Then deploy
+      const deploySpinner = ora('Deploying to Vercel...').start();
+      
+      // Check if this is the first deployment
+      const vercelConfigPath = path.join(process.cwd(), '.vercel', 'project.json');
+      if (!fs.existsSync(vercelConfigPath)) {
+        deploySpinner.stop();
+        console.log(chalk.yellow('\n🚀 First time deploying to Vercel!\n'));
+        
+        const setupConfirm = await prompts({
+          type: 'confirm',
+          name: 'value',
+          message: 'Would you like to set up a new Vercel project?',
+          initial: true
+        });
+        
+        if (setupConfirm.value) {
+          await setupVercelProject(config);
+        } else {
+          console.log(chalk.gray('\nTo deploy manually, run: vercel'));
+          console.log(chalk.gray('To skip deployment, run: doc-builder build\n'));
+          process.exit(0);
+        }
+        deploySpinner.start('Deploying to Vercel...');
+      }
+      
+      const url = await deployToVercel(config, false);
+      deploySpinner.succeed(`Deployed successfully! ${chalk.cyan(url)}`);
+      
+    } catch (error) {
+      console.error(chalk.red('\nError: ' + error.message));
+      console.log(chalk.gray('\nTo build without deploying, run: doc-builder build'));
+      process.exit(1);
+    }
+  });
+
+// Parse arguments
+program.parse(process.argv);

package/index.js

@@ -0,0 +1,38 @@
+/**
+ * @knowcode/doc-builder - Programmatic API
+ * 
+ * This module exports functions for use in scripts or other tools
+ */
+
+const { build } = require('./lib/builder');
+const { startDevServer } = require('./lib/dev-server');
+const { deployToVercel, setupVercelProject } = require('./lib/deploy');
+const { loadConfig, createDefaultConfig } = require('./lib/config');
+
+module.exports = {
+  // Main functions
+  build,
+  startDevServer,
+  deployToVercel,
+  setupVercelProject,
+  
+  // Config utilities
+  loadConfig,
+  createDefaultConfig,
+  
+  // Convenience wrapper for common operations
+  async buildDocs(configPath = 'doc-builder.config.js', options = {}) {
+    const config = await loadConfig(configPath, options);
+    return build(config);
+  },
+  
+  async deploy(configPath = 'doc-builder.config.js', options = {}) {
+    const config = await loadConfig(configPath, options);
+    return deployToVercel(config, options.prod);
+  },
+  
+  async dev(configPath = 'doc-builder.config.js', options = {}) {
+    const config = await loadConfig(configPath, options);
+    return startDevServer(config, options.port || 3000);
+  }
+};

package/lib/builder.js

@@ -0,0 +1,79 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+/**
+ * Main build function
+ * This wraps the existing build.js functionality
+ */
+async function build(config) {
+  console.log(chalk.blue(`\n🚀 Building ${config.siteName}...\n`));
+  
+  // Validate config
+  if (!config || typeof config !== 'object') {
+    throw new Error('Invalid configuration provided to build function');
+  }
+  
+  // For now, we'll use the existing build.js file
+  // In a future refactor, we'll move all the logic here
+  const buildScriptPath = path.join(__dirname, '../../../html/build.js');
+  
+  if (!fs.existsSync(buildScriptPath)) {
+    throw new Error('Build script not found. This package must be run from the cybersolstice project.');
+  }
+  
+  // Set environment variables for the build script
+  process.env.DOC_BUILDER_CONFIG = JSON.stringify(config);
+  
+  // Import and run the existing build
+  const buildModule = require(buildScriptPath);
+  
+  // Run the build - it doesn't take parameters, config is passed via env
+  if (typeof buildModule.build === 'function') {
+    await buildModule.build();
+  } else {
+    // If it's not a function, it might be auto-executing
+    // Just requiring it should run it
+  }
+  
+  // Copy assets to output directory
+  await copyAssets(config);
+  
+  console.log(chalk.green('\n✨ Build complete!\n'));
+}
+
+/**
+ * Copy package assets to output directory
+ */
+async function copyAssets(config) {
+  const outputDir = path.join(process.cwd(), config.outputDir);
+  const assetsDir = path.join(__dirname, '../assets');
+  
+  // Ensure output directory exists
+  await fs.ensureDir(outputDir);
+  
+  // Copy CSS
+  const cssSource = path.join(assetsDir, 'css');
+  const cssDest = path.join(outputDir, 'css');
+  if (fs.existsSync(cssSource)) {
+    await fs.copy(cssSource, cssDest, { overwrite: true });
+  }
+  
+  // Copy JS
+  const jsSource = path.join(assetsDir, 'js');
+  const jsDest = path.join(outputDir, 'js');
+  if (fs.existsSync(jsSource)) {
+    await fs.copy(jsSource, jsDest, { overwrite: true });
+  }
+  
+  // Copy auth.js to root
+  const authSource = path.join(assetsDir, 'js', 'auth.js');
+  const authDest = path.join(outputDir, 'auth.js');
+  if (fs.existsSync(authSource)) {
+    await fs.copy(authSource, authDest, { overwrite: true });
+  }
+}
+
+module.exports = {
+  build
+};

package/lib/config.js

@@ -0,0 +1,255 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+/**
+ * Default configuration
+ */
+const defaultConfig = {
+  // Source and output directories
+  docsDir: 'docs',
+  outputDir: 'html',
+  
+  // Site metadata
+  siteName: 'Documentation',
+  siteDescription: 'Documentation site built with @knowcode/doc-builder',
+  
+  // Features
+  features: {
+    authentication: false,
+    changelog: true,
+    mermaid: true,
+    tooltips: true,
+    search: false,
+    darkMode: true
+  },
+  
+  // Authentication (if enabled)
+  auth: {
+    username: 'admin',
+    password: 'password'
+  },
+  
+  // Changelog settings
+  changelog: {
+    daysBack: 14,
+    enabled: true
+  },
+  
+  // Navigation configuration
+  folderOrder: [],
+  folderDescriptions: {},
+  folderIcons: {},
+  
+  // Deployment
+  deployment: {
+    platform: 'vercel',
+    outputDirectory: 'html'
+  }
+};
+
+/**
+ * Cybersolstice preset - maintains compatibility with existing project
+ */
+const cybersolsticePreset = {
+  docsDir: 'docs',
+  outputDir: 'html',
+  siteName: 'JUNO Platform',  // Keep original for cybersolstice project
+  siteDescription: 'Transforming complex sales through intelligent automation',
+  
+  features: {
+    authentication: true,
+    changelog: true,
+    mermaid: true,
+    tooltips: true,
+    search: false,
+    darkMode: true
+  },
+  
+  auth: {
+    username: 'juno',
+    password: 'docs2025'
+  },
+  
+  changelog: {
+    daysBack: 14,
+    enabled: true
+  },
+  
+  // Folder descriptions from existing code
+  folderDescriptions: {
+    'product-roadmap': 'Strategic vision, timeline, and feature planning for the JUNO platform',
+    'product-requirements': 'Detailed product specifications, requirements documents, and feature definitions',
+    'architecture': 'System design, data flows, and technical infrastructure documentation',
+    'system-analysis': 'Comprehensive system analysis, functional requirements, and cross-component documentation',
+    'bubble': 'Core application platform - business logic, UI/UX, and user workflows',
+    'quickbase': 'Database schema, data management, and backend operations',
+    'activecampaign': 'Marketing automation integration and lead management system',
+    'juno-signer': 'Document signing service for digital signatures and PDF generation',
+    'juno-api-deprecated': 'Legacy API documentation (deprecated, for reference only)',
+    'postman': 'API testing tools, collections, and test automation',
+    'mcp': 'Model Context Protocol setup and configuration guides',
+    'team': 'Team roles, responsibilities, and task assignments',
+    'thought-leadership': 'Strategic thinking, industry insights, and future vision',
+    'paths': 'Dynamic pathway routing system for insurance applications',
+    'testing': 'Testing procedures, checklists, and quality assurance',
+    'technical': 'Technical documentation and implementation details',
+    'application': 'Application components, data types, and workflows'
+  },
+  
+  folderIcons: {
+    'root': 'fas fa-home',
+    'product-roadmap': 'fas fa-road',
+    'product-requirements': 'fas fa-clipboard-list',
+    'architecture': 'fas fa-sitemap',
+    'system-analysis': 'fas fa-analytics',
+    'system': 'fas fa-cogs',
+    'bubble': 'fas fa-bubble',
+    'quickbase': 'fas fa-database',
+    'activecampaign': 'fas fa-envelope',
+    'juno-signer': 'fas fa-signature',
+    'juno-api-deprecated': 'fas fa-archive',
+    'postman': 'fas fa-flask',
+    'mcp': 'fas fa-puzzle-piece',
+    'team': 'fas fa-users',
+    'thought-leadership': 'fas fa-lightbulb',
+    'middleware': 'fas fa-layer-group',
+    'paths': 'fas fa-route',
+    'testing': 'fas fa-vial',
+    'juno-api': 'fas fa-plug'
+  },
+  
+  folderOrder: [
+    'product-roadmap',
+    'product-requirements',
+    'architecture',
+    'system-analysis',
+    'bubble',
+    'quickbase',
+    'activecampaign',
+    'juno-signer',
+    'juno-api-deprecated',
+    'postman',
+    'mcp',
+    'team',
+    'thought-leadership'
+  ]
+};
+
+/**
+ * Load configuration
+ */
+async function loadConfig(configPath, options = {}) {
+  let config = { ...defaultConfig };
+  
+  // Apply preset if specified
+  if (options.preset === 'cybersolstice') {
+    config = { ...config, ...cybersolsticePreset };
+  }
+  
+  // Load custom config file if it exists
+  const customConfigPath = path.join(process.cwd(), configPath);
+  if (fs.existsSync(customConfigPath)) {
+    try {
+      const customConfig = require(customConfigPath);
+      config = { ...config, ...customConfig };
+      console.log(chalk.gray(`Loaded config from ${configPath}`));
+    } catch (error) {
+      console.warn(chalk.yellow(`Warning: Failed to load config file: ${error.message}`));
+    }
+  } else if (!options.preset && !options.legacy) {
+    console.log(chalk.gray('No config file found, using defaults'));
+  }
+  
+  // Apply CLI options (these override config file)
+  if (options.input) {
+    config.docsDir = options.input;
+  }
+  if (options.output) {
+    config.outputDir = options.output;
+  }
+  if (options.auth === false) {
+    config.features.authentication = false;
+  }
+  if (options.changelog === false) {
+    config.features.changelog = false;
+    config.changelog.enabled = false;
+  }
+  
+  // Legacy mode - auto-detect structure
+  if (options.legacy) {
+    const docsPath = path.join(process.cwd(), 'docs');
+    const htmlPath = path.join(process.cwd(), 'html');
+    
+    if (fs.existsSync(docsPath) && fs.existsSync(htmlPath)) {
+      console.log(chalk.gray('Legacy mode: detected docs/ and html/ structure'));
+      config.docsDir = 'docs';
+      config.outputDir = 'html';
+    }
+  }
+  
+  // Validate paths
+  const docsPath = path.join(process.cwd(), config.docsDir);
+  if (!fs.existsSync(docsPath)) {
+    throw new Error(`Documentation directory not found: ${config.docsDir}`);
+  }
+  
+  return config;
+}
+
+/**
+ * Create default configuration
+ */
+async function createDefaultConfig() {
+  const answers = await require('prompts')([
+    {
+      type: 'text',
+      name: 'siteName',
+      message: 'Site name:',
+      initial: 'My Documentation'
+    },
+    {
+      type: 'text',
+      name: 'siteDescription',
+      message: 'Site description:',
+      initial: 'Documentation for my project'
+    },
+    {
+      type: 'confirm',
+      name: 'authentication',
+      message: 'Enable authentication?',
+      initial: false
+    },
+    {
+      type: prev => prev ? 'text' : null,
+      name: 'authUsername',
+      message: 'Authentication username:',
+      initial: 'admin'
+    },
+    {
+      type: prev => prev ? 'password' : null,
+      name: 'authPassword',
+      message: 'Authentication password:',
+      initial: 'password'
+    }
+  ]);
+  
+  const config = { ...defaultConfig };
+  config.siteName = answers.siteName;
+  config.siteDescription = answers.siteDescription;
+  config.features.authentication = answers.authentication;
+  
+  if (answers.authentication) {
+    config.auth.username = answers.authUsername;
+    config.auth.password = answers.authPassword;
+  }
+  
+  return config;
+}
+
+module.exports = {
+  defaultConfig,
+  cybersolsticePreset,
+  loadConfig,
+  createDefaultConfig
+};