@knowcode/doc-builder 1.9.25 → 1.9.27

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.9.26] - 2025-08-10
+
+### Added
+- **Non-Printable Character Handling** - Automatically detects and skips files with non-printable ASCII characters (0x00-0x1F, 0x7F-0x9F) in their names
+- **Safe File Processing** - Prevents YAML parsing errors and build failures caused by malformed filenames
+- **Clear User Feedback** - Displays warning messages with sanitized filenames when problematic files are encountered
+- **Cross-Platform Compatibility** - Handles files with special characters from different operating systems
+
+### Fixed
+- **Build Failures** - Resolved "stream contains non-printable characters" YAML parsing errors during deployment
+- **File Scanning Issues** - Fixed crashes when encountering files with control characters or corrupted metadata
+- **Deployment Errors** - Eliminated deployment failures caused by problematic filenames in source directories
+
+### Technical
+- Added `hasNonPrintableChars()` function to detect problematic filenames
+- Added `sanitizeFilename()` function for safe display of problematic names
+- Updated all file scanning functions (`getAllMarkdownFiles`, `getAllAttachmentFiles`, `findHtmlFiles`)
+- Enhanced `fs.readdir` and `fs.readdirSync` operations with safety checks
+
 ## [1.9.18] - 2025-08-02
 
 ### Added

package/README.md

@@ -310,6 +310,23 @@ doc-builder automatically copies attachment files (Excel, PDF, images, etc.) to
 
 To disable attachment copying, use the `--no-attachments` flag with build or deploy commands.
 
+### 🛡️ File Safety & Non-Printable Character Handling
+
+doc-builder v1.9.26+ automatically handles files with non-printable characters in their names to prevent build failures:
+
+- **Automatic Detection**: Files with non-printable ASCII characters (0x00-0x1F, 0x7F-0x9F) are automatically detected
+- **Safe Processing**: Problematic files are skipped during scanning with a warning message
+- **Clear Feedback**: You'll see messages like: `⚠️ Skipping file with non-printable characters: [sanitized name]`
+- **Prevents Errors**: Eliminates YAML parsing errors and build failures caused by malformed filenames
+
+**Common scenarios this fixes**:
+- Files copied from certain operating systems with special characters
+- Documents exported from applications that add invisible control characters
+- Files with corruption in their metadata
+- Cross-platform compatibility issues
+
+This ensures your documentation builds successfully even when your source directory contains files with problematic names.
+
 ## 📋 Commands Overview
 
 <table>

package/cli.js

@@ -36,6 +36,7 @@ ${chalk.yellow('What it does:')}
   • Deploys to Vercel with one command (zero configuration)
   • ${chalk.green.bold('NEW:')} Shows help by default, use 'deploy' to publish (v1.3.0+)
   • Optional authentication to protect private documentation
+  • Handles files with non-printable characters safely (v1.9.26+)
 
 ${chalk.yellow('Requirements:')}
   • Node.js 14+ installed
@@ -87,6 +88,10 @@ ${chalk.yellow('Examples:')}
   ${chalk.gray('$')} doc-builder build --no-auth              ${chalk.gray('# Build public site without authentication')}
   ${chalk.gray('$')} doc-builder build --no-static            ${chalk.gray('# Skip static output generation')}
   ${chalk.gray('$')} doc-builder build --static-dir public    ${chalk.gray('# Use custom static output directory')}
