@indiccoder/mentis-cli 1.0.8 → 1.1.0

package/dist/utils/ConversationCompacter.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * ConversationCompacter - Compact conversation to save tokens
+ * Summarizes conversation history while preserving important context
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConversationCompacter = void 0;
+const inquirer_1 = __importDefault(require("inquirer"));
+const chalk_1 = __importDefault(require("chalk"));
+class ConversationCompacter {
+    /**
+     * Compact conversation history using AI
+     */
+    async compact(history, modelClient, options) {
+        const { keepSystemMessages = true, focusTopic } = options || {};
+        // Preserve system-style messages
+        const preserved = [];
+        const toCompact = [];
+        for (const msg of history) {
+            if (msg.role === 'system' || msg.role === 'tool') {
+                preserved.push(msg);
+            }
+            else {
+                toCompact.push(msg);
+            }
+        }
+        if (toCompact.length === 0) {
+            return history;
+        }
+        // Create compaction prompt
+        let compactPrompt = 'Please summarize the following conversation into a concise overview. ';
+        compactPrompt += 'Include:\n';
+        compactPrompt += '- The main topic/problem being discussed\n';
+        compactPrompt += '- Key decisions made\n';
+        compactPrompt += '- Important technical details\n';
+        compactPrompt += '- Current status/next steps\n\n';
+        if (focusTopic) {
+            compactPrompt += `Focus primarily on content related to: ${focusTopic}\n\n`;
+        }
+        compactPrompt += 'Return ONLY the summary, no other text.\n\n---\n\n';
+        for (const msg of toCompact.slice(-10)) { // Last 10 messages for context
+            compactPrompt += `${msg.role.toUpperCase()}: ${msg.content}\n\n`;
+        }
+        try {
+            // Call AI to summarize
+            const summaryResponse = await modelClient.chat([{ role: 'user', content: compactPrompt }], []);
+            const summary = summaryResponse.content;
+            // Create new compacted history
+            const newHistory = [...preserved];
+            // Add summary as a system message for context
+            newHistory.push({
+                role: 'system',
+                content: `[Previous Conversation Summary]\n${summary}`
+            });
+            return newHistory;
+        }
+        catch (error) {
+            console.error('Compaction failed:', error);
+            return history; // Return original if compaction fails
+        }
+    }
+    /**
+     * Prompt user to compact when threshold is reached
+     */
+    async promptIfCompactNeeded(percentage, history, modelClient) {
+        if (percentage < 80) {
+            return history;
+        }
+        console.log(chalk_1.default.yellow(`\n⚠️  Context is ${percentage}% full. Consider compacting to save tokens.`));
+        const { shouldCompact } = await inquirer_1.default.prompt([
+            {
+                type: 'confirm',
+                name: 'shouldCompact',
+                message: 'Compact conversation now?',
+                default: true
+            }
+        ]);
+        if (!shouldCompact) {
+            return history;
+        }
+        const { focusTopic } = await inquirer_1.default.prompt([
+            {
+                type: 'input',
+                name: 'focusTopic',
+                message: 'Focus on specific topic? (leave empty for general)',
+                default: ''
+            }
+        ]);
+        return await this.compact(history, modelClient, {
+            keepSystemMessages: true,
+            focusTopic: focusTopic || undefined
+        });
+    }
+}
+exports.ConversationCompacter = ConversationCompacter;

