@indiccoder/mentis-cli 1.1.3 → 1.1.4

package/ARCHITECTURE.md

@@ -0,0 +1,267 @@
+# Mentis CLI Architecture
+
+## Overview
+
+Mentis CLI is an agentic, multi-model CLI coding assistant built with TypeScript. It provides an interactive REPL for AI-assisted coding with support for multiple LLM providers (Gemini, Ollama, Anthropic, OpenAI-compatible).
+
+## Project Structure
+
+```
+mentis-cli/
+├── src/
+│   ├── index.ts              # CLI entry point, argument parsing
+│   ├── repl/                 # REPL session management
+│   │   ├── ReplManager.ts    # Main REPL controller
+│   │   └── HistoryManager.ts # Chat history persistence
+│   ├── llm/                  # LLM provider implementations
+│   │   ├── ModelInterface.ts # Shared interfaces
+│   │   ├── Gemini.ts         # Google Gemini provider
+│   │   ├── Ollama.ts         # Ollama local provider
+│   │   ├── Anthropic.ts      # Anthropic Claude provider
+│   │   └── OpenAI.ts         # OpenAI-compatible provider
+│   ├── tools/                # Tool implementations
+│   │   ├── ToolManager.ts    # Tool registry
+│   │   ├── LoadSkillTool.ts  # Agent Skills tool
+│   │   └── ...               # Individual tools
+│   ├── commands/             # Custom Slash Commands
+│   │   ├── Command.ts        # Command interfaces
+│   │   └── CommandManager.ts # Command discovery & parsing
+│   ├── skills/               # Agent Skills system
+│   │   ├── Skill.ts          # Skill interfaces
+│   │   ├── SkillsManager.ts  # Skill discovery & validation
+│   │   └── LoadSkillTool.ts  # Tool for loading skills
+│   ├── ui/                   # User interface
+│   │   ├── UIManager.ts      # Display formatting
+│   │   └── InputBox.ts       # Input prompt with history
+│   ├── mcp/                  # Model Context Protocol
+│   │   └── McpManager.ts     # MCP server management
+│   └── utils/                # Utilities
+│       ├── ContextVisualizer.ts  # Token usage display
+│       ├── UpdateManager.ts     # Auto-update
+│       └── ...
+├── dist/                     # Compiled JavaScript
+├── .mentis/                  # Project-specific config
+└── package.json
+```
+
+## Core Components
+
+### 1. REPL System (`src/repl/`)
+
+The **ReplManager** is the heart of Mentis CLI. It orchestrates the entire conversation flow:
+
+```
+User Input → Command Parser → Skill/Command Handler → LLM → Tool Execution → Response
+```
+
+**Key responsibilities:**
+- Manage chat history with auto-compact at 80% context
+- Handle slash commands (`/help`, `/clear`, `/skills`, etc.)
+- Inject skills and custom commands into system prompt
+- Execute tool calls returned by LLM
+- Save/restore session checkpoints
+
+### 2. LLM Abstraction (`src/llm/`)
+
+Each LLM provider implements the `ModelInterface`:
+
+```typescript
+interface ModelInterface {
+    chat(messages: ChatMessage[], tools?: ToolInfo[]): Promise<ChatResponse>;
+    streamChat(messages: ChatMessage[], tools?: ToolInfo[]): AsyncIterator<ChatChunk>;
+}
+```
+
+**Supported providers:**
+- **Gemini** (Google) - Default, supports streaming
+- **Ollama** - Local models via API
+- **Anthropic** - Claude models
+- **OpenAI-compatible** - Custom endpoints
+
+### 3. Tool System (`src/tools/`)
+
+Tools are functions the AI can invoke. Each tool implements:
+
+```typescript
+interface Tool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    execute(params: Record<string, unknown>): Promise<ToolResult>;
+}
+```
+
+**Available tools:**
+- File operations: `Read`, `Write`, `Edit`, `Glob`, `Grep`
+- Execution: `Bash`
+- Git: `GitStatus`, `GitDiff`, `GitCommit`
+- Skills: `LoadSkillTool` (progressive disclosure)
+
+### 4. Agent Skills (`src/skills/`)
+
+Agent Skills are reusable AI configurations stored as `SKILL.md` files:
+
+```
+~/.mentis/skills/
+└── code-reviewer/
+    └── SKILL.md
+```
+
+**Features:**
+- Progressive disclosure (metadata loaded first, content on-demand)
+- Optional tool restrictions
+- Validation (name format, description quality)
+- Personal vs project scopes
+
+### 5. Custom Commands (`src/commands/`)
+
+Custom slash commands defined as markdown files:
+
+```
+~/.mentis/commands/
+└── test.md
+```
+
+**Features:**
+- Parameter substitution (`$1`, `$2`, `$ARGUMENTS`)
+- Bash execution (`!`cmd``)
+- File references (`@file`)
+- Namespace support (subdirectories)
+
+## Data Flow
+
+### Conversation Flow
+
+```
+1. User enters input
+2. Check for slash commands
+3. Inject skills/commands context
+4. Call LLM with tools
+5. Parse tool calls
+6. Execute tools
+7. Return results to LLM
+8. Stream response to user
+9. Update history
+10. Check context usage (compact if >80%)
+```
+
+### Tool Execution Flow
+
+```
+LLM returns tool call
+↓
+ToolManager finds tool
+↓
+Validate parameters
+↓
+Execute tool
+↓
+Format result
+↓
+Return to LLM for final response
+```
+
+### Skill Loading Flow
+
+```
+Startup: Load all skill metadata (name, description)
+↓
+User mentions skill keyword
+↓
+LoadSkillTool invoked
+↓
+Load full SKILL.md content
+↓
+Inject into system prompt
+↓
+AI executes with skill context
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+GEMINI_API_KEY=xxx          # Gemini API key
+OLLAMA_BASE_URL=http://...  # Ollama endpoint
+ANTHROPIC_API_KEY=xxx       # Anthropic key
+OPENAI_API_KEY=xxx          # OpenAI-compatible key
+OPENAI_BASE_URL=http://...  # Custom endpoint
+```
+
+### Dotenv Config (`.mentis.md`)
+
+```yaml
+model: gemini-2.5-pro
+temperature: 0.7
+max_tokens: 8192
+```
+
+### Directory Structure
+
+```
+~/.mentis/                   # User config
+├── skills/                  # Personal skills
+├── commands/                # Personal commands
+└── checkpoints/             # Session saves
+
+.mentis/                     # Project config
+├── skills/                  # Project skills
+├── commands/                # Project commands
+└── .mentis.md              # Project config file
+```
+
+## Testing
+
+Jest tests are located in `src/**/__tests__/`:
+
+```bash
+npm test              # Run all tests
+npm run test:watch    # Watch mode
+npm run test:coverage # Coverage report
+```
+
+**Current test coverage:**
+- CommandManager - Command parsing, argument substitution
+- SkillsManager - Skill discovery, validation
+- ContextVisualizer - Token calculation, compacting
+
+## Extension Points
+
+### Adding a New LLM Provider
+
+1. Implement `ModelInterface` in `src/llm/`
+2. Add to `ModelFactory.ts`
+3. Add CLI option for selection
+
+### Adding a New Tool
+
+1. Create tool class in `src/tools/`
+2. Register in `ToolManager.ts`
+3. Update documentation
+
+### Adding a New Slash Command
+
+Create `.md` file in `~/.mentis/commands/`:
+
+```markdown
+---
+description: My custom command
+---
+
+Execute: !`echo "$1"`
+```
+
+## Performance Considerations
+
+- **Streaming**: All LLM calls use streaming for faster perceived response
+- **Progressive Disclosure**: Skills loaded on-demand to reduce startup time
+- **Auto-Compact**: History automatically compacted at 80% context to prevent errors
+- **Caching**: Discovered skills/commands cached in memory
+
+## Security
+
+- API keys stored in environment variables or `.env`
+- No credentials in code or config files
+- Tool execution sandboxed (respects system permissions)
+- Git operations require explicit confirmation (unless `--yolo`)

