@indiccoder/mentis-cli 1.1.3 → 1.1.5

package/src/skills/Skill.ts

@@ -1,26 +1,96 @@
 /**
- * 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...
+ * ```
  */
 
+/**
+ * Core metadata for an Agent Skill
+ *
+ * @remarks
+ * Skills define specialized AI behaviors with optional tool restrictions.
+ * The description should include when to use the skill (e.g., "Use when...").
+ */
 export interface SkillMetadata {
-    name: string;           // Lowercase, numbers, hyphens only (max 64 chars)
-    description: string;    // What it does + when to use it (max 1024 chars)
-    allowedTools?: string[]; // Optional tool restrictions
+    /**
+     * Lowercase skill name with numbers and hyphens only (max 64 chars)
+     *
+     * @pattern ^[a-z0-9-]+$
+     * @maxLength 64
+     */
+    name: string;
+    /**
+     * What the skill does and when to use it (max 1024 chars)
+     *
+     * @remarks
+     * Should include phrases like "Use when..." or "Use for..."
+     * to help the AI understand when to invoke this skill.
+     *
+     * @maxLength 1024
+     */
+    description: string;
+    /**
+     * Optional list of tools the skill is allowed to use
+     *
+     * @remarks
+     * If specified, the AI will be restricted to only these tools
+     * when executing this skill.
+     */
+    allowedTools?: string[];
 }
 
+/**
+ * A fully loaded Agent Skill
+ */
 export interface Skill extends SkillMetadata {
-    path: string;           // Path to SKILL.md
+    /** Absolute path to the SKILL.md file */
+    path: string;
+    /** Whether this is personal, project, or plugin skill */
     type: 'personal' | 'project' | 'plugin';
-    content?: string;       // Loaded on demand (progressive disclosure)
-    directory: string;      // Path to skill directory (for resolving supporting files)
-    isValid: boolean;       // Whether skill passes validation
-    errors?: string[];      // Validation errors if any
+    /**
+     * Full skill content (loaded on demand)
+     *
+     * @remarks
+     * For progressive disclosure, only metadata is loaded initially.
+     * The full content is loaded only when the skill is invoked.
+     */
+    content?: string;
+    /** Directory containing the skill (for resolving supporting files) */
+    directory: string;
+    /** Whether the skill passes validation */
+    isValid: boolean;
+    /** Validation errors if any */
+    errors?: string[];
 }
 
+/**
+ * YAML frontmatter parsed from SKILL.md
+ */
 export interface SkillFrontmatter {
+    /** Skill name */
     name: string;
+    /** Skill description */
     description: string;
+    /**
+     * Optional tool restrictions
+     *
+     * @remarks
+     * YAML key uses kebab-case: allowed-tools
+     */
     'allowed-tools'?: string[];
 }
 
