doc-fetch-cli 1.1.1 → 1.1.3

package/INSTALLATION-FIX.md

@@ -0,0 +1,242 @@
+# DocFetch CLI Installation Fix
+
+**Issue**: "Binary not found" error when installing via NPM  
+**Date**: February 20, 2026  
+**Fixed in**: v1.1.2  
+
+---
+
+## 🐛 **Problem Analysis**
+
+### **Symptom 1: "Binary not found" error**
+```bash
+$ npm install -g doc-fetch-cli
+❌ doc-fetch binary not found!
+```
+
+**Root Cause**: The postinstall script wasn't copying the platform-specific binary to the expected location.
+
+### **Symptom 2: Command name confusion**
+```bash
+$ npm install -g doc-fetch-cli
+$ doc-fetch-cli --help    # ❌ Doesn't work
+$ doc-fetch --help        # ✅ Works
+```
+
+**This is actually CORRECT behavior!** Here's why:
+
+In NPM packages:
+- **Package name** (`doc-fetch-cli`): What you install
+- **Bin command** (`doc-fetch`): What you run
+
+This is standard practice. Examples:
+- `npm install -g nodemon` → run `nodemon`
+- `npm install -g typescript` → run `tsc`
+- `npm install -g doc-fetch-cli` → run `doc-fetch`
+
+---
+
+## 🔧 **What Was Fixed**
+
+### **Fix 1: Improved Binary Detection**
+
+Updated `bin/doc-fetch.js` to:
+- ✅ Try multiple possible binary locations
+- ✅ Detect platform and architecture correctly
+- ✅ Provide helpful error messages with troubleshooting steps
+- ✅ Support Linux (amd64/arm64), macOS, Windows
+
+**Before**:
+```javascript
+const binaryPath = path.join(__dirname, '..', 'doc-fetch');
+// Only checked one location, failed if binary wasn't there
+```
+
+**After**:
+```javascript
+const possiblePaths = [
+  path.join(packageDir, binaryName),        // Root directory
+  path.join(packageDir, 'bin', binaryName), // bin/ directory
+  // ... fallbacks
+];
+
+// Tries each location until found
+```
+
+### **Fix 2: Proper Postinstall Script**
+
+Updated `bin/postinstall.js` to:
+- ✅ Copy the correct platform-specific binary
+- ✅ Set executable permissions
+- ✅ Verify the binary works
+- ✅ Provide clear error messages if binary is missing
+
+**Key logic**:
+```javascript
+// Determine which binary to use for this platform
+if (platform === 'linux') {
+  expectedBinary = 'doc-fetch_linux_amd64';
+} else if (platform === 'darwin') {
+  expectedBinary = 'doc-fetch_darwin_amd64';
+}
+
+// Copy to expected location
+fs.copyFileSync(sourcePath, destPath);
+```
+
+### **Fix 3: Added .npmignore**
+
+Created `.npmignore` to ensure all necessary files are included in the NPM package:
+- ✅ Go binaries for all platforms
+- ✅ Bin wrapper scripts
+- ✅ Postinstall script
+- ❌ Excludes: source code, Python files, test files
+
+---
+
+## 📦 **How to Test the Fix**
+
+### **Clean Install Test**
+```bash
+# Uninstall completely
+npm uninstall -g doc-fetch-cli
+
+# Clear npm cache
+npm cache clean --force
+
+# Install fresh
+npm install -g doc-fetch-cli@latest
+
+# Test (note: command is 'doc-fetch' not 'doc-fetch-cli')
+doc-fetch --help
+```
+
+### **Expected Output**
+```
+🎉 DocFetch CLI installing...
+
+📦 Platform: linux x64
+📦 Expected binary: doc-fetch_linux_amd64
+
+✅ Binary installed: doc-fetch
+✅ Binary verified working
+
+✨ DocFetch CLI installed successfully!
+
+Usage:
+   doc-fetch --url https://docs.example.com --output docs.md
+
+Pro tip: Use --llm-txt flag to generate AI-friendly index files!
+```
+
+---
+
+## 🎯 **Platform Support**
+
+| Platform | Architecture | Binary Name | Status |
+|----------|-------------|-------------|--------|
+| Linux | x64 (amd64) | doc-fetch_linux_amd64 | ✅ Supported |
+| Linux | ARM64 | doc-fetch_linux_arm64 | ⚠️ Coming soon |
+| macOS | x64 (amd64) | doc-fetch_darwin_amd64 | ✅ Supported |
+| macOS | ARM64 (M1/M2) | doc-fetch_darwin_arm64 | ⚠️ Coming soon |
+| Windows | x64 (amd64) | doc-fetch_windows_amd64.exe | ✅ Supported |
+
+---
+
+## 🐛 **Troubleshooting**
+
+### **Error: "Binary not found"**
+
+**Solution 1**: Reinstall
+```bash
+npm uninstall -g doc-fetch-cli
+npm install -g doc-fetch-cli
+```
+
+**Solution 2**: Check what was installed
+```bash
+ls -la $(npm root -g)/doc-fetch-cli/
+```
+
+You should see:
+```
+-rwxr-xr-x  doc-fetch              # ← The actual binary
+-rwxr-xr-x  doc-fetch_linux_amd64  # ← Platform-specific binary
+drwxr-xr-x  bin/                   # ← Contains doc-fetch.js wrapper
+```
+
+**Solution 3**: Manual installation
+```bash
+# Download binary directly
+wget https://github.com/AlphaTechini/doc-fetch/releases/download/v1.1.1/doc-fetch_linux_amd64
+chmod +x doc-fetch_linux_amd64
+sudo mv doc-fetch_linux_amd64 /usr/local/bin/doc-fetch
+```
+
+### **Error: "Command not found: doc-fetch-cli"**
+
+**This is expected!** The command is `doc-fetch`, not `doc-fetch-cli`.
+
+```bash
+# Wrong ❌
+doc-fetch-cli --help
+
+# Correct ✅
+doc-fetch --help
+```
+
+### **Error: "Permission denied"**
+
+**Solution**: Fix permissions
+```bash
+# Find installation directory
+DOC_FETCH_DIR=$(npm root -g)/doc-fetch-cli
+
+# Fix permissions
+chmod +x $DOC_FETCH_DIR/doc-fetch
+chmod +x $DOC_FETCH_DIR/bin/doc-fetch.js
+```
+
+---
+
+## 📝 **For Future Releases**
+
+### **Publishing Checklist**
+
+1. Build all platform binaries:
+   ```bash
+   GOOS=linux GOARCH=amd64 go build -o doc-fetch_linux_amd64 ./cmd
+   GOOS=darwin GOARCH=amd64 go build -o doc-fetch_darwin_amd64 ./cmd
+   GOOS=windows GOARCH=amd64 go build -o doc-fetch_windows_amd64.exe ./cmd
+   ```
+
+2. Verify `.npmignore` includes:
+   - ✅ All platform binaries
+   - ✅ `bin/` directory
+   - ✅ `package.json` with correct `bin` field
+
+3. Test installation locally:
+   ```bash
+   npm pack                    # Create tarball
+   npm install -g ./doc-fetch-cli-*.tgz  # Install locally
+   doc-fetch --help            # Test
+   ```
+
+4. Publish:
+   ```bash
+   npm publish
+   ```
+
+---
+
+## 🔗 **Related Issues**
+
+- GitHub Issue: [#XX](https://github.com/AlphaTechini/doc-fetch/issues/XX)
+- NPM Package: https://www.npmjs.com/package/doc-fetch-cli
+- Documentation: https://github.com/AlphaTechini/doc-fetch/blob/main/README.md
+
+---
+
+**Last Updated**: February 20, 2026  
+**Version**: 1.1.2  
+**Status**: ✅ Fixed and tested

package/bin/doc-fetch.js

@@ -2,16 +2,51 @@
 const { spawn } = require('child_process');
 const path = require('path');
 const os = require('os');
+const fs = require('fs');
 
-// Determine binary path based on platform
-const binDir = path.join(__dirname, '..');
-const binaryName = os.platform() === 'win32' ? 'doc-fetch.exe' : 'doc-fetch';
-const binaryPath = path.join(binDir, binaryName);
+// Get the package installation directory
+const packageDir = path.join(__dirname, '..');
 
-// Check if binary exists
-if (!require('fs').existsSync(binaryPath)) {
+// Determine binary name based on platform
+const platform = os.platform();
+const arch = os.arch();
+let binaryName;
+
+if (platform === 'win32') {
+  binaryName = 'doc-fetch.exe';
+} else if (platform === 'darwin') {
+  binaryName = 'doc-fetch_darwin_amd64';
+} else {
+  // Linux and others
+  binaryName = arch === 'arm64' ? 'doc-fetch_linux_arm64' : 'doc-fetch_linux_amd64';
+}
+
+// Try multiple possible locations
+const possiblePaths = [
+  path.join(packageDir, binaryName),                    // Root directory
+  path.join(packageDir, 'bin', binaryName),             // bin/ directory  
+  path.join(packageDir, binaryName.replace('_linux_amd64', '')), // Fallback to generic name
+];
+
+// Find the binary
+let binaryPath = null;
+for (const testPath of possiblePaths) {
+  if (fs.existsSync(testPath)) {
+    binaryPath = testPath;
+    break;
+  }
+}
+
+if (!binaryPath) {
   console.error('❌ doc-fetch binary not found!');
-  console.error('💡 Please run: npm install doc-fetch');
+  console.error('');
+  console.error('💡 Troubleshooting steps:');
+  console.error('   1. Reinstall: npm uninstall -g doc-fetch-cli && npm install -g doc-fetch-cli');
+  console.error('   2. Check installation: ls -la $(npm root -g)/doc-fetch-cli/');
+  console.error('   3. Report issue: https://github.com/AlphaTechini/doc-fetch/issues');
+  console.error('');
+  console.error(`   Expected binary: ${possiblePaths[0]}`);
+  console.error(`   Platform: ${platform} ${arch}`);
   process.exit(1);
 }
 
@@ -24,8 +59,11 @@ const child = spawn(binaryPath, args, {
 
 child.on('error', (err) => {
   if (err.code === 'ENOENT') {
-    console.error('❌ doc-fetch binary not found!');
-    console.error('💡 Please run: npm install doc-fetch');
+    console.error('❌ Failed to execute doc-fetch binary');
+    console.error(`   Binary path: ${binaryPath}`);
+    console.error('   Error: Binary file may be corrupted or missing execute permissions');
+    console.error('');
+    console.error('💡 Try reinstalling: npm uninstall -g doc-fetch-cli && npm install -g doc-fetch-cli');
   } else {
     console.error('❌ Failed to start doc-fetch:', err.message);
   }

package/bin/postinstall.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * Post-install script for doc-fetch-cli
- * Checks if global bin directory is in PATH and provides helpful instructions
+ * Copies the correct platform-specific binary and sets up PATH
  */
 
 const { execSync } = require('child_process');
@@ -9,75 +9,119 @@ const path = require('path');
 const os = require('os');
 const fs = require('fs');
 
-console.log('🎉 DocFetch CLI installed successfully!\n');
+console.log('🎉 DocFetch CLI installing...\n');
 
-// Get npm global prefix
-let globalPrefix;
+const packageDir = path.join(__dirname, '..');
+const platform = os.platform();
+const arch = os.arch();
+
+// Determine which binary to use
+let binaryName;
+let expectedBinary;
+
+if (platform === 'win32') {
+  binaryName = 'doc-fetch.exe';
+  expectedBinary = 'doc-fetch_windows_amd64.exe';
+} else if (platform === 'darwin') {
+  binaryName = 'doc-fetch';
+  expectedBinary = 'doc-fetch_darwin_amd64';
+} else {
+  // Linux
+  binaryName = 'doc-fetch';
+  expectedBinary = arch === 'arm64' ? 'doc-fetch_linux_arm64' : 'doc-fetch_linux_amd64';
+}
+
+const sourcePath = path.join(packageDir, expectedBinary);
+const destPath = path.join(packageDir, binaryName);
+
+console.log(`📦 Platform: ${platform} ${arch}`);
+console.log(`📦 Expected binary: ${expectedBinary}`);
+console.log(`📦 Will copy to: ${binaryName}\n`);
+
+// Check if the expected binary exists
+if (!fs.existsSync(sourcePath)) {
+  console.error(`⚠️  CRITICAL: Expected binary not found at: ${sourcePath}`);
+  console.error('');
+  console.error('💡 Listing package contents:');
+  try {
+    const files = fs.readdirSync(packageDir);
+    files.forEach(file => {
+      if (file.includes('doc-fetch')) {
+        console.error(`   📄 ${file}`);
+      }
+    });
+  } catch (e) {
+    console.error(`   Could not list directory: ${e.message}`);
+  }
+  console.error('');
+  console.error('💡 This might be because:');
+  console.error('   1. The package was published without binaries');
+  console.error('   2. Your platform/architecture is not supported');
+  console.error('');
+  console.error('Supported platforms:');
+  console.error('   - Linux x64 (amd64)');
+  console.error('   - macOS x64 (amd64)');  
+  console.error('   - Windows x64 (amd64)');
+  console.error('');
+  console.error('💡 Workaround: Install from source');
+  console.error('   npm uninstall -g doc-fetch-cli');
+  console.error('   git clone https://github.com/AlphaTechini/doc-fetch.git');
+  console.error('   cd doc-fetch && go build -o doc-fetch ./cmd/docfetch');
+  if (platform === 'win32') {
+    console.error('   copy doc-fetch.exe %APPDATA%\\npm\\node_modules\\doc-fetch-cli\\');
+  } else {
+    console.error('   sudo cp doc-fetch /usr/local/bin/');
+  }
+  process.exit(1);
+}
+
+console.log(`✅ Found source binary: ${expectedBinary}`);
+
+// Copy the binary to the expected location
 try {
-    globalPrefix = execSync('npm config get prefix', { encoding: 'utf8' }).trim();
+  console.log(`📋 Copying: ${expectedBinary} → ${binaryName}`);
+  fs.copyFileSync(sourcePath, destPath);
+  console.log(`✅ Copy successful`);
+  
+  // Verify the destination exists
+  if (!fs.existsSync(destPath)) {
+    throw new Error('Destination file does not exist after copy');
+  }
+  
+  // Make executable on Unix-like systems
+  if (platform !== 'win32') {
+    fs.chmodSync(destPath, 0o755);
+    console.log(`✅ Set executable permissions`);
+  } else {
+    console.log(`ℹ️  Windows: No chmod needed`);
+  }
+  
+  console.log(`\n✅ Binary installed: ${binaryName}`);
 } catch (error) {
-    console.error('⚠️  Could not determine npm global prefix');
-    globalPrefix = null;
+  console.error(`\n❌ CRITICAL: Failed to install binary!`);
+  console.error(`   Source: ${sourcePath}`);
+  console.error(`   Destination: ${destPath}`);
+  console.error(`   Error: ${error.message}`);
+  console.error('');
+  console.error('💡 Manual fix:');
+  console.error(`   1. Navigate to: ${packageDir}`);
+  console.error(`   2. Rename: ${expectedBinary} → ${binaryName}`);
+  if (platform !== 'win32') {
+    console.error(`   3. Run: chmod +x ${binaryName}`);
+  }
+  process.exit(1);
 }
 
-if (globalPrefix) {
-    const binDir = path.join(globalPrefix, 'bin');
-    const isWindows = os.platform() === 'win32';
-    
-    console.log(`📦 Installed to: ${binDir}\n`);
-    
-    // Check if bin directory is in PATH
-    const pathEnv = process.env.PATH || '';
-    const pathDirs = pathEnv.split(isWindows ? ';' : ':');
-    const isInPath = pathDirs.some(dir => path.resolve(dir) === path.resolve(binDir));
-    
-    if (!isInPath) {
-        console.log('⚠️  WARNING: Global bin directory is not in your PATH!\n');
-        console.log('To use doc-fetch-cli, add this directory to your PATH:\n');
-        console.log(`   ${binDir}\n`);
-        
-        // Provide platform-specific instructions
-        const shell = process.env.SHELL || '/bin/bash';
-        const isZsh = shell.includes('zsh');
-        const isBash = shell.includes('bash');
-        
-        console.log('Quick fix:\n');
-        
-        if (isWindows) {
-            console.log('1. Open System Properties → Environment Variables');
-            console.log('2. Edit PATH variable');
-            console.log('3. Add this path:');
-            console.log(`   ${binDir}`);
-            console.log('4. Restart your terminal\n');
-        } else if (isZsh) {
-            console.log('Add this to your ~/.zshrc:');
-            console.log(`   export PATH="${binDir}:$PATH"\n`);
-            console.log('Then run: source ~/.zshrc\n');
-        } else if (isBash) {
-            console.log('Add this to your ~/.bashrc or ~/.bash_profile:');
-            console.log(`   export PATH="${binDir}:$PATH"\n`);
-            console.log('Then run: source ~/.bashrc\n');
-        }
-        
-        console.log('Alternative: Use npx without installing globally\n');
-        console.log('   npx doc-fetch-cli --url https://docs.example.com --output docs.md\n');
-    } else {
-        console.log('✅ Global bin directory is in your PATH\n');
-        console.log('You can now use doc-fetch-cli!\n');
-        console.log('Example usage:');
-        console.log('   doc-fetch --url https://docs.python.org/3 --output docs.md --llm-txt\n');
-        
-        // Test if the command works
-        try {
-            execSync('doc-fetch --version', { encoding: 'utf8', stdio: 'pipe' });
-            console.log('✅ Command verified working!\n');
-        } catch (error) {
-            console.log('⚠️  Command not found in current shell session.\n');
-            console.log('Try running: hash -r  (to clear command cache)\n');
-            console.log('Or restart your terminal.\n');
-        }
-    }
+// Verify installation
+try {
+  const result = execSync(`"${destPath}" --help`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] });
+  console.log('✅ Binary verified working\n');
+} catch (error) {
+  console.error('⚠️  Warning: Could not verify binary execution');
+  console.error(`   Error: ${error.message}\n`);
 }
 
-console.log('📚 Documentation: https://github.com/AlphaTechini/doc-fetch\n');
-console.log('✨ Pro tip: Use --llm-txt flag to generate AI-friendly index files!\n');
+console.log('✨ DocFetch CLI installed successfully!\n');
+console.log('Usage:');
+console.log('   doc-fetch --url https://docs.example.com --output docs.md\n');
+console.log('Pro tip: Use --llm-txt flag to generate AI-friendly index files!\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doc-fetch-cli",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Dynamic documentation fetching CLI that converts entire documentation sites to single markdown files for AI/LLM consumption",
   "bin": {
     "doc-fetch": "./bin/doc-fetch.js"
@@ -12,7 +12,14 @@
     "type": "git",
     "url": "https://github.com/AlphaTechini/doc-fetch.git"
   },
-  "keywords": ["documentation", "ai", "llm", "markdown", "crawler", "security"],
+  "keywords": [
+    "documentation",
+    "ai",
+    "llm",
+    "markdown",
+    "crawler",
+    "security"
+  ],
   "author": "AlphaTechini",
   "license": "MIT"
-}
+}