add-skill-kit 3.2.3 → 3.2.4

package/lib/agent-cli/lib/skill-learn.js

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+/**
+ * Skill Learn - Auto-update SKILL.md from Hot Patterns
+ * 
+ * When patterns reach threshold hits, automatically add them
+ * to the relevant SKILL.md file as learned rules.
+ * 
+ * This makes the Self-Learning Engine truly "self-learning"!
+ * 
+ * Usage: ag-smart sync-skills
+ */
+
+import fs from "fs";
+import path from "path";
+import { loadKnowledge, saveKnowledge } from "./recall.js";
+import { AGENT_DIR, VERSION } from "./config.js";
+
+// ============================================================================
+// CONFIGURATION
+// ============================================================================
+
+const SYNC_THRESHOLD = 10; // Hits required before syncing to SKILL.md
+const SKILLS_DIR = path.join(AGENT_DIR, "skills");
+
+// Category to skill folder mapping
+const CATEGORY_MAP = {
+    "general": "clean-code",
+    "security": "vulnerability-scanner",
+    "code-quality": "clean-code",
+    "performance": "performance-profiling",
+    "testing": "testing-patterns",
+    "react": "react-patterns",
+    "api": "api-patterns",
+    "database": "database-design"
+};
+
+// ============================================================================
+// SKILL UPDATER
+// ============================================================================
+
+/**
+ * Find the SKILL.md file for a category
+ * @param {string} category 
+ * @returns {string|null}
+ */
+function findSkillFile(category) {
+    const skillFolder = CATEGORY_MAP[category] || CATEGORY_MAP["general"];
+    const skillPath = path.join(SKILLS_DIR, skillFolder, "SKILL.md");
+
+    if (fs.existsSync(skillPath)) {
+        return skillPath;
+    }
+
+    // Fallback to clean-code
+    const fallback = path.join(SKILLS_DIR, "clean-code", "SKILL.md");
+    return fs.existsSync(fallback) ? fallback : null;
+}
+
+/**
+ * Parse SKILL.md structure to find best insertion point
+ * @param {string} skillPath 
+ * @returns {{ sections: Array<{name: string, start: number, end: number}>, content: string }}
+ */
+function parseSkillStructure(skillPath) {
+    const content = fs.readFileSync(skillPath, "utf8");
+    const lines = content.split("\n");
+    const sections = [];
+
+    let currentSection = null;
+
+    lines.forEach((line, idx) => {
+        // Detect section headers (## or ###)
+        const headerMatch = line.match(/^(#{2,3})\s+(.+)/);
+        if (headerMatch) {
+            if (currentSection) {
+                currentSection.end = idx - 1;
+                sections.push(currentSection);
+            }
+            currentSection = {
+                name: headerMatch[2].trim(),
+                level: headerMatch[1].length,
+                start: idx,
+                end: lines.length - 1
+            };
+        }
+    });
+
+    if (currentSection) {
+        sections.push(currentSection);
+    }
+
+    return { sections, content, lines };
+}
+
+/**
+ * Find best section to insert pattern based on category
+ * @param {Array} sections 
+ * @param {string} category 
+ * @returns {number} - Line number to insert at
+ */
+function findInsertionPoint(sections, category) {
+    // Look for "Auto-learned" section first
+    const autoSection = sections.find(s =>
+        s.name.toLowerCase().includes("auto-learned") ||
+        s.name.toLowerCase().includes("learned patterns")
+    );
+    if (autoSection) {
+        return autoSection.end + 1;
+    }
+
+    // Look for relevant category section
+    const categoryMap = {
+        "security": ["security", "vulnerab"],
+        "performance": ["performance", "optim"],
+        "code-quality": ["quality", "best practice", "rule"],
+        "testing": ["test", "spec"]
+    };
+
+    const keywords = categoryMap[category] || ["rule", "pattern"];
+    const matchSection = sections.find(s =>
+        keywords.some(kw => s.name.toLowerCase().includes(kw))
+    );
+    if (matchSection) {
+        return matchSection.end + 1;
+    }
+
+    // Default: append at end
+    return -1; // -1 means append
+}
+
+/**
+ * Generate rule entry for SKILL.md
+ * @param {object} lesson 
+ * @returns {string}
+ */
+function generateRuleEntry(lesson) {
+    const date = new Date().toISOString().split("T")[0];
+    return `
+### 🤖 Auto-learned: ${lesson.id}
+
+> **Pattern:** \`${lesson.pattern}\`
+> 
+> ${lesson.message}
+
+- **Severity:** ${lesson.severity}
+- **Detected:** ${lesson.hitCount} times
+- **Added:** ${date}
+
+---
+`;
+}
+
+/**
+ * Check if pattern already exists in SKILL.md
+ */
+function patternExistsInSkill(skillPath, pattern) {
+    const content = fs.readFileSync(skillPath, "utf8");
+    // Check multiple formats
+    return content.includes(`\`${pattern}\``) ||
+        content.includes(`Pattern:** \`${pattern}\``) ||
+        content.includes(`"${pattern}"`) ||
+        content.includes(`'${pattern}'`);
+}
+
+/**
+ * Insert rule at specific line or append
+ * @param {string} skillPath 
+ * @param {object} lesson 
+ * @param {string} category 
+ */
+function insertRule(skillPath, lesson, category) {
+    const { sections, content, lines } = parseSkillStructure(skillPath);
+    const insertPoint = findInsertionPoint(sections, category);
+    const entry = generateRuleEntry(lesson);
+
+    if (insertPoint === -1 || insertPoint >= lines.length) {
+        // Append at end
+        fs.appendFileSync(skillPath, entry, "utf8");
+    } else {
+        // Insert at specific line
+        lines.splice(insertPoint, 0, entry);
+        fs.writeFileSync(skillPath, lines.join("\n"), "utf8");
+    }
+}
+
+/**
+ * Sync hot patterns to SKILL.md files
+ */
+function syncSkills() {
+    console.log(`\n🔄 Skill Sync v${VERSION}`);
+    console.log(`📊 Threshold: ${SYNC_THRESHOLD} hits\n`);
+    console.log("─".repeat(50));
+
+    const db = loadKnowledge();
+
+    if (!db.lessons || db.lessons.length === 0) {
+        console.log("\nℹ️  No lessons learned yet.");
+        return { synced: 0, skipped: 0 };
+    }
+
+    // Find hot patterns
+    const hotPatterns = db.lessons.filter(l => (l.hitCount || 0) >= SYNC_THRESHOLD && !l.syncedToSkill);
+
+    if (hotPatterns.length === 0) {
+        console.log("\nℹ️  No patterns have reached the sync threshold yet.");
+        console.log(`   Patterns need ${SYNC_THRESHOLD}+ hits to be synced to SKILL.md\n`);
+
+        // Show progress
+        const inProgress = db.lessons.filter(l => l.hitCount > 0 && l.hitCount < SYNC_THRESHOLD);
+        if (inProgress.length > 0) {
+            console.log("📈 Patterns in progress:\n");
+            inProgress.forEach(l => {
+                const progress = Math.round((l.hitCount / SYNC_THRESHOLD) * 100);
+                const bar = "█".repeat(Math.floor(progress / 10)) + "░".repeat(10 - Math.floor(progress / 10));
+                console.log(`   [${l.id}] ${l.hitCount}/${SYNC_THRESHOLD} hits (${progress}%)`);
+                console.log(`   ${bar}`);
+            });
+        }
+        return { synced: 0, skipped: 0 };
+    }
+
+    console.log(`\n🔥 Found ${hotPatterns.length} hot pattern(s) ready to sync:\n`);
+
+    let synced = 0;
+    let skipped = 0;
+
+    hotPatterns.forEach(lesson => {
+        const category = lesson.category || "general";
+        const skillPath = findSkillFile(category);
+
+        if (!skillPath) {
+            console.log(`⚠️  [${lesson.id}] No SKILL.md found for category: ${category}`);
+            skipped++;
+            return;
+        }
+
+        // Check if already synced
+        if (patternExistsInSkill(skillPath, lesson.pattern)) {
+            console.log(`⏭️  [${lesson.id}] Already in ${path.basename(path.dirname(skillPath))}/SKILL.md`);
+            lesson.syncedToSkill = true;
+            skipped++;
+            return;
+        }
+
+        // Append to SKILL.md
+        const entry = generateRuleEntry(lesson);
+        fs.appendFileSync(skillPath, entry, "utf8");
+
+        // Mark as synced
+        lesson.syncedToSkill = true;
+        lesson.syncedAt = new Date().toISOString();
+
+        console.log(`✅ [${lesson.id}] → ${path.basename(path.dirname(skillPath))}/SKILL.md`);
+        console.log(`   Pattern: /${lesson.pattern}/`);
+        console.log(`   Hits: ${lesson.hitCount}`);
+        synced++;
+    });
+
+    // Save updated knowledge base
+    saveKnowledge(db);
+
+    console.log(`\n${"─".repeat(50)}`);
+    console.log(`📊 Summary: ${synced} synced, ${skipped} skipped`);
+
+    if (synced > 0) {
+        console.log(`\n🎉 SKILL.md files updated! The agent will now remember these patterns.`);
+    }
+
+    return { synced, skipped };
+}
+
+// ============================================================================
+// CLI
+// ============================================================================
+
+const args = process.argv.slice(2);
+
+if (args.includes("--help")) {
+    console.log(`
+🔄 Skill Sync - Auto-update SKILL.md
+
+Usage:
+  ag-smart sync-skills
+
+When patterns reach ${SYNC_THRESHOLD}+ violations, they are automatically
+added to the relevant SKILL.md file as learned rules.
+
+This makes the Self-Learning Engine truly "self-learning"!
+
+Options:
+  --help    Show this help
+`);
+    process.exit(0);
+}
+
+syncSkills();

package/lib/agent-cli/lib/stats.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * Smart Stats - Knowledge Base Statistics
+ * 
+ * Display statistics about the knowledge base:
+ * - Total lessons learned
+ * - Most triggered patterns
+ * - Violation trends
+ * 
+ * Usage: ag-smart stats
+ */
+
+import { loadKnowledge } from "./recall.js";
+import { VERSION } from "./config.js";
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+
+// ============================================================================
+// STATS DISPLAY
+// ============================================================================
+
+function displayStats() {
+    const db = loadKnowledge();
+
+    p.intro(pc.cyan(`📊 Smart Agent Knowledge Base v${VERSION}`));
+
+    if (!db.lessons || db.lessons.length === 0) {
+        p.note("No lessons learned yet.\nUse 'ag-smart learn' to add patterns.", pc.dim("Empty"));
+        return;
+    }
+
+    // Summary
+    const totalHits = db.lessons.reduce((sum, l) => sum + (l.hitCount || 0), 0);
+    const errorCount = db.lessons.filter(l => l.severity === "ERROR").length;
+    const warningCount = db.lessons.filter(l => l.severity === "WARNING").length;
+
+    const summaryLines = [
+        `📚 Total Lessons: ${pc.bold(db.lessons.length)}`,
+        `🎯 Total Violations: ${pc.bold(totalHits)}`,
+        `${pc.red("❌")} ERROR patterns: ${errorCount}`,
+        `${pc.yellow("⚠️")} WARNING patterns: ${warningCount}`
+    ];
+    p.note(summaryLines.join("\n"), pc.dim("Summary"));
+
+    // Most triggered
+    const sorted = [...db.lessons]
+        .filter(l => l.hitCount > 0)
+        .sort((a, b) => (b.hitCount || 0) - (a.hitCount || 0))
+        .slice(0, 5);
+
+    if (sorted.length > 0) {
+        const triggeredLines = sorted.map((lesson, idx) => {
+            const bar = "█".repeat(Math.min(15, Math.ceil((lesson.hitCount / (sorted[0].hitCount || 1)) * 15)));
+            return `${idx + 1}. [${lesson.id}] ${lesson.hitCount} hits\n   ${pc.green(bar)}\n   ${pc.dim(lesson.message)}`;
+        });
+        p.note(triggeredLines.join("\n\n"), pc.dim("🔥 Most Triggered"));
+    }
+
+    // Auto-escalated
+    const escalated = db.lessons.filter(l => l.autoEscalated);
+    if (escalated.length > 0) {
+        const escalatedLines = escalated.map(l =>
+            `[${l.id}] → Escalated after ${l.hitCount} violations`
+        );
+        p.note(escalatedLines.join("\n"), pc.dim("⚡ Auto-Escalated"));
+    }
+
+    // Recent activity
+    const withHits = db.lessons.filter(l => l.lastHit);
+    if (withHits.length > 0) {
+        const recent = [...withHits]
+            .sort((a, b) => new Date(b.lastHit) - new Date(a.lastHit))
+            .slice(0, 3);
+
+        const recentLines = recent.map(l => {
+            const timeAgo = getTimeAgo(new Date(l.lastHit));
+            return `[${l.id}] Last hit: ${timeAgo}`;
+        });
+        p.note(recentLines.join("\n"), pc.dim("🕐 Recent Activity"));
+    }
+
+    // Sources breakdown
+    const sources = {};
+    db.lessons.forEach(l => {
+        const src = l.source || "manual";
+        sources[src] = (sources[src] || 0) + 1;
+    });
+
+    const sourceLines = Object.entries(sources).map(([src, count]) => {
+        const icon = src === "manual" ? "✍️" : src === "eslint" ? "🔧" : "🧪";
+        return `${icon} ${src}: ${count}`;
+    });
+    p.note(sourceLines.join("\n"), pc.dim("📥 Lesson Sources"));
+
+    p.outro(pc.green("Stats complete"));
+}
+
+/**
+ * Get human-readable time ago string
+ */
+function getTimeAgo(date) {
+    const seconds = Math.floor((Date.now() - date) / 1000);
+
+    if (seconds < 60) return "just now";
+    if (seconds < 3600) return `${Math.floor(seconds / 60)} minutes ago`;
+    if (seconds < 86400) return `${Math.floor(seconds / 3600)} hours ago`;
+    return `${Math.floor(seconds / 86400)} days ago`;
+}
+
+// ============================================================================
+// CLI
+// ============================================================================
+
+const args = process.argv.slice(2);
+
+if (args.includes("--help")) {
+    console.log(`
+📊 Smart Stats - Knowledge Base Statistics
+
+Usage:
+  ag-smart stats
+
+Shows:
+  - Total lessons and violations
+  - Most triggered patterns
+  - Auto-escalated patterns
+  - Recent activity
+`);
+    process.exit(0);
+}
+
+displayStats();

package/lib/agent-cli/lib/stats.test.js

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Tests for stats.js functionality
+ */
+import { describe, it, expect } from "vitest";
+
+describe("Stats - Statistics Calculation", () => {
+    it("calculates total hits from lessons", () => {
+        const lessons = [
+            { id: "LEARN-001", hitCount: 5 },
+            { id: "LEARN-002", hitCount: 3 },
+            { id: "LEARN-003", hitCount: 0 }
+        ];
+
+        const totalHits = lessons.reduce((sum, l) => sum + (l.hitCount || 0), 0);
+        expect(totalHits).toBe(8);
+    });
+
+    it("counts severity types correctly", () => {
+        const lessons = [
+            { id: "LEARN-001", severity: "ERROR" },
+            { id: "LEARN-002", severity: "WARNING" },
+            { id: "LEARN-003", severity: "ERROR" },
+            { id: "LEARN-004", severity: "WARNING" }
+        ];
+
+        const errorCount = lessons.filter(l => l.severity === "ERROR").length;
+        const warningCount = lessons.filter(l => l.severity === "WARNING").length;
+
+        expect(errorCount).toBe(2);
+        expect(warningCount).toBe(2);
+    });
+
+    it("sorts by hit count descending", () => {
+        const lessons = [
+            { id: "LEARN-001", hitCount: 3 },
+            { id: "LEARN-002", hitCount: 10 },
+            { id: "LEARN-003", hitCount: 5 }
+        ];
+
+        const sorted = [...lessons].sort((a, b) => (b.hitCount || 0) - (a.hitCount || 0));
+
+        expect(sorted[0].id).toBe("LEARN-002");
+        expect(sorted[1].id).toBe("LEARN-003");
+        expect(sorted[2].id).toBe("LEARN-001");
+    });
+
+    it("filters auto-escalated patterns", () => {
+        const lessons = [
+            { id: "LEARN-001", autoEscalated: true },
+            { id: "LEARN-002", autoEscalated: false },
+            { id: "LEARN-003", autoEscalated: true }
+        ];
+
+        const escalated = lessons.filter(l => l.autoEscalated);
+        expect(escalated.length).toBe(2);
+    });
+
+    it("groups by source correctly", () => {
+        const lessons = [
+            { id: "LEARN-001", source: "manual" },
+            { id: "LEARN-002", source: "eslint" },
+            { id: "LEARN-003", source: "manual" },
+            { id: "LEARN-004", source: "test-failure" }
+        ];
+
+        const sources = {};
+        lessons.forEach(l => {
+            const src = l.source || "manual";
+            sources[src] = (sources[src] || 0) + 1;
+        });
+
+        expect(sources["manual"]).toBe(2);
+        expect(sources["eslint"]).toBe(1);
+        expect(sources["test-failure"]).toBe(1);
+    });
+});
+
+describe("Stats - Time Formatting", () => {
+    it("formats time ago correctly", () => {
+        const getTimeAgo = (date) => {
+            const seconds = Math.floor((Date.now() - date) / 1000);
+            if (seconds < 60) return "just now";
+            if (seconds < 3600) return `${Math.floor(seconds / 60)} minutes ago`;
+            if (seconds < 86400) return `${Math.floor(seconds / 3600)} hours ago`;
+            return `${Math.floor(seconds / 86400)} days ago`;
+        };
+
+        const now = Date.now();
+        expect(getTimeAgo(now - 30000)).toBe("just now");
+        expect(getTimeAgo(now - 120000)).toBe("2 minutes ago");
+        expect(getTimeAgo(now - 7200000)).toBe("2 hours ago");
+        expect(getTimeAgo(now - 172800000)).toBe("2 days ago");
+    });
+});

package/lib/agent-cli/lib/types.js

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Type Definitions for agent-skill-kit CLI
+ */
+
+/**
+ * @typedef {Object} Lesson
+ * @property {string} id - Lesson ID (e.g., LEARN-001)
+ * @property {string} pattern - Regex pattern to match
+ * @property {string} message - Explanation message
+ * @property {'WARNING'|'ERROR'} severity - Severity level
+ * @property {string} addedAt - ISO timestamp
+ */
+
+/**
+ * @typedef {Object} KnowledgeBase
+ * @property {Lesson[]} lessons - Array of learned lessons
+ */
+
+/**
+ * @typedef {Object} AuditResult
+ * @property {string} file - File path
+ * @property {string[]} violations - List of violations found
+ * @property {boolean} passed - Whether file passed audit
+ */
+
+/**
+ * @typedef {Object} CLIConfig
+ * @property {string} agentDir - Path to .agent directory
+ * @property {string} knowledgePath - Path to lessons file
+ * @property {string} rulesPath - Path to rules directory
+ */
+
+export { };

package/lib/agent-cli/lib/ui/audit-ui.js

@@ -0,0 +1,146 @@
+/**
+ * Audit UI - Compliance check with Clack UI
+ * 
+ * Wrapper for the audit functionality that integrates
+ * with the main menu instead of spawning a separate process.
+ */
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import fs from "fs";
+import path from "path";
+import { scanDirectory, loadKnowledge, saveKnowledge } from "../recall.js";
+import { VERSION, cwd } from "../config.js";
+
+// ============================================================================
+// CONFIGURATION
+// ============================================================================
+
+const SCAN_EXTENSIONS = [".js", ".ts", ".tsx", ".jsx", ".mjs"];
+
+// ============================================================================
+// GOVERNANCE CHECKS
+// ============================================================================
+
+/**
+ * Check if governance files exist
+ * @param {string} projectRoot 
+ * @returns {{ passed: boolean, details: string[] }}
+ */
+function checkGovernance(projectRoot) {
+    const details = [];
+    let passed = true;
+
+    const governanceFiles = [
+        { path: path.join(projectRoot, ".agent", "GEMINI.md"), name: "GEMINI.md" },
+        { path: path.join(projectRoot, ".agent", "ARCHITECTURE.md"), name: "ARCHITECTURE.md" }
+    ];
+
+    governanceFiles.forEach(file => {
+        if (fs.existsSync(file.path)) {
+            details.push(`${pc.green("✓")} ${file.name} found`);
+        } else {
+            details.push(`${pc.yellow("⚠")} ${file.name} not found (optional)`);
+        }
+    });
+
+    // Check for skills
+    const skillsDir = path.join(projectRoot, ".agent", "skills");
+    if (fs.existsSync(skillsDir)) {
+        try {
+            const skills = fs.readdirSync(skillsDir).filter(f =>
+                fs.statSync(path.join(skillsDir, f)).isDirectory()
+            );
+            details.push(`${pc.green("✓")} ${skills.length} skill(s) loaded`);
+        } catch (e) {
+            details.push(`${pc.dim("○")} Skills directory not accessible`);
+        }
+    }
+
+    return { passed, details };
+}
+
+// ============================================================================
+// AUDIT UI
+// ============================================================================
+
+/**
+ * Run audit with Clack UI
+ */
+export async function runAuditUI() {
+    const projectRoot = cwd;
+
+    p.intro(pc.cyan(`Smart Audit v${VERSION}`));
+
+    const startTime = Date.now();
+    let hasErrors = false;
+
+    // Phase 1: Memory Recall
+    const s1 = p.spinner();
+    s1.start("Phase 1: Memory Recall");
+
+    const db = loadKnowledge();
+
+    if (db.lessons.length === 0) {
+        s1.stop(pc.dim("Phase 1: No lessons learned yet"));
+    } else {
+        const { results } = scanDirectory(projectRoot, db);
+
+        // Count violations
+        let totalViolations = 0;
+        let errorCount = 0;
+        let warningCount = 0;
+
+        results.forEach(result => {
+            result.violations.forEach(({ lesson, matches }) => {
+                totalViolations += matches.length;
+                if (lesson.severity === "ERROR") {
+                    errorCount += matches.length;
+                    hasErrors = true;
+                } else {
+                    warningCount += matches.length;
+                }
+            });
+        });
+
+        if (totalViolations > 0) {
+            s1.stop(`Phase 1: Found ${totalViolations} violation(s)`);
+
+            // Show violations summary
+            if (errorCount > 0 || warningCount > 0) {
+                p.log.warn(`${pc.red("✖")} ${errorCount} error(s)  ${pc.yellow("⚠")} ${warningCount} warning(s)`);
+            }
+
+            saveKnowledge(db);
+        } else {
+            s1.stop(pc.green("Phase 1: No violations found ✓"));
+        }
+    }
+
+    // Phase 2: Governance
+    const s2 = p.spinner();
+    s2.start("Phase 2: Governance Check");
+
+    const govResult = checkGovernance(projectRoot);
+    s2.stop("Phase 2: Governance checked");
+
+    p.note(govResult.details.join("\n"), "Governance");
+
+    // Phase 3: Summary
+    const duration = ((Date.now() - startTime) / 1000).toFixed(2);
+    const totalHits = db.lessons.reduce((sum, l) => sum + (l.hitCount || 0), 0);
+
+    p.note(
+        `${pc.dim("Duration:")}  ${duration}s\n` +
+        `${pc.dim("Lessons:")}   ${db.lessons.length} in memory\n` +
+        `${pc.dim("Hits:")}      ${totalHits} total`,
+        "Summary"
+    );
+
+    if (hasErrors) {
+        p.outro(pc.red("AUDIT FAILED: Please fix ERROR violations"));
+    } else {
+        p.outro(pc.green("AUDIT PASSED: Code is compliant"));
+    }
+}
+
+export default runAuditUI;