@knowcode/doc-builder 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to @knowcode/doc-builder will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.4] - 2025-01-19
+
+### Added
+- Comprehensive Vercel CLI prompt explanations in help text
+- Step-by-step answers for all Vercel setup questions
+- Hints in prompts to guide users through setup
+- Pre-deployment guidance showing what Vercel will ask
+- Better project name sanitization for Vercel URLs
+
+### Improved
+- More detailed deployment help with exact answers to provide
+- Clearer instructions for first-time vs. subsequent deployments
+- Visual question/answer format in help documentation
+
+## [1.0.3] - 2025-01-19
+
+### Fixed
+- Fixed "path argument must be string" error in deploy command
+- Improved Vercel CLI detection with helpful installation instructions
+- Made config loading more lenient for missing directories
+- Auto-build documentation if not already built before deployment
+- Better error messages with stack traces for debugging
+
+### Added
+- Automatic preparation of deployment files (index.html redirect)
+- Check for Vercel CLI before attempting deployment
+- Build documentation automatically if output directory doesn't exist
+- More robust vercel.json generation for static sites
+
 ## [1.0.2] - 2025-01-19
 
 ### Fixed

package/cli.js

@@ -8,7 +8,7 @@ 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 { deployToVercel, setupVercelProject, prepareDeployment } = require('./lib/deploy');
 const { loadConfig, createDefaultConfig } = require('./lib/config');
 const { execSync } = require('child_process');
 
@@ -141,11 +141,36 @@ ${chalk.yellow('First-time Vercel Setup:')}
   ${chalk.cyan('3. Run doc-builder deploy:')}
      ${chalk.gray('$')} npx @knowcode/doc-builder deploy
      
-     The tool will:
-     • Create a new Vercel project
-     • Link it to your documentation
-     • Deploy your site
-     • Provide you with a URL
+     You'll be asked several questions:
+     
+     ${chalk.green('Q: Would you like to set up a new Vercel project?')}
+     → Answer: ${chalk.yellow('Yes')} (first time only)
+     
+     ${chalk.green('Q: What is your project name?')}
+     → Answer: ${chalk.yellow('Your project name')} (e.g., "my-docs" or "gasworld")
+     
+     ${chalk.green('Q: Which framework preset?')}
+     → Answer: ${chalk.yellow('Other (Static HTML)')} (always choose this)
+     
+     ${chalk.green('Q: Make the deployment publicly accessible?')}
+     → Answer: ${chalk.yellow('Yes')} for public docs, ${chalk.yellow('No')} for private
+     
+     ${chalk.gray('Then Vercel CLI will ask:')}
+     
+     ${chalk.green('Q: Set up [your directory]?')}
+     → Answer: ${chalk.yellow('Yes')}
+     
+     ${chalk.green('Q: Which scope should contain your project?')}
+     → Answer: ${chalk.yellow('Select your account')} (usually your username)
+     
+     ${chalk.green('Q: Link to existing project?')}
+     → Answer: ${chalk.yellow('No')} (first time), ${chalk.yellow('Yes')} (if redeploying)
+     
+     ${chalk.green('Q: In which directory is your code located?')}
+     → Answer: ${chalk.yellow('./html')} (or your output directory)
+     
+     ${chalk.green('Q: Want to modify these settings?')}
+     → Answer: ${chalk.yellow('No')} (doc-builder handles this)
   
   ${chalk.cyan('4. Configure Access (Important!):')} 
      After deployment, go to your Vercel dashboard:
@@ -166,7 +191,34 @@ ${chalk.yellow('Troubleshooting:')}
     const spinner = ora('Deploying to Vercel...').start();
     
     try {
-      const config = await loadConfig(options.config, options);
+      const config = await loadConfig(options.config || 'doc-builder.config.js', options);
+      
+      // First check if Vercel CLI is installed
+      try {
+        execSync('vercel --version', { stdio: 'ignore' });
+      } catch (vercelError) {
+        spinner.fail('Vercel CLI not found');
+        console.log(chalk.yellow('\n📦 Vercel CLI is required for deployment\n'));
+        console.log(chalk.cyan('Install it with one of these commands:'));
+        console.log(chalk.gray('  npm install -g vercel'));
+        console.log(chalk.gray('  yarn global add vercel'));
+        console.log(chalk.gray('  brew install vercel     # macOS\n'));
+        console.log(chalk.yellow('Then run deployment again:'));
+        console.log(chalk.gray('  npx @knowcode/doc-builder deploy\n'));
+        process.exit(1);
+      }
+      
+      // Check if we need to build first
+      const outputPath = path.join(process.cwd(), config.outputDir || 'html');
+      if (!fs.existsSync(outputPath) || !options.noBuild) {
+        spinner.stop();
+        console.log(chalk.blue('\n📦 Building documentation first...\n'));
+        await build(config);
+        spinner.start('Deploying to Vercel...');
+      }
+      
+      // Prepare deployment files
+      await prepareDeployment(config);
       
       // Check if this is the first deployment
       const vercelConfigPath = path.join(process.cwd(), '.vercel', 'project.json');
@@ -196,6 +248,9 @@ ${chalk.yellow('Troubleshooting:')}
     } catch (error) {
       spinner.fail('Deployment failed');
       console.error(chalk.red(error.message));
+      if (error.stack) {
+        console.error(chalk.gray(error.stack));
+      }
       process.exit(1);
     }
   });

package/lib/config.js

@@ -188,10 +188,12 @@ async function loadConfig(configPath, options = {}) {
     }
   }
   
-  // Validate paths
+  // Validate paths - but be lenient for deploy command
   const docsPath = path.join(process.cwd(), config.docsDir);
   if (!fs.existsSync(docsPath)) {
-    throw new Error(`Documentation directory not found: ${config.docsDir}`);
+    console.warn(chalk.yellow(`Warning: Documentation directory not found: ${config.docsDir}`));
+    console.log(chalk.gray(`Create it with: mkdir ${config.docsDir} && echo "# Documentation" > ${config.docsDir}/README.md`));
+    // Don't throw error - let commands handle missing directories appropriately
   }
   
   return config;

package/lib/deploy.js

@@ -25,7 +25,8 @@ async function setupVercelProject(config) {
       type: 'text',
       name: 'projectName',
       message: 'What is your project name?',
-      initial: config.siteName || 'my-docs'
+      initial: config.siteName.toLowerCase().replace(/[^a-z0-9-]/g, '-') || 'my-docs',
+      hint: 'This will be your URL: project-name.vercel.app'
     },
     {
       type: 'select',
@@ -36,13 +37,15 @@ async function setupVercelProject(config) {
         { title: 'Next.js', value: 'nextjs' },
         { title: 'Vite', value: 'vite' }
       ],
-      initial: 0
+      initial: 0,
+      hint: 'Choose "Other (Static HTML)" for doc-builder'
     },
     {
       type: 'confirm',
       name: 'publicAccess',
       message: 'Make the deployment publicly accessible?',
-      initial: true
+      initial: true,
+      hint: 'Choose Yes for public docs, No for team-only access'
     }
   ]);
   
@@ -51,10 +54,10 @@ async function setupVercelProject(config) {
   if (!fs.existsSync(vercelConfigPath)) {
     const vercelConfig = {
       outputDirectory: config.outputDir || 'html',
-      framework: answers.framework === 'other' ? null : answers.framework,
-      buildCommand: "npm run build:docs",
-      devCommand: "npm run dev:docs",
-      installCommand: "npm install",
+      framework: null,  // Static HTML
+      buildCommand: "", // No build needed - we already built
+      devCommand: "",   // No dev command
+      installCommand: "", // No install needed
       public: answers.publicAccess
     };
     
@@ -64,6 +67,13 @@ async function setupVercelProject(config) {
   
   // Run Vercel setup
   console.log(chalk.blue('\n🔗 Linking to Vercel...\n'));
+  console.log(chalk.yellow('📝 Vercel will now ask additional questions:\n'));
+  console.log(chalk.gray('• Set up [directory]? → Yes'));
+  console.log(chalk.gray('• Which scope? → Select your account'));
+  console.log(chalk.gray('• Link to existing? → No (first time)'));
+  console.log(chalk.gray('• Project name? → Same as above'));
+  console.log(chalk.gray('• Code directory? → ./html (or your output dir)'));
+  console.log(chalk.gray('• Modify settings? → No\n'));
   
   try {
     execSync('vercel link', { stdio: 'inherit' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowcode/doc-builder",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Reusable documentation builder for markdown-based sites with Vercel deployment support",
   "main": "index.js",
   "bin": {