specweave 2.2.2 → 2.3.0

package/bin/specweave.js

@@ -7,191 +7,17 @@
  * Provides commands for initializing projects, creating increments, and managing skills.
  */
 
-// ============================================================================
-// CRITICAL: Node.js Version Check (MUST run before ANY ESM imports)
-// ============================================================================
-// This check runs synchronously before any imports that use modern syntax
-// (like `import ... with { type: 'json' }`) which would crash on older Node.js
-// ============================================================================
-
-const MIN_NODE_VERSION = '20.12.0';
-const CURRENT_NODE_VERSION = process.versions.node;
-
-/**
- * Compare semver versions
- * @param {string} current - Current version (e.g., "18.17.0")
- * @param {string} required - Required version (e.g., "20.12.0")
- * @returns {boolean} true if current >= required
- */
-function isVersionSatisfied(current, required) {
-  const currentParts = current.split('.').map(Number);
-  const requiredParts = required.split('.').map(Number);
-
-  for (let i = 0; i < 3; i++) {
-    const curr = currentParts[i] || 0;
-    const req = requiredParts[i] || 0;
-    if (curr > req) return true;
-    if (curr < req) return false;
-  }
-  return true; // Equal versions
-}
-
-/**
- * Get platform-specific Node.js upgrade instructions
- */
-function getUpgradeInstructions() {
-  const platform = process.platform;
-  const isNvm = process.env.NVM_DIR || process.env.NVM_BIN;
-  const isFnm = process.env.FNM_DIR || process.env.FNM_MULTISHELL_PATH;
-  const isVolta = process.env.VOLTA_HOME;
-  const isAsdf = process.env.ASDF_DIR;
-
-  let instructions = [];
-
-  // Version manager detection (cross-platform)
-  if (isNvm) {
-    instructions.push('  Using nvm (detected):');
-    instructions.push('    nvm install 22');
-    instructions.push('    nvm use 22');
-    instructions.push('    nvm alias default 22');
-  } else if (isFnm) {
-    instructions.push('  Using fnm (detected):');
-    instructions.push('    fnm install 22');
-    instructions.push('    fnm use 22');
-    instructions.push('    fnm default 22');
-  } else if (isVolta) {
-    instructions.push('  Using Volta (detected):');
-    instructions.push('    volta install node@22');
-  } else if (isAsdf) {
-    instructions.push('  Using asdf (detected):');
-    instructions.push('    asdf install nodejs 22.0.0');
-    instructions.push('    asdf global nodejs 22.0.0');
-  } else {
-    // Platform-specific fallback
-    switch (platform) {
-      case 'darwin':
-        instructions.push('  macOS options:');
-        instructions.push('    # Using Homebrew:');
-        instructions.push('    brew install node@22');
-        instructions.push('');
-        instructions.push('    # Using nvm (recommended):');
-        instructions.push('    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash');
-        instructions.push('    nvm install 22 && nvm use 22');
-        break;
-      case 'linux':
-        instructions.push('  Linux options:');
-        instructions.push('    # Using nvm (recommended):');
-        instructions.push('    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash');
-        instructions.push('    nvm install 22 && nvm use 22');
-        instructions.push('');
-        instructions.push('    # Using NodeSource (Debian/Ubuntu):');
-        instructions.push('    curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -');
-        instructions.push('    sudo apt-get install -y nodejs');
-        break;
-      case 'win32':
-        instructions.push('  Windows options:');
-        instructions.push('    # Using nvm-windows:');
-        instructions.push('    nvm install 22');
-        instructions.push('    nvm use 22');
-        instructions.push('');
-        instructions.push('    # Direct download:');
-        instructions.push('    https://nodejs.org/en/download/');
-        break;
-      default:
-        instructions.push('  Download Node.js 22+ from:');
-        instructions.push('    https://nodejs.org/en/download/');
-    }
-  }
-
-  return instructions.join('\n');
-}
-
-// Perform the version check
-if (!isVersionSatisfied(CURRENT_NODE_VERSION, MIN_NODE_VERSION)) {
-  // Use basic console methods (no chalk yet - it may fail to import)
-  const RED = '\x1b[31m';
-  const YELLOW = '\x1b[33m';
-  const CYAN = '\x1b[36m';
-  const BOLD = '\x1b[1m';
-  const RESET = '\x1b[0m';
-  const DIM = '\x1b[2m';
-  const UNDERLINE = '\x1b[4m';
-
-  console.error('');
-  console.error(`${RED}${BOLD}╔══════════════════════════════════════════════════════════════════╗${RESET}`);
-  console.error(`${RED}${BOLD}║  SpecWeave requires Node.js ${MIN_NODE_VERSION} or higher                     ║${RESET}`);
-  console.error(`${RED}${BOLD}╚══════════════════════════════════════════════════════════════════╝${RESET}`);
-  console.error('');
-  console.error(`${YELLOW}  Your version:${RESET}  ${RED}${CURRENT_NODE_VERSION}${RESET}`);
-  console.error(`${YELLOW}  Required:${RESET}      ${CYAN}≥${MIN_NODE_VERSION}${RESET} (Node.js 22 LTS recommended)`);
-  console.error('');
-  console.error(`${DIM}  Why? SpecWeave uses modern JavaScript features (ES2022+) including${RESET}`);
-  console.error(`${DIM}  import assertions which require Node.js 20.12.0+${RESET}`);
-  console.error('');
-  console.error(`${BOLD}Quick upgrade:${RESET}`);
-  console.error(getUpgradeInstructions());
-  console.error('');
-  console.error(`${BOLD}Full guide:${RESET}`);
-  console.error(`  ${CYAN}${UNDERLINE}https://spec-weave.com/docs/guides/troubleshooting/common-errors#node-version-error${RESET}`);
-  console.error('');
-  console.error(`${DIM}After upgrading, verify with: node --version${RESET}`);
-  console.error('');
-  process.exit(1);
-}
-
-// ============================================================================
-// Node.js version is OK - proceed with normal imports
-// ============================================================================
+import './check-node.js';
 
 import { Command } from 'commander';
 import chalk from 'chalk';
 import { createRequire } from 'module';
