@indiccoder/mentis-cli 1.1.3 → 1.1.4

package/dist/skills/SkillsManager.js

@@ -60,10 +60,20 @@ class SkillsManager {
          } = options;
         const discovered = [];
         if (includePersonal) {
-            discovered.push(...await this.discoverSkillsInDirectory(this.personalSkillsDir, 'personal'));
+            try {
+                discovered.push(...await this.discoverSkillsInDirectory(this.personalSkillsDir, 'personal'));
+            }
+            catch (error) {
+                console.warn(`Warning: Failed to load personal skills from ${this.personalSkillsDir}: ${error.message}`);
+            }
         }
         if (includeProject) {
-            discovered.push(...await this.discoverSkillsInDirectory(this.projectSkillsDir, 'project'));
+            try {
+                discovered.push(...await this.discoverSkillsInDirectory(this.projectSkillsDir, 'project'));
+            }
+            catch (error) {
+                console.warn(`Warning: Failed to load project skills from ${this.projectSkillsDir}: ${error.message}`);
+            }
         }
         // Store skills in map for quick lookup
         for (const skill of discovered) {
@@ -109,6 +119,7 @@ class SkillsManager {
             const content = fs.readFileSync(skillPath, 'utf-8');
             const frontmatter = this.extractFrontmatter(content);
             if (!frontmatter) {
+                console.warn(`Warning: Invalid or missing frontmatter in ${skillPath} (skipping)`);
                 return null;
             }
             // Convert SkillFrontmatter to SkillMetadata for validation
@@ -128,10 +139,24 @@ class SkillsManager {
                 isValid: validation.isValid,
                 errors: validation.errors.length > 0 ? validation.errors : undefined
             };
+            // Log validation warnings
+            if (validation.warnings.length > 0) {
+                for (const warning of validation.warnings) {
+                    console.warn(`Warning (${skill.name}): ${warning}`);
+                }
+            }
             return skill;
         }
         catch (error) {
-            console.error(`Error loading skill metadata from ${skillPath}: ${error.message}`);
+            if (error.code === 'ENOENT') {
+                console.warn(`Warning: Skill file not found: ${skillPath}`);
+            }
+            else if (error.code === 'EACCES') {
+                console.warn(`Warning: Permission denied reading skill: ${skillPath}`);
+            }
+            else {
+                console.error(`Error loading skill metadata from ${skillPath}: ${error.message}`);
+            }
             return null;
         }
     }

package/dist/skills/__tests__/SkillsManager.test.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * Tests for SkillsManager
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const SkillsManager_1 = require("../SkillsManager");
+describe('SkillsManager', () => {
+    let manager;
+    beforeEach(() => {
+        manager = new SkillsManager_1.SkillsManager();
+    });
+    describe('getAllSkills', () => {
+        it('should return empty array initially', () => {
+            const skills = manager.getAllSkills();
+            expect(skills).toEqual([]);
+        });
+    });
+    describe('getSkill', () => {
+        it('should return undefined for non-existent skill', () => {
+            const skill = manager.getSkill('non-existent');
+            expect(skill).toBeUndefined();
+        });
+    });
+    describe('getSkillsContext', () => {
+        it('should return empty string when no skills', () => {
+            const context = manager.getSkillsContext();
+            expect(context).toBe('');
+        });
+    });
+    describe('addSkill', () => {
+        it('should add skill to manager', () => {
+            const skill = {
+                name: 'test-skill',
+                description: 'Test skill',
+                path: '/skills/test.md',
+                type: 'personal',
+                directory: '/skills',
+                isValid: true,
+                content: 'Test content'
+            };
+            manager['skills'].set('test-skill', skill);
+            const retrieved = manager.getSkill('test-skill');
+            expect(retrieved).toBeDefined();
+            expect(retrieved?.name).toBe('test-skill');
+        });
+        it('should return skills context with skills', () => {
+            const skill = {
+                name: 'reviewer',
+                description: 'Code reviewer skill',
+                path: '/skills/reviewer.md',
+                type: 'personal',
+                directory: '/skills',
+                isValid: true,
+                content: 'Review code'
+            };
+            manager['skills'].set('reviewer', skill);
+            const context = manager.getSkillsContext();
+            expect(context).toContain('Available Skills');
+            expect(context).toContain('reviewer');
+        });
+    });
+});

package/dist/utils/__mocks__/chalk.js

