@indiccoder/mentis-cli 1.1.3 → 1.1.4

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/utils/__mocks__/chalk.ts

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

package/src/utils/__tests__/ContextVisualizer.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Tests for ContextVisualizer
+ */
+
+import { ContextVisualizer } from '../ContextVisualizer';
+import { ChatMessage } from '../../llm/ModelInterface';
+
+describe('ContextVisualizer', () => {
+    let visualizer: ContextVisualizer;
+
+    beforeEach(() => {
+        visualizer = new ContextVisualizer();
+    });
+
+    describe('calculateUsage', () => {
+        it('should handle empty history', () => {
+            const history: ChatMessage[] = [];
+            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: ChatMessage[] = [
+                { 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: ChatMessage[] = [
+                { 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: ChatMessage[] = [
+                { 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: ChatMessage[] = [
+                { 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: ChatMessage[] = [];
+            const usage = visualizer.calculateUsage(history);
+
+            expect(usage.maxTokens).toBe(32000);
+            expect(usage.percentage).toBeGreaterThan(1); // Should be higher percentage with smaller max
+        });
+    });
+});