@indiccoder/mentis-cli 1.1.3 → 1.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiccoder/mentis-cli",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "publishConfig": {
     "access": "public"
   },
@@ -12,7 +12,9 @@
   "scripts": {
     "build": "tsc",
     "start": "node dist/index.js",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
   },
   "keywords": [
     "cli",
@@ -36,6 +38,7 @@
     "cli-cursor": "^5.0.0",
     "cli-highlight": "^2.1.11",
     "commander": "^14.0.2",
+    "diff": "^8.0.3",
     "dotenv": "^17.2.3",
     "duck-duck-scrape": "^2.2.7",
     "fast-glob": "^3.3.3",
@@ -60,7 +63,36 @@
     "@types/fs-extra": "^11.0.4",
     "@types/gradient-string": "^1.1.6",
     "@types/inquirer": "^9.0.9",
+    "@types/jest": "^30.0.0",
     "@types/node": "^25.0.2",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6",
     "typescript": "^5.9.3"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "roots": [
+      "<rootDir>/src"
+    ],
+    "testMatch": [
+      "**/__tests__/**/*.ts",
+      "**/?(*.)+(spec|test).ts"
+    ],
+    "collectCoverageFrom": [
+      "src/**/*.ts",
+      "!src/**/*.d.ts"
+    ],
+    "transformIgnorePatterns": [
+      "node_modules/(?!(chalk)/)"
+    ],
+    "coverageThreshold": {
+      "global": {
+        "branches": 20,
+        "functions": 30,
+        "lines": 30,
+        "statements": 30
+      }
+    }
   }
 }

package/scripts/test_exa_mcp.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+/**
+ * Test script for Exa MCP server integration
+ * This script demonstrates how to use the Exa MCP server for web search
+ */
+
+import { McpManager } from '../src/mcp/McpManager';
+import chalk from 'chalk';
+
+async function testExaMcp() {
+    console.log(chalk.cyan.bold('Testing Exa MCP Server Integration\n'));
+
+    const mcpManager = new McpManager();
+
+    try {
+        // Check if Exa API key is available
+        if (!process.env.EXA_API_KEY) {
+            console.log(chalk.yellow('⚠️  EXA_API_KEY environment variable not set.'));
+            console.log(chalk.dim('Set it with: export EXA_API_KEY=your_api_key'));
+            console.log(chalk.dim('Or the MCP server will prompt you for it.\n'));
+        }
+
+        // Connect to Exa Search server
+        console.log(chalk.blue('Connecting to Exa Search MCP server...'));
+        const connection = await mcpManager.connectToServer('Exa Search');
+
+        if (!connection) {
+            console.log(chalk.red('❌ Failed to connect to Exa Search server'));
+            return;
+        }
+
+        console.log(chalk.green('✅ Successfully connected to Exa Search!'));
+
+        // List available tools
+        const tools = connection.tools;
+        console.log(chalk.blue(`\n📦 Available tools (${tools.length}):`));
+        
+        for (const tool of tools) {
+            console.log(chalk.dim(`  • ${chalk.cyan(tool.name)}: ${tool.description}`));
+        }
+
+        // Test a search if search tool is available
+        const searchTool = tools.find(t => t.name.toLowerCase().includes('search'));
+        if (searchTool) {
+            console.log(chalk.blue(`\n🔍 Testing ${searchTool.name}...`));
+            
+            try {
+                const result = await searchTool.execute({
+                    query: 'Mentis CLI MCP integration',
+                    count: 3
+                });
+                
+                console.log(chalk.green('✅ Search executed successfully!'));
+                console.log(chalk.dim('\nSearch results preview:'));
+                console.log(result.substring(0, 500) + (result.length > 500 ? '...' : ''));
+            } catch (error: any) {
+                console.log(chalk.red(`❌ Search failed: ${error.message}`));
+            }
+        }
+
+        // List all configured servers
+        console.log(chalk.blue('\n📋 All configured MCP servers:'));
+        await mcpManager.listServers();
+
+        // Test connection health
+        console.log(chalk.blue('\n🏥 Testing connection health...'));
+        const isHealthy = await mcpManager.testConnection('Exa Search');
+        console.log(isHealthy ? 
+            chalk.green('✅ Connection is healthy') : 
+            chalk.red('❌ Connection test failed')
+        );
+
+        // Disconnect
+        console.log(chalk.blue('\n🔌 Disconnecting...'));
+        await mcpManager.disconnectFromServer('Exa Search');
+        console.log(chalk.green('✅ Disconnected successfully'));
+
+    } catch (error: any) {
+        console.error(chalk.red(`❌ Error: ${error.message}`));
+        process.exit(1);
+    }
+}
+
+// Run the test
+if (require.main === module) {
+    testExaMcp().catch(console.error);
+}
+
+export { testExaMcp };

