claude-flow-novice 1.1.8 → 1.1.9

package/dist/mcp/mcp-server-novice.js

@@ -565,11 +565,19 @@ async function main() {
   console.error(`[${new Date().toISOString()}] INFO [claude-flow-novice-mcp] Server starting with ${toolCount} essential tools`);
 }
 
-if (require.main === module) {
+// ES module entry point detection
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Check if this file is being run directly
+if (import.meta.url === `file://${process.argv[1]}`) {
   main().catch((error) => {
     console.error(`[${new Date().toISOString()}] FATAL [claude-flow-novice-mcp] ${error.message}`);
     process.exit(1);
   });
 }
 
-module.exports = { ClaudeFlowNoviceMCPServer };
+export { ClaudeFlowNoviceMCPServer };

package/dist/src/cli/simple-commands/hooks/session-start-soul.js

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+
+/**
+ * Claude Code Session Start Hook - Soul Integration
+ *
+ * Automatically feeds claude-soul.md content into Claude Code sessions
+ * Handles graceful errors when the file is missing
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { printSuccess, printError, printWarning } from '../../utils.js';
+
+export class SessionStartSoulHook {
+  constructor(projectPath = process.cwd()) {
+    this.projectPath = projectPath;
+    this.claudeSoulPath = path.join(projectPath, 'claude-soul.md');
+    this.hookName = 'session-start-soul';
+  }
+
+  /**
+   * Execute the session start hook
+   */
+  async execute(options = {}) {
+    const {
+      silent = false,
+      generateMissing = true,
+      fallbackToDefault = true
+    } = options;
+
+    try {
+      if (!silent) {
+        console.log('🚀 Session Start: Loading project soul...');
+      }
+
+      const soulContent = await this.loadOrGenerateSoul({
+        generateMissing,
+        fallbackToDefault
+      });
+
+      if (soulContent) {
+        // Log the soul loading for integration tracking
+        await this.logSoulLoad(soulContent, { silent });
+
+        if (!silent) {
+          printSuccess('✅ Project soul available for Claude Code session');
+          console.log(`📖 Soul file: claude-soul.md (${soulContent.length} chars)`);
+        }
+
+        return {
+          success: true,
+          action: 'soul-loaded',
+          contentLength: soulContent.length,
+          source: await this.fileExists(this.claudeSoulPath) ? 'file' : 'generated'
+        };
+      } else {
+        if (!silent) {
+          printWarning('⚠️ No project soul available - continuing without soul context');
+        }
+
+        return {
+          success: true,
+          action: 'no-soul',
+          message: 'Session started without soul context'
+        };
+      }
+
+    } catch (error) {
+      if (!silent) {
+        printError(`❌ Session start soul hook failed: ${error.message}`);
+      }
+
+      return {
+        success: false,
+        action: 'error',
+        error: error.message
+      };
+    }
+  }
+
+  /**
+   * Load existing soul or generate one if missing
+   */
+  async loadOrGenerateSoul(options = {}) {
+    const { generateMissing = true, fallbackToDefault = true } = options;
+
+    try {
+      // Try to load existing soul file
+      if (await this.fileExists(this.claudeSoulPath)) {
+        const content = await fs.readFile(this.claudeSoulPath, 'utf8');
+        console.log('📖 Loading existing claude-soul.md');
+        return content;
+      }
+
+      // File doesn't exist - handle based on options
+      if (generateMissing) {
+        console.log('🔄 claude-soul.md not found, generating...');
+        return await this.generateDefaultSoul();
+      }
+
+      if (fallbackToDefault) {
+        console.log('🔄 Using minimal project soul...');
+        return this.getMinimalSoul();
+      }
+
+      return null;
+
+    } catch (error) {
+      console.warn(`⚠️ Could not load project soul: ${error.message}`);
+
+      if (fallbackToDefault) {
+        return this.getMinimalSoul();
+      }
+
+      return null;
+    }
+  }
+
+  /**
+   * Generate a default soul document
+   */
+  async generateDefaultSoul() {
+    try {
+      // Import the soul generator
+      const { ClaudeSoulSlashCommand } = await import('../../slash-commands/claude-soul.js');
+      const generator = new ClaudeSoulSlashCommand(this.projectPath);
+
+      const result = await generator.execute({ backup: false });
+
+      if (result.success) {
+        const content = await fs.readFile(this.claudeSoulPath, 'utf8');
+        console.log('✅ Generated claude-soul.md for session');
+        return content;
+      } else {
+        throw new Error(`Soul generation failed: ${result.error}`);
+      }
+
+    } catch (error) {
+      console.warn(`⚠️ Could not generate soul: ${error.message}`);
+      return this.getMinimalSoul();
+    }
+  }
+
+  /**
+   * Get minimal soul content as fallback
+   */
+  getMinimalSoul() {
+    const projectName = path.basename(this.projectPath);
+
+    return `# ${projectName} - Project Soul
+
+## WHY - The Purpose
+This project aims to solve important problems through software.
+
+## WHAT - The Essence
+A software project focused on delivering value through clean, maintainable code.
+
+## HOW - The Approach
+Following best practices and iterative development.
+
+## SOUL - The Spirit
+Committed to quality, simplicity, and user-centric design.
+
+---
+*Minimal soul context - generate full claude-soul.md for complete project essence*
+`;
+  }
+
+  /**
+   * Log soul loading for integration tracking
+   */
+  async logSoulLoad(soulContent, options = {}) {
+    const { silent = false } = options;
+
+    try {
+      if (!silent) {
+        console.log('📋 Project soul ready for Claude Code session context');
+      }
+
+      // Log hook execution for integration with other systems
+      await this.logHookExecution(soulContent);
+
+    } catch (error) {
+      console.warn(`⚠️ Could not log soul loading: ${error.message}`);
+    }
+  }
+
+  /**
+   * Log hook execution for integration with other systems
+   */
+  async logHookExecution(soulContent) {
+    try {
+      // Try to use memory store if available
+      const { SqliteMemoryStore } = await import('../../../memory/sqlite-store.js');
+      const store = new SqliteMemoryStore();
+      await store.initialize();
+
+      const hookData = {
+        hookName: this.hookName,
+        executedAt: new Date().toISOString(),
+        soulContentLength: soulContent.length,
+        soulPreview: soulContent.substring(0, 200) + '...',
+        projectPath: this.projectPath
+      };
+
+      await store.store(`session-start:${Date.now()}`, hookData, {
+        namespace: 'session-hooks',
+        metadata: { type: 'session-start', hook: this.hookName }
+      });
+
+      store.close();
+
+    } catch (error) {
+      // Silent fail - memory store is optional
+    }
+  }
+
+  /**
+   * Check if file exists
+   */
+  async fileExists(filePath) {
+    try {
+      await fs.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Clean up (no files to clean since we use claude-soul.md directly)
+   */
+  async cleanup() {
+    // No cleanup needed since we read claude-soul.md directly
+    console.log('🧹 Session soul cleanup completed (no temporary files)');
+  }
+}
+
+/**
+ * Execute the session start soul hook
+ */
+export async function executeSessionStartSoulHook(args = {}) {
+  const hook = new SessionStartSoulHook();
+
+  const options = {
+    silent: args.silent || args.includes('--silent'),
+    generateMissing: !args.includes('--no-generate'),
+    fallbackToDefault: !args.includes('--no-fallback')
+  };
+
+  return await hook.execute(options);
+}
+
+/**
+ * Execute session end cleanup
+ */
+export async function executeSessionEndSoulHook() {
+  const hook = new SessionStartSoulHook();
+  return await hook.cleanup();
+}
+
+// For direct execution
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--cleanup') || args.includes('cleanup')) {
+    executeSessionEndSoulHook();
+  } else {
+    executeSessionStartSoulHook(args);
+  }
+}

