@knowcode/doc-builder 1.9.26 → 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/package.json

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