package/src/checkpoint/CheckpointManager.ts

@@ -58,4 +58,106 @@ export class CheckpointManager {
         const filePath = path.join(this.checkpointDir, `${name}.json`);
         return fs.existsSync(filePath);
     }
+
+    // ─── Per-Directory Local Session Methods ───────────────────────────────
+
+    private getLocalSessionsDir(cwd: string): string {
+        return path.join(cwd, '.mentis', 'sessions');
+    }
+
+    public saveLocalSession(cwd: string, history: ChatMessage[], files: string[]): string {
+        const timestamp = Date.now();
+        const checkpoint: Checkpoint = {
+            timestamp,
+            name: `session-${timestamp}`,
+            history,
+            files
+        };
+        const sessionsDir = this.getLocalSessionsDir(cwd);
+        fs.ensureDirSync(sessionsDir);
+        const filePath = path.join(sessionsDir, `${timestamp}.json`);
+        fs.writeJsonSync(filePath, checkpoint, { spaces: 2 });
+        return filePath;
+    }
+
+    public loadLocalSession(cwd: string, sessionId?: string): Checkpoint | null {
+        const sessionsDir = this.getLocalSessionsDir(cwd);
+        if (!fs.existsSync(sessionsDir)) return null;
+
+        let filePath: string;
+        if (sessionId) {
+            filePath = path.join(sessionsDir, `${sessionId}.json`);
+        } else {
+            // Load most recent
+            const sessions = this.listLocalSessions(cwd);
+            if (sessions.length === 0) return null;
+            filePath = path.join(sessionsDir, `${sessions[0].id}.json`);
+        }
+
+        if (fs.existsSync(filePath)) {
+            return fs.readJsonSync(filePath) as Checkpoint;
+        }
+        return null;
+    }
+
+    public listLocalSessions(cwd: string): Array<{ id: string; timestamp: number; messageCount: number; preview: string }> {
+        const sessionsDir = this.getLocalSessionsDir(cwd);
+        if (!fs.existsSync(sessionsDir)) return [];
+
+        const files = fs.readdirSync(sessionsDir);
+
+        return files
+            .filter(f => f.endsWith('.json'))
+            .map(f => {
+                const filePath = path.join(sessionsDir, f);
+                try {
+                    const data = fs.readJsonSync(filePath) as Checkpoint;
+                    // Extract meaningful preview from LAST user message (to show current state)
+                    const lastUserMsg = [...(data.history || [])].reverse().find(m => m.role === 'user');
+                    let preview = 'No preview';
+                    if (lastUserMsg?.content) {
+                        let clean = lastUserMsg.content;
+
+                        // 1. Remove Repository Structure (explicitly)
+                        clean = clean.replace(/Repository Structure:[\s\S]*?(?=\n\n|$)/g, '');
+
+                        // 2. Remove "User Question:" label (if context insertion logic used it)
+                        clean = clean.replace(/User Question:\s*/g, '');
+
+                        // 3. Remove "Available Custom Commands" block
+                        clean = clean.replace(/Available Custom Commands:[\s\S]*?(?=\n\n|$)/g, '');
+
+                        // 4. Remove "Available Skills" block (if present)
+                        clean = clean.replace(/Available Skills \([\s\S]*?(?=\n\n|$)/g, '');
+                        clean = clean.replace(/Available Skills:[\s\S]*?(?=\n\n|$)/g, '');
+
+                        // 5. Remove [SYSTEM: ...] instructions at the end
+                        clean = clean.replace(/\n\[SYSTEM:[\s\S]*?\]$/g, '');
+
+                        // 6. Clean up code blocks references/markdown if they were just context
+                        const text = clean.trim();
+                        if (text) {
+                            // Take the first 50 chars of what's left
+                            preview = text.substring(0, 50).replace(/\n/g, ' ');
+                        } else {
+                            preview = 'New Session';
+                        }
+                    }
+                    return {
+                        id: f.replace('.json', ''),
+                        timestamp: data.timestamp,
+                        messageCount: data.history?.length || 0,
+                        preview: preview.length >= 50 ? preview + '...' : preview
+                    };
+                } catch {
+                    return null;
+                }
+            })
+            .filter((s): s is { id: string; timestamp: number; messageCount: number; preview: string } => s !== null)
+            .sort((a, b) => b.timestamp - a.timestamp); // Most recent first
+    }
+
+    public localSessionExists(cwd: string): boolean {
+        return this.listLocalSessions(cwd).length > 0;
+    }
 }