package/CONTRIBUTING.md

@@ -0,0 +1,209 @@
+# Contributing to Mentis CLI
+
+Thank you for your interest in contributing to Mentis CLI! This document provides guidelines for contributing.
+
+## Table of Contents
+
+- [Development Setup](#development-setup)
+- [Project Structure](#project-structure)
+- [Coding Standards](#coding-standards)
+- [Testing](#testing)
+- [Submitting Changes](#submitting-changes)
+- [Feature Ideas](#feature-ideas)
+
+## Development Setup
+
+### Prerequisites
+
+- Node.js 18+
+- npm or yarn
+- Git
+
+### Fork and Clone
+
+```bash
+# Fork the repository on GitHub
+git clone https://github.com/YOUR_USERNAME/Mentis-CLI.git
+cd Mentis-CLI
+```
+
+### Install Dependencies
+
+```bash
+npm install
+# or with legacy peer deps if needed
+npm install --legacy-peer-deps
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Link for Local Testing
+
+```bash
+npm link
+# Now you can run 'mentis' anywhere
+```
+
+## Project Structure
+
+Key directories:
+
+- `src/` - TypeScript source code
+- `src/llm/` - LLM provider implementations
+- `src/tools/` - Tool implementations
+- `src/skills/` - Agent Skills system
+- `src/commands/` - Custom Commands system
+- `src/ui/` - User interface components
+- `src/**/__tests__/` - Jest test files
+
+## Coding Standards
+
+### TypeScript
+
+- Use strict TypeScript settings
+- Add JSDoc comments for exported functions/classes
+- Define interfaces for all complex types
+
+### Code Style
+
+- Use 4 spaces for indentation
+- Prefer `const` over `let`
+- Use arrow functions for callbacks
+- Add error handling with specific error codes
+
+### Naming Conventions
+
+- Classes: `PascalCase`
+- Functions/variables: `camelCase`
+- Interfaces: `PascalCase` with `I` prefix avoided
+- Private members: `camelCase` with no prefix (TypeScript's `private` keyword)
+
+### Example
+
+```typescript
+/**
+ * Calculate token usage from message history
+ */
+export function calculateUsage(history: ChatMessage[]): ContextUsage {
+    let totalChars = 0;
+
+    for (const msg of history) {
+        if (msg.content) {
+            totalChars += msg.content.length;
+        }
+    }
+
+    return {
+        tokens: Math.ceil(totalChars / 4),
+        percentage: Math.round((totalChars / maxTokens) * 100),
+        maxTokens
+    };
+}
+```
+
+## Testing
+
+### Running Tests
+
+```bash
+npm test              # Run all tests
+npm run test:watch    # Watch mode
+npm run test:coverage # Coverage report
+```
+
+### Writing Tests
+
+- Place test files in `src/**/__tests__/`
+- Name test files: `*.test.ts`
+- Use Jest conventions (`describe`, `it`, `expect`)
+
+### Example Test
+
+```typescript
+describe('MyFunction', () => {
+    it('should return expected result', () => {
+        const result = myFunction('input');
+        expect(result).toBe('expected');
+    });
+});
+```
+
+### Test Coverage
+
+Aim for:
+- Branches: 50%+
+- Functions: 70%+
+- Lines: 70%+
+
+## Submitting Changes
+
+### Commit Messages
+
+Use conventional commit format:
+
+```
+type(scope): description
+
+feat(tools): add new file search tool
+fix(repl): handle empty input gracefully
+docs(readme): update installation instructions
+test(skills): add validation tests
+```
+
+### Pull Request Process
+
+1. Create a branch from `main`
+2. Make your changes
+3. Add/update tests
+4. Run tests: `npm test`
+5. Build: `npm run build`
+6. Commit with conventional message
+7. Push to your fork
+8. Open a pull request
+
+### PR Checklist
+
+- [ ] Tests pass
+- [ ] New features include tests
+- [ ] Documentation updated
+- [ ] Commit messages follow conventions
+- [ ] No console errors/warnings
+
+## Feature Ideas
+
+Looking for something to work on? Here are some ideas:
+
+### High Priority
+
+- [ ] Add more LLM providers (Mistral, Cohere, etc.)
+- [ ] Implement MCP server protocol
+- [ ] Add skill templates/generator
+- [ ] Improve error recovery
+
+### Medium Priority
+
+- [ ] Add conversation search
+- [ ] Implement plugin system
+- [ ] Add code generation templates
+- [ ] Improve completions for custom commands
+
+### Low Priority
+
+- [ ] Add themes for UI
+- [ ] Implement voice input
+- [ ] Add collaborative features
+- [ ] Create web UI
+
+## Questions?
+
+- Open an issue for bugs or feature requests
+- Start a discussion for questions
+- Check existing issues before creating new ones
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the ISC License.

package/dist/commands/Command.js

@@ -1,6 +1,20 @@
 "use strict";
 /**
  * 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`
+ * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });

package/dist/commands/CommandManager.js

@@ -57,9 +57,19 @@ class CommandManager {
     async discoverCommands() {
         const discovered = [];
         // Personal commands
-        discovered.push(...await this.discoverCommandsInDirectory(this.personalCommandsDir, 'personal'));
+        try {
+            discovered.push(...await this.discoverCommandsInDirectory(this.personalCommandsDir, 'personal'));
+        }
+        catch (error) {
+            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) {
+            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) {
             this.commands.set(command.name, command);
@@ -102,6 +112,7 @@ class CommandManager {
             const frontmatter = this.extractFrontmatter(content);
             const commandName = this.getCommandName(commandPath, type);
             if (!commandName) {
+                console.warn(`Warning: Invalid command name in ${commandPath} (skipping)`);
                 return null;
             }
             // Get namespace (subdirectory)
@@ -121,7 +132,15 @@ class CommandManager {
             return command;
         }
         catch (error) {
-            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;
         }
     }
@@ -217,7 +236,10 @@ 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
         content = content.replace(/!`[^`]+`/g, '[BASH_OUTPUT]');
@@ -225,7 +247,10 @@ 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/dist/commands/__tests__/CommandManager.test.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Tests for CommandManager
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const CommandManager_1 = require("../CommandManager");
+describe('CommandManager', () => {
+    let manager;
+    beforeEach(() => {
+        manager = new CommandManager_1.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 = {
+                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 = {
+                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 = {
+                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/dist/index.js

@@ -1,7 +1,24 @@
 #!/usr/bin/env node
 "use strict";
+/**
+ * Mentis CLI - An Agentic, Multi-Model CLI Coding Assistant
+ *
+ * @packageDocumentation
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 const ReplManager_1 = require("./repl/ReplManager");
+/**
+ * Parse command line arguments
+ *
+ * @returns Parsed command and options
+ *
+ * @example
+ * ```bash
+ * mentis --resume
+ * mentis -p "fix the bug"
+ * mentis --yolo
+ * ```
+ */
 function parseArgs() {
     const args = process.argv.slice(2);
     const options = {
@@ -59,6 +76,11 @@ Commands (in REPL):
     }
     return { command, options };
 }
+/**
+ * Main entry point for Mentis CLI
+ *
+ * Parses arguments and starts the REPL or update manager
+ */
 async function main() {
     const { command, options } = parseArgs();
     // Handle update command
@@ -72,6 +94,7 @@ async function main() {
     const repl = new ReplManager_1.ReplManager(options);
     await repl.start();
 }
+// Start the application
 main().catch((error) => {
     console.error('Fatal error:', error);
     process.exit(1);

package/dist/skills/Skill.js

@@ -1,6 +1,21 @@
 "use strict";
 /**
- * Skill data structure for Agent Skills system
- * Based on Claude Code's Agent Skills format
+ * Agent Skills System
+ *
+ * Based on Claude Code's Agent Skills format. Skills are reusable AI agent
+ * configurations stored as SKILL.md files in dedicated directories.
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```markdown
+ * ---
+ * name: code-reviewer
+ * description: Use when the user asks for a code review. Examines code for bugs, style issues, and improvements.
+ * allowed-tools: [Read, Grep, Glob]
+ * ---
+ *
+ * Review the code for...
+ * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });