opendraft 1.6.16 → 1.6.17

package/README.md

@@ -1,6 +1,6 @@
 # OpenDraft
 
-AI-powered research paper draft generator.
+AI-powered research paper generator with verified citations.
 
 ## Quick Start
 
@@ -8,10 +8,12 @@ AI-powered research paper draft generator.
 npx opendraft
 ```
 
-That's it! The CLI will:
-1. Check if Python 3.9+ is installed
-2. Install the OpenDraft package if needed
-3. Launch the interactive paper generator
+That's it! The CLI will guide you through setup.
+
+## Requirements
+
+- **Node.js 14+** (for npx)
+- **Python 3.10+** (installed automatically on first run)
 
 ## Usage
 
@@ -20,37 +22,46 @@ That's it! The CLI will:
 npx opendraft
 
 # Quick generate
-npx opendraft "Impact of AI on Modern Education"
+npx opendraft "Your Research Topic"
 
 # With options
-npx opendraft "Your Topic" --level master --style apa
+npx opendraft "AI in Healthcare" --level master --lang en
 ```
 
 ## Options
 
-| Option | Values | Default |
-|--------|--------|---------|
-| `--level, -l` | research_paper, bachelor, master, phd | research_paper |
-| `--style, -s` | apa, mla, chicago, ieee | apa |
-| `--output, -o` | Directory path | ./opendraft_output |
+| Option | Description |
+|--------|-------------|
+| `--level` | Academic level: `research_paper`, `bachelor`, `master`, `phd` |
+| `--style` | Citation style: `apa`, `mla`, `chicago`, `ieee` |
+| `--lang` | Language: `en`, `de`, `es`, `fr`, `it`, `pt`, `zh`, `ja`, `ko`, `ru` |
+| `--author` | Your name (for cover page) |
+| `--institution` | University/institution name |
 
-## Requirements
+## Troubleshooting
+
+### Python Not Found
 
-- Node.js 16+ (for npx)
-- Python 3.9+ (installed automatically if missing guidance provided)
+If you see "Python not found", install Python 3.10+:
 
-## Features
+- **macOS**: `brew install python@3.11` or download from [python.org](https://python.org)
+- **Windows**: Download from [python.org](https://python.org) (check "Add to PATH")
+- **Linux**: `sudo apt install python3 python3-pip`
 
-- 19 specialized AI agents working together
-- Real citations from CrossRef, Semantic Scholar, arXiv
-- PDF and Word output
-- Multiple citation styles (APA, MLA, Chicago, IEEE)
+### Installation Failed
+
+Try installing the Python package manually:
+
+```bash
+pip install opendraft
+```
 
 ## Links
 
 - Website: https://opendraft.xyz
 - Documentation: https://opendraft.xyz/docs
 - GitHub: https://github.com/federicodeponte/opendraft
+- Issues: https://github.com/federicodeponte/opendraft/issues
 
 ## License
 

package/bin/opendraft.js

@@ -13,6 +13,7 @@ const { spawn, execSync } = require('child_process');
 const os = require('os');
 const path = require('path');
 
+// ANSI colors for terminal output
 const PURPLE = '\x1b[95m';
 const GREEN = '\x1b[92m';
 const YELLOW = '\x1b[93m';
@@ -26,6 +27,21 @@ function print(msg) {
   console.log(`  ${msg}`);
 }
 
+function printBox(lines, color = PURPLE) {
+  const maxLen = Math.max(...lines.map(l => l.replace(/\x1b\[[0-9;]*m/g, '').length));
+  const width = maxLen + 4;
+
+  console.log();
+  print(`${color}${'─'.repeat(width)}${RESET}`);
+  for (const line of lines) {
+    const cleanLen = line.replace(/\x1b\[[0-9;]*m/g, '').length;
+    const padding = ' '.repeat(maxLen - cleanLen);
+    print(`${color}│${RESET}  ${line}${padding}  ${color}│${RESET}`);
+  }
+  print(`${color}${'─'.repeat(width)}${RESET}`);
+  console.log();
+}
+
 function printLogo() {
   console.log(`
 ${PURPLE}${BOLD}  ╔══════════════════════════════════════════════════════════╗
@@ -50,8 +66,7 @@ ${PURPLE}${BOLD}  ╔═══════════════════
 function checkPython() {
   const home = os.homedir();
 
-  // Check Python commands - prefer stable versions (3.9-3.13), avoid dev versions (3.14+)
-  // Order matters: check specific stable versions first before generic python3
+  // Check Python commands - prefer stable versions (3.10-3.13)
   const pythonCommands = [
     // Homebrew (stable versions first)
     '/opt/homebrew/bin/python3.13',
@@ -75,7 +90,7 @@ function checkPython() {
     // pyenv
     `${home}/.pyenv/shims/python3`,
     `${home}/.pyenv/shims/python`,
-    // Generic (last resort - may pick dev versions)
+    // Generic
     'python3.13',
     'python3.12',
     'python3.11',
@@ -93,7 +108,7 @@ function checkPython() {
       if (match) {
         const major = parseInt(match[1]);
         const minor = parseInt(match[2]);
-        // Require Python 3.10-3.13 (3.9 lacks packages_distributions, 3.14+ is dev/unstable)
+        // Require Python 3.10-3.13
         if (major === 3 && minor >= 10 && minor <= 13) {
           return { cmd, version: `${major}.${minor}` };
         }
@@ -107,22 +122,38 @@ function checkPython() {
 
 function checkOpendraftInstalled(pythonCmd) {
   try {
-    execSync(`${pythonCmd} -c "import opendraft"`, { encoding: 'utf8', stdio: 'pipe' });
-    return true;
+    // Check specifically for opendraft.cli module (not just opendraft)
+    execSync(`${pythonCmd} -c "from opendraft.cli import main"`, {
+      encoding: 'utf8',
+      stdio: 'pipe'
+    });
+    return { installed: true, error: null };
   } catch (e) {
-    return false;
+    // Parse the error to give helpful feedback
+    const stderr = e.stderr || e.message || '';
+
+    if (stderr.includes('No module named')) {
+      return { installed: false, error: 'not_installed' };
+    } else if (stderr.includes('SyntaxError')) {
+      return { installed: false, error: 'syntax_error' };
+    } else if (stderr.includes('ImportError')) {
+      return { installed: false, error: 'import_error' };
+    }
+
+    return { installed: false, error: 'unknown', details: stderr };
   }
 }
 
 function installOpendraft(pythonCmd) {
-  print(`${CYAN}Installing OpenDraft...${RESET}`);
+  print(`${CYAN}Installing OpenDraft Python package...${RESET}`);
+  console.log();
 
   // Try pipx first (cleanest for CLI tools)
   try {
     execSync('which pipx', { encoding: 'utf8', stdio: 'pipe' });
-    print(`${GRAY}Using pipx...${RESET}`);
+    print(`${GRAY}Using pipx (recommended)...${RESET}`);
     execSync('pipx install opendraft', { encoding: 'utf8', stdio: 'inherit' });
-    return true;
+    return { success: true };
   } catch (e) {
     // pipx not available, try pip
   }
@@ -133,7 +164,7 @@ function installOpendraft(pythonCmd) {
       encoding: 'utf8',
       stdio: 'inherit'
     });
-    return true;
+    return { success: true };
   } catch (e) {
     // Try without --break-system-packages for older pip
   }
@@ -144,31 +175,183 @@ function installOpendraft(pythonCmd) {
       encoding: 'utf8',
       stdio: 'inherit'
     });
-    return true;
+    return { success: true };
   } catch (e) {
-    return false;
+    return {
+      success: false,
+      error: e.stderr || e.message || 'Unknown installation error'
+    };
   }
 }
 
 function runOpendraft(pythonCmd, args) {
-  // ALWAYS run via the verified Python to avoid version mismatches
-  // This ensures we use Python 3.10+ that was checked earlier
+  // Run via the verified Python to avoid version mismatches
   const script = `
 import sys
 sys.argv = ['opendraft'] + ${JSON.stringify(args)}
 from opendraft.cli import main
 main()
 `;
+
   const proc = spawn(pythonCmd, ['-c', script], {
     stdio: 'inherit',
     env: process.env
   });
 
+  proc.on('error', (err) => {
+    showFriendlyError('run_failed', {
+      pythonCmd,
+      error: err.message
+    });
+    process.exit(1);
+  });
+
   proc.on('close', (code) => {
-    process.exit(code);
+    process.exit(code || 0);
   });
 }
 
+function showFriendlyError(errorType, details = {}) {
+  console.log();
+
+  switch (errorType) {
+    case 'no_python':
+      printBox([
+        `${RED}${BOLD}Python Not Found${RESET}`,
+        ``,
+        `OpenDraft needs Python 3.10 or higher to run.`,
+        ``,
+        `${BOLD}To fix this:${RESET}`,
+      ], RED);
+
+      const platform = os.platform();
+      if (platform === 'darwin') {
+        print(`${BOLD}Option 1: Download from python.org (easiest)${RESET}`);
+        print(`  1. Go to ${CYAN}https://python.org/downloads${RESET}`);
+        print(`  2. Click the yellow "Download Python" button`);
+        print(`  3. Run the installer`);
+        print(`  4. Try ${CYAN}npx opendraft${RESET} again`);
+        console.log();
+        print(`${BOLD}Option 2: Use Homebrew${RESET}`);
+        print(`  ${CYAN}brew install python@3.11${RESET}`);
+      } else if (platform === 'win32') {
+        print(`${BOLD}Download Python:${RESET}`);
+        print(`  1. Go to ${CYAN}https://python.org/downloads${RESET}`);
+        print(`  2. Click "Download Python"`);
+        print(`  3. ${YELLOW}IMPORTANT: Check "Add Python to PATH"${RESET}`);
+        print(`  4. Run the installer`);
+        print(`  5. ${BOLD}Restart your terminal${RESET}`);
+        print(`  6. Try ${CYAN}npx opendraft${RESET} again`);
+      } else {
+        print(`${BOLD}Install Python:${RESET}`);
+        print(`  ${CYAN}sudo apt install python3 python3-pip${RESET}  (Ubuntu/Debian)`);
+        print(`  ${CYAN}sudo dnf install python3 python3-pip${RESET}  (Fedora)`);
+        print(`  ${CYAN}sudo pacman -S python python-pip${RESET}      (Arch)`);
+      }
+      break;
+
+    case 'install_failed':
+      printBox([
+        `${RED}${BOLD}Installation Failed${RESET}`,
+        ``,
+        `We couldn't install the OpenDraft Python package.`,
+      ], RED);
+
+      print(`${BOLD}Try these fixes:${RESET}`);
+      console.log();
+      print(`${BOLD}1. Install manually with pip:${RESET}`);
+      print(`   ${CYAN}pip install opendraft${RESET}`);
+      console.log();
+      print(`${BOLD}2. If that fails, try with sudo (Linux/Mac):${RESET}`);
+      print(`   ${CYAN}sudo pip install opendraft${RESET}`);
+      console.log();
+      print(`${BOLD}3. Or use pipx (recommended for CLI tools):${RESET}`);
+      print(`   ${CYAN}brew install pipx && pipx install opendraft${RESET}`);
+      console.log();
+
+      if (details.error) {
+        print(`${GRAY}Technical details: ${details.error.substring(0, 200)}${RESET}`);
+      }
+      break;
+
+    case 'module_not_found':
+      printBox([
+        `${RED}${BOLD}OpenDraft Package Issue${RESET}`,
+        ``,
+        `Python is installed, but the OpenDraft package`,
+        `is missing or incomplete.`,
+      ], RED);
+
+      print(`${BOLD}To fix this, reinstall the package:${RESET}`);
+      console.log();
+      print(`  ${CYAN}pip uninstall opendraft -y${RESET}`);
+      print(`  ${CYAN}pip install opendraft${RESET}`);
+      console.log();
+      print(`Then try again: ${CYAN}npx opendraft${RESET}`);
+      console.log();
+
+      print(`${GRAY}If the problem persists, you may need to upgrade pip:${RESET}`);
+      print(`  ${CYAN}pip install --upgrade pip${RESET}`);
+      break;
+
+    case 'import_error':
+      printBox([
+        `${RED}${BOLD}Missing Dependencies${RESET}`,
+        ``,
+        `OpenDraft is installed but some required`,
+        `Python packages are missing.`,
+      ], RED);
+
+      print(`${BOLD}To fix this:${RESET}`);
+      console.log();
+      print(`  ${CYAN}pip install --upgrade opendraft${RESET}`);
+      console.log();
+      print(`This will install all required dependencies.`);
+      console.log();
+      print(`Then try again: ${CYAN}npx opendraft${RESET}`);
+      break;
+
+    case 'run_failed':
+      printBox([
+        `${RED}${BOLD}Failed to Start${RESET}`,
+        ``,
+        `Something went wrong while starting OpenDraft.`,
+      ], RED);
+
+      print(`${BOLD}Try these steps:${RESET}`);
+      console.log();
+      print(`1. Reinstall the package:`);
+      print(`   ${CYAN}pip install --upgrade --force-reinstall opendraft${RESET}`);
+      console.log();
+      print(`2. If using a virtual environment, make sure it's activated`);
+      console.log();
+      print(`3. Check Python version (need 3.10+):`);
+      print(`   ${CYAN}python3 --version${RESET}`);
+      console.log();
+
+      if (details.error) {
+        print(`${GRAY}Error: ${details.error}${RESET}`);
+      }
+      break;
+
+    default:
+      printBox([
+        `${RED}${BOLD}Something Went Wrong${RESET}`,
+        ``,
+        `An unexpected error occurred.`,
+      ], RED);
+
+      print(`${BOLD}Please try:${RESET}`);
+      print(`  ${CYAN}pip install --upgrade opendraft${RESET}`);
+      print(`  ${CYAN}npx opendraft${RESET}`);
+      console.log();
+      print(`${BOLD}Still having issues?${RESET}`);
+      print(`  Report at: ${CYAN}https://github.com/federicodeponte/opendraft/issues${RESET}`);
+  }
+
+  console.log();
+}
+
 function hasHomebrew() {
   try {
     execSync('which brew', { encoding: 'utf8', stdio: 'pipe' });
@@ -193,78 +376,39 @@ function askQuestion(question) {
   });
 }
 
-async function installPythonWithHomebrew() {
-  print(`${CYAN}Installing Python 3.11 via Homebrew...${RESET}`);
-  print(`${GRAY}This may take a few minutes.${RESET}`);
-  console.log();
-
-  try {
-    execSync('brew install python@3.11', { stdio: 'inherit' });
-    print(`${GREEN}✓${RESET} Python installed successfully!`);
-    return true;
-  } catch (e) {
-    print(`${RED}✗${RESET} Installation failed`);
-    return false;
-  }
-}
-
-async function showInstallInstructions() {
-  console.log();
-  print(`${YELLOW}Python 3.10+ is needed to run OpenDraft.${RESET}`);
-  console.log();
-
+async function offerPythonInstall() {
   const platform = os.platform();
 
   if (platform === 'darwin' && hasHomebrew()) {
-    // macOS with Homebrew - offer auto-install
-    print(`Good news! We can install Python automatically.`);
+    console.log();
+    print(`${GREEN}Good news!${RESET} We can install Python automatically.`);
     console.log();
 
-    const answer = await askQuestion(`  Install Python now? (Y/n): `);
+    const answer = await askQuestion(`  Install Python 3.11 now? (Y/n): `);
 
     if (answer === '' || answer === 'y' || answer === 'yes') {
       console.log();
-      const success = await installPythonWithHomebrew();
-      if (success) {
+      print(`${CYAN}Installing Python 3.11 via Homebrew...${RESET}`);
+      print(`${GRAY}This may take a few minutes.${RESET}`);
+      console.log();
+
+      try {
+        execSync('brew install python@3.11', { stdio: 'inherit' });
         console.log();
-        print(`${GREEN}Ready!${RESET} Run this command again:`);
-        print(`  ${CYAN}npx opendraft${RESET}`);
+        print(`${GREEN}${BOLD}Success!${RESET} Python is now installed.`);
         console.log();
-        return;
+        print(`Run this command again: ${CYAN}npx opendraft${RESET}`);
+        console.log();
+        return true;
+      } catch (e) {
+        console.log();
+        print(`${RED}Installation failed.${RESET} Please install manually.`);
+        return false;
       }
     }
-
-    // User declined or install failed
-    console.log();
-    print(`To install manually:`);
-    print(`  ${CYAN}brew install python@3.11${RESET}`);
-
-  } else if (platform === 'darwin') {
-    // macOS without Homebrew
-    print(`Download Python from:`);
-    console.log();
-    print(`  ${CYAN}https://python.org/downloads${RESET}`);
-    console.log();
-    print(`${GRAY}(Click the big yellow "Download Python" button)${RESET}`);
-
-  } else if (platform === 'win32') {
-    print(`${BOLD}Download Python:${RESET}`);
-    console.log();
-    print(`  ${CYAN}https://python.org/downloads${RESET}`);
-    console.log();
-    print(`  ${YELLOW}Important:${RESET} Check "Add Python to PATH" during install!`);
-
-  } else {
-    // Linux
-    print(`${BOLD}Install with your package manager:${RESET}`);
-    console.log();
-    print(`  ${CYAN}sudo apt install python3 python3-pip${RESET}  (Ubuntu/Debian)`);
-    print(`  ${CYAN}sudo dnf install python3 python3-pip${RESET}  (Fedora)`);
   }
 
-  console.log();
-  print(`Then run: ${CYAN}npx opendraft${RESET}`);
-  console.log();
+  return false;
 }
 
 async function main() {
@@ -299,14 +443,14 @@ async function main() {
     console.log();
     print(`${BOLD}Examples:${RESET}`);
     print(`  ${CYAN}npx opendraft "AI in Healthcare" --level master${RESET}`);
-    print(`  ${CYAN}npx opendraft "Climate Change" --lang de --author "Max Müller"${RESET}`);
+    print(`  ${CYAN}npx opendraft "Climate Change" --lang de --author "Max Muller"${RESET}`);
     console.log();
     print(`${GRAY}https://opendraft.xyz/docs${RESET}`);
     console.log();
     return;
   }
 
-  // Show logo immediately so user knows something is happening
+  // Show logo immediately
   printLogo();
   print(`${GRAY}Checking environment...${RESET}`);
 
@@ -314,42 +458,81 @@ async function main() {
   const python = checkPython();
 
   if (!python) {
-    await showInstallInstructions();
-    process.exit(1);
+    showFriendlyError('no_python');
+
+    // Offer to install automatically on macOS with Homebrew
+    const installed = await offerPythonInstall();
+    if (!installed) {
+      process.exit(1);
+    }
+
+    // Re-check Python after installation
+    const pythonAfter = checkPython();
+    if (!pythonAfter) {
+      print(`${RED}Python still not found.${RESET} Please restart your terminal and try again.`);
+      process.exit(1);
+    }
+    return;
   }
 
   print(`${GREEN}✓${RESET} Python ${python.version} found`);
 
   // Handle --install
   if (args.includes('--install')) {
-    print(`${GRAY}Installing OpenDraft...${RESET}`);
-    if (installOpendraft(python.cmd)) {
-      print(`${GREEN}✓${RESET} OpenDraft installed successfully`);
+    const result = installOpendraft(python.cmd);
+    if (result.success) {
+      console.log();
+      print(`${GREEN}${BOLD}Success!${RESET} OpenDraft is ready.`);
       console.log();
       print(`Run: ${CYAN}npx opendraft${RESET}`);
+      console.log();
     } else {
-      print(`${RED}✗${RESET} Installation failed`);
+      showFriendlyError('install_failed', { error: result.error });
       process.exit(1);
     }
-    console.log();
     return;
   }
 
   // Check if opendraft is installed
-  if (!checkOpendraftInstalled(python.cmd)) {
-    print(`${YELLOW}First time setup - installing OpenDraft...${RESET}`);
-    if (!installOpendraft(python.cmd)) {
-      print(`${RED}✗${RESET} Failed to install OpenDraft`);
+  const installCheck = checkOpendraftInstalled(python.cmd);
+
+  if (!installCheck.installed) {
+    if (installCheck.error === 'not_installed') {
+      print(`${YELLOW}First-time setup${RESET} - installing OpenDraft...`);
+      console.log();
+
+      const result = installOpendraft(python.cmd);
+
+      if (!result.success) {
+        showFriendlyError('install_failed', { error: result.error });
+        process.exit(1);
+      }
+
+      print(`${GREEN}✓${RESET} OpenDraft installed`);
+
+      // Verify installation worked
+      const verifyCheck = checkOpendraftInstalled(python.cmd);
+      if (!verifyCheck.installed) {
+        showFriendlyError('module_not_found');
+        process.exit(1);
+      }
+    } else if (installCheck.error === 'import_error') {
+      showFriendlyError('import_error');
+      process.exit(1);
+    } else {
+      showFriendlyError('module_not_found');
       process.exit(1);
     }
-    print(`${GREEN}✓${RESET} OpenDraft installed`);
   }
 
+  print(`${GREEN}✓${RESET} OpenDraft ready`);
+  console.log();
+
   // Run opendraft
   runOpendraft(python.cmd, args);
 }
 
 main().catch((err) => {
-  console.error(err);
+  showFriendlyError('unknown', { error: err.message });
   process.exit(1);
 });

package/package.json

@@ -1,31 +1,31 @@
 {
   "name": "opendraft",
-  "version": "1.6.16",
-  "description": "AI-powered research paper draft generator",
+  "version": "1.6.17",
+  "description": "AI-powered research paper generator with verified citations",
   "bin": {
-    "opendraft": "./bin/opendraft.js"
-  },
-  "scripts": {
-    "test": "node bin/opendraft.js --version"
+    "opendraft": "bin/opendraft.js"
   },
   "keywords": [
     "research",
     "paper",
     "thesis",
-    "academic",
     "ai",
+    "academic",
     "writing",
     "citations",
     "generator"
   ],
-  "author": "OpenDraft Team",
+  "author": "Federico De Ponte",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/federicodeponte/opendraft.git"
+    "url": "git+https://github.com/federicodeponte/opendraft.git"
+  },
+  "bugs": {
+    "url": "https://github.com/federicodeponte/opendraft/issues"
   },
   "homepage": "https://opendraft.xyz",
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=14.0.0"
   }
 }