cntx-ui 2.0.13 → 3.0.0

package/bin/cntx-ui.js

@@ -1,9 +1,17 @@
 #!/usr/bin/env node
 
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
 import { startServer, startMCPServer, generateBundle, initConfig, getStatus, setupMCP } from '../server.js';
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packagePath = join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(readFileSync(packagePath, 'utf8'));
+
 const args = process.argv.slice(2);
-const command = args[0] || 'watch';
+const command = args[0] || 'help';
+const isVerbose = args.includes('--verbose');
 
 // Graceful shutdown
 process.on('SIGINT', () => {
@@ -11,63 +19,138 @@ process.on('SIGINT', () => {
   process.exit(0);
 });
 
-switch (command) {
-  case 'watch':
-    const port = parseInt(args[1]) || 3333;
-    const withMcp = args.includes('--with-mcp');
-    startServer({ port, withMcp });
-    break;
-
-  case 'mcp':
-    // MCP server mode - runs on stdio
-    startMCPServer({ cwd: process.cwd() });
-    break;
-
-  case 'bundle':
-    const bundleName = args[1] || 'master';
-    try {
-      generateBundle(bundleName);
-      console.log(`✅ Bundle '${bundleName}' generated`);
-    } catch (e) {
-      console.error(`❌ Bundle '${bundleName}' not found`);
-    }
-    break;
+function showHelp() {
+  console.log(`cntx-ui v${packageJson.version}
 
-  case 'init':
-    initConfig();
-    break;
+${packageJson.description}
 
-  case 'status':
-    getStatus();
-    break;
+Usage:
+  cntx-ui <command> [options]
 
-  case 'setup-mcp':
-    setupMCP();
-    break;
+Commands:
+  init                        Initialize configuration in current directory
+  watch [port]                Start web server (default port: 3333)
+  mcp                         Start MCP server (stdio transport)
+  bundle [name]               Generate specific bundle (default: master)
+  status                      Show current project status
+  setup-mcp                   Add this project to Claude Desktop MCP config
+
+Options:
+  --verbose                   Enable detailed logging
+  --with-mcp                  Start web server with MCP status tracking
+  --version, -v               Show version number
+  --help, -h                  Show this help message
 
-  default:
-    console.log(`cntx-ui v2.0.8
-        
-Usage:
-  cntx-ui init                Initialize configuration
-  cntx-ui watch [port]        Start web server (default port: 3333)
-  cntx-ui watch --with-mcp    Start web server with MCP status tracking
-  cntx-ui mcp                 Start MCP server (stdio transport)
-  cntx-ui setup-mcp           Add this project to Claude Desktop MCP config
-  cntx-ui bundle [name]       Generate specific bundle (default: master)
-  cntx-ui status              Show current status
-  
 Examples:
-  cntx-ui init
-  cntx-ui watch 8080
-  cntx-ui watch --with-mcp
-  cntx-ui setup-mcp
-  cntx-ui mcp
-  cntx-ui bundle api
-
-MCP Usage:
-  The MCP server provides AI-accessible bundle management:
-  - Resources: Access bundles and files via cntx:// URIs
-  - Tools: List bundles, generate bundles, get project status
-  - Integration: Use with Claude Desktop, Cursor, or other MCP clients`);
+  cntx-ui init                Initialize a new project
+  cntx-ui watch               Start web server on port 3333
+  cntx-ui watch 8080          Start web server on port 8080
+  cntx-ui watch --verbose     Start with detailed logs
+  cntx-ui watch --with-mcp    Start with MCP integration
+  cntx-ui bundle api          Generate 'api' bundle
+  cntx-ui status              Show project status
+  cntx-ui setup-mcp           Configure Claude Desktop integration
+
+MCP Integration:
+  The MCP server provides AI-accessible bundle management for Claude Desktop
+  and other MCP-compatible clients. Use 'setup-mcp' to configure automatic
+  integration with Claude Desktop.
+
+Agent Collaboration:
+  To get an external agent up to speed with your project, use this prompt:
+
+  "I'm working in a project that uses cntx-ui for file organization and AI 
+  collaboration. Please read these files to understand the project structure 
+  and help me with activities:
+
+  @.cntx/agent-instructions.md
+  @.cntx/activities/README.md  
+  @.cntx/activities/activities.json
+
+  After reading those, please also examine:
+  @.cntx/activities/lib/create-activity.mdc
+  @.cntx/activities/lib/generate-tasks.mdc
+  @.cntx/activities/lib/process-task-list.mdc
+
+  These files contain the complete workflow for creating and managing 
+  activities with agent assistance."
+
+Repository: ${packageJson.repository.url}
+Author: ${packageJson.author}
+License: ${packageJson.license}`);
+}
+
+function showVersion() {
+  console.log(`cntx-ui v${packageJson.version}`);
 }
+
+async function main() {
+  // Handle version flags
+  if (args.includes('--version') || args.includes('-v')) {
+    return showVersion();
+  }
+
+  // Handle help flags
+  if (args.includes('--help') || args.includes('-h') || command === 'help') {
+    return showHelp();
+  }
+
+  // Handle default command (watch if no command provided and no flags)
+  const actualCommand = command === 'help' ? 'watch' : command;
+
+  try {
+    switch (actualCommand) {
+      case 'watch':
+      case 'w':
+        const port = parseInt(args[1]) || 3333;
+        // Enable MCP status tracking by default for the web dashboard
+        const withMcp = !args.includes('--no-mcp');
+        await startServer({ port, withMcp, verbose: isVerbose });
+        break;
+
+      case 'mcp':
+        // MCP server mode - runs on stdio
+        await startMCPServer({ cwd: process.cwd(), verbose: isVerbose });
+        break;
+
+      case 'bundle':
+      case 'b':
+        const bundleName = args[1] || 'master';
+        try {
+          await generateBundle(bundleName);
+          console.log(`✅ Bundle '${bundleName}' generated successfully`);
+        } catch (error) {
+          console.error(`❌ Failed to generate bundle '${bundleName}': ${error.message}`);
+          process.exit(1);
+        }
+        break;
+
+      case 'init':
+      case 'i':
+        await initConfig();
+        break;
+
+      case 'status':
+      case 's':
+        await getStatus();
+        break;
+
+      case 'setup-mcp':
+        setupMCP();
+        break;
+
+      default:
+        console.error(`❌ Unknown command: ${command}`);
+        console.log('Run "cntx-ui --help" for usage information.');
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error(`❌ Error: ${error.message}`);
+    if (isVerbose) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+main().catch(console.error);

package/lib/agent-runtime.js

@@ -0,0 +1,301 @@
+/**
+ * Agent Runtime for Codebase Exploration and Development
+ * Now stateful with SQLite-based working memory
+ */
+
+import AgentTools from './agent-tools.js';
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+export class AgentRuntime {
+  constructor(cntxServer) {
+    this.cntxServer = cntxServer;
+    this.db = cntxServer.databaseManager;
+    this.tools = new AgentTools(cntxServer);
+    this.currentSessionId = null;
+  }
+
+  /**
+   * Initialize or resume a session
+   */
+  async startSession(id = null, title = 'New Exploration') {
+    this.currentSessionId = id || crypto.randomUUID();
+    this.db.createSession(this.currentSessionId, title);
+    // Refresh manifest when a new session starts
+    await this.generateAgentManifest();
+    return this.currentSessionId;
+  }
+
+  /**
+   * Generates a .cntx/AGENT.md manifest for machine consumption
+   */
+  async generateAgentManifest() {
+    const overview = await this.getCodebaseOverview();
+    const summary = await this.getSemanticSummary();
+    const bundles = await this.analyzeBundles('all');
+    
+    // Auto-generate tool reference from MCP server
+    let toolsReference = '';
+    if (this.cntxServer.mcpServer) {
+      const tools = this.cntxServer.mcpServer.getToolDefinitions();
+      toolsReference = tools.map(t => {
+        let params = [];
+        if (t.inputSchema?.properties) {
+          params = Object.entries(t.inputSchema.properties).map(([name, prop]) => {
+            const isReq = t.inputSchema.required?.includes(name) ? 'required' : 'optional';
+            return `\`${name}\` (${prop.type}, ${isReq}): ${prop.description}`;
+          });
+        }
+        return `### \`${t.name}\`\n${t.description}\n${params.length > 0 ? '**Parameters:**\n- ' + params.join('\n- ') : '*No parameters required*'}\n`;
+      }).join('\n');
+    }
+
+    const manifest = `# 🤖 Agent Handshake: ${overview.projectPath.split('/').pop()}
+
+## Project Overview
+- **Path:** \`${overview.projectPath}\`
+- **Total Files:** ${overview.totalFiles}
+- **Semantic Intelligence:** ${summary.totalChunks} persistent chunks indexed.
+
+## Codebase Organization (Bundles)
+${bundles.map(b => `- **${b.name}**: ${b.purpose} (${b.fileCount} files)`).join('\n')}
+
+## Intelligence Interface (MCP Tools)
+You have access to a specialized "Repository Intelligence" engine. Use these tools for high-signal exploration:
+
+${toolsReference || '*(MCP Server not yet initialized, tools will appear here)*'}
+
+---
+
+## 🛠 Complete Tool & API Reference
+Refer to the dynamic reference below for full parameter schemas and HTTP fallback endpoints.
+
+${fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), '../templates/TOOLS.md'), 'utf8')}
+
+## Working Memory
+This agent is **stateful**. All interactions in this directory are logged to a persistent SQLite database (\`.cntx/bundles.db\`), allowing for context retention across sessions.
+
+---
+*Generated automatically by cntx-ui. Optimized for LLM consumption.*
+`;
+
+    const manifestPath = path.join(this.cntxServer.CNTX_DIR, 'AGENT.md');
+    fs.writeFileSync(manifestPath, manifest, 'utf8');
+    if (this.cntxServer.verbose) console.log('📄 Agent manifest updated: .cntx/AGENT.md');
+  }
+
+  /**
+   * Log an interaction to the agent's memory
+   */
+  async logInteraction(role, content, metadata = {}) {
+    if (!this.currentSessionId) await this.startSession();
+    this.db.addMessage(this.currentSessionId, role, content, metadata);
+  }
+
+  /**
+   * Discovery Mode: "Tell me about this codebase"
+   * Now logs the discovery process to memory
+   */
+  async discoverCodebase(options = {}) {
+    const { scope = 'all', includeDetails = true } = options;
+    
+    try {
+      await this.logInteraction('agent', `Starting codebase discovery for scope: ${scope}`);
+      
+      const discovery = {
+        overview: await this.getCodebaseOverview(),
+        bundles: await this.analyzeBundles(scope),
+        architecture: await this.analyzeArchitecture(),
+        patterns: await this.identifyPatterns(),
+        recommendations: []
+      };
+
+      if (includeDetails) {
+        discovery.semanticSummary = await this.getSemanticSummary();
+        discovery.fileTypes = await this.analyzeFileTypes();
+        discovery.complexity = await this.analyzeComplexity();
+      }
+
+      discovery.recommendations = await this.generateDiscoveryRecommendations(discovery);
+      
+      await this.logInteraction('agent', `Discovery complete. Found ${discovery.overview.totalFiles} files.`, { discovery });
+
+      return discovery;
+    } catch (error) {
+      await this.logInteraction('agent', `Discovery failed: ${error.message}`);
+      throw new Error(`Discovery failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Query Mode: "Where is the user authentication handled?"
+   * Now recalls previous context from SQLite
+   */
+  async answerQuery(question, options = {}) {
+    const { scope = null, maxResults = 10, includeCode = false } = options;
+
+    try {
+      await this.logInteraction('user', question);
+      
+      // Perform semantic search via Vector Store
+      const combinedResults = await this.cntxServer.vectorStore.search(question, { limit: maxResults });
+
+      // Generate contextual answer
+      const answer = await this.generateContextualAnswer(question, { chunks: combinedResults, files: [] }, includeCode);
+
+      const response = {
+        question,
+        answer: answer.response,
+        evidence: answer.evidence,
+        confidence: answer.confidence,
+        relatedFiles: [...new Set(combinedResults.map(c => c.filePath))].slice(0, 5)
+      };
+
+      await this.logInteraction('agent', response.answer, { response });
+
+      return response;
+    } catch (error) {
+      throw new Error(`Query failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Feature Investigation Mode: Now persists the investigation approach
+   */
+  async investigateFeature(featureDescription, options = {}) {
+    const { includeRecommendations = true } = options;
+
+    try {
+      await this.logInteraction('user', `Investigating feature: ${featureDescription}`);
+      
+      const investigation = {
+        feature: featureDescription,
+        existing: await this.findExistingImplementations(featureDescription),
+        related: await this.findRelatedCode(featureDescription),
+        integration: await this.findIntegrationPoints(featureDescription)
+      };
+
+      if (includeRecommendations) {
+        investigation.approach = await this.suggestImplementationApproach(investigation);
+      }
+
+      await this.logInteraction('agent', `Investigation complete for ${featureDescription}`, { investigation });
+
+      return investigation;
+    } catch (error) {
+      throw new Error(`Feature investigation failed: ${error.message}`);
+    }
+  }
+
+  // --- Helper Methods (reusing your existing logic but streamlined) ---
+
+  async getCodebaseOverview() {
+    const bundles = Array.from(this.cntxServer.bundleManager.getAllBundleInfo());
+    const totalFiles = bundles.reduce((sum, b) => sum + b.fileCount, 0);
+    const totalSize = bundles.reduce((sum, b) => sum + b.size, 0);
+
+    return {
+      projectPath: this.cntxServer.CWD,
+      totalBundles: bundles.length,
+      totalFiles,
+      totalSize,
+      bundleNames: bundles.map(b => b.name)
+    };
+  }
+
+  async analyzeBundles(scope) {
+    const bundles = this.cntxServer.bundleManager.getAllBundleInfo();
+    const filtered = scope === 'all' ? bundles : bundles.filter(b => b.name === scope);
+    
+    return filtered.map(b => ({
+      ...b,
+      purpose: this.inferBundlePurpose(b.name, b.files)
+    }));
+  }
+
+  inferBundlePurpose(name, files) {
+    if (name.includes('component') || name.includes('ui')) return 'UI Components';
+    if (name.includes('api') || name.includes('server')) return 'Backend API';
+    return 'General Module';
+  }
+
+  async analyzeArchitecture() {
+    return {
+      type: 'Dynamic Architecture',
+      timestamp: new Date().toISOString()
+    };
+  }
+
+  async identifyPatterns() {
+    return {
+      coding: 'Modern Node.js',
+      style: 'Functional / Modular'
+    };
+  }
+
+  async getSemanticSummary() {
+    const chunks = this.db.db.prepare('SELECT COUNT(*) as count FROM semantic_chunks').get();
+    return { totalChunks: chunks.count };
+  }
+
+  async analyzeFileTypes() {
+    const rows = this.db.db.prepare('SELECT file_path FROM semantic_chunks').all();
+    const exts = {};
+    rows.forEach(r => {
+      const ext = r.file_path.split('.').pop();
+      exts[ext] = (exts[ext] || 0) + 1;
+    });
+    return exts;
+  }
+
+  async analyzeComplexity() {
+    const rows = this.db.db.prepare('SELECT complexity_score FROM semantic_chunks').all();
+    const scores = { low: 0, medium: 0, high: 0 };
+    rows.forEach(r => {
+      if (r.complexity_score < 5) scores.low++;
+      else if (r.complexity_score < 15) scores.medium++;
+      else scores.high++;
+    });
+    return scores;
+  }
+
+  async generateDiscoveryRecommendations() {
+    return [{ type: 'info', message: 'Continue organizing by semantic purpose.' }];
+  }
+
+  async findExistingImplementations(featureDescription) {
+    return await this.cntxServer.vectorStore.search(featureDescription, { limit: 5 });
+  }
+
+  async findRelatedCode(featureDescription) {
+    return [];
+  }
+
+  async findIntegrationPoints(featureDescription) {
+    return [];
+  }
+
+  async suggestImplementationApproach(investigation) {
+    return { strategy: 'TBD', description: 'Ready to plan' };
+  }
+
+  async generateContextualAnswer(question, results, includeCode) {
+    let response = `Based on the codebase analysis:\n\n`;
+    if (results.chunks.length > 0) {
+      const top = results.chunks[0];
+      response += `The most relevant implementation found is \`${top.name}\` in \`${top.filePath}\` (Purpose: ${top.purpose}).\n\n`;
+    } else {
+      response += `No direct semantic matches found. Try refining your query.`;
+    }
+
+    return {
+      response,
+      evidence: results.chunks.slice(0, 3),
+      confidence: results.chunks.length > 0 ? 0.8 : 0.2
+    };
+  }
+}
+
+export default AgentRuntime;