-import { fileURLToPath } from 'url';
-import { dirname } from 'path';
-
-// ESM equivalents for __dirname and __filename
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
 
 // For importing package.json (need createRequire in ESM)
 const require = createRequire(import.meta.url);
 const packageJson = require('../package.json');
 
-// ============================================================================
-// DEVELOPMENT GUARD: Check if dist/ is built (prevents silent hangs)
-// ============================================================================
-// This only matters for developers running from source. NPM users always get
-// a pre-built package via prepublishOnly hook.
-// ============================================================================
-import { existsSync } from 'fs';
-import { join } from 'path';
-
-const distCliPath = join(__dirname, '..', 'dist', 'src', 'cli', 'commands', 'init.js');
-const isDevEnvironment = existsSync(join(__dirname, '..', 'tsconfig.json'));
-
-if (isDevEnvironment && !existsSync(distCliPath)) {
-  const RED = '\x1b[31m';
-  const YELLOW = '\x1b[33m';
-  const CYAN = '\x1b[36m';
-  const BOLD = '\x1b[1m';
-  const RESET = '\x1b[0m';
-  const DIM = '\x1b[2m';
-
-  console.error('');
-  console.error(`${RED}${BOLD}╔══════════════════════════════════════════════════════════════════╗${RESET}`);
-  console.error(`${RED}${BOLD}║  SpecWeave is not built! Run: npm run rebuild                    ║${RESET}`);
-  console.error(`${RED}${BOLD}╚══════════════════════════════════════════════════════════════════╝${RESET}`);
-  console.error('');
-  console.error(`${YELLOW}  Missing:${RESET}  ${DIM}dist/src/cli/commands/init.js${RESET}`);
-  console.error('');
-  console.error(`${BOLD}Quick fix:${RESET}`);
-  console.error(`  ${CYAN}npm run rebuild${RESET}`);
-  console.error('');
-  console.error(`${DIM}  This happens when 'npm run clean' runs without 'npm run build'.${RESET}`);
-  console.error(`${DIM}  NPM users never see this - packages are pre-built before publish.${RESET}`);
-  console.error('');
-  process.exit(1);
-}
+import './check-build.js';
 
 const program = new Command();
 
@@ -559,7 +385,6 @@ program
       noPush: options.push === false, // Handle --no-push
       force: options.force,
       branch: options.branch,
