@agentskillkit/agent-skills 1.0.1

package/packages/cli/lib/learn.v2.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+/**
+ * Smart Learning Script - ESM Version (Production-Ready)
+ * 
+ * The "Teacher" script. Adds new lessons to the system memory.
+ * 
+ * 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, VERSION } from "./config.js";
+
+// ============================================================================
+// CORE FUNCTIONS
+// ============================================================================
+
+/**
+ * Load knowledge base from YAML file
+ * @returns {{ lessons: Array, version?: number }}
+ */
+function loadKnowledge() {
+    try {
+        if (!fs.existsSync(LESSONS_PATH)) {
+            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: [], version: 1 };
+    } catch (error) {
+        console.error("❌ Failed to load knowledge base:", error.message);
+        if (DEBUG) console.error(error.stack);
+        process.exit(1);
+    }
+}
+
+/**
+ * Save knowledge base to YAML file
+ * @param {{ lessons: Array, version?: number }} data
+ */
+function saveKnowledge(data) {
+    try {
+        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) {
+        console.error("❌ Failed to save knowledge base:", error.message);
+        if (DEBUG) console.error(error.stack);
+        process.exit(1);
+    }
+}
+
+/**
+ * Add a new lesson to the knowledge base
+ * @param {string} pattern - Regex pattern
+ * @param {string} message - Explanation message
+ * @param {string} severity - WARNING or ERROR
+ * @param {string} category - Category tag
+ */
+function addLesson(pattern, message, severity = "WARNING", category = "general") {
+    const db = loadKnowledge();
+
+    // Validate Regex
+    try {
+        new RegExp(pattern);
+    } catch (e) {
+        console.error("❌ Invalid Regex pattern:", e.message);
+        process.exit(1);
+    }
+
+    // Validate 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")}`;
+
+    const lesson = {
+        id,
+        pattern,
+        message,
+        severity: severity.toUpperCase(),
+        category,
+        source: "manual",
+        hitCount: 0,
+        lastHit: null,
+        autoEscalated: false,
+        addedAt: new Date().toISOString()
+    };
+
+    db.lessons.push(lesson);
+    saveKnowledge(db);
+
+    console.log(`\n🎓 Lesson Learned: [${id}]`);
+    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(category = null) {
+    const db = loadKnowledge();
+
+    if (!db.lessons || db.lessons.length === 0) {
+        console.log("\nℹ️  No lessons learned yet.");
+        console.log("   Use: ag-smart learn --add --pattern \"pat\" --message \"msg\"\n");
+        return;
+    }
+
+    let lessons = db.lessons;
+    if (category) {
+        lessons = lessons.filter(l => l.category === category);
+    }
+
+    console.log(`\n🧠 Smart Agent 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("");
+    });
+}
+
+// ============================================================================
+// CLI
+// ============================================================================
+
+function printHelp() {
+    console.log(`
+🎓 Smart Learning Tool v${VERSION}
+
+USAGE:
+  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    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
+`);
+}
+
+function main() {
+    const args = process.argv.slice(2);
+
+    if (args.includes("--help") || args.length === 0) {
+        printHelp();
+        process.exit(0);
+    }
+
+    if (args.includes("--list")) {
+        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);
+    }
+
+    if (args.includes("--add")) {
+        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");
+            process.exit(1);
+        }
+
+        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, category);
+    }
+}
+
+main();

package/packages/cli/lib/recall.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * Smart Recall Script
+ * 
+ * The "Memory" script. Checks code against learned lessons.
+ * Usage: node recall.js <file_path>
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+const KNOWLEDGE_PATH = path.join(process.cwd(), '.agent', 'knowledge', 'lessons-learned.yaml');
+
+function loadKnowledge() {
+    try {
+        if (!fs.existsSync(KNOWLEDGE_PATH)) {
+            return { lessons: [] };
+        }
+        const content = fs.readFileSync(KNOWLEDGE_PATH, 'utf8');
+        return yaml.load(content) || { lessons: [] };
+    } catch (error) {
+        return { lessons: [] };
+    }
+}
+
+function checkFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+        console.error(`File not found: ${filePath}`);
+        process.exit(1);
+    }
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    const db = loadKnowledge();
+
+    if (!db.lessons || db.lessons.length === 0) return;
+
+    let issuesFound = 0;
+
+    console.log(`\n🧠 Checking memory for: ${path.basename(filePath)}...`);
+
+    db.lessons.forEach(lesson => {
+        try {
+            const regex = new RegExp(lesson.pattern, 'g');
+            const matches = content.match(regex);
+
+            if (matches) {
+                issuesFound++;
+                console.log(`\n❌ Violation of Lesson [${lesson.id}]:`);
+                console.log(`   Recall: "${lesson.message}"`);
+                console.log(`   Severity: ${lesson.severity}`);
+                console.log(`   Found ${matches.length} occurence(s) matching /${lesson.pattern}/`);
+            }
+        } catch (e) {
+            // Ignore invalid regex in db
+        }
+    });
+
+    if (issuesFound === 0) {
+        console.log("✅ No learned anti-patterns detected.");
+        process.exit(0);
+    } else {
+        console.log(`\n⚠️  Found ${issuesFound} potential issues from past lessons.`);
+        // We generally don't exit 1 here unless we want to block strict builds
+        process.exit(1);
+    }
+}
+
+const args = process.argv.slice(2);
+if (args.length === 0) {
+    console.log("Usage: node recall.js <file_path>");
+    process.exit(1);
+}
+
+checkFile(args[0]);

package/packages/cli/lib/recall.v2.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+/**
+ * Smart Recall Script - ESM Version (Production-Ready)
+ * 
+ * The "Memory" script. Checks code against learned lessons.
+ * Features:
+ * - Streaming file scanner (multiple files)
+ * - Context-aware pattern matching (shows line numbers)
+ * - Hit tracking for frequency analysis
+ * 
+ * Usage: 
+ *   node recall.js <file_path>
+ *   node recall.js <directory> --recursive
+ */
+
+import fs from "fs";
+import path from "path";
+import yaml from "js-yaml";
+import { KNOWLEDGE_DIR, LESSONS_PATH, DEBUG } from "./config.js";
+
+// ============================================================================
+// KNOWLEDGE BASE
+// ============================================================================
+
+/**
+ * Load knowledge base from YAML file
+ * @returns {{ lessons: Array<{ id: string, pattern: string, message: string, severity: string, hitCount?: number, lastHit?: string }>, version?: number }}
+ */
+export function loadKnowledge() {
+    try {
+        if (!fs.existsSync(LESSONS_PATH)) {
+            return { lessons: [], version: 1 };
+        }
+        const content = fs.readFileSync(LESSONS_PATH, "utf8");
+        return yaml.load(content) || { lessons: [], version: 1 };
+    } catch (error) {
+        if (DEBUG) console.error("Error loading knowledge:", error.message);
+        return { lessons: [], version: 1 };
+    }
+}
+
+/**
+ * Save knowledge base to YAML file
+ * @param {{ lessons: Array, version?: number }} data
+ */
+export function saveKnowledge(data) {
+    try {
+        fs.mkdirSync(KNOWLEDGE_DIR, { recursive: true });
+        const str = yaml.dump(data, { lineWidth: -1 });
+        fs.writeFileSync(LESSONS_PATH, str, "utf8");
+    } catch (error) {
+        console.error("❌ Failed to save knowledge base:", error.message);
+    }
+}
+
+// ============================================================================
+// FILE SCANNING
+// ============================================================================
+
+/**
+ * Scan a single file against learned patterns
+ * @param {string} filePath - Path to file to scan
+ * @param {{ lessons: Array }} db - Knowledge base
+ * @param {boolean} updateHits - Whether to update hit counts
+ * @returns {{ file: string, violations: Array<{ lesson: object, matches: Array<{ line: number, content: string }> }> }}
+ */
+export function scanFile(filePath, db, updateHits = false) {
+    const violations = [];
+
+    if (!fs.existsSync(filePath)) {
+        return { file: filePath, violations: [], error: "File not found" };
+    }
+
+    const content = fs.readFileSync(filePath, "utf8");
+    const lines = content.split("\n");
+
+    if (!db.lessons || db.lessons.length === 0) {
+        return { file: filePath, violations: [] };
+    }
+
+    db.lessons.forEach(lesson => {
+        try {
+            const regex = new RegExp(lesson.pattern, "g");
+            const matches = [];
+
+            lines.forEach((line, idx) => {
+                if (regex.test(line)) {
+                    matches.push({
+                        line: idx + 1,
+                        content: line.trim().substring(0, 80)
+                    });
+                    regex.lastIndex = 0; // Reset for next test
+                }
+            });
+
+            if (matches.length > 0) {
+                violations.push({ lesson, matches });
+
+                // Track hit count
+                if (updateHits) {
+                    lesson.hitCount = (lesson.hitCount || 0) + matches.length;
+                    lesson.lastHit = new Date().toISOString();
+
+                    // Auto-escalation: WARNING → ERROR after 5 violations
+                    if (lesson.severity === "WARNING" && lesson.hitCount >= 5 && !lesson.autoEscalated) {
+                        lesson.severity = "ERROR";
+                        lesson.autoEscalated = true;
+                        console.log(`⚡ Auto-escalated [${lesson.id}] to ERROR (${lesson.hitCount} violations)`);
+                    }
+                }
+            }
+        } catch (e) {
+            if (DEBUG) console.error(`Invalid regex in lesson ${lesson.id}:`, e.message);
+        }
+    });
+
+    return { file: filePath, violations };
+}
+
+/**
+ * Scan multiple files in a directory recursively
+ * @param {string} dirPath - Directory to scan
+ * @param {{ lessons: Array }} db - Knowledge base
+ * @param {string[]} extensions - File extensions to scan
+ * @returns {Array<{ file: string, violations: Array }>}
+ */
+export function scanDirectory(dirPath, db, extensions = [".js", ".ts", ".tsx", ".jsx"]) {
+    const results = [];
+
+    function walk(dir) {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+
+            // Skip node_modules, .git, etc.
+            if (entry.isDirectory()) {
+                if (!["node_modules", ".git", "dist", "build", ".next"].includes(entry.name)) {
+                    walk(fullPath);
+                }
+            } else if (entry.isFile()) {
+                const ext = path.extname(entry.name);
+                if (extensions.includes(ext)) {
+                    const result = scanFile(fullPath, db, true);
+                    if (result.violations.length > 0) {
+                        results.push(result);
+                    }
+                }
+            }
+        }
+    }
+
+    if (fs.statSync(dirPath).isDirectory()) {
+        walk(dirPath);
+    } else {
+        results.push(scanFile(dirPath, db, true));
+    }
+
+    return results;
+}
+
+// ============================================================================
+// REPORTING
+// ============================================================================
+
+/**
+ * Print scan results in a readable format
+ * @param {Array} results - Scan results
+ */
+export function printResults(results) {
+    let totalViolations = 0;
+    let errorCount = 0;
+    let warningCount = 0;
+
+    results.forEach(result => {
+        if (result.violations.length === 0) return;
+
+        console.log(`\n📄 ${path.relative(process.cwd(), result.file)}`);
+
+        result.violations.forEach(({ lesson, matches }) => {
+            totalViolations += matches.length;
+            if (lesson.severity === "ERROR") errorCount += matches.length;
+            else warningCount += matches.length;
+
+            const icon = lesson.severity === "ERROR" ? "❌" : "⚠️";
+            console.log(`  ${icon} [${lesson.id}] ${lesson.message}`);
+
+            matches.forEach(m => {
+                console.log(`     L${m.line}: ${m.content}`);
+            });
+        });
+    });
+
+    console.log(`\n${"─".repeat(50)}`);
+    console.log(`📊 Total: ${totalViolations} violation(s) | ❌ ${errorCount} error(s) | ⚠️  ${warningCount} warning(s)`);
+
+    return { total: totalViolations, errors: errorCount, warnings: warningCount };
+}
+
+// ============================================================================
+// CLI
+// ============================================================================
+
+function main() {
+    const args = process.argv.slice(2);
+
+    if (args.length === 0 || args.includes("--help")) {
+        console.log(`
+🧠 Smart Recall - Memory Check Tool
+
+Usage:
+  recall <file>           Check single file
+  recall <directory>      Check all files in directory
+  recall --staged         Check git staged files only
+
+Options:
+  --help                  Show this help
+`);
+        process.exit(0);
+    }
+
+    const target = args[0];
+    const db = loadKnowledge();
+
+    if (!db.lessons || db.lessons.length === 0) {
+        console.log("ℹ️  No lessons learned yet. Use 'ag-smart learn' to add patterns.");
+        process.exit(0);
+    }
+
+    console.log(`\n🧠 Checking memory against ${db.lessons.length} learned pattern(s)...`);
+
+    const results = scanDirectory(target, db);
+    const stats = printResults(results);
+
+    // Save updated hit counts
+    saveKnowledge(db);
+
+    if (stats.errors > 0) {
+        console.log("\n💡 Fix ERROR violations before committing.");
+        process.exit(1);
+    } else if (stats.total === 0) {
+        console.log("\n✅ No learned anti-patterns detected.");
+        process.exit(0);
+    } else {
+        process.exit(0); // Warnings don't fail
+    }
+}
+
+// Run if executed directly
+if (process.argv[1].includes("recall")) {
+    main();
+}

package/packages/cli/lib/session_manager.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""
+Session Manager - Agent Skills Kit
+=================================
+Analyzes project state, detects tech stack, tracks file statistics, and provides
+a summary of the current session.
+
+Usage:
+    python .agent/scripts/session_manager.py status [path]
+    python .agent/scripts/session_manager.py info [path]
+"""
+
+import os
+import json
+import argparse
+from pathlib import Path
+from typing import Dict, Any, List
+
+def get_project_root(path: str) -> Path:
+    return Path(path).resolve()
+
+def analyze_package_json(root: Path) -> Dict[str, Any]:
+    pkg_file = root / "package.json"
+    if not pkg_file.exists():
+        return {"type": "unknown", "dependencies": {}}
+    
+    try:
+        with open(pkg_file, 'r', encoding='utf-8') as f:
+            data = json.load(f)
+            
+        deps = data.get("dependencies", {})
+        dev_deps = data.get("devDependencies", {})
+        all_deps = {**deps, **dev_deps}
+        
+        stack = []
+        if "next" in all_deps: stack.append("Next.js")
+        elif "react" in all_deps: stack.append("React")
+        elif "vue" in all_deps: stack.append("Vue")
+        elif "svelte" in all_deps: stack.append("Svelte")
+        elif "express" in all_deps: stack.append("Express")
+        elif "nestjs" in all_deps or "@nestjs/core" in all_deps: stack.append("NestJS")
+        
+        if "tailwindcss" in all_deps: stack.append("Tailwind CSS")
+        if "prisma" in all_deps: stack.append("Prisma")
+        if "typescript" in all_deps: stack.append("TypeScript")
+        
+        return {
+            "name": data.get("name", "unnamed"),
+            "version": data.get("version", "0.0.0"),
+            "stack": stack,
+            "scripts": list(data.get("scripts", {}).keys())
+        }
+    except Exception as e:
+        return {"error": str(e)}
+
+def count_files(root: Path) -> Dict[str, int]:
+    stats = {"created": 0, "modified": 0, "total": 0}
+    # Simple count for now, comprehensive tracking would require git diff or extensive history
+    exclude = {".git", "node_modules", ".next", "dist", "build", ".agent", ".gemini", "__pycache__"}
+    
+    for root_dir, dirs, files in os.walk(root):
+        dirs[:] = [d for d in dirs if d not in exclude]
+        stats["total"] += len(files)
+        
+    return stats
+
+def detect_features(root: Path) -> List[str]:
+    # Heuristic: look at folder names in src/
+    features = []
+    src = root / "src"
+    if src.exists():
+        possible_dirs = ["components", "modules", "features", "app", "pages", "services"]
+        for d in possible_dirs:
+            p = src / d
+            if p.exists() and p.is_dir():
+                # List subdirectories as likely features
+                for child in p.iterdir():
+                    if child.is_dir():
+                        features.append(child.name)
+    return features[:10] # Limit to top 10
+
+def print_status(root: Path):
+    info = analyze_package_json(root)
+    stats = count_files(root)
+    features = detect_features(root)
+    
+    print("\n=== Project Status ===")
+    print(f"\n📁 Project: {info.get('name', root.name)}")
+    print(f"📂 Path: {root}")
+    print(f"🏷️  Type: {', '.join(info.get('stack', ['Generic']))}")
+    print(f"📊 Status: Active")
+    
+    print("\n🔧 Tech Stack:")
+    for tech in info.get('stack', []):
+        print(f"   • {tech}")
+        
+    print(f"\n✅ Detected Modules/Features ({len(features)}):")
+    for feat in features:
+        print(f"   • {feat}")
+    if not features:
+        print("   (No distinct feature modules detected)")
+        
+    print(f"\n📄 Files: {stats['total']} total files tracked")
+    print("\n====================\n")
+
+def main():
+    parser = argparse.ArgumentParser(description="Session Manager")
+    parser.add_argument("command", choices=["status", "info"], help="Command to run")
+    parser.add_argument("path", nargs="?", default=".", help="Project path")
+    
+    args = parser.parse_args()
+    root = get_project_root(args.path)
+    
+    if args.command == "status":
+        print_status(root)
+    elif args.command == "info":
+        print(json.dumps(analyze_package_json(root), indent=2))
+
+if __name__ == "__main__":
+    main()