package/src/commands/Command.ts

@@ -1,40 +1,91 @@
 /**
  * Custom Slash Commands System
- * Users can define their own slash commands as markdown files
+ *
+ * Users can define their own slash commands as markdown files with YAML frontmatter.
+ * Commands support parameter substitution, bash execution, and file references.
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```markdown
+ * ---
+ * description: Run tests and show coverage
+ * argument-hint: [test-pattern]
+ * ---
+ *
+ * Run tests with !`npm test $1`
+ * ```
  */
 
+/**
+ * YAML frontmatter options for custom commands
+ */
 export interface CommandFrontmatter {
+    /** Human-readable description of what the command does */
     description?: string;
+    /** Restrict which tools the AI can use when executing this command */
     'allowed-tools'?: string[];
+    /** Hint shown to user about expected arguments (e.g., "[pattern]") */
     'argument-hint'?: string;
+    /** Specific model to use for this command */
     model?: string;
+    /** Disable AI model invocation (execute bash/reads only) */
     'disable-model-invocation'?: boolean;
 }
 
+/**
+ * A custom slash command
+ */
 export interface Command {
-    name: string;              // Command name (from filename)
-    type: 'personal' | 'project';  // Personal or project command
-    path: string;               // Path to command file
-    directory: string;          // Directory containing the command
+    /** Command name (derived from filename, without .md extension) */
+    name: string;
+    /** Whether this is a personal or project-level command */
+    type: 'personal' | 'project';
+    /** Absolute path to the command's .md file */
+    path: string;
+    /** Directory containing the command file */
+    directory: string;
+    /** Parsed YAML frontmatter from the command file */
     frontmatter: CommandFrontmatter;
-    content: string;            // Command content (markdown)
-    description: string;        // Command description
-    hasParameters: boolean;     // Whether command uses parameters
+    /** Raw markdown content of the command */
+    content: string;
+    /** Human-readable description for display */
+    description: string;
+    /** Whether the command uses $1, $2, or $ARGUMENTS placeholders */
+    hasParameters: boolean;
 }
 
+/**
+ * Execution context for running a custom command
+ */
 export interface CommandExecutionContext {
+    /** The command being executed */
     command: Command;
-    args: string[];             // Command arguments
+    /** Arguments passed to the command */
+    args: string[];
+    /** Function to substitute $1, $2, $ARGUMENTS placeholders */
     substitutePlaceholders: (content: string, args: string[]) => string;
+    /** Function to execute bash commands */
     executeBash: (bashCommand: string) => Promise<string>;
+    /** Function to read file contents */
     readFile: (filePath: string) => Promise<string>;
 }
 
 /**
- * Parsed command with substitutions applied
+ * Parsed command with all substitutions applied
+ *
+ * @remarks
+ * After parsing, the command content will have:
+ * - $1, $2, etc. replaced with positional arguments
+ * - $ARGUMENTS replaced with all arguments joined by spaces
+ * - !`cmd` patterns extracted to bashCommands and replaced with [BASH_OUTPUT]
+ * - @file patterns extracted to fileReferences
  */
 export interface ParsedCommand {
-    content: string;            // Content with substitutions applied
-    bashCommands: string[];     // Bash commands to execute
-    fileReferences: string[];   // Files to read
+    /** Content with all substitutions applied */
+    content: string;
+    /** Bash commands extracted from !`cmd` patterns */
+    bashCommands: string[];
+    /** File paths extracted from @file patterns */
+    fileReferences: string[];
 }

package/src/commands/CommandManager.ts