-      projectRoot: process.cwd()
     });
   });
 
@@ -954,6 +779,13 @@ program
     if (!result.success) process.exit(1);
   });
 
+// Route lazy CLI actions through the guarded command factory. Keep registrations
+// here so static shell-completion generation still sees every command and option.
+async function runLspCommand(args) {
+  const { createLspCommand } = await import('../dist/src/cli/commands/lsp.js');
+  await createLspCommand().parseAsync(args, { from: 'user' });
+}
+
 // LSP command - Code intelligence operations
 const lspCmd = program
   .command('lsp')
@@ -963,40 +795,35 @@ lspCmd
   .command('refs <file> <symbol>')
   .description('Find all references to a symbol')
   .action(async (file, symbol) => {
-    const { handleLspRefs } = await import('../dist/src/cli/commands/lsp.js');
-    await handleLspRefs(process.cwd(), file, symbol);
+    await runLspCommand(['refs', '--', file, symbol]);
   });
 
 lspCmd
   .command('def <file> <symbol>')
   .description('Go to definition of a symbol')
   .action(async (file, symbol) => {
-    const { handleLspDef } = await import('../dist/src/cli/commands/lsp.js');
-    await handleLspDef(process.cwd(), file, symbol);
+    await runLspCommand(['def', '--', file, symbol]);
   });
 
 lspCmd
   .command('hover <file> <symbol>')
   .description('Get type information for a symbol')
   .action(async (file, symbol) => {
-    const { handleLspHover } = await import('../dist/src/cli/commands/lsp.js');
-    await handleLspHover(process.cwd(), file, symbol);
+    await runLspCommand(['hover', '--', file, symbol]);
   });
 
 lspCmd
   .command('symbols <file>')
   .description('List all symbols in a file')
   .action(async (file) => {
-    const { handleLspSymbols } = await import('../dist/src/cli/commands/lsp.js');
-    await handleLspSymbols(process.cwd(), file);
+    await runLspCommand(['symbols', '--', file]);
   });
 
 lspCmd
   .command('search <query>')
   .description('Search for symbols in workspace')
   .action(async (query) => {
-    const { handleLspSearch } = await import('../dist/src/cli/commands/lsp.js');
-    await handleLspSearch(process.cwd(), query);
+    await runLspCommand(['search', '--', query]);
   });
 
 lspCmd
@@ -1004,16 +831,14 @@ lspCmd
   .description('Warm up LSP by pre-indexing workspace (run on session start)')
   .option('--quiet', 'Suppress output')
   .action(async (files, options) => {
-    const { handleLspWarmup } = await import('../dist/src/cli/commands/lsp.js');
-    await handleLspWarmup(process.cwd(), files, options.quiet ?? false);
+    await runLspCommand(['warmup', ...(options.quiet ? ['--quiet'] : []), '--', ...files]);
   });
 
 lspCmd
   .command('status')
   .description('Show LSP status and warm-up state')
   .action(async () => {
-    const { handleLspStatus } = await import('../dist/src/cli/commands/lsp.js');
-    await handleLspStatus(process.cwd());
+    await runLspCommand(['status']);
   });
 
 lspCmd
@@ -1024,13 +849,10 @@ lspCmd
   .option('--dry-run', 'Show what would be installed without installing')
   .option('--scope <scope>', 'Installation scope: user, project, local', 'project')
   .action(async (options) => {
-    const { handleLspSetup } = await import('../dist/src/cli/commands/lsp.js');
-    await handleLspSetup(process.cwd(), {
-      maxLanguages: parseInt(options.max, 10),
-      minFileCount: parseInt(options.minFiles, 10),
-      dryRun: options.dryRun ?? false,
-      scope: options.scope,
-    });
+    await runLspCommand([
+      'setup', '--max', options.max, '--min-files', options.minFiles,
+      '--scope', options.scope, ...(options.dryRun ? ['--dry-run'] : []),
+    ]);
   });
 
 // Commits command - Display last 2 git commits
@@ -1537,114 +1359,13 @@ program
     });
   });
 