package/dist/utils/ProjectInitializer.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * ProjectInitializer - Initialize project with .mentis.md
+ * Interactive wizard for creating project guide files
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProjectInitializer = void 0;
+const inquirer_1 = __importDefault(require("inquirer"));
+const chalk_1 = __importDefault(require("chalk"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+class ProjectInitializer {
+    /**
+     * Run the interactive project initialization wizard
+     */
+    async run(cwd = process.cwd()) {
+        console.log('\n📁 Initialize Project with .mentis.md\n');
+        // Step 1: Project name
+        const { projectName } = await inquirer_1.default.prompt([
+            {
+                type: 'input',
+                name: 'projectName',
+                message: 'Project name:',
+                default: path.basename(cwd)
+            }
+        ]);
+        // Step 2: Project description
+        const { description } = await inquirer_1.default.prompt([
+            {
+                type: 'input',
+                name: 'description',
+                message: 'Brief description:',
+                default: 'A software project'
+            }
+        ]);
+        // Step 3: Tech stack
+        const { techStack } = await inquirer_1.default.prompt([
+            {
+                type: 'checkbox',
+                name: 'techStack',
+                message: 'Select technologies:',
+                choices: [
+                    'TypeScript',
+                    'JavaScript',
+                    'Python',
+                    'React',
+                    'Vue',
+                    'Node.js',
+                    'Express',
+                    'PostgreSQL',
+                    'MongoDB',
+                    'Redis',
+                    'Docker',
+                    'GraphQL',
+                    'REST API',
+                    'Other'
+                ]
+            }
+        ]);
+        // Step 4: Project type
+        const { projectType } = await inquirer_1.default.prompt([
+            {
+                type: 'list',
+                name: 'projectType',
+                message: 'Project type:',
+                choices: ['Web Application', 'API/Backend', 'CLI Tool', 'Library/Package', 'Mobile App', 'Desktop App', 'Other']
+            }
+        ]);
+        // Step 5: Conventions
+        const { useConventions } = await inquirer_1.default.prompt([
+            {
+                type: 'confirm',
+                name: 'useConventions',
+                message: 'Add coding conventions?',
+                default: true
+            }
+        ]);
+        let conventions = '';
+        if (useConventions) {
+            const { conventionStyle } = await inquirer_1.default.prompt([
+                {
+                    type: 'list',
+                    name: 'conventionStyle',
+                    message: 'Style guide:',
+                    choices: ['Standard', 'Airbnb', 'Google', 'Prettier', 'Custom']
+                }
+            ]);
+            conventions = this.getConventionText(conventionStyle);
+        }
+        // Create .mentis.md content
+        const content = this.generateMentisMd({
+            projectName,
+            description,
+            techStack,
+            projectType,
+            conventions
+        });
+        // Write to file
+        const mentisMdPath = path.join(cwd, '.mentis.md');
+        fs.writeFileSync(mentisMdPath, content, 'utf-8');
+        console.log(chalk_1.default.green(`\n✓ Created .mentis.md`));
+        console.log(chalk_1.default.dim(`\nTip: Edit .mentis.md to add project-specific instructions for Mentis.\n`));
+        return true;
+    }
+    /**
+     * Generate .mentis.md content
+     */
+    generateMentisMd(options) {
+        const { projectName, description, techStack, projectType, conventions } = options;
+        let content = `# ${projectName}\n\n`;
+        content += `${description}\n\n`;
+        content += `**Type**: ${projectType}\n\n`;
+        content += `## Tech Stack\n\n`;
+        content += techStack.map(t => `- ${t}`).join('\n');
+        content += `\n\n`;
+        if (conventions) {
+            content += `## Coding Conventions\n\n`;
+            content += `${conventions}\n\n`;
+        }
+        content += `## Project Structure\n\n`;
+        content += `<!-- Add project structure here -->\n\n`;
+        content += `## Guidelines for Mentis\n\n`;
+        content += `- When writing code, follow the conventions above\n`;
+        content += `- Prefer existing patterns in the codebase\n`;
+        content += `- Add comments for complex logic\n`;
+        content += `- Run tests before suggesting changes\n\n`;
+        content += `## Common Commands\n\n`;
+        content += `<!-- Add common development commands here -->\n`;
+        return content;
+    }
+    /**
+     * Get convention text based on style
+     */
+    getConventionText(style) {
+        const conventions = {
+            'Standard': `- Use 2 spaces for indentation\n- Use camelCase for variables\n- Use PascalCase for classes\n- Prefer const over let\n- Use arrow functions`,
+            'Airbnb': `- Follow Airbnb Style Guide\n- Use 2 spaces for indentation\n- Prefer named exports\n- Use template literals`,
+            'Google': `- Follow Google JavaScript Style Guide\n- Use 2 spaces for indentation\n- JSDoc comments for functions`,
+            'Prettier': `- Use Prettier for formatting\n- 2 spaces for indentation\n- Single quotes for strings\n- No trailing commas`,
+            'Custom': `- Define your conventions below`
+        };
+        return conventions[style] || conventions['Standard'];
+    }
+}
+exports.ProjectInitializer = ProjectInitializer;

package/docs/SKILLS.md

@@ -0,0 +1,319 @@
+# Agent Skills - User Guide
+
+## Overview
+
+Agent Skills allow you to package your expertise into modular, reusable capabilities that Mentis can autonomously discover and use. Skills are organized folders containing instructions, scripts, and resources that extend Mentis's functionality.
+
+## How Skills Work
+
+1. **Discovery**: Mentis scans `~/.mentis/skills/` (personal) and `.mentis/skills/` (project) for skills
+2. **Metadata Injection**: At startup, skill names and descriptions are added to the system context
+3. **Model-Invoked**: When Mentis determines a skill is relevant to your request, it automatically loads the full skill content
+4. **Progressive Disclosure**: Supporting files are only loaded when explicitly referenced
+
+## Skill Structure
+
+```
+skill-directory/
+├── SKILL.md           # Required: YAML frontmatter + instructions
+├── reference.md       # Optional: Additional documentation
+├── examples.md        # Optional: Usage examples
+├── scripts/           # Optional: Executable utilities
+│   └── helper.py
+└── templates/         # Optional: File templates
+    └── template.txt
+```
+
+## SKILL.md Format
+
+```yaml
+---
+name: your-skill-name
+description: What this skill does and when to use it
+allowed-tools: Read, Grep, Glob  # Optional: Restrict tools
+---
+
+# Your Skill Name
+
+## Instructions
+Step-by-step guidance for Mentis.
+
+## Examples
+Concrete usage examples.
+```
+
+### Required Fields
+
+- **name**: Lowercase letters, numbers, hyphens only (max 64 characters)
+- **description**: What the skill does + when to use it (max 1024 characters)
+
+### Optional Fields
+
+- **allowed-tools**: List of tools the skill can use without permission
+
+## Creating Your First Skill
+
+### Option 1: Interactive Wizard
+
+```
+/skills create
+```
+
+Follow the prompts:
+1. Enter skill name (e.g., `my-custom-skill`)
+2. Choose type (personal or project)
+3. Write description (include "Use when..." for better discovery)
+4. Optionally restrict allowed tools
+
+### Option 2: Manual Creation
+
+```bash
+# Create directory
+mkdir -p ~/.mentis/skills/my-skill
+
+# Create SKILL.md
+cat > ~/.mentis/skills/my-skill/SKILL.md << 'EOF'
+---
+name: my-skill
+description: Does something useful. Use when the user mentions specific keywords.
+---
+
+# My Skill
+
+## Instructions
+1. Do this first
+2. Then do that
+
+## Examples
+Example usage...
+EOF
+```
+
+## Skill Commands
+
+| Command | Description |
+|---------|-------------|
+| `/skills` | List all available skills |
+| `/skills list` | List all available skills |
+| `/skills show <name>` | Display full skill content |
+| `/skills create [name]` | Interactive skill creator |
+| `/skills validate` | Validate all skills for errors |
+
+## Skill Types
+
+### Personal Skills
+
+Stored in `~/.mentis/skills/` - available across all projects.
+
+**Use for**:
+- Individual workflows and preferences
+- Experimental skills in development
+- Personal productivity tools
+
+### Project Skills
+
+Stored in `.mentis/skills/` - shared with your team via git.
+
+**Use for**:
+- Team workflows and conventions
+- Project-specific expertise
+- Shared utilities and scripts
+
+## Best Practices
+
+### 1. Write Clear Descriptions
+
+❌ **Too vague**:
+```yaml
+description: Helps with data
+```
+
+✅ **Specific**:
+```yaml
+description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files.
+```
+
+**Tip**: Include both what the skill does AND when to use it.
+
+### 2. Use Progressive Disclosure
+
+Keep `SKILL.md` lean. Move detailed content to supporting files:
+
+**SKILL.md**:
+```markdown
+## Quick Start
+Basic instructions here.
+
+For advanced patterns, see [reference.md](reference.md).
+```
+
+**reference.md**:
+```markdown
+# Advanced Reference
+Detailed documentation...
+```
+
+### 3. Validate Your Skills
+
+```
+/skills validate
+```
+
+Check for:
+- Missing required fields
+- Invalid name format
+- Description length
+- Unknown tools in allowed-tools
+
+### 4. Test Skills
+
+After creating a skill:
+1. Restart Mentis to load it
+2. Ask a question that should trigger the skill
+3. Verify Mentis loads and uses the skill
+
+## Example Skills
+
+### commit-helper
+
+```yaml
+---
+name: commit-helper
+description: Generates clear, conventional commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
+allowed-tools: ["GitStatus", "GitDiff", "GitCommit"]
+---
+```
+
+### code-reviewer
+
+```yaml
+---
+name: code-reviewer
+description: Reviews code for best practices, potential bugs, security issues. Use when reviewing code or checking PRs.
+allowed-tools: ["Read", "Grep", "Glob"]
+---
+```
+
+See `examples/skills/` for complete examples.
+
+## Troubleshooting
+
+### Skill Not Loading
+
+**Check 1**: File location
+```bash
+# Personal skills
+ls ~/.mentis/skills/my-skill/SKILL.md
+
+# Project skills
+ls .mentis/skills/my-skill/SKILL.md
+```
+
+**Check 2**: YAML syntax
+```bash
+# Verify frontmatter format
+cat ~/.mentis/skills/my-skill/SKILL.md | head -n 10
+```
+
+Ensure:
+- `---` on line 1
+- `---` closes frontmatter
+- Valid YAML (no tabs, correct indentation)
+
+**Check 3**: Validation
+```bash
+/skills validate
+```
+
+### Mentis Not Using Skill
+
+**Problem**: Skill exists but Mentis doesn't invoke it.
+
+**Solution**: Improve description to include trigger keywords.
+
+❌ **Vague**:
+```yaml
+description: Code improvement
+```
+
+✅ **Clear with triggers**:
+```yaml
+description: Refactor code for better performance and readability. Use when the user mentions optimization, refactoring, performance, or code cleanup.
+```
+
+### allowed-tools Not Working
+
+**Check**: Tool names must match Mentis tool names exactly.
+
+Valid tools: `Read`, `Write`, `Edit`, `Grep`, `Glob`, `ListDir`, `SearchFile`, `RunShell`, `WebSearch`, `GitStatus`, `GitDiff`, `GitCommit`, `GitPush`, `GitPull`
+
+## Sharing Skills
+
+### Via Git (Project Skills)
+
+```bash
+# Add to repository
+git add .mentis/skills/
+git commit -m "Add team skill for X"
+git push
+
+# Team members get it automatically
+git pull
+# Skill is now available
+```
+
+### Via Manual Copy
+
+```bash
+# Export
+tar czf my-skill.tar.gz -C ~/.mentis/skills my-skill
+
+# Import on another machine
+tar xzf my-skill.tar.gz -C ~/.mentis/skills
+```
+
+## Advanced Topics
+
+### Code Execution in Skills
+
+Skills can include executable scripts:
+
+```markdown
+## Running the Script
+
+```bash
+python scripts/analyze.py data.csv
+```
+```
+
+Mentis will execute the script and return results.
+
+### Tool Permissions
+
+Use `allowed-tools` to:
+- Restrict read-only skills from making changes
+- Limit scope of specialized skills
+- Add security for sensitive operations
+
+```yaml
+---
+allowed-tools: ["Read", "Grep", "Glob"]
+---
+```
+
+When this skill is active, only these tools can be used without explicit permission.
+
+### Dynamic Tool Loading
+
+The model can invoke tools to load skills:
+
+```
+load_skill({ name: "pdf-processing" })
+```
+
+This loads the full SKILL.md content into context.
+
+## Resources
+
+- [Claude Code Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) - Official announcement
+- [examples/skills/](../examples/skills/) - Example skills directory

package/examples/skills/code-reviewer/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: code-reviewer
+description: Reviews code for best practices, potential bugs, security issues, and improvements. Use when reviewing code, checking pull requests, or analyzing code quality.
+allowed-tools: ["Read", "Grep", "Glob"]
+---
+
+# Code Reviewer
+
+This skill provides systematic code review to identify issues and suggest improvements.
+
+## Review Checklist
+
+### 1. Code Organization
+- [ ] Single Responsibility Principle followed
+- [ ] Clear and descriptive names
+- [ ] Proper separation of concerns
+- [ ] Appropriate abstraction levels
+
+### 2. Error Handling
+- [ ] Proper error handling for all operations
+- [ ] Meaningful error messages
+- [ ] Graceful degradation
+- [ ] No silent failures
+
+### 3. Performance
+- [ ] No obvious performance issues
+- [ ] Appropriate data structures used
+- [ ] Caching where applicable
+- [ ] Resource cleanup (no memory leaks)
+
+### 4. Security
+- [ ] Input validation
+- [ ] No hardcoded credentials
+- [ ] SQL injection prevention
+- [ ] XSS prevention (web apps)
+- [ ] Proper authentication/authorization
+
+### 5. Testing
+- [ ] Test coverage adequate
+- [ ] Edge cases considered
+- [ ] Error scenarios tested
+
+### 6. Documentation
+- [ ] Complex logic explained
+- [ ] Public API documented
+- [ ] Usage examples provided
+
+## How to Review
+
+1. **Understand the purpose**: What is this code supposed to do?
+2. **Read the code**: Follow the execution flow
+3. **Check against checklist**: Go through each category
+4. **Provide feedback**:
+   - **Critical**: Must fix before merge
+   - **Important**: Should fix
+   - **Suggestion**: Nice to have
+5. **Explain why**: Don't just point out problems
+
+## Feedback Format
+
+```markdown
+## Critical Issues
+- Issue description
+  - Location: file.ts:123
+  - Why: [reason]
+  - Suggestion: [fix]
+
+## Important Notes
+- Note description
+  - Location: file.ts:456
+
+## Suggestions
+- Suggestion description
+  - Could improve [aspect]
+```
+
+## Common Issues to Look For
+
+| Issue | Example |
+|-------|---------|
+| Unhandled promises | No `.catch()` or `await` without try/catch |
+| Missing null checks | Accessing properties without null check |
+| Race conditions | Async operations without proper ordering |
+| Resource leaks | File handles, connections not closed |
+| Type coercion | Using `==` instead of `===` |
+| Magic numbers | Unexplained numeric literals |
+| Large functions | Functions > 50 lines |
+| Deep nesting | More than 3 levels of nesting |