package/dist/src/slash-commands/README.md

@@ -0,0 +1,157 @@
+# CLAUDE.md Slash Command System
+
+## 🎯 Simple, Focused CLAUDE.md Generation
+
+A lightweight slash command system for generating CLAUDE.md files with NPX protection.
+
+## 📋 Features
+
+### ✅ **Simple Slash Command**
+```bash
+/claude-md                    # Generate CLAUDE.md for current project
+/claude-md --preview         # Show what would be generated
+/claude-md --force           # Overwrite without confirmation
+/claude-md --detect          # Auto-detect project and show recommendations
+/claude-md --no-backup       # Skip backup creation
+```
+
+### 🛡️ **NPX Protection System**
+- **Problem**: NPX installs overwrite customized CLAUDE.md files
+- **Solution**: Generate `claude-copy-to-main.md` when existing CLAUDE.md detected
+- **Benefit**: User customizations are never lost
+
+### 🔄 **Integration Flow**
+
+**Normal Usage (Slash Command):**
+1. User runs `/claude-md`
+2. System detects project type
+3. Generates appropriate CLAUDE.md
+4. Creates backup if file exists
+
+**NPX Install Protection:**
+1. NPX installs claude-flow-novice
+2. `postinstall` script runs
+3. Detects existing CLAUDE.md
+4. Creates `claude-copy-to-main.md` instead
+5. User manually merges desired changes
+
+## 🏗️ Architecture
+
+### **Files:**
+- `claude-md.js` - Core slash command implementation
+- `register-claude-md.js` - Slash command registration
+- `../npx/claude-md-protection.js` - NPX protection logic
+- `../../scripts/post-install-claude-md.js` - Post-install hook
+
+### **Integration Points:**
+- **Existing Generator**: Uses `../language/claude-md-generator.js`
+- **Language Detection**: Uses `../language/language-detector.js`
+- **Preferences**: Reads `.claude-flow-novice/preferences/generation.json`
+- **Package.json**: `postinstall` script triggers protection
+
+## 🎮 Usage Examples
+
+### **Basic Generation:**
+```bash
+# Generate CLAUDE.md for current project
+/claude-md
+
+# Output:
+# 🚀 Generating CLAUDE.md...
+# ✅ CLAUDE.md generated successfully
+```
+
+### **Preview Mode:**
+```bash
+# See what would be generated
+/claude-md --preview
+
+# Output:
+# 📄 CLAUDE.md Preview:
+# ══════════════════════════════════════════════════
+# # Claude Code Configuration - JavaScript Project
+# ...
+# ══════════════════════════════════════════════════
+# 📊 Total length: 2,847 characters
+```
+
+### **NPX Protection:**
+```bash
+# When NPX detects existing CLAUDE.md
+npm install claude-flow-novice
+
+# Output:
+# 🛡️ NPX Protection Activated
+# 📄 Generated: claude-copy-to-main.md
+# 💡 Your existing CLAUDE.md is protected from overwrite
+# 🔄 Review and merge changes manually as needed
+```
+
+## 🧠 Smart Detection
+
+### **Project Type Detection:**
+- Analyzes `package.json`, file patterns, and directory structure
+- Detects frameworks (React, Express, Django, etc.)
+- Suggests appropriate CLAUDE.md configurations
+
+### **Confidence Levels:**
+- **High (>70%)**: Automatic generation recommended
+- **Medium (30-70%)**: Generate with user confirmation
+- **Low (<30%)**: Manual review suggested
+
+## 🔧 Configuration
+
+### **Generation Preferences:**
+`.claude-flow-novice/preferences/generation.json`:
+```json
+{
+  "autoGenerate": true,
+  "includeFrameworkSpecific": true,
+  "includeBestPractices": true,
+  "backupExisting": true,
+  "confidenceThreshold": 0.3
+}
+```
+
+### **NPX Detection:**
+- Environment variables (`NPX_INSTALL=true`)
+- Temporary directory patterns (`/.npm/_npx/`)
+- Package.json analysis (fresh installs)
+
+## 🎯 Design Principles
+
+### **Keep It Simple:**
+- Single focused command
+- Minimal configuration
+- Clear user feedback
+- No feature bloat
+
+### **Protect User Work:**
+- Never overwrite without permission
+- Always offer backup options
+- Provide clear merge instructions
+- Preserve customizations
+
+### **Smart Defaults:**
+- Auto-detect project type
+- Use appropriate templates
+- Respect user preferences
+- Fail safely
+
+## 🚀 Future Enhancements
+
+### **Potential Improvements (If Needed):**
+- Interactive confirmation prompts
+- Template customization options
+- Multi-project detection
+- Advanced merge assistance
+
+### **Not Planned (Avoiding Bloat):**
+- SQLite analysis integration
+- Multi-file scaffolding
+- Complex workflow automation
+- Enterprise features
+
+---
+
+**Simple, focused, and protective - exactly what CLAUDE.md generation should be!** 🎯

