grimoire-framework 1.0.0

package/bin/grimoire.js

@@ -0,0 +1,1118 @@
+#!/usr/bin/env node
+
+/**
+ * grimoire-FullStack CLI
+ * Main entry point - Standalone (no external dependencies for npx compatibility)
+ * Version: 4.0.0
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { execSync } = require('child_process');
+
+// Read package.json for version
+const packageJsonPath = path.join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+
+// Parse arguments
+const args = process.argv.slice(2);
+const command = args[0];
+
+// Helper: Run initialization wizard
+async function runWizard(options = {}) {
+  // Use the v4 wizard from packages/installer/src/wizard/index.js
+  const wizardPath = path.join(__dirname, '..', 'packages', 'installer', 'src', 'wizard', 'index.js');
+
+  if (!fs.existsSync(wizardPath)) {
+    // Fallback to legacy wizard if new wizard not found
+    const legacyScript = path.join(__dirname, 'grimoire-init.js');
+    if (fs.existsSync(legacyScript)) {
+      if (!options.quiet) {
+        console.log('⚠️  Using legacy wizard (src/wizard not found)');
+      }
+      // Legacy wizard doesn't support options, pass via env vars
+      process.env.grimoire_INSTALL_FORCE = options.force ? '1' : '';
+      process.env.grimoire_INSTALL_QUIET = options.quiet ? '1' : '';
+      process.env.grimoire_INSTALL_DRY_RUN = options.dryRun ? '1' : '';
+      require(legacyScript);
+      return;
+    }
+    console.error('❌ Initialization wizard not found');
+    console.error('Please ensure grimoire-FullStack is installed correctly.');
+    process.exit(1);
+  }
+
+  try {
+    // Run the v4 wizard with options
+    const { runWizard: executeWizard } = require(wizardPath);
+    await executeWizard(options);
+  } catch (error) {
+    console.error('❌ Wizard error:', error.message);
+    process.exit(1);
+  }
+}
+
+// Helper: Show help
+function showHelp() {
+  console.log(`
+grimoire-FullStack v${packageJson.version}
+AI-Orchestrated System for Full Stack Development
+
+USAGE:
+  npx grimoire@latest              # Run installation wizard
+  npx grimoire@latest install      # Install in current project
+  npx grimoire@latest init <name>  # Create new project
+  npx grimoire@latest update       # Update to latest version
+  npx grimoire@latest validate     # Validate installation integrity
+  npx grimoire@latest info         # Show system info
+  npx grimoire@latest doctor       # Run diagnostics
+  npx grimoire@latest --version    # Show version
+  npx grimoire@latest --version -d # Show detailed version info
+  npx grimoire@latest --help       # Show this help
+
+UPDATE:
+  grimoire update                    # Update to latest version
+  grimoire update --check            # Check for updates without applying
+  grimoire update --dry-run          # Preview what would be updated
+  grimoire update --force            # Force update even if up-to-date
+  grimoire update --verbose          # Show detailed output
+
+VALIDATION:
+  grimoire validate                    # Validate installation integrity
+  grimoire validate --repair           # Repair missing/corrupted files
+  grimoire validate --repair --dry-run # Preview repairs
+  grimoire validate --detailed         # Show detailed file list
+
+CONFIGURATION:
+  grimoire config show                       # Show resolved configuration
+  grimoire config show --debug               # Show with source annotations
+  grimoire config diff --levels L1,L2        # Compare config levels
+  grimoire config migrate                    # Migrate monolithic to layered
+  grimoire config validate                   # Validate config files
+  grimoire config init-local                 # Create local-config.yaml
+
+SERVICE DISCOVERY:
+  grimoire workers search <query>            # Search for workers
+  grimoire workers search "json" --category=data
+  grimoire workers search "transform" --tags=etl,data
+  grimoire workers search "api" --format=json
+
+EXAMPLES:
+  # Install in current directory
+  npx grimoire@latest
+
+  # Install with minimal mode (only expansion-creator)
+  npx grimoire-minimal@latest
+
+  # Create new project
+  npx grimoire@latest init my-project
+
+  # Search for workers
+  grimoire workers search "json csv"
+
+For more information, visit: https://github.com/grimoireAI/grimoire
+`);
+}
+
+// Helper: Show version
+async function showVersion() {
+  const isDetailed = args.includes('--detailed') || args.includes('-d');
+
+  if (!isDetailed) {
+    // Simple version output (backwards compatible)
+    console.log(packageJson.version);
+    return;
+  }
+
+  // Detailed version output (Story 7.2: Version Tracking)
+  console.log(`grimoire-FullStack v${packageJson.version}`);
+  console.log('Package: grimoire');
+
+  // Check for local installation
+  const localVersionPath = path.join(process.cwd(), '.grimoire', 'version.json');
+
+  if (fs.existsSync(localVersionPath)) {
+    try {
+      const versionInfo = JSON.parse(fs.readFileSync(localVersionPath, 'utf8'));
+      console.log('\n📦 Local Installation:');
+      console.log(`  Version:    ${versionInfo.version}`);
+      console.log(`  Mode:       ${versionInfo.mode || 'unknown'}`);
+
+      if (versionInfo.installedAt) {
+        const installedDate = new Date(versionInfo.installedAt);
+        console.log(`  Installed:  ${installedDate.toLocaleDateString()}`);
+      }
+
+      if (versionInfo.updatedAt) {
+        const updatedDate = new Date(versionInfo.updatedAt);
+        console.log(`  Updated:    ${updatedDate.toLocaleDateString()}`);
+      }
+
+      if (versionInfo.fileHashes) {
+        const fileCount = Object.keys(versionInfo.fileHashes).length;
+        console.log(`  Files:      ${fileCount} tracked`);
+      }
+
+      if (versionInfo.customized && versionInfo.customized.length > 0) {
+        console.log(`  Customized: ${versionInfo.customized.length} files`);
+      }
+
+      // Version comparison
+      if (versionInfo.version !== packageJson.version) {
+        console.log('\n⚠️  Version mismatch!');
+        console.log(`  Local:  ${versionInfo.version}`);
+        console.log(`  Latest: ${packageJson.version}`);
+        console.log('  Run \'npx grimoire update\' to update.');
+      } else {
+        console.log('\n✅ Up to date');
+      }
+    } catch (error) {
+      console.log(`\n⚠️  Could not read version.json: ${error.message}`);
+    }
+  } else {
+    console.log('\n📭 No local installation found');
+    console.log('  Run \'npx grimoire install\' to install grimoire in this project.');
+  }
+}
+
+// Helper: Show system info
+function showInfo() {
+  console.log('📊 grimoire-FullStack System Information\n');
+  console.log(`Version: ${packageJson.version}`);
+  console.log(`Platform: ${process.platform}`);
+  console.log(`Node.js: ${process.version}`);
+  console.log(`Architecture: ${process.arch}`);
+  console.log(`Working Directory: ${process.cwd()}`);
+  console.log(`Install Location: ${path.join(__dirname, '..')}`);
+
+  // Check if .grimoire exists
+  const grimoireCoreDir = path.join(__dirname, '..', '.grimoire');
+  if (fs.existsSync(grimoireCoreDir)) {
+    console.log('\n✓ grimoire Core installed');
+
+    // Count components
+    const countFiles = (dir) => {
+      try {
+        return fs.readdirSync(dir).length;
+      } catch {
+        return 0;
+      }
+    };
+
+    console.log(`  - Agents: ${countFiles(path.join(grimoireCoreDir, 'development', 'agents'))}`);
+    console.log(`  - Tasks: ${countFiles(path.join(grimoireCoreDir, 'development', 'tasks'))}`);
+    console.log(`  - Templates: ${countFiles(path.join(grimoireCoreDir, 'development', 'templates'))}`);
+    console.log(`  - Workflows: ${countFiles(path.join(grimoireCoreDir, 'development', 'workflows'))}`);
+  } else {
+    console.log('\n⚠️  grimoire Core not found');
+  }
+
+  // Check grimoire Pro status (Task 5.1)
+  const proDir = path.join(__dirname, '..', 'pro');
+  if (fs.existsSync(proDir)) {
+    console.log('\n✓ grimoire Pro installed');
+
+    try {
+      const { featureGate } = require(path.join(proDir, 'license', 'feature-gate'));
+      const state = featureGate.getLicenseState();
+      const info = featureGate.getLicenseInfo();
+
+      const stateEmoji = {
+        'Active': '✅',
+        'Grace': '⚠️',
+        'Expired': '❌',
+        'Not Activated': '➖',
+      };
+
+      console.log(`  - License: ${stateEmoji[state] || ''} ${state}`);
+
+      if (info && info.features) {
+        const availableCount = featureGate.listAvailable().length;
+        console.log(`  - Features: ${availableCount} available`);
+      }
+    } catch {
+      console.log('  - License: Unable to check status');
+    }
+  }
+}
+
+// Helper: Run installation validation
+async function runValidate() {
+  const validateArgs = args.slice(1); // Remove 'validate' from args
+
+  try {
+    // Load the validate command module
+    const { createValidateCommand } = require('../.grimoire/cli/commands/validate/index.js');
+    const validateCmd = createValidateCommand();
+
+    // Parse and execute (Note: don't include 'validate' as it's the command name, not an argument)
+    await validateCmd.parseAsync(['node', 'grimoire', ...validateArgs]);
+  } catch (_error) {
+    // Fallback: Run quick validation inline
+    console.log('Running installation validation...\n');
+
+    try {
+      const validatorPath = path.join(
+        __dirname,
+        '..',
+        'packages',
+        'installer',
+        'src',
+        'installer',
+        'post-install-validator.js',
+      );
+      const { PostInstallValidator, formatReport } = require(validatorPath);
+
+      const projectRoot = process.cwd();
+      const validator = new PostInstallValidator(projectRoot, path.join(__dirname, '..'));
+      const report = await validator.validate();
+
+      console.log(formatReport(report, { colors: true }));
+
+      if (
+        report.status === 'failed' ||
+        report.stats.missingFiles > 0 ||
+        report.stats.corruptedFiles > 0
+      ) {
+        process.exit(1);
+      }
+    } catch (validatorError) {
+      console.error(`❌ Validation error: ${validatorError.message}`);
+      if (args.includes('--verbose') || args.includes('-v')) {
+        console.error(validatorError.stack);
+      }
+      process.exit(2);
+    }
+  }
+}
+
+// Helper: Run update command
+async function runUpdate() {
+  const updateArgs = args.slice(1);
+  const isCheck = updateArgs.includes('--check');
+  const isDryRun = updateArgs.includes('--dry-run');
+  const isForce = updateArgs.includes('--force');
+  const isVerbose = updateArgs.includes('--verbose') || updateArgs.includes('-v');
+
+  try {
+    const updaterPath = path.join(__dirname, '..', 'packages', 'installer', 'src', 'updater', 'index.js');
+
+    if (!fs.existsSync(updaterPath)) {
+      console.error('❌ Updater module not found');
+      console.error('Please ensure grimoire-FullStack is installed correctly.');
+      process.exit(1);
+    }
+
+    const { grimoireUpdater, formatCheckResult, formatUpdateResult } = require(updaterPath);
+
+    const updater = new grimoireUpdater(process.cwd(), {
+      verbose: isVerbose,
+      force: isForce,
+    });
+
+    if (isCheck) {
+      // Check only mode
+      console.log('🔍 Checking for updates...\n');
+      const result = await updater.checkForUpdates();
+      console.log(formatCheckResult(result, { colors: true }));
+
+      if (result.status === 'check_failed') {
+        process.exit(1);
+      }
+    } else {
+      // Update mode
+      console.log('🔄 grimoire Update\n');
+
+      const result = await updater.update({
+        dryRun: isDryRun,
+        onProgress: (phase, message) => {
+          if (isVerbose) {
+            console.log(`[${phase}] ${message}`);
+          }
+        },
+      });
+
+      console.log(formatUpdateResult(result, { colors: true }));
+
+      if (!result.success && result.error !== 'Already up to date') {
+        process.exit(1);
+      }
+    }
+  } catch (error) {
+    console.error(`❌ Update error: ${error.message}`);
+    if (args.includes('--verbose') || args.includes('-v')) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+// Helper: Run doctor diagnostics
+async function runDoctor() {
+  const doctorArgs = args.slice(1);
+  const shouldFix = doctorArgs.includes('--fix');
+  const isDryRun = doctorArgs.includes('--dry-run');
+  const showHelp = doctorArgs.includes('--help') || doctorArgs.includes('-h');
+
+  if (showHelp) {
+    console.log(`
+Usage: grimoire doctor [options]
+
+Run system diagnostics and optionally fix issues.
+
+Options:
+  --fix          Attempt to automatically fix detected issues
+  --dry-run      Show what would be fixed without making changes
+  -h, --help     Show this help message
+
+Examples:
+  $ npx grimoire doctor              # Run diagnostics
+  $ npx grimoire doctor --fix        # Fix detected issues
+  $ npx grimoire doctor --dry-run    # Preview fixes
+`);
+    return;
+  }
+
+  console.log('🏥 grimoire System Diagnostics\n');
+
+  const issues = [];
+  let hasErrors = false;
+
+  // Helper: Compare semver versions
+  const compareVersions = (a, b) => {
+    const pa = a.split('.').map((n) => parseInt(n, 10));
+    const pb = b.split('.').map((n) => parseInt(n, 10));
+    for (let i = 0; i < 3; i++) {
+      const na = pa[i] || 0;
+      const nb = pb[i] || 0;
+      if (na > nb) return 1;
+      if (na < nb) return -1;
+    }
+    return 0;
+  };
+
+  // Check 1: Node.js version
+  const nodeVersion = process.version.replace('v', '');
+  const requiredNodeVersion = '18.0.0';
+  const nodeOk = compareVersions(nodeVersion, requiredNodeVersion) >= 0;
+
+  if (!nodeOk) {
+    issues.push({
+      type: 'node_version',
+      autoFix: false,
+      message: `Node.js version: ${process.version} (requires >=18.0.0)`,
+      suggestion: 'nvm install 20 && nvm use 20',
+    });
+    hasErrors = true;
+  }
+  console.log(
+    `${nodeOk ? '✔' : '✗'} Node.js version: ${process.version} ${nodeOk ? '(meets requirement: >=18.0.0)' : '(requires >=18.0.0)'}`,
+  );
+
+  // Check 2: npm
+  try {
+    const npmVersion = execSync('npm --version', { encoding: 'utf8' }).trim();
+    console.log(`✔ npm version: ${npmVersion}`);
+  } catch {
+    issues.push({
+      type: 'npm',
+      autoFix: false,
+      message: 'npm not found',
+      suggestion: 'Install Node.js from https://nodejs.org (includes npm)',
+    });
+    console.log('✗ npm not found');
+    hasErrors = true;
+  }
+
+  // Check 3: Git
+  try {
+    const gitVersion = execSync('git --version', { encoding: 'utf8' }).trim();
+    console.log(`✔ Git installed: ${gitVersion}`);
+  } catch {
+    issues.push({
+      type: 'git',
+      autoFix: false,
+      message: 'Git not found (optional but recommended)',
+      suggestion: 'Install Git from https://git-scm.com',
+    });
+    console.log('⚠️  Git not found (optional but recommended)');
+  }
+
+  // Check 4: grimoire installation
+  const grimoireCoreDir = path.join(__dirname, '..', '.grimoire');
+  if (fs.existsSync(grimoireCoreDir)) {
+    console.log(`✔ Grimoire: v${packageJson.version}`);
+
+    // Check for corruption using validate (if available)
+    try {
+      const validatorPath = path.join(__dirname, '..', 'packages', 'installer', 'src', 'installer', 'post-install-validator');
+      const { PostInstallValidator } = require(validatorPath);
+      const validator = new PostInstallValidator(process.cwd(), path.join(__dirname, '..'));
+      const report = await validator.validate();
+
+      if (report.stats && (report.stats.missingFiles > 0 || report.stats.corruptedFiles > 0)) {
+        issues.push({
+          type: 'grimoire_corrupted',
+          autoFix: true,
+          message: `grimoire Core: ${report.stats.missingFiles} missing, ${report.stats.corruptedFiles} corrupted files`,
+          fixAction: async () => {
+            console.log('  🔧 Repairing grimoire installation...');
+            await validator.repair();
+            console.log('  ✓ Repair complete');
+          },
+        });
+        hasErrors = true;
+        console.log(`⚠️  grimoire Core: ${report.stats.missingFiles} missing, ${report.stats.corruptedFiles} corrupted files`);
+      }
+    } catch {
+      // Validation not available, skip corruption check
+    }
+  } else {
+    issues.push({
+      type: 'grimoire_missing',
+      autoFix: true,
+      message: 'grimoire Core not installed',
+      fixAction: async () => {
+        console.log('  🔧 Installing grimoire...');
+        try {
+          execSync('npx grimoire install --force --quiet', { stdio: 'inherit', timeout: 60000 });
+          console.log('  ✓ Installation complete');
+        } catch (installError) {
+          console.error(`  ✗ Installation failed: ${installError.message}`);
+          throw installError;
+        }
+      },
+    });
+    hasErrors = true;
+    console.log('✗ grimoire Core not installed');
+    console.log('  Run: npx grimoire@latest');
+  }
+
+  // Check 5: grimoire Pro status
+  const proDetector = require('./utils/pro-detector');
+  if (proDetector.isProAvailable()) {
+    console.log('✔ grimoire Pro: Active (Full Version)');
+  }
+
+  // Apply fixes if --fix
+  if (shouldFix && issues.length > 0) {
+    console.log('\n🔧 Attempting fixes...\n');
+
+    let fixed = 0;
+    let manual = 0;
+
+    for (const issue of issues) {
+      if (issue.autoFix && issue.fixAction) {
+        if (isDryRun) {
+          console.log(`  [DRY RUN] Would fix: ${issue.type}`);
+          fixed++;
+        } else {
+          try {
+            await issue.fixAction();
+            fixed++;
+          } catch (fixError) {
+            console.error(`  ✗ Failed to fix ${issue.type}: ${fixError.message}`);
+            manual++;
+          }
+        }
+      } else {
+        manual++;
+        console.log(`  ⚠️  ${issue.message}`);
+        console.log(`     💡 Fix: ${issue.suggestion}`);
+      }
+    }
+
+    console.log('');
+    if (isDryRun) {
+      console.log(`✅ Dry run completed - ${fixed} issues would be fixed`);
+      if (manual > 0) {
+        console.log(`⚠️  ${manual} issues require manual action`);
+      }
+    } else {
+      if (fixed > 0) {
+        console.log(`✅ Fixed ${fixed} issue${fixed > 1 ? 's' : ''}`);
+      }
+      if (manual > 0) {
+        console.log(`⚠️  ${manual} issue${manual > 1 ? 's' : ''} require manual action`);
+        process.exit(1);
+      }
+    }
+  } else {
+    // Summary (no --fix)
+    console.log('');
+    if (hasErrors) {
+      console.log('⚠️  Some issues were detected. Run with --fix to auto-repair.');
+      process.exit(1);
+    } else {
+      console.log('✅ All checks passed! Your installation is healthy.');
+    }
+  }
+}
+
+// Helper: Format bytes to human readable
+function formatBytes(bytes) {
+  if (bytes === 0) return '0 Bytes';
+  const k = 1024;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+}
+
+// Helper: Remove grimoire sections from .gitignore
+function cleanGitignore(gitignorePath) {
+  if (!fs.existsSync(gitignorePath)) return { removed: false };
+
+  const content = fs.readFileSync(gitignorePath, 'utf8');
+  const lines = content.split('\n');
+  const newLines = [];
+  let ingrimoireSection = false;
+  let removedLines = 0;
+
+  for (const line of lines) {
+    if (line.includes('# grimoire') || line.includes('# Added by grimoire')) {
+      ingrimoireSection = true;
+      removedLines++;
+      continue;
+    }
+    if (ingrimoireSection && line.trim() === '') {
+      ingrimoireSection = false;
+      continue;
+    }
+    if (ingrimoireSection) {
+      removedLines++;
+      continue;
+    }
+    newLines.push(line);
+  }
+
+  if (removedLines > 0) {
+    fs.writeFileSync(gitignorePath, newLines.join('\n'));
+    return { removed: true, lines: removedLines };
+  }
+  return { removed: false };
+}
+
+// Helper: Show uninstall help
+function showUninstallHelp() {
+  console.log(`
+Usage: npx grimoire uninstall [options]
+
+Remove grimoire from the current project.
+
+Options:
+  --force      Skip confirmation prompt
+  --keep-data  Keep .grimoire/ directory (settings and history)
+  --dry-run    Show what would be removed without removing
+  -h, --help   Show this help message
+
+What gets removed:
+  - .grimoire/     Framework core files
+  - docs/stories/   Story files (if created by grimoire)
+  - squads/         Squad definitions
+  - .gitignore      grimoire-added entries only
+
+What is preserved (with --keep-data):
+  - .grimoire/          Project settings and agent history
+
+Exit Codes:
+  0  Uninstall successful
+  1  Uninstall failed or cancelled
+
+Examples:
+  # Interactive uninstall (with confirmation)
+  npx grimoire uninstall
+
+  # Force uninstall without prompts
+  npx grimoire uninstall --force
+
+  # See what would be removed
+  npx grimoire uninstall --dry-run
+
+  # Uninstall but keep project data
+  npx grimoire uninstall --keep-data
+`);
+}
+
+// Helper: Show doctor help
+function showDoctorHelp() {
+  console.log(`
+Usage: npx grimoire doctor [options]
+
+Run health checks on your grimoire installation.
+
+Options:
+  --fix        Automatically fix detected issues
+  --dry-run    Show what --fix would do without making changes
+  --quiet      Minimal output (exit code only)
+  -h, --help   Show this help message
+
+Checks performed:
+  • Required directories exist (.grimoire/, .grimoire/)
+  • Configuration files are valid JSON/YAML
+  • Agent definitions are complete
+  • Task files have required fields
+  • Dependencies are installed
+
+Exit Codes:
+  0  All checks passed (or issues fixed with --fix)
+  1  Issues detected (run with --fix to repair)
+
+Examples:
+  # Run health check
+  npx grimoire doctor
+
+  # Auto-fix detected issues
+  npx grimoire doctor --fix
+
+  # Preview what would be fixed
+  npx grimoire doctor --fix --dry-run
+`);
+}
+
+// Uninstall grimoire from project
+async function runUninstall(options = {}) {
+  const { force = false, keepData = false, dryRun = false, quiet = false } = options;
+  const cwd = process.cwd();
+
+  // Items to remove
+  const itemsToRemove = [
+    { path: '.grimoire', description: 'Framework core' },
+    { path: 'squads', description: 'Squad definitions' },
+  ];
+
+  // Optionally remove .grimoire
+  if (!keepData) {
+    itemsToRemove.push({ path: '.grimoire', description: 'Project data and settings' });
+  }
+
+  // Check what exists
+  const existingItems = itemsToRemove.filter(item =>
+    fs.existsSync(path.join(cwd, item.path)),
+  );
+
+  if (existingItems.length === 0) {
+    console.log('ℹ️  No grimoire installation found in this directory.');
+    return;
+  }
+
+  // Calculate total size
+  let totalSize = 0;
+  const itemSizes = [];
+
+  for (const item of existingItems) {
+    const itemPath = path.join(cwd, item.path);
+    try {
+      const stats = fs.statSync(itemPath);
+      if (stats.isDirectory()) {
+        // Simple recursive size calculation
+        const getSize = (dir) => {
+          let size = 0;
+          try {
+            const files = fs.readdirSync(dir);
+            for (const file of files) {
+              const filePath = path.join(dir, file);
+              const stat = fs.statSync(filePath);
+              if (stat.isDirectory()) {
+                size += getSize(filePath);
+              } else {
+                size += stat.size;
+              }
+            }
+          } catch { /* ignore errors */ }
+          return size;
+        };
+        const size = getSize(itemPath);
+        totalSize += size;
+        itemSizes.push({ ...item, size });
+      } else {
+        totalSize += stats.size;
+        itemSizes.push({ ...item, size: stats.size });
+      }
+    } catch {
+      itemSizes.push({ ...item, size: 0 });
+    }
+  }
+
+  // Show what will be removed
+  if (!quiet) {
+    console.log('\n📋 Items to be removed:\n');
+    for (const item of itemSizes) {
+      const sizeStr = item.size > 0 ? ` (${formatBytes(item.size)})` : '';
+      console.log(`  • ${item.path}/${sizeStr} - ${item.description}`);
+    }
+    console.log(`\n  Total: ${formatBytes(totalSize)}`);
+
+    // Check for .gitignore cleanup
+    const gitignorePath = path.join(cwd, '.gitignore');
+    if (fs.existsSync(gitignorePath)) {
+      const content = fs.readFileSync(gitignorePath, 'utf8');
+      if (content.includes('# grimoire') || content.includes('# Added by grimoire')) {
+        console.log('  • .gitignore grimoire entries will be cleaned');
+      }
+    }
+    console.log('');
+  }
+
+  // Dry run - stop here
+  if (dryRun) {
+    console.log('🔍 Dry run - no changes made.');
+    return;
+  }
+
+  // Confirmation
+  if (!force) {
+    const readline = require('readline');
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    const answer = await new Promise(resolve => {
+      rl.question('⚠️  Are you sure you want to uninstall grimoire? (y/N): ', resolve);
+    });
+    rl.close();
+
+    if (answer.toLowerCase() !== 'y' && answer.toLowerCase() !== 'yes') {
+      console.log('❌ Uninstall cancelled.');
+      process.exit(1);
+    }
+  }
+
+  // Perform removal
+  if (!quiet) console.log('\n🗑️  Removing grimoire components...\n');
+
+  for (const item of existingItems) {
+    const itemPath = path.join(cwd, item.path);
+    try {
+      fs.rmSync(itemPath, { recursive: true, force: true });
+      if (!quiet) console.log(`  ✓ Removed ${item.path}/`);
+    } catch (error) {
+      console.error(`  ✗ Failed to remove ${item.path}: ${error.message}`);
+    }
+  }
+
+  // Clean .gitignore
+  const gitignorePath = path.join(cwd, '.gitignore');
+  const gitignoreResult = cleanGitignore(gitignorePath);
+  if (gitignoreResult.removed && !quiet) {
+    console.log(`  ✓ Cleaned ${gitignoreResult.lines} grimoire entries from .gitignore`);
+  }
+
+  // Summary
+  if (!quiet) {
+    console.log('\n✅ grimoire has been uninstalled.');
+    if (keepData) {
+      console.log('   Your project data in .grimoire/ has been preserved.');
+    }
+    console.log('\n   To reinstall: npx grimoire install');
+  }
+}
+
+// Helper: Show install help
+function showInstallHelp() {
+  console.log(`
+Usage: npx grimoire install [options]
+
+Install grimoire in the current directory.
+
+Options:
+  --force      Overwrite existing grimoire installation
+  --quiet      Minimal output (no banner, no prompts) - ideal for CI/CD
+  --dry-run    Simulate installation without modifying files
+  --merge      Auto-merge existing config files (brownfield mode)
+  --no-merge   Disable merge option, use legacy overwrite behavior
+  -h, --help   Show this help message
+
+Smart Merge (Brownfield):
+  When installing in a project with existing config files (.env, CLAUDE.md),
+  grimoire can merge new settings while preserving your customizations.
+
+  - .env files: Adds new variables, preserves existing values
+  - CLAUDE.md: Updates grimoire sections, keeps your custom rules
+
+Exit Codes:
+  0  Installation successful
+  1  Installation failed
+
+Examples:
+  # Interactive installation
+  npx grimoire install
+
+  # Force reinstall without prompts
+  npx grimoire install --force
+
+  # Brownfield: merge configs automatically
+  npx grimoire install --merge
+
+  # Silent install for CI/CD
+  npx grimoire install --quiet --force
+
+  # Preview what would be installed
+  npx grimoire install --dry-run
+`);
+}
+
+// Helper: Create new project
+// Helper: Show init help
+function showInitHelp() {
+  console.log(`
+Usage: npx grimoire init <project-name> [options]
+
+Create a new grimoire project with the specified name.
+
+Options:
+  --force              Force creation in non-empty directory
+  --skip-install       Skip npm dependency installation
+  --template <name>    Use specific template (default: default)
+  -t <name>            Shorthand for --template
+  -h, --help           Show this help message
+
+Available Templates:
+  default     Full installation with all agents, tasks, and workflows
+  minimal     Essential files only (dev agent + basic tasks)
+  enterprise  Everything + dashboards + team integrations
+
+Examples:
+  npx grimoire init my-project
+  npx grimoire init my-project --template minimal
+  npx grimoire init my-project --force --skip-install
+  npx grimoire init . --template enterprise
+`);
+}
+
+async function initProject() {
+  // 1. Parse ALL args after 'init'
+  const initArgs = args.slice(1);
+
+  // 2. Handle --help FIRST (before creating any directories)
+  if (initArgs.includes('--help') || initArgs.includes('-h')) {
+    showInitHelp();
+    return;
+  }
+
+  // 3. Parse flags
+  const isForce = initArgs.includes('--force');
+  const skipInstall = initArgs.includes('--skip-install');
+
+  // Template with argument
+  const templateIndex = initArgs.findIndex((a) => a === '--template' || a === '-t');
+  let template = 'default';
+  if (templateIndex !== -1) {
+    template = initArgs[templateIndex + 1];
+    if (!template || template.startsWith('-')) {
+      console.error('❌ --template requires a template name');
+      console.error('Available templates: default, minimal, enterprise');
+      process.exit(1);
+    }
+  }
+
+  // Validate template
+  const validTemplates = ['default', 'minimal', 'enterprise'];
+  if (!validTemplates.includes(template)) {
+    console.error(`❌ Unknown template: ${template}`);
+    console.error(`Available templates: ${validTemplates.join(', ')}`);
+    process.exit(1);
+  }
+
+  // 4. Extract project name (anything that doesn't start with - and isn't a template value)
+  const projectName = initArgs.find((arg, i) => {
+    if (arg.startsWith('-')) return false;
+    // Skip if it's the value after --template
+    const prevArg = initArgs[i - 1];
+    if (prevArg === '--template' || prevArg === '-t') return false;
+    return true;
+  });
+
+  if (!projectName) {
+    console.error('❌ Project name is required');
+    console.log('\nUsage: npx grimoire init <project-name> [options]');
+    console.log('Run with --help for more information.');
+    process.exit(1);
+  }
+
+  // 5. Handle "." to install in current directory
+  const isCurrentDir = projectName === '.';
+  const targetPath = isCurrentDir ? process.cwd() : path.join(process.cwd(), projectName);
+  const displayName = isCurrentDir ? path.basename(process.cwd()) : projectName;
+
+  // 6. Check if directory exists
+  if (fs.existsSync(targetPath) && !isCurrentDir) {
+    const contents = fs.readdirSync(targetPath).filter((f) => !f.startsWith('.'));
+    if (contents.length > 0 && !isForce) {
+      console.error(`❌ Directory already exists and is not empty: ${projectName}`);
+      console.error('Use --force to overwrite.');
+      process.exit(1);
+    }
+    if (contents.length > 0 && isForce) {
+      console.log(`⚠️  Using --force: overwriting existing directory: ${projectName}`);
+    } else {
+      console.log(`✓ Using existing empty directory: ${projectName}`);
+    }
+  } else if (!fs.existsSync(targetPath)) {
+    fs.mkdirSync(targetPath, { recursive: true });
+    console.log(`✓ Created directory: ${projectName}`);
+  }
+
+  console.log(`Creating new grimoire project: ${displayName}`);
+  if (template !== 'default') {
+    console.log(`Template: ${template}`);
+  }
+  if (skipInstall) {
+    console.log('Skip install: enabled');
+  }
+  console.log('');
+
+  // 7. Change to project directory (if not already there)
+  if (!isCurrentDir) {
+    process.chdir(targetPath);
+  }
+
+  // 8. Run the initialization wizard with options
+  await runWizard({
+    template,
+    skipInstall,
+    force: isForce,
+  });
+}
+
+// Command routing (async main function)
+async function main() {
+  switch (command) {
+    case 'workers':
+      // Service Discovery CLI - Story 2.7
+      try {
+        const { run } = require('../.grimoire/cli/index.js');
+        await run(process.argv);
+      } catch (error) {
+        console.error(`❌ Workers command error: ${error.message}`);
+        process.exit(1);
+      }
+      break;
+
+    case 'config':
+      // Layered Configuration CLI - Story PRO-4
+      try {
+        const { run } = require('../.grimoire/cli/index.js');
+        await run(process.argv);
+      } catch (error) {
+        console.error(`❌ Config command error: ${error.message}`);
+        process.exit(1);
+      }
+      break;
+
+    case 'pro':
+      // grimoire Pro License Management - Story PRO-6
+      try {
+        const { run } = require('../.grimoire/cli/index.js');
+        await run(process.argv);
+      } catch (error) {
+        console.error(`❌ Pro command error: ${error.message}`);
+        process.exit(1);
+      }
+      break;
+
+    case 'install': {
+      // Install in current project with flag support
+      const installArgs = args.slice(1);
+      if (installArgs.includes('--help') || installArgs.includes('-h')) {
+        showInstallHelp();
+        break;
+      }
+      const installOptions = {
+        force: installArgs.includes('--force'),
+        quiet: installArgs.includes('--quiet'),
+        dryRun: installArgs.includes('--dry-run'),
+        forceMerge: installArgs.includes('--merge'),
+        noMerge: installArgs.includes('--no-merge'),
+      };
+      if (!installOptions.quiet) {
+        console.log('grimoire-FullStack Installation\n');
+      }
+      await runWizard(installOptions);
+      break;
+    }
+
+    case 'uninstall': {
+      // Uninstall grimoire from project
+      const uninstallArgs = args.slice(1);
+      if (uninstallArgs.includes('--help') || uninstallArgs.includes('-h')) {
+        showUninstallHelp();
+        break;
+      }
+      const uninstallOptions = {
+        force: uninstallArgs.includes('--force'),
+        keepData: uninstallArgs.includes('--keep-data'),
+        dryRun: uninstallArgs.includes('--dry-run'),
+        quiet: uninstallArgs.includes('--quiet'),
+      };
+      await runUninstall(uninstallOptions);
+      break;
+    }
+
+    case 'init': {
+      // Create new project (flags parsed inside initProject)
+      await initProject();
+      break;
+    }
+
+    case 'info':
+      showInfo();
+      break;
+
+    case 'doctor': {
+      // Run health check with flag support
+      const doctorArgs = args.slice(1);
+      if (doctorArgs.includes('--help') || doctorArgs.includes('-h')) {
+        showDoctorHelp();
+        break;
+      }
+      const doctorOptions = {
+        fix: doctorArgs.includes('--fix'),
+        dryRun: doctorArgs.includes('--dry-run'),
+        quiet: doctorArgs.includes('--quiet'),
+      };
+      await runDoctor(doctorOptions);
+      break;
+    }
+
+    case 'validate':
+      // Post-installation validation - Story 6.19
+      await runValidate();
+      break;
+
+    case 'update':
+      // Update to latest version - Epic 7
+      await runUpdate();
+      break;
+
+    case '--version':
+    case '-v':
+    case '-V':
+      await showVersion();
+      break;
+
+    case '--help':
+    case '-h':
+      showHelp();
+      break;
+
+    case undefined:
+      // No arguments - run wizard directly (npx default behavior)
+      console.log('grimoire-FullStack Installation\n');
+      await runWizard();
+      break;
+
+    default:
+      console.error(`❌ Unknown command: ${command}`);
+      console.log('\nRun with --help to see available commands');
+      process.exit(1);
+  }
+}
+
+// Execute main function
+main().catch((error) => {
+  console.error('❌ Fatal error:', error.message);
+  process.exit(1);
+});
+
+