@@ -31,10 +31,18 @@ export class CommandManager {
         const discovered: Command[] = [];
 
         // Personal commands
-        discovered.push(...await this.discoverCommandsInDirectory(this.personalCommandsDir, 'personal'));
+        try {
+            discovered.push(...await this.discoverCommandsInDirectory(this.personalCommandsDir, 'personal'));
+        } catch (error: any) {
+            console.warn(`Warning: Failed to load personal commands from ${this.personalCommandsDir}: ${error.message}`);
+        }
 
         // Project commands
-        discovered.push(...await this.discoverCommandsInDirectory(this.projectCommandsDir, 'project'));
+        try {
+            discovered.push(...await this.discoverCommandsInDirectory(this.projectCommandsDir, 'project'));
+        } catch (error: any) {
+            console.warn(`Warning: Failed to load project commands from ${this.projectCommandsDir}: ${error.message}`);
+        }
 
         // Store commands in map (project commands override personal)
         for (const command of discovered) {
@@ -85,6 +93,7 @@ export class CommandManager {
             const commandName = this.getCommandName(commandPath, type);
 
             if (!commandName) {
+                console.warn(`Warning: Invalid command name in ${commandPath} (skipping)`);
                 return null;
             }
 
@@ -107,7 +116,13 @@ export class CommandManager {
 
             return command;
         } catch (error: any) {
-            console.error(`Error parsing command ${commandPath}: ${error.message}`);
+            if (error.code === 'ENOENT') {
+                console.warn(`Warning: Command file not found: ${commandPath}`);
+            } else if (error.code === 'EACCES') {
+                console.warn(`Warning: Permission denied reading command: ${commandPath}`);
+            } else {
+                console.error(`Error parsing command ${commandPath}: ${error.message}`);
+            }
             return null;
         }
     }
@@ -222,7 +237,10 @@ export class CommandManager {
         const bashRegex = /!`([^`]+)`/g;
         let bashMatch;
         while ((bashMatch = bashRegex.exec(content)) !== null) {
-            bashCommands.push(bashMatch[1]);
+            const bashCommand = bashMatch[1].trim();
+            if (bashCommand) {
+                bashCommands.push(bashCommand);
+            }
         }
 
         // Remove bash command markers
@@ -232,7 +250,10 @@ export class CommandManager {
         const fileRegex = /@([^\s]+)/g;
         let fileMatch;
         while ((fileMatch = fileRegex.exec(content)) !== null) {
-            fileReferences.push(fileMatch[1]);
+            const fileRef = fileMatch[1].trim();
+            if (fileRef && !fileReferences.includes(fileRef)) {
+                fileReferences.push(fileRef);
+            }
         }
 
         return { content, bashCommands, fileReferences };

package/src/commands/__tests__/CommandManager.test.ts

@@ -0,0 +1,83 @@
+/**
+ * Tests for CommandManager
+ */
+
+import { CommandManager } from '../CommandManager';
+import { Command } from '../Command';
+
+describe('CommandManager', () => {
+    let manager: CommandManager;
+
+    beforeEach(() => {
+        manager = new CommandManager();
+    });
+
+    describe('getAllCommands', () => {
+        it('should return empty array initially', () => {
+            const commands = manager.getAllCommands();
+            expect(commands).toEqual([]);
+        });
+    });
+
+    describe('getCommandsContext', () => {
+        it('should return empty string when no commands', () => {
+            const context = manager.getCommandsContext();
+            expect(context).toBe('');
+        });
+    });
+
+    describe('parseCommand', () => {
+        it('should replace $ARGUMENTS placeholder', async () => {
+            const command: Command = {
+                name: 'echo',
+                type: 'personal',
+                path: '/echo.md',
+                directory: '/commands',
+                description: 'Echo arguments',
+                frontmatter: {},
+                content: 'You said: $ARGUMENTS',
+                hasParameters: true
+            };
+
+            const parsed = await manager.parseCommand(command, ['hello', 'world']);
+
+            expect(parsed.content).toContain('hello world');
+        });
+
+        it('should replace $1, $2 placeholders', async () => {
+            const command: Command = {
+                name: 'greet',
+                type: 'personal',
+                path: '/greet.md',
+                directory: '/commands',
+                description: 'Greet user',
+                frontmatter: {},
+                content: 'Hello $1, welcome to $2',
+                hasParameters: true
+            };
+
+            const parsed = await manager.parseCommand(command, ['Alice', 'Wonderland']);
+
+            expect(parsed.content).toContain('Hello Alice');
+            expect(parsed.content).toContain('welcome to Wonderland');
+        });
+
+        it('should extract bash commands from content', async () => {
+            const command: Command = {
+                name: 'run-test',
+                type: 'personal',
+                path: '/run-test.md',
+                directory: '/commands',
+                description: 'Run tests',
+                frontmatter: {},
+                content: 'Run tests with !`npm test`',
+                hasParameters: false
+            };
+
+            const parsed = await manager.parseCommand(command, []);
+
+            expect(parsed.bashCommands).toHaveLength(1);
+            expect(parsed.bashCommands[0]).toBe('npm test');
+        });
+    });
+});

package/src/debug_google.ts

@@ -0,0 +1,30 @@
+
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+
+const query = "expo go latest sdk";
+const url = `https://www.google.com/search?q=${encodeURIComponent(query)}&hl=en`;
+console.log(`Fetching Google: ${url}`);
+
+try {
+    // Mimic standard browser
+    const userAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
+    const cmd = `curl -s -L -A "${userAgent}" "${url}"`;
+    const html = execSync(cmd, { encoding: 'utf-8' });
+
+    fs.writeFileSync('google_dump.html', html);
+    console.log('Dumped HTML to google_dump.html. Length:', html.length);
+
+    if (html.includes('Captcha') || html.includes('unusual traffic')) {
+        console.log('BLOCKED by Google Captcha');
+    } else {
+        console.log('Seems OK? Checking for result markers...');
+        // Google uses complex class names, but often "h3" is title
+        if (html.includes('<h3')) {
+            console.log('Found h3 tags (likely titles).');
+        }
+    }
+
+} catch (e: any) {
+    console.error('Error:', e.message);
+}

package/src/debug_lite.ts

@@ -0,0 +1,18 @@
+
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+
+const query = "expo go latest sdk";
+const url = `https://lite.duckduckgo.com/lite/?q=${encodeURIComponent(query)}`;
+console.log(`Fetching Lite DDG: ${url}`);
+
+try {
+    const cmd = `curl -s -L -A "Mozilla/5.0" "${url}"`;
+    const html = execSync(cmd, { encoding: 'utf-8' });
+
+    fs.writeFileSync('lite_dump.html', html);
+    console.log('Dumped HTML to lite_dump.html');
+
+} catch (e: any) {
+    console.error('Error:', e.message);
+}

package/src/debug_lite_headers.ts

@@ -0,0 +1,25 @@
+
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+
+const query = "expo go latest sdk";
+const url = `https://lite.duckduckgo.com/lite/?q=${encodeURIComponent(query)}`;
+console.log(`Testing Lite Headers: ${url}`);
+
+try {
+    const cmd = `curl -s -L -A "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36" -H "Referer: https://duckduckgo.com/" -H "Accept-Language: en-US,en;q=0.9" "${url}"`;
+    const html = execSync(cmd, { encoding: 'utf-8' });
+
+    fs.writeFileSync('lite_headers_dump.html', html);
+
+    if (html.includes('anomaly-modal')) {
+        console.log('STILL BLOCKED by Captcha');
+    } else if (html.includes('result-link')) {
+        console.log('SUCCESS! Found result links.');
+    } else {
+        console.log('Unknown response. Check dump.');
+    }
+
+} catch (e: any) {
+    console.error('Error:', e.message);
+}

package/src/debug_search.ts

@@ -0,0 +1,18 @@
+
+import { execSync } from 'child_process';
+
+const query = "test";
+const url = `https://lite.duckduckgo.com/lite/?q=${encodeURIComponent(query)}`;
+console.log(`Testing Lite DDG: ${url}`);
+
+try {
+    const cmd = `curl -s -L -A "Mozilla/5.0" "${url}"`;
+    const html = execSync(cmd, { encoding: 'utf-8' });
+
+    console.log('HTML Length:', html.length);
+    console.log('Snippet (first 2000 chars):');
+    console.log(html.substring(0, 2000));
+
+} catch (e: any) {
+    console.error('Error:', e.message);
+}

package/src/index.ts

@@ -1,13 +1,39 @@
 #!/usr/bin/env node
+
+/**
+ * Mentis CLI - An Agentic, Multi-Model CLI Coding Assistant
+ *
+ * @packageDocumentation
+ */
+
 import { ReplManager } from './repl/ReplManager';
 
+/**
+ * CLI options for controlling Mentis behavior
+ */
 interface CliOptions {
+    /** Resume from the last saved checkpoint */
     resume: boolean;
+    /** Auto-confirm all prompts (skip confirmations) */
     yolo: boolean;
+    /** Run in headless (non-interactive) mode */
     headless: boolean;
+    /** Prompt to execute in headless mode */
     headlessPrompt?: string;
 }
 
+/**
+ * Parse command line arguments
+ *
+ * @returns Parsed command and options
+ *
+ * @example
+ * ```bash
+ * mentis --resume
+ * mentis -p "fix the bug"
+ * mentis --yolo
+ * ```
+ */
 function parseArgs(): { command: string | null, options: CliOptions } {
     const args = process.argv.slice(2);
     const options: CliOptions = {
@@ -69,7 +95,12 @@ Commands (in REPL):
     return { command, options };
 }
 
-async function main() {
+/**
+ * Main entry point for Mentis CLI
+ *
+ * Parses arguments and starts the REPL or update manager
+ */
+async function main(): Promise<void> {
     const { command, options } = parseArgs();
 
     // Handle update command
@@ -85,6 +116,19 @@ async function main() {
     await repl.start();
 }
 
+// Global error handlers to prevent silent crashes
+process.on('uncaughtException', (error) => {
+    console.error('Uncaught Exception:', error.message);
+    console.error(error.stack);
+    process.exit(1);
+});
+
+process.on('unhandledRejection', (reason, promise) => {
+    console.error('Unhandled Rejection at:', promise, 'reason:', reason);
+    process.exit(1);
+});
+
+// Start the application
 main().catch((error) => {
     console.error('Fatal error:', error);
     process.exit(1);