beth-copilot 1.0.12 → 1.0.14

package/CHANGELOG.md

@@ -6,6 +6,53 @@ All notable changes to Beth are documented here. Format based on [Keep a Changel
 
 ---
 
+## [1.0.14] - 2026-02-04
+
+### Changed
+- **User-friendly error messages** — CLI errors now display formatted boxes with clear problem descriptions, fix instructions, and the exact command to run. No more raw stack traces.
+
+---
+
+## [1.0.13] - 2026-02-04
+
+### Fixed
+- **ENOTDIR crash during init** — Fixed `copyDirRecursive` crashing when destination path exists as a file instead of a directory. Now properly detects the conflict and provides a clear error message (or removes the file with `--force`).
+
+---
+
+## [Unreleased]
+
+### Added
+- **CLI TypeScript foundation** — Migrated CLI to TypeScript with proper build system
+- **Doctor command** — `beth doctor` validates installation and configuration
+- **Quickstart command** — `beth quickstart` for guided setup
+- **Agent schema types** — TypeScript types for agent definitions
+- **Unit tests** — 86 tests passing for CLI commands and path validation
+- **Architecture diagrams** — Interactive mermaid diagrams with zoom in README
+
+### Changed
+- **DEMO.md** — Rewritten with Beth's personality and beads integration
+- **P2 backlog completed** — Beth orchestrator references added to all agents, MCP skills updated, documentation fixes
+
+### Fixed
+- Removed unnecessary backlog.md CLI dependency
+- Fixed security-reviewer.agent.md syntax errors
+- Corrected agent/skill counts in help output
+- Allowlisted security documentation examples in Gitleaks config
+
+### Documentation
+- CLI Architecture guide (docs/CLI-ARCHITECTURE.md)
+- CLI Implementation Plan (docs/CLI-IMPLEMENTATION-PLAN.md)
+
+---
+
+## [1.0.12] - 2026-02-01
+
+### Changed
+- Added CHANGELOG.md to npm package
+
+---
+
 ## [1.0.11] - 2026-02-01
 
 ### Changed

package/README.md

@@ -80,44 +80,119 @@ Beth's team comes equipped:
 
 She doesn't micromanage. She delegates to specialists and holds them accountable.
 
-```
-Your Request
-     │
-     ▼
-┌─────────────────────────────────────────┐
-│               @Beth                      │
-│   "I don't need permission to be me."   │
-│                                          │
-│   • Analyzes your request               │
-│   • Picks the right people              │
-│   • Runs parallel ops when smart        │
-│   • Delivers results, not excuses       │
-└─────────────────────────────────────────┘
-     │
-     ├──▶ @product-manager (strategy)
-     ├──▶ @researcher (intelligence)  
-     ├──▶ @ux-designer (design)
-     ├──▶ @developer (implementation)
-     ├──▶ @tester (quality gate)
-     └──▶ @security-reviewer (protection)
+### Architecture
+
+```mermaid
+flowchart TB
+    subgraph User["👤 User"]
+        Request[User Request]
+    end
+
+    subgraph Orchestrator["🎯 Beth - The Orchestrator"]
+        Beth["@Beth<br/><i>'I don't speak dipshit'</i>"]
+        Assess[Assess Request]
+        Plan[Plan Workflow]
+        Route[Route to Specialists]
+    end
+
+    subgraph Agents["🧑‍💼 Specialist Agents"]
+        PM["@product-manager<br/>WHAT to build"]
+        Researcher["@researcher<br/>User/Market Intel"]
+        Designer["@ux-designer<br/>HOW it works"]
+        Developer["@developer<br/>Implementation"]
+        Security["@security-reviewer<br/>Protection"]
+        Tester["@tester<br/>Quality Gate"]
+    end
+
+    Request --> Beth
+    Beth --> Assess --> Plan --> Route
+    
+    Route --> PM
+    Route --> Researcher
+    Route --> Designer
+    Route --> Developer
+    Route --> Security
+    Route --> Tester
+
+    style Beth fill:#1e3a5f,color:#fff
+    style Orchestrator fill:#f0f4f8
+    style Agents fill:#f8f4f0
 ```
 
 ### The Workflow
 
-**New Feature?**
-```
-Request → Product (requirements) → Research (validation) → Design (interface) 
-       → Developer (build) → Security (review) → Tester (QA)
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant B as Beth
+    participant PM as Product Manager
+    participant UX as UX Designer
+    participant D as Developer
+    participant S as Security
+    participant T as Tester
+
+    U->>B: "Build me a feature"
+    B->>B: Assess & Plan
+    B->>PM: Define requirements
+    PM-->>B: Requirements ready
+    B->>UX: Design the experience
+    UX-->>B: Design specs ready
+    B->>D: Implement feature
+    D-->>B: Implementation complete
+    B->>S: Security review
+    S-->>B: Security approved
+    B->>T: Test & verify
+    T-->>B: Quality verified
+    B->>U: Feature complete ✅
 ```
 
-**Bug Hunt?**
-```
-Report → Tester (reproduce) → Developer (fix) → Security (verify) → Tester (confirm)
-```
-
-**Security Audit?**
-```
-Concern → Security (threat model) → Developer (remediation) → Tester (penetration)
+**Bug Hunt?** Tester → Developer → Security → Tester  
+**Security Audit?** Security → Developer → Tester → Security
+
+### Agent Delegation
+
+```mermaid
+flowchart TB
+    subgraph Beth["Beth (Orchestrator)"]
+        BethCore["Routes all work<br/>Spawns subagents"]
+    end
+
+    subgraph PM["Product Manager"]
+        PMCore["Requirements<br/>Priorities"]
+    end
+
+    subgraph R["Researcher"]
+        RCore["User insights<br/>Market intel"]
+    end
+
+    subgraph UX["UX Designer"]
+        UXCore["Component specs<br/>Design tokens"]
+    end
+
+    subgraph D["Developer"]
+        DCore["React/TS/Next.js<br/>Implementation"]
+    end
+
+    subgraph S["Security"]
+        SCore["Threat modeling<br/>Vulnerabilities"]
+    end
+
+    subgraph T["Tester"]
+        TCore["QA & a11y<br/>Performance"]
+    end
+
+    BethCore -->|"Product Strategy"| PMCore
+    BethCore -->|"User Research"| RCore
+    BethCore -->|"UX Design"| UXCore
+    BethCore -->|"Development"| DCore
+    BethCore -->|"Security Review"| SCore
+    BethCore -->|"Quality Assurance"| TCore
+
+    PMCore -.->|"subagent"| RCore
+    PMCore -.->|"subagent"| UXCore
+    UXCore -.->|"subagent"| DCore
+    DCore -.->|"subagent"| TCore
+    SCore -.->|"subagent"| DCore
 ```
 
 ## Quick Commands
@@ -174,6 +249,38 @@ Beth operates on a few principles:
 3. **Move fast, break enemies** — Parallel execution, aggressive timelines.
 4. **Loyalty earns trust** — Agents that perform get the good work.
 
+### IDEO Design Thinking
+
+Beth follows human-centered design methodology:
+
+```mermaid
+flowchart LR
+    subgraph Empathize["1. Empathize"]
+        E["@researcher<br/>User interviews<br/>Pain points"]
+    end
+
+    subgraph Define["2. Define"]
+        D["@product-manager<br/>Problem framing<br/>Requirements"]
+    end
+
+    subgraph Ideate["3. Ideate"]
+        I["@ux-designer<br/>Component specs<br/>Patterns"]
+    end
+
+    subgraph Prototype["4. Prototype"]
+        P["@developer<br/>Build to learn<br/>Feature spikes"]
+    end
+
+    subgraph Test["5. Test"]
+        T["@tester<br/>Validate<br/>Accessibility"]
+    end
+
+    E --> D --> I --> P --> T
+    T -.->|iterate| E
+    T -.->|iterate| D
+    T -.->|iterate| I
+```
+
 ## Quality Standards
 
 Beth doesn't ship garbage:
@@ -184,6 +291,39 @@ Beth doesn't ship garbage:
 - **Type Safety**: Full TypeScript coverage. No `any` unless you want a lecture.
 - **Test Coverage**: Unit, integration, E2E. If it's not tested, it's not done.
 
+```mermaid
+flowchart TB
+    subgraph Standards["Quality Standards"]
+        A11y["WCAG 2.1 AA<br/>Accessibility"]
+        Perf["Core Web Vitals<br/>LCP < 2.5s"]
+        Sec["OWASP Compliant<br/>Zero vulnerabilities"]
+        Type["Full TypeScript<br/>No any"]
+        Coverage["Test Coverage<br/>Unit + Integration + E2E"]
+    end
+
+    subgraph Gates["Enforcement"]
+        Designer["UX Designer<br/>reviews a11y specs"]
+        Developer["Developer<br/>implements patterns"]
+        Security["Security Reviewer<br/>audits code"]
+        Tester["Tester<br/>verifies all gates"]
+    end
+
+    A11y --> Designer
+    Perf --> Developer
+    Sec --> Security
+    Type --> Developer
+    Coverage --> Tester
+
+    Designer --> Ship{Ship?}
+    Developer --> Ship
+    Security --> Ship
+    Tester --> Ship
+
+    Ship -->|All Pass| Deploy["🚀 Deploy"]
+    Ship -->|Fail| Fix["🔧 Fix & Retry"]
+    Fix --> Gates
+```
+
 ## Why Beth?
 
 <p align="center">
@@ -225,6 +365,7 @@ Full details: [docs/MCP-SETUP.md](docs/MCP-SETUP.md)
 
 - [Installation Guide](docs/INSTALLATION.md) — Full setup instructions
 - [MCP Setup](docs/MCP-SETUP.md) — Optional server integrations
+- [System Flow & Diagrams](docs/SYSTEM-FLOW.md) — Architecture and agent orchestration diagrams
 - [Changelog](CHANGELOG.md) — Version history and updates
 - [Security Policy](SECURITY.md) — Vulnerability reporting
 

package/bin/cli.js

@@ -2,16 +2,29 @@
 
 import { fileURLToPath } from 'url';
 import { dirname, join, relative } from 'path';
-import { existsSync, mkdirSync, readdirSync, statSync, copyFileSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readdirSync, statSync, copyFileSync, readFileSync, writeFileSync, unlinkSync } from 'fs';
 import { createRequire } from 'module';
 import { execSync, spawn } from 'child_process';
-import { validateBeadsPath, validateBacklogPath, validateBinaryPath } from './lib/pathValidation.js';
+import { validateBeadsPath, validateBinaryPath } from './lib/pathValidation.js';
 
 const require = createRequire(import.meta.url);
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const TEMPLATES_DIR = join(__dirname, '..', 'templates');
 
+// TypeScript commands are in dist/ after build
+const DIST_DIR = join(__dirname, '..', 'dist');
+
+// Dynamic import for TypeScript commands (lazy loaded)
+async function loadTsCommand(commandName) {
+  const commandPath = join(DIST_DIR, 'cli', 'commands', `${commandName}.js`);
+  if (!existsSync(commandPath)) {
+    console.error(`Command '${commandName}' not found. Run 'npm run build' first.`);
+    process.exit(1);
+  }
+  return import(commandPath);
+}
+
 // Get current package version
 const packageJson = require('../package.json');
 const CURRENT_VERSION = packageJson.version;
@@ -396,6 +409,54 @@ function logError(message) {
   log(`✗ ${message}`, COLORS.red);
 }
 
+/**
+ * User-facing error with actionable fix instructions
+ */
+class UserError extends Error {
+  constructor(message, { problem, fix, command } = {}) {
+    super(message);
+    this.name = 'UserError';
+    this.problem = problem;
+    this.fix = fix;
+    this.command = command;
+  }
+}
+
+/**
+ * Display a user-friendly error with fix instructions
+ */
+function showUserError(error) {
+  console.log('');
+  console.log(`${COLORS.red}╔════════════════════════════════════════════════════════════╗${COLORS.reset}`);
+  console.log(`${COLORS.red}║${COLORS.reset}  ${COLORS.bright}${COLORS.red}Installation Error${COLORS.reset}                                       ${COLORS.red}║${COLORS.reset}`);
+  console.log(`${COLORS.red}╚════════════════════════════════════════════════════════════╝${COLORS.reset}`);
+  console.log('');
+  
+  if (error.problem) {
+    console.log(`${COLORS.bright}Problem:${COLORS.reset}`);
+    console.log(`  ${error.problem}`);
+    console.log('');
+  }
+  
+  if (error.fix) {
+    console.log(`${COLORS.bright}Fix:${COLORS.reset}`);
+    console.log(`  ${error.fix}`);
+    console.log('');
+  }
+  
+  if (error.command) {
+    console.log(`${COLORS.bright}Run this command:${COLORS.reset}`);
+    console.log(`  ${COLORS.cyan}${error.command}${COLORS.reset}`);
+    console.log('');
+  }
+  
+  if (globalThis.VERBOSE) {
+    console.log(`${COLORS.dim}Stack trace:${COLORS.reset}`);
+    console.log(`${COLORS.dim}${error.stack}${COLORS.reset}`);
+    console.log('');
+  }
+}
+
 function logInfo(message) {
   log(`  ${message}`, COLORS.cyan);
 }
@@ -457,48 +518,6 @@ async function checkForUpdates() {
   }
 }
 