+
+${chalk.yellow('File Safety:')}
+  Files with non-printable characters in their names are automatically skipped
+  to prevent build failures. You'll see warnings for any problematic files.
 `)
   .action(async (options) => {
     const spinner = ora('Building documentation...').start();
@@ -628,6 +633,10 @@ ${chalk.yellow('Examples:')}
   ${chalk.gray('$')} doc-builder deploy --no-prod       ${chalk.gray('# Deploy preview only')}
   ${chalk.gray('$')} doc-builder deploy --no-auth       ${chalk.gray('# Deploy public site without authentication')}
 
+${chalk.yellow('File Safety:')}
+  Files with non-printable characters are automatically skipped during deployment
+  to prevent YAML parsing errors. You'll see warnings for any problematic files.
+
 ${chalk.yellow('First-time Vercel Setup:')}
   
   ${chalk.cyan('1. Install Vercel CLI:')}

package/lib/core-builder.js

@@ -64,6 +64,19 @@ function escapeHtml(text) {
   return text.replace(/[&<>"']/g, m => map[m]);
 }
 
+// Helper function to check if filename contains non-printable characters
+function hasNonPrintableChars(filename) {
+  // Check for non-printable ASCII characters (0x00-0x1F, 0x7F-0x9F)
+  // Exclude common allowed control chars like tab (0x09), newline (0x0A), carriage return (0x0D)
+  return /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F-\x9F]/.test(filename);
+}
+
+// Helper function to sanitize filename for safe processing
+function sanitizeFilename(filename) {
+  // Remove non-printable characters
+  return filename.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F-\x9F]/g, '');
+}
+
 // Helper function to smartly capitalize text while preserving existing capitalization
 function smartCapitalize(text) {
   if (!text) return text;
@@ -1121,6 +1134,12 @@ async function getAllMarkdownFiles(dir, baseDir = dir, options = {}) {
   const items = await fs.readdir(dir);
   
   for (const item of items) {
+    // Skip files with non-printable characters in their names
+    if (hasNonPrintableChars(item)) {
+      console.log(chalk.yellow(`⚠️  Skipping file with non-printable characters: ${sanitizeFilename(item)}`));
+      continue;
+    }
+    
     const fullPath = path.join(dir, item);
     const stat = await fs.stat(fullPath);
     
@@ -1183,6 +1202,12 @@ async function getAllAttachmentFiles(dir, baseDir = dir, attachmentTypes) {
   const items = await fs.readdir(dir);
   
   for (const item of items) {
+    // Skip files with non-printable characters in their names
+    if (hasNonPrintableChars(item)) {
+      console.log(chalk.yellow(`⚠️  Skipping attachment with non-printable characters: ${sanitizeFilename(item)}`));
+      continue;
+    }
+    
     const fullPath = path.join(dir, item);
     const stat = await fs.stat(fullPath);
     
@@ -1307,7 +1332,8 @@ async function buildDocumentation(config) {
   
   // List all HTML files in output directory
   if (fs.existsSync(outputDir)) {
-    const htmlFiles = fs.readdirSync(outputDir).filter(f => f.endsWith('.html'));
+    const htmlFiles = fs.readdirSync(outputDir)
+      .filter(f => !hasNonPrintableChars(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!`));
@@ -1398,6 +1424,10 @@ async function buildDocumentation(config) {
     const walkDir = (dir, baseDir = '') => {
       const items = fs.readdirSync(dir);
       items.forEach(item => {
+        // Skip files with non-printable characters
+        if (hasNonPrintableChars(item)) {
+          return;
+        }
         const fullPath = path.join(dir, item);
         const stat = fs.statSync(fullPath);
         if (stat.isDirectory()) {
@@ -1548,6 +1578,10 @@ async function buildDocumentation(config) {
       const walkDir = (dir, baseDir = '') => {
         const items = fs.readdirSync(dir);
         items.forEach(item => {
+          // Skip files with non-printable characters
+          if (hasNonPrintableChars(item)) {
+            return;
+          }
           const fullPath = path.join(dir, item);
           const stat = fs.statSync(fullPath);
           if (stat.isDirectory()) {
@@ -1737,6 +1771,10 @@ async function createDefaultIndexPage(outputDir, config, version) {
   async function findHtmlFiles(dir, baseDir = dir) {
     const items = await fs.readdir(dir);
     for (const item of items) {
+      // Skip files with non-printable characters
+      if (hasNonPrintableChars(item)) {
+        continue;
+      }
       const fullPath = path.join(dir, item);
       const stat = await fs.stat(fullPath);
       if (stat.isDirectory() && !item.startsWith('.')) {

package/package.json

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