@knowcode/doc-builder 1.0.4 → 1.0.6

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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.6] - 2025-01-19
+
+### Added
+- Much more prominent and helpful Vercel setup instructions
+- Step-by-step visual guide with numbered steps and emojis
+- Warning about common "username/html" project linking mistake
+- Detection and warning for existing project deployments
+- Comprehensive troubleshooting for "html/html does not exist" error
+- Clear instructions for fixing Root Directory settings
+
+### Improved
+- Enhanced visual formatting for Vercel prompts with boxes and colors
+- Added critical warnings about NOT linking to generic "html" projects
+- Better error detection and user guidance
+- More helpful project settings URLs
+
+### Fixed
+- Updated vercel.json to use empty strings instead of false values
+- Added installCommand to vercel.json for better compatibility
+
+## [1.0.5] - 2025-01-19
+
+### Fixed
+- Fixed "vercel.json file should be inside of the provided root directory" error
+- Deploy commands now run from the output directory (html/) instead of project root
+- Vercel link command runs from correct directory during setup
+- vercel.json is now created in the output directory where it belongs
+
+### Changed
+- Simplified vercel.json configuration for static sites
+- Updated deployment flow to work correctly with Vercel's expectations
+- Vercel project detection now checks in output directory
+
 ## [1.0.4] - 2025-01-19
 
 ### Added

package/cli.js

@@ -166,8 +166,7 @@ ${chalk.yellow('First-time Vercel Setup:')}
      ${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.gray('Note: Vercel will auto-detect that we\'re deploying from the output directory')}
      
      ${chalk.green('Q: Want to modify these settings?')}
      → Answer: ${chalk.yellow('No')} (doc-builder handles this)
@@ -186,6 +185,24 @@ ${chalk.yellow('Troubleshooting:')}
   • ${chalk.cyan('Command not found:')} Install Vercel CLI globally
   • ${chalk.cyan('Not authenticated:')} Run ${chalk.gray('vercel login')}
   • ${chalk.cyan('Project not linked:')} Delete ${chalk.gray('.vercel')} folder and redeploy