-function getBacklogPath() {
-  // Check if backlog is available in PATH
-  try {
-    logDebug('Checking if backlog is in PATH...');
-    execSync('backlog --version', { stdio: 'ignore' });
-    logDebug('Found backlog in PATH');
-    return 'backlog';
-  } catch {
-    logDebug('backlog not in PATH, checking common locations...');
-    // Check common installation paths
-    const homeDir = process.env.HOME || process.env.USERPROFILE || '';
-    const isWindows = process.platform === 'win32';
-    
-    const commonPaths = isWindows ? [
-      join(process.env.APPDATA || '', 'npm', 'backlog.cmd'),
-      join(homeDir, 'AppData', 'Roaming', 'npm', 'backlog.cmd'),
-      join(homeDir, 'AppData', 'Local', 'npm-global', 'backlog.cmd'),
-    ] : [
-      join(homeDir, '.local', 'bin', 'backlog'),
-      join(homeDir, 'bin', 'backlog'),
-      '/usr/local/bin/backlog',
-      join(homeDir, '.npm-global', 'bin', 'backlog'),
-      join(homeDir, '.bun', 'bin', 'backlog'),
-    ];
-    
-    for (const backlogPath of commonPaths) {
-      logDebug(`Checking: ${backlogPath}`);
-      if (existsSync(backlogPath)) {
-        logDebug(`Found at: ${backlogPath}`);
-        return backlogPath;
-      }
-    }
-    
-    logDebug('backlog not found in any common location');
-    return null;
-  }
-}
-
-function isBacklogCliInstalled() {
-  return getBacklogPath() !== null;
-}
-
 function getBeadsPath() {
   // Check if bd is available in PATH
   try {
@@ -582,79 +601,6 @@ async function promptForInput(question) {
   });
 }
 
-/**
- * Installs the backlog.md CLI globally via npm.
- * 
- * SECURITY NOTE - shell:true usage:
- * - Required for cross-platform npm execution (npm.cmd on Windows, npm on Unix)
- * - Arguments are HARDCODED - no user input is passed to the shell
- * - Command injection risk: NONE (no dynamic/user-supplied values)
- * 
- * Alternative considered: Using platform-specific binary names (npm.cmd vs npm)
- * would eliminate shell:true but adds complexity and edge cases for non-standard installs.
- * 
- * @returns {Promise<boolean>} True if installation succeeded and was verified
- */
-async function installBacklogCli() {
-  const isWindows = process.platform === 'win32';
-  const isMac = process.platform === 'darwin';
-  
-  log('\nInstalling backlog.md CLI via npm...', COLORS.cyan);
-  logInfo('npm install -g backlog.md');
-  
-  // SECURITY: shell:true is required for cross-platform npm execution.
-  // All arguments are hardcoded constants - no user input reaches the shell.
-  return new Promise((resolve) => {
-    const child = spawn('npm', ['install', '-g', 'backlog.md'], {
-      stdio: 'inherit',
-      shell: true
-    });
-    
-    child.on('close', (code) => {
-      if (code === 0) {
-        // CRITICAL: Verify installation actually worked before claiming success
-        const verifiedPath = getBacklogPath();
-        if (verifiedPath) {
-          logSuccess('backlog.md CLI installed and verified!');
-          resolve(true);
-        } else {
-          logWarning('npm reported success but backlog CLI not found in PATH.');
-          logInfo('This can happen if npm global bin is not in your PATH.');
-          if (globalThis.VERBOSE) {
-            showPathDiagnostics();
-          } else {
-            logInfo('Run with --verbose for PATH diagnostics.');
-          }
-          console.log('');
-          showBacklogAlternatives(isMac);
-          resolve(false);
-        }
-      } else {
-        logError('npm install failed.');
-        console.log('');
-        showBacklogAlternatives(isMac);
-        resolve(false);
-      }
-    });
-    
-    child.on('error', () => {
-      logError('Failed to run npm.');
-      logInfo('Make sure npm is installed and in your PATH.');
-      resolve(false);
-    });
-  });
-}
-
-function showBacklogAlternatives(isMac) {
-  logInfo('Alternative installation methods:');
-  if (isMac) {
-    logInfo('  Homebrew: brew install backlog-md');
-  }
-  logInfo('  Bun:      bun install -g backlog.md');
-  logInfo('');
-  logInfo('Learn more: https://github.com/MrLesk/Backlog.md');
-}
-
 /**
  * Installs the beads CLI globally via npm.
  * 
@@ -793,6 +739,8 @@ function showHelp() {
 
 ${COLORS.bright}Usage:${COLORS.reset}
   npx beth-copilot init [options]     Initialize Beth in current directory
+  npx beth-copilot doctor             Check system health and dependencies
+  npx beth-copilot quickstart         Run init + doctor + beads setup
   npx beth-copilot help               Show this help message
 
 ${COLORS.bright}Options:${COLORS.reset}
@@ -805,10 +753,11 @@ ${COLORS.bright}Options:${COLORS.reset}
 ${COLORS.bright}Examples:${COLORS.reset}
   npx beth-copilot init               Set up Beth in current project
   npx beth-copilot init --force       Overwrite existing Beth files
+  npx beth-copilot doctor             Verify installation health
 
 ${COLORS.bright}What gets installed:${COLORS.reset}
-  .github/agents/                     8 specialized AI agents
-  .github/skills/                     6 domain knowledge modules
+  .github/agents/                     7 specialized AI agents
+  .github/skills/                     8 domain knowledge modules
   .github/copilot-instructions.md     Copilot configuration
   .vscode/settings.json               Recommended VS Code settings
   AGENTS.md                           Workflow documentation
@@ -828,7 +777,26 @@ ${COLORS.bright}Documentation:${COLORS.reset}
 function copyDirRecursive(src, dest, options = {}) {
   const { force = false, copiedFiles = [] } = options;
   
-  if (!existsSync(dest)) {
+  if (existsSync(dest)) {
+    const destStats = statSync(dest);
+    if (!destStats.isDirectory()) {
+      if (force) {
+        // Destination exists as a file but should be a directory - remove it
+        unlinkSync(dest);
+        mkdirSync(dest, { recursive: true });
+      } else {
+        const relativePath = relative(process.cwd(), dest);
+        throw new UserError(
+          `Path conflict: ${relativePath}`,
+          {
+            problem: `"${relativePath}" exists as a file, but Beth needs it to be a directory.`,
+            fix: 'Either remove the file manually, or use --force to let Beth handle it.',
+            command: 'npx beth-copilot@latest init --force'
+          }
+        );
+      }
+    }
+  } else {
     mkdirSync(dest, { recursive: true });
   }
 
@@ -1080,87 +1048,17 @@ ${COLORS.yellow}╔════════════════════
     logWarning('Skipped beads check (--skip-beads). Beth may not function correctly.');
   }
 
-  // Check for backlog.md CLI (REQUIRED for Beth)
-  if (!skipBacklog) {
-    console.log('');
-    log('Checking backlog.md CLI (required for task management)...', COLORS.cyan);
-    
-    let backlogPath = getBacklogPath();
-    
-    // Loop until backlog.md is installed
-    while (!backlogPath) {
-      logWarning('backlog.md CLI is not installed.');
-      logInfo('Beth requires backlog.md for human-readable task tracking and boards.');
-      logInfo('Learn more: https://github.com/MrLesk/Backlog.md');
-      console.log('');
-      
-      const shouldInstall = await promptYesNo('Install backlog.md CLI now? (required)');
-      if (shouldInstall) {
-        const installed = await installBacklogCli();
-        if (installed) {
-          // Re-check for backlog after installation
-          backlogPath = getBacklogPath();
-          if (!backlogPath) {
-            console.log('');
-            logWarning('backlog.md installed but not found in common paths.');
-            logInfo('The installer may have placed it in a custom location.');
-            console.log('');
-            logInfo('Please try one of these options:');
-            logInfo('  1. Open a NEW terminal and run: npx beth-copilot init');
-            logInfo('  2. Run: source ~/.bashrc (or ~/.zshrc) then retry');
-            console.log('');
-            
-            const retryCheck = await promptYesNo('Retry detection?');
-            if (retryCheck) {
-              backlogPath = getBacklogPath();
-            }
-          }
-        } else {
-          console.log('');
-          logError('Installation failed.');
-          logInfo('You can try installing manually:');
-          logInfo('  npm install -g backlog.md');
-          if (process.platform === 'darwin') {
-            logInfo('  brew install backlog-md');
-          }
-          logInfo('  bun install -g backlog.md');
-          console.log('');
-        }
-      } else {
-        console.log('');
-        logError('backlog.md is REQUIRED for Beth to function.');
-        logInfo('Beth uses Backlog.md to maintain human-readable task history and boards.');
-        logInfo('This complements beads for a complete task management workflow.');
-        console.log('');
-        
-        const tryAgain = await promptYesNo('Would you like to try installing backlog.md?');
-        if (!tryAgain) {
-          logError('Cannot continue without backlog.md. Exiting.');
-          logInfo('Install manually and run "npx beth-copilot init" again:');
-          logInfo('  npm install -g backlog.md');
-          process.exit(1);
-        }
-      }
-    }
-    
-    logSuccess('backlog.md CLI is installed');
-  } else {
-    logWarning('Skipped backlog check (--skip-backlog). Beth may not function correctly.');
-  }
-
   // Final verification
   console.log('');
   log('Verifying installation...', COLORS.cyan);
   
   const finalBeadsOk = skipBeads || getBeadsPath();
-  const finalBacklogOk = skipBacklog || getBacklogPath();
   const finalBeadsInit = skipBeads || isBeadsInitialized(cwd);
   
-  if (finalBeadsOk && finalBacklogOk && finalBeadsInit) {
+  if (finalBeadsOk && finalBeadsInit) {
     logSuccess('All dependencies installed and configured!');
   } else {
     if (!finalBeadsOk) logError('beads CLI not found');
-    if (!finalBacklogOk) logError('backlog.md CLI not found');
     if (!finalBeadsInit) logError('beads not initialized in project');
     logError('Setup incomplete. Please resolve issues above and run init again.');
     process.exit(1);
@@ -1183,7 +1081,7 @@ ${COLORS.cyan}"They broke my wings and forgot I had claws."${COLORS.reset}
 }
 
 // Input validation constants
-const ALLOWED_COMMANDS = ['init', 'help', '--help', '-h'];
+const ALLOWED_COMMANDS = ['init', 'help', '--help', '-h', 'doctor', 'quickstart'];
 const ALLOWED_FLAGS = ['--force', '--skip-backlog', '--skip-mcp', '--skip-beads', '--verbose'];
 const MAX_ARG_LENGTH = 50;
 
@@ -1230,7 +1128,27 @@ if (unknownFlags.length > 0) {
 
 switch (command) {
   case 'init':
-    await init(options);
+    try {
+      await init(options);
+    } catch (error) {
+      if (error instanceof UserError) {
+        showUserError(error);
+        process.exit(1);
+      }
+      throw error;
+    }
+    break;
+  case 'doctor':
+    {
+      const { doctor } = await loadTsCommand('doctor');
+      await doctor(options);
+    }
+    break;
+  case 'quickstart':
+    {
+      const { quickstart } = await loadTsCommand('quickstart');
+      await quickstart(options);
+    }
     break;
   case 'help':
   case '--help':