claude-flow-novice 1.1.7 → 1.1.9

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

@@ -1,17 +1,10 @@
 #!/usr/bin/env node
 /**
- * Claude-Flow Novice MCP Server - SIMPLIFIED VERSION
+ * Claude-Flow Novice MCP Server - SIMPLIFIED STANDALONE VERSION
  * Only 36 essential tools for beginners
- * 80% complexity reduction while preserving core capabilities
+ * No external dependencies, completely self-contained
  */
 
-import { promises as fs } from 'fs';
-import path from 'path';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
 class ClaudeFlowNoviceMCPServer {
   constructor() {
     this.version = '2.0.0-novice-simplified';
@@ -396,7 +389,6 @@ class ClaudeFlowNoviceMCPServer {
 
   initializeResources() {
     return {
-      // Simple resource definitions for novice users
       'memory://sessions': {
         uri: 'memory://sessions',
         name: 'Memory Sessions',
@@ -443,7 +435,8 @@ class ClaudeFlowNoviceMCPServer {
   }
 
   handleInitialize(params) {
-    console.error(`[${new Date().toISOString()}] INFO [claude-flow-novice-mcp] (${this.sessionId}) Initialized with ${Object.keys(this.tools).length} tools`);
+    const toolCount = Object.keys(this.tools).length;
+    console.error(`[${new Date().toISOString()}] INFO [claude-flow-novice-mcp] (${this.sessionId}) Initialized with ${toolCount} tools`);
     return {
       protocolVersion: '2024-11-05',
       capabilities: this.capabilities,
@@ -469,8 +462,6 @@ class ClaudeFlowNoviceMCPServer {
 
     console.error(`[${new Date().toISOString()}] INFO [claude-flow-novice-mcp] (${this.sessionId}) Executing tool: ${name}`);
 
-    // Simple mock implementations for demonstration
-    // In a real implementation, these would call actual functionality
     const result = {
       success: true,
       tool: name,
@@ -570,9 +561,18 @@ async function main() {
     process.exit(0);
   });
 
-  console.error(`[${new Date().toISOString()}] INFO [claude-flow-novice-mcp] Server starting with 36 essential tools`);
+  const toolCount = Object.keys(server.tools).length;
+  console.error(`[${new Date().toISOString()}] INFO [claude-flow-novice-mcp] Server starting with ${toolCount} essential tools`);
 }
 
+// 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}`);

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!** 🎯