@agentskillkit/agent-skills 1.0.1 → 3.2.2

package/packages/cli/lib/backup.test.js

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Tests for backup module
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs";
+import path from "path";
+import os from "os";
+
+describe("backup", () => {
+    const testDir = path.join(os.tmpdir(), "test-backup-" + Date.now());
+
+    beforeEach(() => {
+        fs.mkdirSync(testDir, { recursive: true });
+    });
+
+    afterEach(() => {
+        if (fs.existsSync(testDir)) {
+            fs.rmSync(testDir, { recursive: true, force: true });
+        }
+    });
+
+    describe("backup file format", () => {
+        it("creates timestamped filename", () => {
+            const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+            const filename = `backup-${timestamp}.yaml`;
+
+            expect(filename).toMatch(/^backup-\d{4}-\d{2}-\d{2}/);
+        });
+
+        it("backup contains valid YAML", () => {
+            const backupContent = `lessons:\n  - id: TEST\n    pattern: "x"`;
+            const backupPath = path.join(testDir, "backup.yaml");
+            fs.writeFileSync(backupPath, backupContent);
+
+            expect(fs.existsSync(backupPath)).toBe(true);
+            expect(fs.readFileSync(backupPath, "utf8")).toContain("lessons:");
+        });
+    });
+
+    describe("listBackups", () => {
+        it("returns empty array when no backups", () => {
+            const backupDir = path.join(testDir, "backups");
+            fs.mkdirSync(backupDir, { recursive: true });
+
+            const files = fs.readdirSync(backupDir);
+            expect(files).toHaveLength(0);
+        });
+
+        it("lists backup files", () => {
+            const backupDir = path.join(testDir, "backups");
+            fs.mkdirSync(backupDir, { recursive: true });
+            fs.writeFileSync(path.join(backupDir, "backup-2024.yaml"), "test");
+
+            const files = fs.readdirSync(backupDir);
+            expect(files).toHaveLength(1);
+        });
+    });
+
+    describe("pruneBackups", () => {
+        it("keeps specified number of backups", () => {
+            const backupDir = path.join(testDir, "backups");
+            fs.mkdirSync(backupDir, { recursive: true });
+
+            // Create 5 backups
+            for (let i = 1; i <= 5; i++) {
+                fs.writeFileSync(path.join(backupDir, `backup-${i}.yaml`), "test");
+            }
+
+            // Simulate pruning to keep 2
+            const files = fs.readdirSync(backupDir).sort().reverse();
+            const toDelete = files.slice(2);
+            toDelete.forEach(f => fs.unlinkSync(path.join(backupDir, f)));
+
+            expect(fs.readdirSync(backupDir)).toHaveLength(2);
+        });
+    });
+});

package/packages/cli/lib/cognitive-lesson.js

