@knowcode/doc-builder 1.2.8 → 1.2.10

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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.2.10] - 2025-07-19
+
+### Fixed
+- **Critical fix**: Now properly replaces old directory listing index.html files
+- Detects and replaces index.html if it's under 3KB (likely a directory listing)
+- Detects and replaces index.html if it doesn't contain doc-builder markers
+- Fixes the issue where gasworld.vercel.app showed a directory listing instead of documentation
+
+### Added
+- Smart detection of outdated or non-doc-builder index.html files
+- Automatic replacement of directory listing pages with proper documentation
+- Clear logging when replacing an existing index.html file
+
+## [1.2.9] - 2025-07-19
+
+### Added
+- Comprehensive console logging for debugging index.html creation
+- Detailed file existence checks with paths and sizes
+- File copy verification with size comparison
+- List of HTML files found during build and deployment
+- Error handling with detailed error messages
+- Final verification step to confirm index.html exists
+
+### Improved
+- Much more verbose output to help diagnose deployment issues
+- Clear indication of what files are being processed
+- Better error reporting when file operations fail
+
 ## [1.2.8] - 2025-07-19
 
 ### Changed

package/lib/core-builder.js

@@ -460,6 +460,14 @@ async function buildDocumentation(config) {
   const files = await getAllMarkdownFiles(docsDir);
   console.log(chalk.green(`✅ Found ${files.length} markdown files${readmeGenerated ? ' (including auto-generated README)' : ''}`));
   
+  // Log the files found
+  if (files.length > 0) {
+    console.log(chalk.gray('  Found files:'));
+    files.forEach(file => {
+      console.log(chalk.gray(`  - ${file.relativePath} → ${file.urlPath}`));
+    });
+  }
+  
   console.log(chalk.blue('📝 Processing files...'));
   for (const file of files) {
     const outputPath = path.join(outputDir, file.urlPath);
@@ -499,23 +507,91 @@ async function buildDocumentation(config) {
   const indexSourcePath = path.join(outputDir, 'index.html'); // from index.md
   const readmePath = path.join(outputDir, 'README.html');
   
-  console.log(chalk.blue('📄 Checking for index.html creation...'));
-  console.log(chalk.gray(`  - index.html exists: ${fs.existsSync(indexPath)})`));
-  console.log(chalk.gray(`  - README.html exists: ${fs.existsSync(readmePath)})`));
+  console.log(chalk.blue('\n📄 Checking for index.html creation...'));
+  console.log(chalk.gray(`  - Output directory: ${outputDir}`));
+  console.log(chalk.gray(`  - Index path: ${indexPath}`));
+  console.log(chalk.gray(`  - README path: ${readmePath}`));
+  console.log(chalk.gray(`  - index.html exists: ${fs.existsSync(indexPath)}`));
+  console.log(chalk.gray(`  - README.html exists: ${fs.existsSync(readmePath)}`));
+  
+  // List all HTML files in output directory
+  if (fs.existsSync(outputDir)) {
+    const htmlFiles = fs.readdirSync(outputDir).filter(f => f.endsWith('.html'));
+    console.log(chalk.gray(`  - HTML files in output: [${htmlFiles.join(', ')}]`));
+  } else {
+    console.log(chalk.red(`  - ERROR: Output directory does not exist!`));
+  }
+  
+  // Check if we need to create/replace index.html
+  let shouldCreateIndex = false;
   
   if (!fs.existsSync(indexPath)) {
+    console.log(chalk.yellow('⚠️  index.html does not exist, need to create it'));
+    shouldCreateIndex = true;
+  } else {
+    // Check if existing index.html is likely a directory listing or outdated
+    const indexStats = fs.statSync(indexPath);
+    const indexContent = fs.readFileSync(indexPath, 'utf8');
+    
+    // Check if it's a small file (likely directory listing) or contains directory listing markers
+    if (indexStats.size < 3000 || indexContent.includes('<title>Documentation</title>') && indexContent.includes('<ul>') && !indexContent.includes('class="navigation"')) {
+      console.log(chalk.yellow('⚠️  Existing index.html appears to be a directory listing (size: ' + indexStats.size + ' bytes), will replace it'));
+      shouldCreateIndex = true;
+    } else if (!indexContent.includes('@knowcode/doc-builder')) {
+      console.log(chalk.yellow('⚠️  Existing index.html was not created by doc-builder, will replace it'));
+      shouldCreateIndex = true;
+    }
+  }
+  
+  if (shouldCreateIndex) {
     if (fs.existsSync(readmePath)) {
-      await fs.copy(readmePath, indexPath);
-      console.log(chalk.green('✅ Created index.html from README.html'));
+      console.log(chalk.blue('  → Found README.html, copying to index.html'));
+      try {
+        await fs.copy(readmePath, indexPath);
+        console.log(chalk.green('✅ Successfully created index.html from README.html'));
+        
+        // Verify the copy worked
+        if (fs.existsSync(indexPath)) {
+          const stats = fs.statSync(indexPath);
+          console.log(chalk.gray(`  - index.html size: ${stats.size} bytes`));
+        } else {
+          console.log(chalk.red('  - ERROR: index.html was not created!'));
+        }
+      } catch (error) {
+        console.log(chalk.red(`  - ERROR copying README.html: ${error.message}`));
+      }
     } else {
       // No README.html, create informative default page
       console.log(chalk.yellow('⚠️  No README.html found, creating default index.html'));
-      const defaultIndex = await createDefaultIndexPage(outputDir, config, packageJson.version);
-      await fs.writeFile(indexPath, defaultIndex);
-      console.log(chalk.green('✅ Created default index.html with instructions'));
+      try {
+        const defaultIndex = await createDefaultIndexPage(outputDir, config, packageJson.version);
+        await fs.writeFile(indexPath, defaultIndex);
+        console.log(chalk.green('✅ Created default index.html with instructions'));
+        
+        // Verify the write worked
+        if (fs.existsSync(indexPath)) {
+          const stats = fs.statSync(indexPath);
+          console.log(chalk.gray(`  - index.html size: ${stats.size} bytes`));
+        } else {
+          console.log(chalk.red('  - ERROR: default index.html was not created!'));
+        }
+      } catch (error) {
+        console.log(chalk.red(`  - ERROR creating default index.html: ${error.message}`));
+      }
     }
   } else {
-    console.log(chalk.gray('ℹ️  index.html already exists (likely from index.md)'));
+    console.log(chalk.gray('ℹ️  index.html already exists and appears valid'));
+    const stats = fs.statSync(indexPath);
+    console.log(chalk.gray(`  - Existing index.html size: ${stats.size} bytes`));
+    console.log(chalk.gray(`  - Keeping existing index.html (likely from index.md or custom page)`));
+  }
+  
+  // Final verification
+  console.log(chalk.blue('\n📋 Final index.html check:'));
+  if (fs.existsSync(indexPath)) {
+    console.log(chalk.green(`  ✅ index.html exists at: ${indexPath}`));
+  } else {
+    console.log(chalk.red(`  ❌ index.html is MISSING at: ${indexPath}`));
   }
   
   console.log(chalk.green('✅ Documentation build complete!'));

package/lib/deploy.js

@@ -346,17 +346,73 @@ async function prepareDeployment(config) {
   console.log(chalk.blue(`\n📦 Preparing deployment with @knowcode/doc-builder v${packageJson.version}`));
   
   // Create index.html from README.html if needed
+  console.log(chalk.blue('\n📁 Deployment preparation - index.html check:'));
   const indexPath = path.join(outputDir, 'index.html');
-  console.log(chalk.gray(`  - Checking index.html: ${fs.existsSync(indexPath) ? 'exists' : 'missing'}}`));
+  const readmePath = path.join(outputDir, 'README.html');
+  
+  console.log(chalk.gray(`  - Output directory: ${outputDir}`));
+  console.log(chalk.gray(`  - Output dir exists: ${fs.existsSync(outputDir)}`));
+  
+  if (fs.existsSync(outputDir)) {
+    const files = fs.readdirSync(outputDir);
+    const htmlFiles = files.filter(f => f.endsWith('.html'));
+    console.log(chalk.gray(`  - Total files: ${files.length}`));
+    console.log(chalk.gray(`  - HTML files: [${htmlFiles.slice(0, 5).join(', ')}${htmlFiles.length > 5 ? '...' : ''}]`));
+  }
+  
+  console.log(chalk.gray(`  - Checking index.html: ${fs.existsSync(indexPath) ? 'exists' : 'missing'}`));
+  console.log(chalk.gray(`  - Index path: ${indexPath}`));
+  
+  // Check if we need to create/replace index.html
+  let shouldCreateIndex = false;
   
   if (!fs.existsSync(indexPath)) {
-    const readmePath = path.join(outputDir, 'README.html');
-    console.log(chalk.gray(`  - Checking README.html: ${fs.existsSync(readmePath) ? 'exists' : 'missing'}}`));
+    console.log(chalk.yellow('  ⚠️  index.html is missing, attempting to create...'));
+    shouldCreateIndex = true;
+  } else {
+    // Check if existing index.html needs replacement
+    const indexStats = fs.statSync(indexPath);
+    const indexContent = fs.readFileSync(indexPath, 'utf8');
+    
+    if (indexStats.size < 3000 || (indexContent.includes('<title>Documentation</title>') && indexContent.includes('<ul>') && !indexContent.includes('class="navigation"'))) {
+      console.log(chalk.yellow(`  ⚠️  Existing index.html appears to be a directory listing (${indexStats.size} bytes), will replace`));
+      shouldCreateIndex = true;
+    } else if (!indexContent.includes('@knowcode/doc-builder')) {
+      console.log(chalk.yellow('  ⚠️  Existing index.html was not created by doc-builder, will replace'));
+      shouldCreateIndex = true;
+    }
+  }
+  
+  if (shouldCreateIndex) {
+    console.log(chalk.gray(`  - Checking README.html: ${fs.existsSync(readmePath) ? 'exists' : 'missing'}`));
+    console.log(chalk.gray(`  - README path: ${readmePath}`));
     
     if (fs.existsSync(readmePath)) {
       // Copy README.html to index.html for proper root page
-      fs.copyFileSync(readmePath, indexPath);
-      console.log(chalk.green('✅ Created index.html from README.html'));
+      console.log(chalk.blue('  → Copying README.html to index.html...'));
+      try {
+        fs.copyFileSync(readmePath, indexPath);
+        console.log(chalk.green('  ✅ Successfully copied README.html to index.html'));
+        
+        // Verify the copy
+        if (fs.existsSync(indexPath)) {
+          const readmeStats = fs.statSync(readmePath);
+          const indexStats = fs.statSync(indexPath);
+          console.log(chalk.gray(`  - README.html size: ${readmeStats.size} bytes`));
+          console.log(chalk.gray(`  - index.html size: ${indexStats.size} bytes`));
+          
+          if (readmeStats.size === indexStats.size) {
+            console.log(chalk.green('  ✅ File sizes match - copy successful'));
+          } else {
+            console.log(chalk.yellow('  ⚠️  File sizes do not match!'));
+          }
+        } else {
+          console.log(chalk.red('  ❌ ERROR: index.html was not created after copy!'));
+        }
+      } catch (error) {
+        console.log(chalk.red(`  ❌ ERROR copying file: ${error.message}`));
+        console.log(chalk.red(`  - Error stack: ${error.stack}`));
+      }
     } else {
       // If no README.html, find first available HTML file or create informative page
       console.log(chalk.yellow('⚠️  No README.html found, looking for other HTML files...'));
@@ -403,16 +459,31 @@ async function prepareDeployment(config) {
       }
     }
   } else {
-    console.log(chalk.gray('  ✓ index.html already exists'));
+    console.log(chalk.gray('  ✓ index.html already exists and appears valid'));
+    const stats = fs.statSync(indexPath);
+    console.log(chalk.gray(`  - Keeping existing index.html (${stats.size} bytes)`));
   }
   
   // Final check - log what files exist
   console.log(chalk.blue('\n📁 Final deployment state:'));
+  
+  // Double-check index.html one more time
+  const finalIndexExists = fs.existsSync(indexPath);
+  console.log(chalk[finalIndexExists ? 'green' : 'red'](`  - index.html: ${finalIndexExists ? 'EXISTS' : 'MISSING'}`));
+  
+  if (finalIndexExists) {
+    const stats = fs.statSync(indexPath);
+    console.log(chalk.gray(`  - index.html size: ${stats.size} bytes`));
+    console.log(chalk.gray(`  - index.html modified: ${stats.mtime.toISOString()}`));
+  }
+  
   const finalFiles = fs.readdirSync(outputDir)
     .filter(file => file.endsWith('.html'))
     .slice(0, 5); // Show first 5 HTML files
+  console.log(chalk.gray(`\n  HTML files in ${outputDir}:`));
   finalFiles.forEach(file => {
-    console.log(chalk.gray(`  - ${file}`));
+    const size = fs.statSync(path.join(outputDir, file)).size;
+    console.log(chalk.gray(`  - ${file} (${size} bytes)`));
   });
   if (fs.readdirSync(outputDir).filter(f => f.endsWith('.html')).length > 5) {
     console.log(chalk.gray(`  - ... and ${fs.readdirSync(outputDir).filter(f => f.endsWith('.html')).length - 5} more HTML files`));

package/package.json

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