-// Help text
-program.on('--help', () => {
-  console.log('');
-  console.log('Examples:');
-  console.log('  $ specweave init my-saas                    # Create new project (auto-detect tool)');
-  console.log('  $ specweave init my-saas --adapter cursor   # Create project for Cursor');
-  console.log('  $ specweave init my-saas --language ru      # Create project with Russian language');
-  console.log('  $ specweave install pm --local              # Install PM agent locally');
-  console.log('  $ specweave install --global                # Install all (interactive)');
-  console.log('  $ specweave list                            # List all available components');
-  console.log('  $ specweave list --installed                # Show installed components');
-  console.log('  $ specweave status                          # Show all increments status');
-  console.log('  $ specweave status --verbose                # Show detailed increment info');
-  console.log('  $ specweave status-line                     # Display current increment progress');
-  console.log('  $ specweave status-line --json              # Output progress as JSON');
-  console.log('  $ specweave pause 0007 --reason "blocked"   # Pause increment 0007');
-  console.log('  $ specweave resume 0007                     # Resume increment 0007');
-  console.log('  $ specweave abandon 0007 --reason "obsolete" # Abandon increment 0007');
-  console.log('  $ specweave qa 0008                         # Quick quality check');
-  console.log('  $ specweave qa 0008 --pre                   # Pre-implementation check');
-  console.log('  $ specweave qa 0008 --gate --export         # Quality gate + export to tasks');
-  console.log('  $ specweave sync status                     # Token/account, provider health, sync gaps');
-  console.log('  $ specweave jobs                            # Show active background jobs');
-  console.log('  $ specweave jobs --follow <jobId>           # Follow job progress live');
-  console.log('  $ specweave jobs --logs <jobId>             # View worker logs');
-  console.log('  $ specweave jobs --resume <jobId>           # Resume paused job');
-  console.log('  $ specweave living-docs                     # Launch Living Docs (interactive)');
-  console.log('  $ specweave living-docs --depth deep-native # AI-powered analysis (FREE w/ MAX)');
-  console.log('  $ specweave living-docs --full-scan         # Full deep scan (all phases)');
-  console.log('  $ specweave living-docs --resume <jobId>    # Resume orphaned job');
-  console.log('  $ specweave sync push 0008                  # Push increment progress to GitHub/Jira/ADO');
-  console.log('  $ specweave sync pull --since 3             # Show external changes from the last 3 days');
-  console.log('  $ specweave cache                           # Show cache status');
-  console.log('  $ specweave cache --rebuild                 # Rebuild dashboard cache');
-  console.log('  $ specweave cache --debug                   # Show cache debug info');
-  console.log('  $ specweave sync setup --validate           # Validate tracker configuration + credentials');
-  console.log('  $ specweave docs                            # Preview internal docs (port 3015)');
-  console.log('  $ specweave docs public                     # Preview public docs (port 3016)');
-  console.log('  $ specweave docs build                      # Build internal site');
-  console.log('  $ specweave docs build --scope public       # Build public site');
-  console.log('  $ specweave docs validate                   # Check for docs errors');
-  console.log('  $ specweave docs status                     # Show docs status');
-  console.log('  $ specweave docs kill                       # Stop all docs servers');
-  console.log('  $ specweave doctor --fix-status             # Fix metadata/spec status desyncs');
-  console.log('  $ specweave refresh-plugins                 # Refresh core SpecWeave plugin');
-  console.log('  $ specweave refresh-plugins --all           # Refresh every installed plugin');
-  console.log('  $ specweave refresh-plugins --force         # Force reinstall (skip hash check)');
-  console.log('  $ specweave update                          # Update CLI + instructions + config');
-  console.log('  $ specweave update --plugins                # Also refresh marketplace plugins');
-  console.log('  $ specweave update --no-self                # Skip CLI update, only project files');
-  console.log('  $ specweave update --check                  # Dry run - preview changes');
-  console.log('');
-  console.log('Plugin Management (use Claude CLI commands):');
-  console.log('  $ claude plugin install sw@specweave        # Install core SpecWeave');
-  console.log('  $ claude plugin list                        # Show installed plugins');
-  console.log('  $ vskill install anton-abyzov/vskill --plugin mobile  # Install domain plugin');
-  console.log('');
-  console.log('Supported AI Tools:');
-  console.log('  - Claude Code (full automation) - Native skills, agents, hooks');
-  console.log('  - Cursor (semi-automation) - .cursorrules, @ shortcuts');
-  console.log('  - GitHub Copilot (basic) - Workspace instructions');
-  console.log('  - Generic (manual) - Works with ANY AI (ChatGPT, Gemini, etc.)');
-  console.log('');
-  console.log('For more information, visit: https://spec-weave.com');
-});
-
-// Startup duplicate check (runs before any command)
-async function checkForDuplicates() {
-  try {
-    // Skip check for init command (no .specweave yet)
-    const args = process.argv.slice(2);
-    if (args.length === 0 || args[0] === 'init' || args[0] === '--help' || args[0] === '-h' || args[0] === '--version' || args[0] === '-V') {
-      return;
-    }
-
-    // Check if .specweave exists
-    const { default: fs } = await import('fs-extra');
-    const { default: path } = await import('path');
-    const specweavePath = path.join(process.cwd(), '.specweave');
-
-    if (!fs.existsSync(specweavePath)) {
-      return; // No .specweave directory, skip check
-    }
+// Supplementary CLI help and project coordination.
+import { registerHelp } from './help.js';
+import { registerProjectCommand } from './project.js';
+registerHelp(program);
+registerProjectCommand(program);
 
-    // Detect duplicates
-    const { detectAllDuplicates } = await import('../dist/src/core/increment/duplicate-detector.js');
-    const report = await detectAllDuplicates(process.cwd());
-
-    if (report.duplicateCount > 0) {
-      console.log(chalk.yellow('\n⚠️  Duplicate increment(s) detected:\n'));
-
-      for (const duplicate of report.duplicates) {
-        console.log(chalk.dim(`  ${duplicate.incrementNumber}:`));
-        for (const location of duplicate.locations) {
-          const indicator = location === duplicate.recommendedWinner ? chalk.green('→') : chalk.red('✗');
-          console.log(`    ${indicator} ${location.name} [${location.status}]`);
-        }
-      }
-
-      console.log(chalk.dim('\n  Run sw:fix-duplicates to resolve\n'));
-    }
-  } catch (error) {
-    // Silently ignore errors (don't block CLI startup)
-    if (process.env.DEBUG) {
-      console.error(chalk.dim(`[DEBUG] Duplicate check failed: ${error}`));
-    }
-  }
-}
+import { checkForDuplicates } from './startup-check.js';
 
 // Dashboard command - Real-time observability dashboard
 program