@@ -0,0 +1,476 @@
+/**
+ * Cognitive Lesson Engine - Intelligence Layers
+ * 
+ * This module implements the cognitive intelligence that transforms
+ * raw data (mistakes.yaml + improvements.yaml) into Cognitive Lesson Units
+ * 
+ * Levels:
+ * 1. Intent Inference - detect purpose
+ * 2. Pattern Intelligence - context matching
+ * 3. Maturity Calculation - confidence & state
+ * 4. Evolution Analysis - gap detection
+ * 5. Feedback Loop - self-evolution
+ */
+
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = path.join(__dirname, '../../..');
+const KNOWLEDGE_DIR = path.join(PROJECT_ROOT, '.agent/knowledge');
+
+// ============================================================================
+// LEVEL 0: Data Loading
+// ============================================================================
+
+/**
+ * Load mistakes from YAML
+ */
+export function loadMistakes() {
+    const filepath = path.join(KNOWLEDGE_DIR, 'mistakes.yaml');
+    if (!fs.existsSync(filepath)) {
+        return { version: 4.0, mistakes: [] };
+    }
+    try {
+        const content = fs.readFileSync(filepath, 'utf8');
+        return yaml.load(content) || { version: 4.0, mistakes: [] };
+    } catch (error) {
+        console.error('Error loading mistakes:', error.message);
+        return { version: 4.0, mistakes: [] };
+    }
+}
+
+/**
+ * Load improvements from YAML
+ */
+export function loadImprovements() {
+    const filepath = path.join(KNOWLEDGE_DIR, 'improvements.yaml');
+    if (!fs.existsSync(filepath)) {
+        return { version: 4.0, improvements: [] };
+    }
+    try {
+        const content = fs.readFileSync(filepath, 'utf8');
+        return yaml.load(content) || { version: 4.0, improvements: [] };
+    } catch (error) {
+        console.error('Error loading improvements:', error.message);
+        return { version: 4.0, improvements: [] };
+    }
+}
+
+// ============================================================================
+// LEVEL 1: Intent Inference
+// ============================================================================
+
+/**
+ * Intent vocabulary - maps tag patterns to intents
+ */
+const INTENT_PATTERNS = {
+    'safe-rebranding': {
+        keywords: ['rebrand', 'rename', 'file-safety'],
+        goal: 'Rename files/entities without data loss or breaking changes',
+        category: 'file-operations',
+    },
+    'cli-ux-consistency': {
+        keywords: ['cli', 'ux', 'menu', 'navigation', 'clack'],
+        goal: 'Provide consistent, intuitive CLI user experience',
+        category: 'user-experience',
+    },
+    'error-prevention': {
+        keywords: ['validation', 'error', 'check', 'verify'],
+        goal: 'Prevent runtime errors through proactive validation',
+        category: 'reliability',
+    },
+    'code-quality': {
+        keywords: ['import', 'architecture', 'quality'],
+        goal: 'Maintain clean, maintainable code structure',
+        category: 'maintainability',
+    },
+};
+
+/**
+ * Infer lesson intent from tags
+ * NO NEW FILE - computed runtime
+ */
+export function inferIntent(tags) {
+    if (!tags || tags.length === 0) {
+        return {
+            id: 'unknown',
+            goal: 'General code quality improvement',
+            strength: 0.3,
+            category: 'general',
+        };
+    }
+
+    let bestMatch = null;
+    let bestScore = 0;
+
+    for (const [intentId, pattern] of Object.entries(INTENT_PATTERNS)) {
+        const matchCount = tags.filter(tag =>
+            pattern.keywords.some(kw => tag.toLowerCase().includes(kw.toLowerCase()))
+        ).length;
+
+        const score = matchCount / tags.length; // 0-1 confidence
+
+        if (score > bestScore) {
+            bestScore = score;
+            bestMatch = {
+                id: intentId,
+                goal: pattern.goal,
+                strength: score,
+                category: pattern.category,
+            };
+        }
+    }
+
+    return bestMatch || {
+        id: 'unknown',
+        goal: 'General code quality improvement',
+        strength: 0.3,
+        category: 'general',
+    };
+}
+
+// ============================================================================
+// LEVEL 2: Pattern Intelligence
+// ============================================================================
+
+/**
+ * Build execution context from code
+ * Used for contextual pattern matching
+ */
+export function buildContext(filePath, code) {
+    const context = {
+        framework: null,
+        intents: [],
+        environment: 'development',
+        fileType: path.extname(filePath),
+    };
+
+    // Detect framework from imports
+    if (code.includes('@clack/prompts')) context.framework = 'clack';
+    if (code.includes('inquirer')) context.framework = 'inquirer';
+    if (code.includes('react')) context.framework = 'react';
+
+    // Detect intent from code patterns
+    if (code.includes('p.select') || code.includes('showActionMenu')) {
+        context.intents.push('select-menu');
+    }
+    if (code.includes('rename') || code.includes('move')) {
+        context.intents.push('file-operation');
+    }
+    if (code.includes('import')) {
+        context.intents.push('module-usage');
+    }
+
+    return context;
+}
+
+/**
+ * Contextual pattern matching
+ * Smarter than text-only regex
+ */
+export function matchPattern(code, mistake, context) {
+    // Basic pattern match
+    const regex = new RegExp(mistake.pattern);
+    const patternMatch = regex.test(code);
+
+    if (!patternMatch) return false;
+
+    // Context filtering - skip if not applicable
+    if (mistake.when) {
+        // Check framework requirement
+        if (mistake.when.framework && context.framework !== mistake.when.framework) {
+            return false; // Wrong framework, not applicable
+        }
+
+        // Check intent requirement
+        if (mistake.when.intent && !context.intents.includes(mistake.when.intent)) {
+            return false; // Intent mismatch
+        }
+    }
+
+    return true; // Pattern + context match
+}
+
+// ============================================================================
+// LEVEL 3: Maturity Calculation
+// ============================================================================
+
+/**
+ * Calculate evidence score based on hit counts
+ */
+function calculateEvidenceScore(mistakes, improvements) {
+    const totalMistakeHits = mistakes.reduce((sum, m) => sum + (m.hitCount || 0), 0);
+    const totalImprovementHits = improvements.reduce((sum, i) => sum + (i.appliedCount || 0), 0);
+
+    const totalHits = totalMistakeHits + totalImprovementHits;
+
+    if (totalHits === 0) return 0.1; // No evidence
+    if (totalHits < 5) return 0.3;   // Weak
+    if (totalHits < 20) return 0.6;  // Moderate
+    return 0.9;                       // Strong
+}
+
+/**
+ * Calculate recency score
+ */
+function calculateRecencyScore(mistakes, improvements) {
+    const now = Date.now();
+
+    const allDates = [
+        ...mistakes.map(m => new Date(m.lastHit || m.added).getTime()),
+        ...improvements.map(i => new Date(i.lastApplied || i.added).getTime()),
+    ];
+
+    if (allDates.length === 0) return 0.5;
+
+    const lastUpdate = Math.max(...allDates);
+    const daysSinceUpdate = (now - lastUpdate) / (1000 * 60 * 60 * 24);
+
+    if (daysSinceUpdate < 7) return 1.0;    // This week
+    if (daysSinceUpdate < 30) return 0.8;   // This month
+    if (daysSinceUpdate < 90) return 0.5;   // This quarter
+    return 0.3;                              // Stale
+}
+
+/**
+ * Get recommendation based on state and confidence
+ */
+function getRecommendation(state, confidence) {
+    if (state === 'RAW') {
+        return 'URGENT: Discover best practices for this area';
+    }
+    if (state === 'LEARNING' && confidence < 0.5) {
+        return 'Needs more improvements to balance anti-patterns';
+    }
+    if (state === 'MATURE' && confidence > 0.8) {
+        return 'Stable - can be trusted for skill injection';
+    }
+    if (state === 'IDEAL') {
+        return 'Perfect - all best practices, no anti-patterns';
+    }
+    return 'Continue learning';
+}
+
+/**
+ * Calculate lesson maturity metrics
+ */
+export function calculateMaturity(mistakes, improvements) {
+    const m = mistakes.length;
+    const i = improvements.length;
+
+    // State determination
+    let state;
+    if (i === 0 && m > 0) state = 'RAW';          // 🟥 Only mistakes
+    else if (i > 0 && m === 0) state = 'IDEAL';   // 🟦 Only improvements (rare)
+    else if (i >= m) state = 'MATURE';            // 🟩 Balanced or improvement-heavy
+    else state = 'LEARNING';                       // 🟨 More mistakes than solutions
+
+    // Multi-factor confidence
+    const balanceScore = i / (m + i);                                // 0-1: improvement ratio
+    const evidenceScore = calculateEvidenceScore(mistakes, improvements); // 0-1: hit validation
+    const recencyScore = calculateRecencyScore(mistakes, improvements);   // 0-1: freshness
+
+    const confidence = (
+        balanceScore * 0.5 +      // Balance is most important
+        evidenceScore * 0.3 +      // Evidence validates
+        recencyScore * 0.2         // Fresh is better
+    );
+
+    return {
+        state,
+        confidence: Math.round(confidence * 100) / 100,
+        indicators: {
+            balance: Math.round(balanceScore * 100) / 100,
+            evidence: Math.round(evidenceScore * 100) / 100,
+            recency: Math.round(recencyScore * 100) / 100,
+        },
+        coverage: `${m} mistakes / ${i} improvements`,
+        recommendation: getRecommendation(state, confidence),
+    };
+}
+
+// ============================================================================
+// LEVEL 4: Evolution Analysis
+// ============================================================================
+
+/**
+ * Check if mistake has related improvement
+ */
+function hasRelatedImprovement(mistake, improvements) {
+    return improvements.some(i =>
+        i.tags && mistake.tags && i.tags.some(tag => mistake.tags.includes(tag))
+    );
+}
+
+/**
+ * Determine next action from signals
+ */
+function determineNextAction(signals) {
+    if (signals.some(s => s.priority === 'CRITICAL')) {
+        return 'Document solution for high-frequency violations immediately';
+    }
+    if (signals.some(s => s.type === 'SUGGEST_IMPROVEMENT_DISCOVERY')) {
+        return 'Research and document best practices in underserved areas';
+    }
+    return 'Continue normal learning';
+}
+
+/**
+ * Analyze evolution needs and gaps
+ */
+export function analyzeEvolution(mistakes, improvements, intent) {
+    const signals = [];
+    const missingAreas = [];
+
+    // Signal 1: Many mistakes, few solutions
+    if (mistakes.length > improvements.length * 2) {
+        signals.push({
+            type: 'SUGGEST_IMPROVEMENT_DISCOVERY',
+            priority: 'HIGH',
+            reason: `${mistakes.length} anti-patterns but only ${improvements.length} solution(s)`,
+        });
+    }
+
+    // Signal 2: Uncovered tags
+    const mistakeTags = new Set(mistakes.flatMap(m => m.tags || []));
+    const improvementTags = new Set(improvements.flatMap(i => i.tags || []));
+
+    const uncoveredTags = [...mistakeTags].filter(tag => !improvementTags.has(tag));
+
+    uncoveredTags.forEach(tag => {
+        missingAreas.push({
+            area: tag,
+            reason: 'Anti-patterns detected but no best practice documented',
+            mistakeCount: mistakes.filter(m => m.tags && m.tags.includes(tag)).length,
+        });
+    });
+
+    // Signal 3: High-hit mistakes without solution
+    mistakes.forEach(m => {
+        if ((m.hitCount || 0) > 10 && !hasRelatedImprovement(m, improvements)) {
+            signals.push({
+                type: 'HOT_MISTAKE_NEEDS_SOLUTION',
+                priority: 'CRITICAL',
+                mistake: m.id,
+                reason: `${m.title} hit ${m.hitCount} times but no solution documented`,
+            });
+
+            missingAreas.push({
+                area: `solution-for-${m.id}`,
+                reason: 'Frequently violated anti-pattern needs best practice',
+                hitCount: m.hitCount,
+            });
+        }
+    });
+
+    // Signal 4: Intent under-served
+    if (intent && intent.strength > 0.7) {
+        const coverageScore = improvements.length / (mistakes.length + improvements.length);
+        if (coverageScore < 0.5) {
+            signals.push({
+                type: 'INTENT_UNDER_SERVED',
+                priority: 'MEDIUM',
+                reason: `Intent "${intent.goal}" is clear but solutions are scarce`,
+            });
+        }
+    }
+
+    return {
+        signals,
+        missingAreas,
+        nextAction: determineNextAction(signals),
+    };
+}
+
+// ============================================================================
+// SYNTHESIS: Build Cognitive Lessons
+// ============================================================================
+
+/**
+ * Format tag as title
+ */
+function formatTagAsTitle(tag) {
+    return tag
+        .split('-')
+        .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ');
+}
+
+/**
+ * Synthesize Cognitive Lesson Units from mistakes + improvements
+ * THIS IS THE MAIN FUNCTION
+ */
+export function synthesizeLessons() {
+    const mistakesDb = loadMistakes();
+    const improvementsDb = loadImprovements();
+
+    // Group by tag
+    const groups = new Map();
+
+    // Add mistakes to groups
+    mistakesDb.mistakes.forEach(m => {
+        const tags = m.tags || ['uncategorized'];
+        tags.forEach(tag => {
+            if (!groups.has(tag)) {
+                groups.set(tag, { mistakes: [], improvements: [] });
+            }
+            groups.get(tag).mistakes.push(m);
+        });
+    });
+
+    // Add improvements to groups
+    improvementsDb.improvements.forEach(i => {
+        const tags = i.tags || ['uncategorized'];
+        tags.forEach(tag => {
+            if (!groups.has(tag)) {
+                groups.set(tag, { mistakes: [], improvements: [] });
+            }
+            groups.get(tag).improvements.push(i);
+        });
+    });
+
+    // Build Cognitive Lessons
+    const lessons = [];
+    let lessonId = 1;
+
+    groups.forEach((group, tag) => {
+        const intent = inferIntent([tag, ...group.mistakes.flatMap(m => m.tags || [])]);
+        const maturity = calculateMaturity(group.mistakes, group.improvements);
+        const evolution = analyzeEvolution(group.mistakes, group.improvements, intent);
+
+        lessons.push({
+            id: `LESSON-${String(lessonId++).padStart(3, '0')}`,
+            title: formatTagAsTitle(tag),
+            tag,
+            intent,
+            mistakes: group.mistakes,
+            improvements: group.improvements,
+            maturity,
+            evolution,
+        });
+    });
+
+    // Sort by maturity (MATURE first, RAW last)
+    const stateOrder = { 'IDEAL': 0, 'MATURE': 1, 'LEARNING': 2, 'RAW': 3 };
+    lessons.sort((a, b) => {
+        const stateCompare = stateOrder[a.maturity.state] - stateOrder[b.maturity.state];
+        if (stateCompare !== 0) return stateCompare;
+        return b.maturity.confidence - a.maturity.confidence; // Higher confidence first
+    });
+
+    return lessons;
+}
+
+export default {
+    loadMistakes,
+    loadImprovements,
+    inferIntent,
+    buildContext,
+    matchPattern,
+    calculateMaturity,
+    analyzeEvolution,
+    synthesizeLessons,
+};

