cntx-ui 3.0.8 → 3.1.0

package/dist/bin/cntx-ui.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+import { readFileSync, existsSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { startServer, initConfig, getStatus, setupMCP, generateBundle } from '../server.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+let packagePath = join(__dirname, '..', 'package.json');
+if (!existsSync(packagePath)) {
+    packagePath = join(__dirname, '..', '..', 'package.json');
+}
+const packageJson = JSON.parse(readFileSync(packagePath, 'utf8'));
+const args = process.argv.slice(2);
+const command = args[0] || 'help';
+const isVerbose = args.includes('--verbose');
+// Graceful shutdown
+process.on('SIGINT', () => {
+    console.log('\n👋 Shutting down cntx-ui...');
+    process.exit(0);
+});
+async function main() {
+    try {
+        const actualCommand = command === 'w' ? 'watch' : command;
+        switch (actualCommand) {
+            case 'watch':
+                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 'init':
+                console.log('🚀 Initializing cntx-ui...');
+                await initConfig();
+                break;
+            case 'mcp':
+                await startServer({ withMcp: true, skipFileWatcher: true, skipBundleGeneration: true });
+                break;
+            case 'bundle':
+                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 'status':
+                await getStatus();
+                break;
+            case 'setup-mcp':
+                setupMCP();
+                break;
+            case 'version':
+            case '-v':
+            case '--version':
+                console.log(`v${packageJson.version}`);
+                break;
+            case 'help':
+            default:
+                console.log(`
+cntx-ui v${packageJson.version} - Repository Intelligence engine
+
+Usage:
+  cntx-ui watch [port]    Start the visual dashboard and intelligence engine (default: 3333)
+  cntx-ui init            Initialize cntx-ui configuration in the current directory
+  cntx-ui mcp             Start the Model Context Protocol (MCP) server on stdio
+  cntx-ui bundle [name]   Generate specific bundle (default: master)
+  cntx-ui status          Show current project status
+  cntx-ui setup-mcp       Add this project to Claude Desktop MCP config
+  cntx-ui version         Show current version
+  cntx-ui help            Show this help information
+
+Options:
+  --verbose               Show detailed logging
+  --no-mcp                Disable MCP server when running watch
+        `);
+                break;
+        }
+    }
+    catch (error) {
+        console.error(`❌ Error: ${error.message}`);
+        if (isVerbose) {
+            console.error(error.stack);
+        }
+        process.exit(1);
+    }
+}
+main().catch(console.error);

package/dist/lib/agent-runtime.js

@@ -0,0 +1,269 @@
+/**
+ * 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 {
+    cntxServer;
+    db;
+    tools;
+    currentSessionId;
+    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();
+            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 { 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 ---
+    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() || 'unknown';
+            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;

package/dist/lib/agent-tools.js

@@ -0,0 +1,162 @@
+/**
+ * Agent Tools for Codebase Exploration
+ * Built on top of existing cntx-ui infrastructure
+ */
+import { existsSync, statSync } from 'fs';
+import { join, relative } from 'path';
+import path from 'path';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+const execAsync = promisify(exec);
+export default class AgentTools {
+    cntxServer;
+    constructor(cntxServer) {
+        this.cntxServer = cntxServer;
+    }
+    /**
+     * Execute a shell command within the project context
+     */
+    async executeCommand(command) {
+        try {
+            const { stdout, stderr } = await execAsync(command, { cwd: this.cntxServer.CWD });
+            return { stdout, stderr };
+        }
+        catch (error) {
+            return { error: error.message, stdout: error.stdout, stderr: error.stderr };
+        }
+    }
+    /**
+     * List files in a directory, respecting ignore patterns
+     */
+    async listFiles(dirPath = '.') {
+        try {
+            const absolutePath = join(this.cntxServer.CWD, dirPath);
+            if (!existsSync(absolutePath)) {
+                return { error: `Directory not found: ${dirPath}` };
+            }
+            const files = this.cntxServer.fileSystemManager.getAllFiles(absolutePath);
+            return files.map(f => relative(this.cntxServer.CWD, f));
+        }
+        catch (error) {
+            return { error: error.message };
+        }
+    }
+    /**
+     * Search for code chunks based on semantic similarity or text matching
+     */
+    async searchChunks(query, options = {}) {
+        const { maxResults = 10 } = options;
+        try {
+            let chunks = [];
+            // Try semantic search if vector store is initialized
+            if (this.cntxServer.vectorStoreInitialized) {
+                try {
+                    const searchResults = await this.cntxServer.vectorStore.search(query, { limit: maxResults * 2 });
+                    const chunkIds = searchResults.map(r => r.id || r.chunkId).filter(Boolean);
+                    const allChunks = await this.cntxServer.getSemanticAnalysis();
+                    chunks = allChunks.chunks.filter((c) => chunkIds.includes(c.id));
+                }
+                catch (error) {
+                    console.warn('Semantic search failed, falling back to text search:', error);
+                }
+            }
+            // Fallback or combine with text search if needed
+            if (chunks.length < maxResults) {
+                const allChunks = await this.cntxServer.getSemanticAnalysis();
+                const textResults = allChunks.chunks.filter((c) => c.name.toLowerCase().includes(query.toLowerCase()) ||
+                    c.purpose.toLowerCase().includes(query.toLowerCase()) ||
+                    c.code.toLowerCase().includes(query.toLowerCase()));
+                // Merge and deduplicate
+                const seenIds = new Set(chunks.map(c => c.id));
+                for (const chunk of textResults) {
+                    if (!seenIds.has(chunk.id)) {
+                        chunks.push(chunk);
+                        if (chunks.length >= maxResults * 2)
+                            break;
+                    }
+                }
+            }
+            return chunks.slice(0, maxResults);
+        }
+        catch (error) {
+            return { error: error.message };
+        }
+    }
+    /**
+     * Get technical metadata for a file
+     */
+    async getFileMetadata(filePath) {
+        try {
+            const fullPath = join(this.cntxServer.CWD, filePath);
+            if (!existsSync(fullPath)) {
+                return { error: `File not found: ${filePath}` };
+            }
+            const stats = statSync(fullPath);
+            const chunks = this.cntxServer.databaseManager.getChunksByFile(filePath);
+            return {
+                path: filePath,
+                size: stats.size,
+                modified: stats.mtime,
+                type: this.getFileType(filePath),
+                semanticChunks: chunks.length,
+                complexity: chunks.reduce((sum, c) => sum + (c.complexity?.score || 0), 0)
+            };
+        }
+        catch (error) {
+            return { error: error.message };
+        }
+    }
+    // --- Helper Methods ---
+    getFileSize(filePath) {
+        try {
+            const fullPath = join(this.cntxServer.CWD, filePath);
+            const stats = statSync(fullPath);
+            return stats.size;
+        }
+        catch {
+            return 0;
+        }
+    }
+    getFileType(filePath) {
+        const ext = path.extname(filePath).toLowerCase();
+        const typeMap = {
+            '.js': 'javascript',
+            '.jsx': 'javascript',
+            '.ts': 'typescript',
+            '.tsx': 'typescript',
+            '.py': 'python',
+            '.rs': 'rust',
+            '.go': 'go',
+            '.java': 'java',
+            '.cpp': 'cpp',
+            '.c': 'c',
+            '.md': 'markdown',
+            '.json': 'json',
+            '.yaml': 'yaml',
+            '.yml': 'yaml',
+            '.toml': 'toml'
+        };
+        return typeMap[ext] || 'text';
+    }
+    getMimeType(filePath) {
+        const ext = path.extname(filePath).toLowerCase();
+        const mimeTypes = {
+            '.js': 'application/javascript',
+            '.jsx': 'application/javascript',
+            '.ts': 'application/typescript',
+            '.tsx': 'application/typescript',
+            '.json': 'application/json',
+            '.md': 'text/markdown',
+            '.html': 'text/html',
+            '.css': 'text/css',
+            '.txt': 'text/plain',
+            '.rs': 'text/x-rust'
+        };
+        return mimeTypes[ext] || 'text/plain';
+    }
+    truncateContent(content, maxLength = 1000) {
+        if (!content || content.length <= maxLength)
+            return content;
+        return content.substring(0, maxLength) + '...';
+    }
+}