+  
+  ${chalk.red.bold('• Path "html/html" does not exist error:')}
+    ${chalk.yellow('This happens when Vercel has the wrong Root Directory setting.')}
+    
+    ${chalk.green('Fix:')}
+    1. Go to your Vercel project settings
+    2. Under "Build & Development Settings"
+    3. Set "Root Directory" to ${chalk.yellow.bold('empty (leave blank)')}
+    4. Save and redeploy
+    
+  ${chalk.red.bold('• Linked to wrong project (username/html):')}
+    ${chalk.yellow('Never link to the generic "html" project!')}
+    
+    ${chalk.green('Fix:')}
+    1. Delete the ${chalk.gray('html/.vercel')} folder
+    2. Run deployment again
+    3. When asked "Link to existing project?" say ${chalk.red.bold('NO')}
+    4. Create a new project with your actual name
 `)
   .action(async (options) => {
     const spinner = ora('Deploying to Vercel...').start();
@@ -221,8 +238,8 @@ ${chalk.yellow('Troubleshooting:')}
       await prepareDeployment(config);
       
       // Check if this is the first deployment
-      const vercelConfigPath = path.join(process.cwd(), '.vercel', 'project.json');
-      if (!fs.existsSync(vercelConfigPath)) {
+      const vercelProjectPath = path.join(outputPath, '.vercel', 'project.json');
+      if (!fs.existsSync(vercelProjectPath)) {
         spinner.stop();
         console.log(chalk.yellow('\n🚀 First time deploying to Vercel!\n'));
         
@@ -355,8 +372,8 @@ program
       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)) {
+      const vercelProjectPath = path.join(outputPath, '.vercel', 'project.json');
+      if (!fs.existsSync(vercelProjectPath)) {
         deploySpinner.stop();
         console.log(chalk.yellow('\n🚀 First time deploying to Vercel!\n'));
         

package/lib/deploy.js

@@ -49,34 +49,58 @@ async function setupVercelProject(config) {
     }
   ]);
   
-  // Create vercel.json if it doesn't exist
-  const vercelConfigPath = path.join(process.cwd(), 'vercel.json');
-  if (!fs.existsSync(vercelConfigPath)) {
-    const vercelConfig = {
-      outputDirectory: config.outputDir || 'html',
-      framework: null,  // Static HTML
-      buildCommand: "", // No build needed - we already built
-      devCommand: "",   // No dev command
-      installCommand: "", // No install needed
-      public: answers.publicAccess
-    };
-    
-    fs.writeJsonSync(vercelConfigPath, vercelConfig, { spaces: 2 });
-    console.log(chalk.green('✅ Created vercel.json'));
+  // Create vercel.json in the output directory
+  const outputDir = path.join(process.cwd(), config.outputDir || 'html');
+  const vercelConfigPath = path.join(outputDir, 'vercel.json');
+  
+  // Ensure output directory exists
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
   }
   
-  // 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'));
+  // Create vercel.json for static site
+  // Use empty string instead of false to avoid Vercel issues
+  const vercelConfig = {
+    buildCommand: "",
+    outputDirectory: ".",
+    installCommand: "",
+    framework: null
+  };
+  
+  fs.writeJsonSync(vercelConfigPath, vercelConfig, { spaces: 2 });
+  console.log(chalk.green(`✅ Created vercel.json in ${config.outputDir || 'html'} directory`));
+  
+  // Run Vercel setup with prominent instructions
+  console.log(chalk.blue('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+  console.log(chalk.blue('🔗 Linking to Vercel - IMPORTANT INSTRUCTIONS'));
+  console.log(chalk.blue('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'));
+  
+  console.log(chalk.yellow('⚠️  FOLLOW THESE ANSWERS CAREFULLY:\n'));
+  
+  console.log(chalk.white('1️⃣  ') + chalk.green('Set up "~/Documents/.../html"?'));
+  console.log(chalk.white('   👉 Answer: ') + chalk.yellow.bold('YES') + '\n');
+  
+  console.log(chalk.white('2️⃣  ') + chalk.green('Which scope should contain your project?'));
+  console.log(chalk.white('   👉 Answer: ') + chalk.yellow.bold('Select your account') + ' (usually your username)\n');
+  
+  console.log(chalk.white('3️⃣  ') + chalk.green('Found project "username/html". Link to it?'));
+  console.log(chalk.white('   👉 Answer: ') + chalk.red.bold('NO') + ' (this is NOT your project!)\n');
+  
+  console.log(chalk.white('4️⃣  ') + chalk.green('Link to different existing project?'));
+  console.log(chalk.white('   👉 Answer: ') + chalk.yellow.bold('YES') + ' if you have an existing project');
+  console.log(chalk.white('   👉 Answer: ') + chalk.yellow.bold('NO') + ' to create new project\n');
+  
+  console.log(chalk.white('5️⃣  ') + chalk.green('What\'s the name of your existing project?'));
+  console.log(chalk.white('   👉 Answer: ') + chalk.yellow.bold(answers.projectName) + ' (your actual project name)\n');
+  
+  console.log(chalk.blue('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'));
   
   try {
-    execSync('vercel link', { stdio: 'inherit' });
+    // Run vercel link from the output directory
+    execSync('vercel link', { 
+      stdio: 'inherit',
+      cwd: outputDir
+    });
   } catch (error) {
     console.error(chalk.red('Failed to link Vercel project'));
     process.exit(1);
@@ -84,11 +108,18 @@ async function setupVercelProject(config) {
   
   // Important reminders for Vercel settings
   console.log(chalk.yellow('\n⚠️  IMPORTANT: Vercel Project Settings\n'));
-  console.log(chalk.white('After deployment, go to your Vercel dashboard and:'));
-  console.log(chalk.gray('1. Navigate to Project Settings > General'));
-  console.log(chalk.gray('2. Under "Security", find "Deployment Protection"'));
-  console.log(chalk.gray('3. Set "Deployment Protection" to "Disabled" for public access'));
-  console.log(chalk.gray('4. Or configure authentication if you want to keep it private'));
+  console.log(chalk.white('After deployment, go to your Vercel dashboard:'));
+  console.log();
+  console.log(chalk.red.bold('🔴 CRITICAL: Check Root Directory Setting'));
+  console.log(chalk.white('1. Go to: ') + chalk.cyan(`https://vercel.com/${answers.projectName}/settings`));
+  console.log(chalk.white('2. Under "Build & Development Settings"'));
+  console.log(chalk.white('3. Make sure "Root Directory" is ') + chalk.yellow.bold('EMPTY or "./"'));
+  console.log(chalk.white('   (NOT "html" or any other directory)'));
+  console.log();
+  console.log(chalk.yellow('🔐 For Public Access:'));
+  console.log(chalk.white('1. Navigate to Project Settings > General'));
+  console.log(chalk.white('2. Under "Security", find "Deployment Protection"'));
+  console.log(chalk.white('3. Set "Deployment Protection" to ') + chalk.yellow.bold('Disabled'));
   console.log();
   console.log(chalk.cyan('Dashboard URL: https://vercel.com/dashboard'));
   console.log();
@@ -114,13 +145,38 @@ async function deployToVercel(config, isProd = false) {
     throw new Error(`Output directory ${outputPath} does not exist. Run 'doc-builder build' first.`);
   }
   
+  // Check for existing project link
+  const vercelProjectPath = path.join(outputPath, '.vercel', 'project.json');
+  if (fs.existsSync(vercelProjectPath)) {
+    try {
+      const projectInfo = fs.readJsonSync(vercelProjectPath);
+      console.log(chalk.yellow('\n⚠️  Deploying to existing project: ') + chalk.cyan(projectInfo.projectId || 'unknown'));
+      console.log(chalk.yellow('If deployment fails with path errors, check your Root Directory setting:'));
+      console.log(chalk.cyan(`https://vercel.com/dashboard/project/${projectInfo.projectId || 'settings'}\n`));
+    } catch (e) {
+      // Ignore read errors
+    }
+  }
+  
+  // Create vercel.json in output directory for deployment
+  const vercelConfigPath = path.join(outputPath, 'vercel.json');
+  if (!fs.existsSync(vercelConfigPath)) {
+    const vercelConfig = {
+      buildCommand: "",
+      outputDirectory: ".",
+      installCommand: "",
+      framework: null
+    };
+    fs.writeJsonSync(vercelConfigPath, vercelConfig, { spaces: 2 });
+  }
+  
   // Deploy command
   const deployCmd = isProd ? 'vercel --prod' : 'vercel';
   
   try {
-    // Run deployment and capture output
+    // Run deployment from the output directory
     const output = execSync(deployCmd, { 
-      cwd: process.cwd(),
+      cwd: outputPath,
       encoding: 'utf8'
     });
     

package/package.json

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