package/packages/cli/lib/completion.js

@@ -0,0 +1,149 @@
+/**
+ * @fileoverview Shell completion scripts generator
+ * Supports PowerShell, Bash, and Zsh
+ */
+
+/**
+ * All available commands for completion
+ */
+const COMMANDS = [
+    { name: "learn", description: "Teach a new pattern" },
+    { name: "recall", description: "Scan for violations" },
+    { name: "stats", description: "View statistics" },
+    { name: "audit", description: "Run compliance check" },
+    { name: "watch", description: "Real-time monitoring" },
+    { name: "settings", description: "Configure agent behavior" },
+    { name: "backup", description: "Backup & restore data" },
+    { name: "export", description: "Export & import data" },
+    { name: "proposals", description: "AI agent skill updates" },
+    { name: "completion", description: "Shell completion scripts" },
+    { name: "init", description: "Initialize agent config" },
+    { name: "help", description: "Show help" }
+];
+
+/**
+ * Generate PowerShell completion script
+ * @returns {string}
+ */
+export function generatePowerShellCompletion() {
+    const commands = COMMANDS.map(c => `'${c.name}'`).join(", ");
+
+    return `
+# Agent Skill Kit PowerShell Completion
+# Add to your $PROFILE
+
+Register-ArgumentCompleter -Native -CommandName agent -ScriptBlock {
+    param($wordToComplete, $commandAst, $cursorPosition)
+    
+    $commands = @(
+${COMMANDS.map(c => `        @{ Name = '${c.name}'; Description = '${c.description}' }`).join("\n")}
+    )
+    
+    $commands | Where-Object { $_.Name -like "$wordToComplete*" } | ForEach-Object {
+        [System.Management.Automation.CompletionResult]::new(
+            $_.Name,
+            $_.Name,
+            'ParameterValue',
+            $_.Description
+        )
+    }
+}
+
+Write-Host "Agent Skill Kit completion loaded" -ForegroundColor Green
+`;
+}
+
+/**
+ * Generate Bash completion script
+ * @returns {string}
+ */
+export function generateBashCompletion() {
+    const commands = COMMANDS.map(c => c.name).join(" ");
+
+    return `
+# Agent Skill Kit Bash Completion
+# Add to ~/.bashrc or ~/.bash_completion
+
+_agent_completions() {
+    local cur="\${COMP_WORDS[COMP_CWORD]}"
+    local commands="${commands}"
+    
+    COMPREPLY=($(compgen -W "$commands" -- "$cur"))
+}
+
+complete -F _agent_completions agent
+
+echo "Agent Skill Kit completion loaded"
+`;
+}
+
+/**
+ * Generate Zsh completion script
+ * @returns {string}
+ */
+export function generateZshCompletion() {
+    return `
+#compdef agent
+
+# Agent Skill Kit Zsh Completion
+# Add to ~/.zshrc or place in $fpath
+
+_agent() {
+    local -a commands
+    commands=(
+${COMMANDS.map(c => `        '${c.name}:${c.description}'`).join("\n")}
+    )
+    
+    _describe 'command' commands
+}
+
+compdef _agent agent
+
+echo "Agent Skill Kit completion loaded"
+`;
+}
+
+/**
+ * Get shell type from environment
+ * @returns {string} 'powershell' | 'bash' | 'zsh' | 'unknown'
+ */
+export function detectShell() {
+    if (process.platform === "win32") {
+        return "powershell";
+    }
+
+    const shell = process.env.SHELL || "";
+    if (shell.includes("zsh")) return "zsh";
+    if (shell.includes("bash")) return "bash";
+
+    return "unknown";
+}
+
+/**
+ * Get completion script for current or specified shell
+ * @param {string} [shell] - Optional shell type
+ * @returns {{ shell: string, script: string }}
+ */
+export function getCompletionScript(shell) {
+    const targetShell = shell || detectShell();
+
+    switch (targetShell) {
+        case "powershell":
+            return { shell: "powershell", script: generatePowerShellCompletion() };
+        case "bash":
+            return { shell: "bash", script: generateBashCompletion() };
+        case "zsh":
+            return { shell: "zsh", script: generateZshCompletion() };
+        default:
+            return { shell: "unknown", script: "" };
+    }
+}
+
+export default {
+    COMMANDS,
+    generatePowerShellCompletion,
+    generateBashCompletion,
+    generateZshCompletion,
+    detectShell,
+    getCompletionScript
+};