@@ -28,13 +98,20 @@ export interface SkillFrontmatter {
  * Validation result for a skill
  */
 export interface SkillValidationResult {
+    /** Whether the skill is valid */
     isValid: boolean;
+    /** Validation errors that must be fixed */
     errors: string[];
+    /** Warnings that don't block usage */
     warnings: string[];
 }
 
 /**
- * Skill context format for model injection
+ * Minimal skill context for model injection
+ *
+ * @remarks
+ * This is the format used when injecting skills into the system prompt.
+ * Only name and description are included (progressive disclosure).
  */
 export interface SkillContext {
     name: string;
@@ -45,7 +122,10 @@ export interface SkillContext {
  * Options for skill discovery
  */
 export interface SkillDiscoveryOptions {
+    /** Include personal skills from ~/.mentis/skills */
     includePersonal?: boolean;
+    /** Include project skills from .mentis/skills */
     includeProject?: boolean;
+    /** Include plugin skills (not yet implemented) */
     includePlugin?: boolean;
 }

package/src/skills/SkillsManager.ts

@@ -43,11 +43,19 @@ export class SkillsManager {
         const discovered: Skill[] = [];
 
         if (includePersonal) {
-            discovered.push(...await this.discoverSkillsInDirectory(this.personalSkillsDir, 'personal'));
+            try {
+                discovered.push(...await this.discoverSkillsInDirectory(this.personalSkillsDir, 'personal'));
+            } catch (error: any) {
+                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: any) {
+                console.warn(`Warning: Failed to load project skills from ${this.projectSkillsDir}: ${error.message}`);
+            }
         }
 
         // Store skills in map for quick lookup
@@ -102,6 +110,7 @@ export class SkillsManager {
             const frontmatter = this.extractFrontmatter(content);
 
             if (!frontmatter) {
+                console.warn(`Warning: Invalid or missing frontmatter in ${skillPath} (skipping)`);
                 return null;
             }
 
@@ -124,9 +133,22 @@ export class SkillsManager {
                 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: any) {
-            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/src/skills/__tests__/SkillsManager.test.ts

@@ -0,0 +1,73 @@
+/**
+ * Tests for SkillsManager
+ */
+
+import { SkillsManager } from '../SkillsManager';
+import { Skill } from '../Skill';
+
+describe('SkillsManager', () => {
+    let manager: SkillsManager;
+
+    beforeEach(() => {
+        manager = new 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: 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: 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/src/tools/AskQuestionTool.ts

@@ -0,0 +1,197 @@
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import { Tool } from './Tool';
+
+/**
+ * Question types supported by AskQuestionTool
+ */
+export type QuestionType = 'text' | 'confirm' | 'list' | 'checkbox';
+
+/**
+ * Question definition for the AI to create
+ */
+interface QuestionDef {
+    type: QuestionType;
+    question: string;
+    options?: Array<{ label: string; description?: string }>;
+    default?: any;
+}
+
+/**
+ * AskQuestionTool - Allows the AI to ask clarifying questions
+ * This enables interactive plan mode where AI can gather requirements
+ */
+export class AskQuestionTool implements Tool {
+    name = 'ask_question';
+    description = 'Ask the user a clarifying question. Use this in plan mode to gather requirements before implementation. Supports: text, confirm (yes/no), list (single choice), checkbox (multi-select).';
+    parameters = {
+        type: 'object',
+        properties: {
+            question: {
+                type: 'string',
+                description: 'The question to ask the user'
+            },
+            type: {
+                type: 'string',
+                enum: ['text', 'confirm', 'list', 'checkbox'],
+                description: 'Type of question: text (free input), confirm (yes/no), list (single choice), checkbox (multi-select)'
+            },
+            options: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        label: { type: 'string', description: 'Display text for the option' },
+                        description: { type: 'string', description: 'Additional context (optional)' }
+                    }
+                },
+                description: 'Options for list/checkbox questions. Required for list/checkbox types.'
+            },
+            default: {
+                oneOf: [{ type: 'string' }, { type: 'boolean' }, { type: 'array' }],
+                description: 'Default value (optional)'
+            }
+        },
+        required: ['question', 'type']
+    };
+
+    /**
+     * Execute the question and return the user's answer
+     */
+    async execute(args: QuestionDef & { question: string }): Promise<string> {
+        const questionType = args.type || 'text';
+
+        // Show question header
+        console.log('');
+        console.log(chalk.cyan('🤔 Question from AI:'));
+        console.log(chalk.gray('─'.repeat(60)));
+
+        try {
+            let result: any;
+
+            switch (questionType) {
+                case 'text':
+                    result = await this.askText(args.question, args.default);
+                    break;
+
+                case 'confirm':
+                    result = await this.askConfirm(args.question, args.default);
+                    break;
+
+                case 'list':
+                    if (!args.options || args.options.length === 0) {
+                        return 'Error: list questions require options';
+                    }
+                    result = await this.askList(args.question, args.options, args.default);
+                    break;
+
+                case 'checkbox':
+                    if (!args.options || args.options.length === 0) {
+                        return 'Error: checkbox questions require options';
+                    }
+                    result = await this.askCheckbox(args.question, args.options, args.default);
+                    break;
+
+                default:
+                    return `Error: Unknown question type: ${questionType}`;
+            }
+
+            console.log(chalk.gray('─'.repeat(60)));
+
+            // Format result as string for return to LLM
+            return this.formatResult(result, questionType);
+
+        } catch (error: any) {
+            return `Error asking question: ${error.message}`;
+        }
+    }
+
+    /**
+     * Ask a free-text question
+     */
+    private async askText(question: string, defaultValue?: string): Promise<string> {
+        const { answer } = await inquirer.prompt([
+            {
+                type: 'input',
+                name: 'answer',
+                message: question,
+                default: defaultValue
+            }
+        ]);
+        return answer;
+    }
+
+    /**
+     * Ask a yes/no confirmation
+     */
+    private async askConfirm(question: string, defaultValue?: boolean): Promise<boolean> {
+        const { answer } = await inquirer.prompt([
+            {
+                type: 'confirm',
+                name: 'answer',
+                message: question,
+                default: defaultValue ?? true
+            }
+        ]);
+        return answer;
+    }
+
+    /**
+     * Ask a single-choice list question
+     */
+    private async askList(question: string, options: Array<{ label: string; description?: string }>, defaultValue?: string): Promise<string> {
+        const { answer } = await inquirer.prompt([
+            {
+                type: 'list',
+                name: 'answer',
+                message: question,
+                choices: options.map((opt, i) => ({
+                    name: opt.label,
+                    value: opt.label,
+                    short: opt.label
+                })),
+                default: defaultValue
+            }
+        ]);
+        return answer;
+    }
+
+    /**
+     * Ask a multi-select checkbox question
+     */
+    private async askCheckbox(question: string, options: Array<{ label: string; description?: string }>, defaultValue?: string[]): Promise<string[]> {
+        const { answer } = await inquirer.prompt([
+            {
+                type: 'checkbox',
+                name: 'answer',
+                message: question,
+                choices: options.map((opt, i) => ({
+                    name: opt.label,
+                    value: opt.label,
+                    checked: defaultValue?.includes(opt.label),
+                    short: opt.label
+                }))
+            }
+        ]);
+        return answer;
+    }
+
+    /**
+     * Format the result for return to the LLM
+     */
+    private formatResult(result: any, questionType: QuestionType): string {
+        switch (questionType) {
+            case 'confirm':
+                return result === true ? 'Yes' : 'No';
+
+            case 'checkbox':
+                if (Array.isArray(result) && result.length > 0) {
+                    return `Selected: ${result.join(', ')}`;
+                }
+                return 'None selected';
+
+            default:
+                return String(result);
+        }
+    }
+}

package/src/tools/EditFileTool.ts

@@ -0,0 +1,172 @@
+import { Tool } from './Tool';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+/**
+ * EditFileTool - Performs string replacement in files (like Claude's Edit tool)
+ * Returns a unified diff preview instead of writing immediately
+ */
+export class EditFileTool implements Tool {
+    name = 'edit_file';
+    description = 'Make targeted edits to files using string replacement. Returns diff preview. Requires approval before writing.';
+    parameters = {
+        type: 'object',
+        properties: {
+            file_path: {
+                type: 'string',
+                description: 'The path to the file to edit'
+            },
+            old_string: {
+                type: 'string',
+                description: 'The exact string to replace. Must match exactly (including whitespace).'
+            },
+            new_string: {
+                type: 'string',
+                description: 'The new string to replace old_string with.'
+            },
+            auto_format: {
+                type: 'boolean',
+                description: 'Auto-format code after edit (default: false)'
+            }
+        },
+        required: ['file_path', 'old_string', 'new_string']
+    };
+
+    /**
+     * Execute the edit and return a diff preview
+     * Note: This does NOT write the file - it returns what WOULD change
+     * The caller (ReplManager) should handle approval before calling applyEdit()
+     */
+    async execute(args: {
+        file_path: string;
+        old_string: string;
+        new_string: string;
+        auto_format?: boolean;
+    }): Promise<string> {
+        const filePath = resolve(process.cwd(), args.file_path);
+
+        if (!existsSync(filePath)) {
+            return `Error: File not found: ${args.file_path}`;
+        }
+
+        const originalContent = readFileSync(filePath, 'utf-8');
+
+        if (!originalContent.includes(args.old_string)) {
+            return `Error: old_string not found in file. The string must match exactly (including whitespace and indentation).`;
+        }
+
+        // Count occurrences
+        const occurrences = (originalContent.match(new RegExp(this.escapeRegex(args.old_string), 'g')) || []).length;
+
+        if (occurrences > 1) {
+            return `Warning: old_string found ${occurrences} times. All occurrences will be replaced.\n\n${this.generateDiff(originalContent, args.old_string, args.new_string, args.file_path)}`;
+        }
+
+        // Generate and return diff
+        return this.generateDiff(originalContent, args.old_string, args.new_string, args.file_path);
+    }
+
+    /**
+     * Apply the edit after approval
+     * This should be called after user approves the diff
+     */
+    applyEdit(args: {
+        file_path: string;
+        old_string: string;
+        new_string: string;
+    }): { success: boolean; message: string } {
+        const filePath = resolve(process.cwd(), args.file_path);
+
+        if (!existsSync(filePath)) {
+            return { success: false, message: `File not found: ${args.file_path}` };
+        }
+
+        const originalContent = readFileSync(filePath, 'utf-8');
+
+        if (!originalContent.includes(args.old_string)) {
+            return { success: false, message: 'old_string not found in file' };
+        }
+
+        const newContent = originalContent.replace(args.old_string, args.new_string);
+
+        writeFileSync(filePath, newContent, 'utf-8');
+
+        return {
+            success: true,
+            message: `Successfully edited ${args.file_path}`
+        };
+    }
+
+    /**
+     * Generate a unified diff preview
+     */
+    private generateDiff(content: string, oldString: string, newString: string, filePath: string): string {
+        const lines = content.split('\n');
+        const oldLines = oldString.split('\n');
+        const newLines = newString.split('\n');
+
+        // Find the line number where old_string starts
+        let startLine = -1;
+        for (let i = 0; i <= lines.length - oldLines.length; i++) {
+            let match = true;
+            for (let j = 0; j < oldLines.length; j++) {
+                if (lines[i + j] !== oldLines[j]) {
+                    match = false;
+                    break;
+                }
+            }
+            if (match) {
+                startLine = i;
+                break;
+            }
+        }
+
+        if (startLine === -1) {
+            return 'Error: Could not locate old_string in file';
+        }
+
+        // Build unified diff
+        let diff = `\n${'─'.repeat(60)}\n`;
+        diff += `📝 Edit Preview: ${filePath}\n`;
+        diff += `${'─'.repeat(60)}\n`;
+        diff += `Line ${startLine + 1}:\n\n`;
+
+        // Show context (2 lines before)
+        const contextStart = Math.max(0, startLine - 2);
+        if (contextStart < startLine) {
+            for (let i = contextStart; i < startLine; i++) {
+                diff += `  ${lines[i]}\n`;
+            }
+        }
+
+        // Show removed lines (red)
+        for (const line of oldLines) {
+            diff += `\x1b[31m- ${line}\x1b[0m\n`;
+        }
+
+        // Show added lines (green)
+        for (const line of newLines) {
+            diff += `\x1b[32m+ ${line}\x1b[0m\n`;
+        }
+
+        // Show context (2 lines after)
+        const contextEnd = Math.min(lines.length, startLine + oldLines.length + 2);
+        if (startLine + oldLines.length < contextEnd) {
+            for (let i = startLine + oldLines.length; i < contextEnd; i++) {
+                diff += `  ${lines[i]}\n`;
+            }
+        }
+
+        diff += `${'─'.repeat(60)}\n`;
+
+        return diff;
+    }
+
+    /**
+     * Escape special regex characters
+     */
+    private escapeRegex(str: string): string {
+        return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+}

package/src/tools/FileTools.ts

@@ -1,6 +1,9 @@
 import fs from 'fs-extra';
 import path from 'path';
 import { Tool } from './Tool';
+export { EditFileTool } from './EditFileTool';
+export { AskQuestionTool } from './AskQuestionTool';
+export { PlanModeTool } from './PlanModeTool';
 
 export class WriteFileTool implements Tool {
     name = 'write_file';

package/src/tools/PlanModeTool.ts

@@ -0,0 +1,50 @@
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import { Tool } from './Tool';
+import { PlanModeUI } from '../ui/PlanModeUI';
+
+/**
+ * PlanModeTool - Allows AI to suggest switching to plan mode
+ * Use this when the task is complex, requires architecture design, or needs requirements gathering
+ */
+export class PlanModeTool implements Tool {
+    name = 'enter_plan_mode';
+    description = 'Suggest switching to plan mode for complex tasks. Call this when you need to gather requirements, design architecture, or break down a complex implementation before coding.';
+    parameters = {
+        type: 'object',
+        properties: {
+            reason: {
+                type: 'string',
+                description: 'Explain why plan mode is recommended for this task'
+            }
+        },
+        required: ['reason']
+    };
+
+    /**
+     * Execute - Ask user if they want to switch to plan mode
+     */
+    async execute(args: { reason: string }): Promise<string> {
+        console.log('');
+        console.log(chalk.cyan('🎯 AI suggests entering PLAN MODE'));
+        console.log(chalk.gray('─'.repeat(60)));
+        console.log(chalk.dim(`Reason: ${args.reason}`));
+        console.log(chalk.gray('─'.repeat(60)));
+
+        const { confirm } = await inquirer.prompt([
+            {
+                type: 'confirm',
+                name: 'confirm',
+                message: 'Switch to plan mode?',
+                default: true
+            }
+        ]);
+
+        if (confirm) {
+            PlanModeUI.showPlanHeader();
+            return 'User approved. Switching to plan mode for requirements gathering and planning.';
+        }
+
+        return 'User declined. Continuing in current mode.';
+    }
+}