package/bin/startup-check.js

@@ -0,0 +1,44 @@
+import chalk from 'chalk';
+// Startup duplicate check (runs before any command)
+export async function checkForDuplicates() {
+  try {
+    // Skip check for init command (no .specweave yet)
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args[0] === 'init' || args[0] === '--help' || args[0] === '-h' || args[0] === '--version' || args[0] === '-V') {
+      return;
+    }
+
+    // Check if .specweave exists
+    const { default: fs } = await import('fs-extra');
+    const { default: path } = await import('path');
+    const specweavePath = path.join(process.cwd(), '.specweave');
+
+    if (!fs.existsSync(specweavePath)) {
+      return; // No .specweave directory, skip check
+    }
+
+    // Detect duplicates
+    const { detectAllDuplicates } = await import('../dist/src/core/increment/duplicate-detector.js');
+    const report = await detectAllDuplicates(process.cwd());
+
+    if (report.duplicateCount > 0) {
+      console.log(chalk.yellow('\n⚠️  Duplicate increment(s) detected:\n'));
+
+      for (const duplicate of report.duplicates) {
+        console.log(chalk.dim(`  ${duplicate.incrementNumber}:`));
+        for (const location of duplicate.locations) {
+          const indicator = location === duplicate.recommendedWinner ? chalk.green('→') : chalk.red('✗');
+          console.log(`    ${indicator} ${location.name} [${location.status}]`);
+        }
+      }
+
+      console.log(chalk.dim('\n  Run sw:fix-duplicates to resolve\n'));
+    }
+  } catch (error) {
+    // Silently ignore errors (don't block CLI startup)
+    if (process.env.DEBUG) {
+      console.error(chalk.dim(`[DEBUG] Duplicate check failed: ${error}`));
+    }
+  }
+}
+