@@ -0,0 +1,20 @@
+"use strict";
+// Manual mock for chalk to avoid ESM issues in Jest
+module.exports = {
+    dim: (str) => str,
+    green: (str) => str,
+    yellow: (str) => str,
+    red: (str) => str,
+    gray: (str) => str,
+    bold: (str) => str,
+    cyan: (str) => str,
+    default: {
+        dim: (str) => str,
+        green: (str) => str,
+        yellow: (str) => str,
+        red: (str) => str,
+        gray: (str) => str,
+        bold: (str) => str,
+        cyan: (str) => str
+    }
+};

package/dist/utils/__tests__/ContextVisualizer.test.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * Tests for ContextVisualizer
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const ContextVisualizer_1 = require("../ContextVisualizer");
+describe('ContextVisualizer', () => {
+    let visualizer;
+    beforeEach(() => {
+        visualizer = new ContextVisualizer_1.ContextVisualizer();
+    });
+    describe('calculateUsage', () => {
+        it('should handle empty history', () => {
+            const history = [];
+            const usage = visualizer.calculateUsage(history);
+            // Includes 2000 char overhead = 500 tokens
+            expect(usage.tokens).toBe(500);
+            expect(usage.maxTokens).toBe(128000);
+            expect(usage).toHaveProperty('percentage');
+            expect(usage).toHaveProperty('tokens');
+            expect(usage).toHaveProperty('maxTokens');
+        });
+        it('should calculate tokens for messages', () => {
+            const history = [
+                { role: 'system', content: 'You are a helpful assistant.' },
+                { role: 'user', content: 'Hello' },
+                { role: 'assistant', content: 'Hi there!' }
+            ];
+            const usage = visualizer.calculateUsage(history);
+            expect(usage.tokens).toBeGreaterThan(500);
+            expect(usage.tokens).toBeLessThan(1000);
+            expect(usage.maxTokens).toBe(128000);
+        });
+        it('should handle large messages', () => {
+            const largeContent = 'x'.repeat(10000);
+            const history = [
+                { role: 'user', content: largeContent }
+            ];
+            const usage = visualizer.calculateUsage(history);
+            expect(usage.tokens).toBeGreaterThan(1500);
+        });
+    });
+    describe('formatBar', () => {
+        it('should format bar at low usage', () => {
+            const usage = { tokens: 1000, percentage: 5, maxTokens: 128000 };
+            const bar = visualizer.formatBar(usage);
+            // Check that bar contains expected data (without chalk dependency)
+            expect(bar).toContain('5');
+            expect(bar).toContain('1k');
+            expect(bar).toContain('128');
+        });
+        it('should format bar at medium usage', () => {
+            const usage = { tokens: 50000, percentage: 40, maxTokens: 128000 };
+            const bar = visualizer.formatBar(usage);
+            expect(bar).toContain('40');
+            expect(bar).toContain('50k');
+        });
+        it('should format bar at high usage', () => {
+            const usage = { tokens: 100000, percentage: 80, maxTokens: 128000 };
+            const bar = visualizer.formatBar(usage);
+            expect(bar).toContain('80');
+            expect(bar).toContain('100k');
+        });
+    });
+    describe('shouldCompact', () => {
+        it('should return false for low percentage', () => {
+            const history = [
+                { role: 'user', content: 'small message' }
+            ];
+            const shouldCompact = visualizer.shouldCompact(history);
+            expect(shouldCompact).toBe(false);
+        });
+        it('should return true at 80% threshold', () => {
+            // Create enough content to exceed 80%
+            // 80% of 128000 tokens = 102400 tokens = ~409600 chars
+            // Subtract 2000 overhead = ~407400 chars needed
+            const largeContent = 'x'.repeat(410000);
+            const history = [
+                { role: 'system', content: largeContent },
+                { role: 'user', content: largeContent }
+            ];
+            const shouldCompact = visualizer.shouldCompact(history);
+            expect(shouldCompact).toBe(true);
+        });
+    });
+    describe('setMaxTokens', () => {
+        it('should update max tokens', () => {
+            visualizer.setMaxTokens(32000);
+            const history = [];
+            const usage = visualizer.calculateUsage(history);
+            expect(usage.maxTokens).toBe(32000);
+            expect(usage.percentage).toBeGreaterThan(1); // Should be higher percentage with smaller max
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiccoder/mentis-cli",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "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",
@@ -60,7 +62,26 @@
     "@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/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/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,7 @@ async function main() {
     await repl.start();
 }
 
+// Start the application
 main().catch((error) => {
     console.error('Fatal error:', error);
     process.exit(1);