package/dist/src/slash-commands/claude-md.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+
+/**
+ * CLAUDE.md Slash Command
+ *
+ * Simple wrapper around the existing CLAUDE.md generator with NPX protection
+ * Keeps it focused and lightweight - no bloat!
+ */
+
+import { ClaudeMdGenerator } from '../language/claude-md-generator.js';
+import { LanguageDetector } from '../language/language-detector.js';
+import fs from 'fs/promises';
+import path from 'path';
+
+export class ClaudeMdSlashCommand {
+  constructor(projectPath = process.cwd()) {
+    this.projectPath = projectPath;
+    this.claudeMdPath = path.join(projectPath, 'CLAUDE.md');
+    this.copyToMainPath = path.join(projectPath, 'claude-copy-to-main.md');
+  }
+
+  /**
+   * Main slash command execution
+   */
+  async execute(options = {}) {
+    const {
+      backup = true,
+      preview = false,
+      force = false,
+      isNpxInstall = false
+    } = options;
+
+    try {
+      console.log('🚀 Generating CLAUDE.md...');
+
+      // Step 1: Detect if this is an NPX install scenario
+      const existingClaudeExists = await this.fileExists(this.claudeMdPath);
+      const shouldUseNpxProtection = isNpxInstall && existingClaudeExists;
+
+      // Step 2: Generate content using existing system
+      const generator = new ClaudeMdGenerator(this.projectPath, {
+        backupExisting: backup && !shouldUseNpxProtection,
+        preserveCustomSections: true
+      });
+
+      const newContent = await generator.generateClaudeMd();
+
+      // Step 3: Handle NPX protection
+      if (shouldUseNpxProtection) {
+        await this.handleNpxProtection(newContent);
+        return {
+          success: true,
+          action: 'npx-protection',
+          file: 'claude-copy-to-main.md',
+          message: 'Generated claude-copy-to-main.md to protect your existing CLAUDE.md'
+        };
+      }
+
+      // Step 4: Handle preview mode
+      if (preview) {
+        return {
+          success: true,
+          action: 'preview',
+          content: newContent,
+          message: 'Preview generated successfully'
+        };
+      }
+
+      // Step 5: Handle force/confirmation for existing files
+      if (existingClaudeExists && !force) {
+        const shouldOverwrite = await this.confirmOverwrite();
+        if (!shouldOverwrite) {
+          return {
+            success: false,
+            action: 'cancelled',
+            message: 'Generation cancelled by user'
+          };
+        }
+      }
+
+      // Step 6: Write the file
+      await fs.writeFile(this.claudeMdPath, newContent, 'utf8');
+
+      console.log('✅ CLAUDE.md generated successfully');
+      return {
+        success: true,
+        action: 'generated',
+        file: 'CLAUDE.md',
+        length: newContent.length
+      };
+
+    } catch (error) {
+      console.error('❌ CLAUDE.md generation failed:', error.message);
+      return {
+        success: false,
+        action: 'error',
+        error: error.message
+      };
+    }
+  }
+
+  /**
+   * NPX Protection: Generate claude-copy-to-main.md instead of overwriting
+   */
+  async handleNpxProtection(newContent) {
+    const protectedContent = this.createProtectedContent(newContent);
+
+    await fs.writeFile(this.copyToMainPath, protectedContent, 'utf8');
+
+    console.log('🛡️ NPX Protection Activated');
+    console.log('📄 Generated: claude-copy-to-main.md');
+    console.log('💡 Your existing CLAUDE.md is protected from overwrite');
+    console.log('🔄 Review and merge changes manually as needed');
+  }
+
+  /**
+   * Create content for the protected file with merge instructions
+   */
+  createProtectedContent(newContent) {
+    return `# 🛡️ NPX-Protected CLAUDE.md Content
+
+## 📋 Merge Instructions
+
+This file was generated because you have an existing CLAUDE.md file.
+To protect your customizations from being overwritten by NPX installs,
+the new content is provided here for manual review and merging.
+
+### 🔄 How to Merge:
+1. Review the content below
+2. Copy sections you want to your main CLAUDE.md
+3. Delete this file when done
+4. Your customizations remain safe!
+
+---
+
+# Generated CLAUDE.md Content
+
+${newContent}
+
+---
+
+## 🗑️ Cleanup
+Delete this file after merging: \`rm claude-copy-to-main.md\`
+`;
+  }
+
+  /**
+   * Simple confirmation prompt for overwriting existing files
+   */
+  async confirmOverwrite() {
+    // In a real implementation, this would use readline or similar
+    // For now, return true (could be enhanced with proper prompting)
+    console.log('⚠️ CLAUDE.md exists. Use --force to overwrite or --preview to see changes.');
+    return false;
+  }
+
+  /**
+   * Check if file exists
+   */
+  async fileExists(filePath) {
+    try {
+      await fs.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Show preview of what would be generated
+   */
+  async showPreview() {
+    const result = await this.execute({ preview: true });
+
+    if (result.success) {
+      console.log('📄 CLAUDE.md Preview:');
+      console.log('━'.repeat(50));
+      console.log(result.content.substring(0, 1000) + '...');
+      console.log('━'.repeat(50));
+      console.log(`📊 Total length: ${result.content.length} characters`);
+    }
+
+    return result;
+  }
+
+  /**
+   * Auto-detect project and suggest generation
+   */
+  async autoDetectAndSuggest() {
+    const detector = new LanguageDetector(this.projectPath);
+    const detection = await detector.detectProject();
+
+    console.log('🔍 Project Detection Results:');
+    console.log(`  Type: ${detection.projectType}`);
+    console.log(`  Confidence: ${(detection.confidence * 100).toFixed(1)}%`);
+
+    if (detection.confidence > 0.7) {
+      console.log('💡 High confidence - CLAUDE.md generation recommended');
+      return true;
+    } else {
+      console.log('⚠️ Low confidence - manual review recommended');
+      return false;
+    }
+  }
+}
+
+/**
+ * CLI Interface for slash command
+ */
+export async function executeClaudeMdCommand(args = {}) {
+  const command = new ClaudeMdSlashCommand();
+
+  // Handle different command modes
+  if (args.preview) {
+    return await command.showPreview();
+  }
+
+  if (args.detect) {
+    return await command.autoDetectAndSuggest();
+  }
+
+  // Default: generate CLAUDE.md
+  return await command.execute(args);
+}
+
+// For direct execution
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = {
+    preview: process.argv.includes('--preview'),
+    force: process.argv.includes('--force'),
+    backup: !process.argv.includes('--no-backup'),
+    detect: process.argv.includes('--detect'),
+    isNpxInstall: process.env.NPX_INSTALL === 'true'
+  };
+
+  executeClaudeMdCommand(args);
+}