@agentskillkit/agent-skills 1.0.1 → 3.2.1

package/packages/cli/lib/learn.js

@@ -1,15 +1,24 @@
 #!/usr/bin/env node
 /**
- * Smart Learning Script - ESM Version
+ * Smart Learning Script - ESM Version (Production-Ready)
  * 
  * The "Teacher" script. Adds new lessons to the system memory.
- * Usage: node learn.js --add --pattern "regex" --message "why bad"
+ * 
+ * Features:
+ * - Manual lesson addition
+ * - Category tagging
+ * - Source tracking (manual, eslint, test-failure)
+ * 
+ * Usage:
+ *   ag-smart learn --add --pattern "regex" --message "why bad"
+ *   ag-smart learn --list
+ *   ag-smart learn --remove <id>
  */
 
 import fs from "fs";
 import path from "path";
 import yaml from "js-yaml";
-import { KNOWLEDGE_DIR, LESSONS_PATH, DEBUG } from "./config.js";
+import { KNOWLEDGE_DIR, LESSONS_PATH, DEBUG, VERSION } from "./config.js";
 
 // ============================================================================
 // CORE FUNCTIONS
@@ -17,19 +26,18 @@ import { KNOWLEDGE_DIR, LESSONS_PATH, DEBUG } from "./config.js";
 
 /**
  * Load knowledge base from YAML file
- * @returns {import('./types.js').KnowledgeBase}
+ * @returns {{ lessons: Array, version?: number }}
  */
 function loadKnowledge() {
     try {
         if (!fs.existsSync(LESSONS_PATH)) {
-            // Create if missing
-            const initial = { lessons: [] };
+            const initial = { lessons: [], version: 1 };
             fs.mkdirSync(KNOWLEDGE_DIR, { recursive: true });
             fs.writeFileSync(LESSONS_PATH, yaml.dump(initial), "utf8");
             return initial;
         }
         const content = fs.readFileSync(LESSONS_PATH, "utf8");
-        return yaml.load(content) || { lessons: [] };
+        return yaml.load(content) || { lessons: [], version: 1 };
     } catch (error) {
         console.error("❌ Failed to load knowledge base:", error.message);
         if (DEBUG) console.error(error.stack);
@@ -39,11 +47,12 @@ function loadKnowledge() {
 
 /**
  * Save knowledge base to YAML file
- * @param {import('./types.js').KnowledgeBase} data
+ * @param {{ lessons: Array, version?: number }} data
  */
 function saveKnowledge(data) {
     try {
-        const str = yaml.dump(data, { lineWidth: -1 });
+        fs.mkdirSync(KNOWLEDGE_DIR, { recursive: true });
+        const str = yaml.dump(data, { lineWidth: -1, quotingType: '"' });
         fs.writeFileSync(LESSONS_PATH, str, "utf8");
         console.log("✅ Knowledge base updated successfully.");
     } catch (error) {
@@ -57,9 +66,10 @@ function saveKnowledge(data) {
  * Add a new lesson to the knowledge base
  * @param {string} pattern - Regex pattern
  * @param {string} message - Explanation message
- * @param {'WARNING'|'ERROR'} severity - Severity level
+ * @param {string} severity - WARNING or ERROR
+ * @param {string} category - Category tag
  */
-function addLesson(pattern, message, severity = "WARNING") {
+function addLesson(pattern, message, severity = "WARNING", category = "general") {
     const db = loadKnowledge();
 
     // Validate Regex
@@ -71,19 +81,30 @@ function addLesson(pattern, message, severity = "WARNING") {
     }
 
     // Validate severity
-    if (!["WARNING", "ERROR"].includes(severity)) {
+    if (!["WARNING", "ERROR"].includes(severity.toUpperCase())) {
         console.error("❌ Invalid severity. Must be WARNING or ERROR");
         process.exit(1);
     }
 
+    // Check for duplicates
+    const exists = db.lessons.some(l => l.pattern === pattern);
+    if (exists) {
+        console.log("⚠️  Pattern already exists in knowledge base.");
+        process.exit(0);
+    }
+
     const id = `LEARN-${String(db.lessons.length + 1).padStart(3, "0")}`;
 
-    /** @type {import('./types.js').Lesson} */
     const lesson = {
         id,
         pattern,
         message,
-        severity,
+        severity: severity.toUpperCase(),
+        category,
+        source: "manual",
+        hitCount: 0,
+        lastHit: null,
+        autoEscalated: false,
         addedAt: new Date().toISOString()
     };
 
@@ -91,25 +112,63 @@ function addLesson(pattern, message, severity = "WARNING") {
     saveKnowledge(db);
 
     console.log(`\n🎓 Lesson Learned: [${id}]`);
-    console.log(`   Pattern: /${pattern}/`);
-    console.log(`   Message: ${message}`);
+    console.log(`   Pattern:  /${pattern}/`);
+    console.log(`   Message:  ${message}`);
+    console.log(`   Severity: ${severity.toUpperCase()}`);
+    console.log(`   Category: ${category}\n`);
+}
+
+/**
+ * Remove a lesson by ID
+ * @param {string} lessonId 
+ */
+function removeLesson(lessonId) {
+    const db = loadKnowledge();
+    const idx = db.lessons.findIndex(l => l.id === lessonId.toUpperCase());
+
+    if (idx === -1) {
+        console.log(`❌ Lesson not found: ${lessonId}`);
+        process.exit(1);
+    }
+
+    const removed = db.lessons.splice(idx, 1)[0];
+    saveKnowledge(db);
+
+    console.log(`\n🗑️  Removed lesson: [${removed.id}]`);
+    console.log(`   Pattern: /${removed.pattern}/\n`);
 }
 
 /**
  * List all learned lessons
+ * @param {string} category - Filter by category
  */
-function listLessons() {
+function listLessons(category = null) {
     const db = loadKnowledge();
+
     if (!db.lessons || db.lessons.length === 0) {
-        console.log("ℹ️  No lessons learned yet.");
+        console.log("\nℹ️  No lessons learned yet.");
+        console.log("   Use: ag-smart learn --add --pattern \"pat\" --message \"msg\"\n");
         return;
     }
 
-    console.log("\n🧠 Smart Agent Knowledge Base:\n");
-    db.lessons.forEach(l => {
-        console.log(`  [${l.id}] /${l.pattern}/ -> ${l.message} (${l.severity})`);
+    let lessons = db.lessons;
+    if (category) {
+        lessons = lessons.filter(l => l.category === category);
+    }
+
+    console.log(`\n🧠 Agent Skill Kit Knowledge Base (${lessons.length} lesson(s))\n`);
+    console.log("─".repeat(60));
+
+    lessons.forEach(l => {
+        const icon = l.severity === "ERROR" ? "❌" : "⚠️";
+        const hits = l.hitCount ? ` (${l.hitCount} hits)` : "";
+        const escalated = l.autoEscalated ? " ⚡" : "";
+
+        console.log(`${icon} [${l.id}] ${l.message}${hits}${escalated}`);
+        console.log(`   Pattern: /${l.pattern}/`);
+        console.log(`   Category: ${l.category || "general"} | Source: ${l.source || "manual"}`);
+        console.log("");
     });
-    console.log("");
 }
 
 // ============================================================================
@@ -118,19 +177,27 @@ function listLessons() {
 
 function printHelp() {
     console.log(`
-Smart Learning Tool
+🎓 Smart Learning Tool v${VERSION}
 
 USAGE:
-  node learn.js --add --pattern "..." --message "..."
-  node learn.js --list
-  node learn.js --help
+  ag-smart learn --add --pattern "..." --message "..."
+  ag-smart learn --list [--category <cat>]
+  ag-smart learn --remove <ID>
 
 OPTIONS:
-  --add       Add a new lesson
-  --pattern   Regex pattern to flag
-  --message   Explanation message
-  --severity  Severity (WARNING/ERROR), default WARNING
-  --list      List all learned lessons
+  --add         Add a new lesson
+  --pattern     Regex pattern to flag
+  --message     Explanation message
+  --severity    WARNING (default) or ERROR
+  --category    Category tag (default: general)
+  --list        List all lessons
+  --remove      Remove lesson by ID
+  --help        Show this help
+
+EXAMPLES:
+  ag-smart learn --add --pattern "console\\.log" --message "No console.log in production" --severity ERROR
+  ag-smart learn --list
+  ag-smart learn --remove LEARN-001
 `);
 }
 
@@ -143,7 +210,20 @@ function main() {
     }
 
     if (args.includes("--list")) {
-        listLessons();
+        const catIdx = args.indexOf("--category");
+        const category = catIdx !== -1 ? args[catIdx + 1] : null;
+        listLessons(category);
+        process.exit(0);
+    }
+
+    if (args.includes("--remove")) {
+        const removeIdx = args.indexOf("--remove");
+        const lessonId = args[removeIdx + 1];
+        if (!lessonId) {
+            console.error("❌ Missing lesson ID for --remove");
+            process.exit(1);
+        }
+        removeLesson(lessonId);
         process.exit(0);
     }
 
@@ -151,6 +231,7 @@ function main() {
         const pIdx = args.indexOf("--pattern");
         const mIdx = args.indexOf("--message");
         const sIdx = args.indexOf("--severity");
+        const cIdx = args.indexOf("--category");
 
         if (pIdx === -1 || mIdx === -1) {
             console.error("❌ --pattern and --message are required for --add");
@@ -160,13 +241,14 @@ function main() {
         const pattern = args[pIdx + 1];
         const message = args[mIdx + 1];
         const severity = sIdx !== -1 ? args[sIdx + 1] : "WARNING";
+        const category = cIdx !== -1 ? args[cIdx + 1] : "general";
 
         if (!pattern || !message) {
             console.error("❌ Missing values for pattern/message");
             process.exit(1);
         }
 
-        addLesson(pattern, message, severity);
+        addLesson(pattern, message, severity, category);
     }
 }
 

package/packages/cli/lib/migrate-to-v4.js

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+/**
+ * Migration Script: v3.x → v4.x Cognitive Lesson Engine
+ * 
+ * This script:
+ * 1. Backs up current lessons-learned.yaml
+ * 2. Classifies lessons into mistakes vs improvements
+ * 3. Generates mistakes.yaml and improvements.yaml
+ * 4. Preserves all existing data
+ */
+
+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');
+const LESSONS_PATH = path.join(KNOWLEDGE_DIR, 'lessons-learned.yaml');
+const BACKUP_DIR = path.join(KNOWLEDGE_DIR, '_migration_backup');
+const MISTAKES_PATH = path.join(KNOWLEDGE_DIR, 'mistakes.yaml');
+const IMPROVEMENTS_PATH = path.join(KNOWLEDGE_DIR, 'improvements.yaml');
+
+// ============================================================================
+// STEP 1: Backup Current Data
+// ============================================================================
+
+function backupCurrentLessons() {
+    console.log('📦 Step 1: Backing up current lessons...');
+
+    if (!fs.existsSync(LESSONS_PATH)) {
+        console.log('⚠️  No lessons-learned.yaml found, skipping backup');
+        return null;
+    }
+
+    // Create backup directory
+    fs.mkdirSync(BACKUP_DIR, { recursive: true });
+
+    // Backup with timestamp
+    const timestamp = new Date().toISOString().replace(/:/g, '-');
+    const backupPath = path.join(BACKUP_DIR, `lessons-learned_${timestamp}.yaml`);
+
+    fs.copyFileSync(LESSONS_PATH, backupPath);
+    console.log(`✅ Backup created: ${backupPath}`);
+
+    // Load and return data
+    const content = fs.readFileSync(LESSONS_PATH, 'utf8');
+    return yaml.load(content);
+}
+
+// ============================================================================
+// STEP 2: Classification Logic
+// ============================================================================
+
+/**
+ * Auto-classify lesson as mistake or improvement
+ * Conservative: default to mistake (safer assumption)
+ */
+function classifyLesson(lesson) {
+    const message = lesson.message.toLowerCase();
+
+    // Keywords that indicate improvement/best practice
+    const improvementKeywords = [
+        'use ', 'always use', 'prefer ', 'should use',
+        'best practice', 'recommended', 'instead use',
+        'better to', 'proper way', 'correct approach'
+    ];
+
+    // Keywords that indicate mistake/anti-pattern
+    const mistakeKeywords = [
+        'never', 'avoid', 'don\'t', 'do not', 'incorrect',
+        'wrong', 'bad', 'conflicts', 'causes', 'breaks'
+    ];
+
+    const hasMistakeKeyword = mistakeKeywords.some(kw => message.includes(kw));
+    const hasImprovementKeyword = improvementKeywords.some(kw => message.includes(kw));
+
+    // Both keywords present - need manual review
+    if (hasMistakeKeyword && hasImprovementKeyword) {
+        return 'mixed';
+    }
+
+    // Clear improvement
+    if (hasImprovementKeyword && !hasMistakeKeyword) {
+        return 'improvement';
+    }
+
+    // Default: mistake (conservative)
+    return 'mistake';
+}
+
+/**
+ * Extract tags from lesson data
+ * Tags used for grouping into Cognitive Lessons
+ */
+function extractTags(lesson) {
+    const tags = new Set();
+
+    // Add category as tag
+    if (lesson.category) {
+        tags.add(lesson.category);
+    }
+
+    // Extract from pattern
+    const pattern = lesson.pattern.toLowerCase();
+    if (pattern.includes('select')) tags.add('cli-navigation');
+    if (pattern.includes('menu')) tags.add('ux');
+    if (pattern.includes('rename') || pattern.includes('move') || pattern.includes('rebrand')) {
+        tags.add('file-safety');
+        tags.add('rebranding');
+    }
+    if (pattern.includes('import')) tags.add('imports');
+    if (pattern.includes('recursive')) tags.add('architecture');
+
+    // Extract from message
+    const message = lesson.message.toLowerCase();
+    if (message.includes('esc')) tags.add('cli-navigation');
+    if (message.includes('clack')) tags.add('clack-framework');
+    if (message.includes('menu')) tags.add('ux');
+    if (message.includes('security')) tags.add('security');
+    if (message.includes('performance')) tags.add('performance');
+
+    return Array.from(tags);
+}
+
+/**
+ * Split mixed lessons into mistake + improvement
+ */
+function splitMixedLesson(lesson) {
+    const message = lesson.message;
+
+    // Try to extract both parts
+    // Pattern: "NEVER X. Use Y instead"
+    const neverMatch = message.match(/(NEVER|Don't|Avoid)\s+([^.]+)\./i);
+    const useMatch = message.match(/(Use|Always use|Instead use)\s+([^.]+)/i);
+
+    const mistake = {
+        ...lesson,
+        id: lesson.id.replace('LEARN', 'MISTAKE'),
+        title: neverMatch ? neverMatch[0] : message.split('.')[0],
+        message: neverMatch ? neverMatch[0] : message.split('.')[0],
+    };
+
+    let improvement = null;
+    if (useMatch) {
+        improvement = {
+            id: lesson.id.replace('LEARN', 'IMPROVE'),
+            title: useMatch[0],
+            message: useMatch[0],
+            pattern: lesson.pattern,
+            priority: lesson.severity === 'ERROR' ? 'HIGH' : 'MEDIUM',
+            tags: extractTags(lesson),
+            added: lesson.addedAt,
+            appliedCount: 0,
+        };
+    }
+
+    return { mistake, improvement };
+}
+
+// ============================================================================
+// STEP 3: Migration Logic
+// ============================================================================
+
+function migrateToV4(oldData) {
+    console.log('\n🔄 Step 2: Classifying lessons...');
+
+    const mistakes = [];
+    const improvements = [];
+    const needsReview = [];
+
+    oldData.lessons.forEach((lesson, index) => {
+        const classification = classifyLesson(lesson);
+        const tags = extractTags(lesson);
+
+        console.log(`  ${lesson.id}: ${classification} (tags: ${tags.join(', ')})`);
+
+        if (classification === 'mistake') {
+            mistakes.push({
+                id: lesson.id.replace('LEARN', 'MISTAKE'),
+                title: lesson.message.split('.')[0], // First sentence as title
+                pattern: lesson.pattern,
+                message: lesson.message,
+                severity: lesson.severity,
+                tags,
+                context: lesson.category,
+                hitCount: lesson.hitCount || 0,
+                lastHit: lesson.lastHit,
+                added: lesson.addedAt,
+                source: lesson.source,
+                excludePaths: lesson.excludePaths || [],
+            });
+        } else if (classification === 'improvement') {
+            improvements.push({
+                id: lesson.id.replace('LEARN', 'IMPROVE'),
+                title: lesson.message.split('.')[0],
+                pattern: lesson.pattern,
+                message: lesson.message,
+                priority: lesson.severity === 'ERROR' ? 'HIGH' : 'MEDIUM',
+                tags,
+                added: lesson.addedAt,
+                appliedCount: lesson.hitCount || 0,
+                lastApplied: lesson.lastHit,
+                source: lesson.source,
+            });
+        } else {
+            // Mixed - split into both
+            const { mistake, improvement } = splitMixedLesson(lesson);
+            mistakes.push({
+                ...mistake,
+                severity: lesson.severity,
+                tags,
+                hitCount: lesson.hitCount || 0,
+                lastHit: lesson.lastHit,
+                added: lesson.addedAt,
+                source: lesson.source,
+                excludePaths: lesson.excludePaths || [],
+            });
+
+            if (improvement) {
+                improvements.push({
+                    ...improvement,
+                    source: lesson.source,
+                });
+            }
+
+            needsReview.push({
+                ...lesson,
+                reason: 'Mixed mistake + improvement keywords, auto-split but needs verification',
+            });
+        }
+    });
+
+    console.log(`\n✅ Classification complete:`);
+    console.log(`   ${mistakes.length} mistakes`);
+    console.log(`   ${improvements.length} improvements`);
+    console.log(`   ${needsReview.length} need manual review`);
+
+    return { mistakes, improvements, needsReview };
+}
+
+// ============================================================================
+// STEP 4: Save New Files
+// ============================================================================
+
+function saveYAML(filename, data) {
+    const filepath = path.join(KNOWLEDGE_DIR, filename);
+    const yamlStr = yaml.dump(data, {
+        lineWidth: -1,
+        noRefs: true,
+        sortKeys: false,
+    });
+    fs.writeFileSync(filepath, yamlStr, 'utf8');
+    console.log(`✅ Created: ${filename}`);
+}
+
+function saveNewStructure(result) {
+    console.log('\n📝 Step 3: Creating new data files...');
+
+    // Save mistakes
+    saveYAML('mistakes.yaml', {
+        version: 4.0,
+        mistakes: result.mistakes,
+    });
+
+    // Save improvements
+    saveYAML('improvements.yaml', {
+        version: 4.0,
+        improvements: result.improvements,
+    });
+
+    // Save review queue if needed
+    if (result.needsReview.length > 0) {
+        saveYAML('_needs_review.yaml', {
+            note: 'These lessons contained both mistake and improvement keywords and were auto-split. Please review.',
+            items: result.needsReview,
+        });
+        console.log(`⚠️  ${result.needsReview.length} items saved to _needs_review.yaml`);
+    }
+}
+
+// ============================================================================
+// MAIN MIGRATION
+// ============================================================================
+
+async function main() {
+    console.log('🧠 Cognitive Lesson Engine v4.x Migration\n');
+    console.log('This script will transform your lessons into the new architecture.');
+    console.log('All existing data will be preserved in backups.\n');
+
+    try {
+        // Step 1: Backup
+        const oldData = backupCurrentLessons();
+
+        if (!oldData || !oldData.lessons || oldData.lessons.length === 0) {
+            console.log('❌ No lessons found to migrate.');
+            return;
+        }
+
+        // Step 2: Classify
+        const result = migrateToV4(oldData);
+
+        // Step 3: Save
+        saveNewStructure(result);
+
+        // Step 4: Summary
+        console.log('\n🎉 Migration complete!');
+        console.log('\nNext steps:');
+        console.log('  1. Review _needs_review.yaml (if exists)');
+        console.log('  2. Test with: node packages/cli/lib/ui/index.js');
+        console.log('  3. Original file preserved in _migration_backup/');
+        console.log('\n✅ You can now use the Cognitive Lesson Engine!');
+
+    } catch (error) {
+        console.error('\n❌ Migration failed:', error.message);
+        console.error(error.stack);
+        process.exit(1);
+    }
+}
+
+main();