@agentskillkit/agent-skills 1.0.1 → 3.2.2

package/packages/cli/.agent/knowledge/scans/scan_demo.json

@@ -0,0 +1,58 @@
+{
+  "scanId": "scan_demo_2026_01_29",
+  "timestamp": 1738148400000,
+  "projectPath": "C:\\Users\\sofma\\Desktop\\agent-skill-kit\\packages\\cli",
+  "totalIssues": 8,
+  "summary": {
+    "errors": 5,
+    "warnings": 3,
+    "filesScanned": 12,
+    "ignoredFiles": 28
+  },
+  "issues": [
+    {
+      "id": "LEARN-002_bin_ag_smart_js_L52",
+      "lessonId": "LEARN-002",
+      "type": "console-log",
+      "severity": "WARNING",
+      "file": "bin/ag-smart.js",
+      "line": 52,
+      "message": "Remove debug console.log statements before production",
+      "pattern": "console.log",
+      "matchedCode": "console.error(`❌ Failed to run ${script}:`, err.message);",
+      "fixable": true,
+      "confidence": 0.95
+    },
+    {
+      "id": "LEARN-001_examples_demo_violations_js_L12",
+      "lessonId": "LEARN-001",
+      "type": "todo-comment",
+      "severity": "WARNING",
+      "file": "examples/demo-violations.js",
+      "line": 12,
+      "message": "Remove TODO comments before committing",
+      "pattern": "TODO",
+      "matchedCode": "// TODO: Fix this intentional violation",
+      "fixable": false,
+      "confidence": 0.90
+    },
+    {
+      "id": "LEARN-004_lib_knowledge_loader_js_L45",
+      "lessonId": "LEARN-004",
+      "type": "promise-then",
+      "severity": "INFO",
+      "file": "lib/knowledge-loader.js",
+      "line": 45,
+      "message": "Consider using async/await instead of .then() for better readability",
+      "pattern": ".then(",
+      "matchedCode": "return fs.readFile(path).then(JSON.parse);",
+      "fixable": true,
+      "confidence": 0.85
+    }
+  ],
+  "metadata": {
+    "lessonsApplied": ["LEARN-001", "LEARN-002", "LEARN-004"],
+    "scanDuration": 1250,
+    "cliVersion": "3.3.0"
+  }
+}

package/packages/cli/README.md

@@ -0,0 +1,21 @@
+# Agent Skill Kit CLI
+
+The intelligent CLI engine for Agent Skill Kit, featuring:
+- **Routing Engine**: Semantic routing validation
+- **Audit System**: Skill usage auditing and metrics
+- **Interactive Mode**: Smart interactive agent interface
+
+## Installation
+
+This package is typically managed by the `add-skill-kit` installer.
+
+```bash
+# Global install (managed by installer)
+npm install -g @agentskillskit/cli
+
+# Usage
+agent
+```
+
+## Documentation
+See the main [Agent Skill Kit](https://github.com/agentskillskit/agent-skills) repository.

package/packages/cli/bin/{ag-smart.js → agent.js}

@@ -19,6 +19,11 @@ import path from "path";
 import { fileURLToPath } from "url";
 import { VERSION } from "../lib/config.js";
 
+// Fix UTF-8 output on Windows PowerShell/Console
+if (process.platform === "win32" && process.stdout.isTTY) {
+    process.stdout.setDefaultEncoding("utf8");
+}
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ARGS = process.argv.slice(2);
 const COMMAND = ARGS[0];
@@ -50,7 +55,7 @@ function run(script, args = [], baseDir = SCRIPTS_DIR) {
 
 function printHelp() {
     console.log(`
-🤖 Agent Skills Kit CLI v${VERSION}
+🤖 Agent Skill Kit CLI v${VERSION}
 
 Usage: ag-smart <command> [options]
 
@@ -93,6 +98,18 @@ ${"─".repeat(50)}
   sync-skills    🆕 Sync hot patterns to SKILL.md
                  ag-smart sync-skills
 
+  index          🆕 Knowledge index management
+                 ag-smart index --rebuild | --status
+
+  metrics        🆕 Knowledge metrics dashboard
+                 ag-smart metrics [--json]
+
+  validate        Schema validation for knowledge files
+                 ag-smart validate [--fix] [--json]
+
+  retention       Retention policy runner
+                 ag-smart retention [--dry-run] [--apply] [--status]
+
 ${"─".repeat(50)}
 
 📖 HELP:
@@ -108,13 +125,13 @@ ${"─".repeat(50)}
 switch (COMMAND) {
     // Core commands (v2 versions)
     case "learn":
-        run("learn.v2.js", ARGS.slice(1));
+        run("learn.js", ARGS.slice(1));
         break;
     case "recall":
-        run("recall.v2.js", ARGS.slice(1));
+        run("recall.js", ARGS.slice(1));
         break;
     case "audit":
-        run("audit.v2.js", ARGS.slice(1));
+        run("audit.js", ARGS.slice(1));
         break;
 
     // Production features
@@ -136,6 +153,18 @@ switch (COMMAND) {
     case "sync-skills":
         run("skill-learn.js", ARGS.slice(1));
         break;
+    case "index":
+        run("knowledge-index.js", ARGS.slice(1));
+        break;
+    case "metrics":
+        run("knowledge-metrics.js", ARGS.slice(1));
+        break;
+    case "validate":
+        run("knowledge-validator.js", ARGS.slice(1));
+        break;
+    case "retention":
+        run("knowledge-retention.js", ARGS.slice(1));
+        break;
 
     // Meta
     case "--version":
@@ -145,9 +174,12 @@ switch (COMMAND) {
     case "help":
     case "--help":
     case "-h":
-    case undefined:
         printHelp();
         break;
+    case undefined:
+        // No command = show interactive Clack menu
+        import("../lib/ui/index.js").then(m => m.showMainMenu()).catch(console.error);
+        break;
     default:
         console.log(`❌ Unknown command: ${COMMAND}`);
         console.log("   Run 'ag-smart help' for available commands.\n");

package/packages/cli/examples/demo-violations.js

@@ -0,0 +1,27 @@
+/**
+ * Demo Violations File - Agent Skill Kit CLI Testing
+ * 
+ * Purpose: This file intentionally contains code violations to test
+ * the CLI's violation detection system (self-evolution signals).
+ * 
+ * Expected Violations:
+ * - IMPROVE-004: Missing import resolution
+ * - MISTAKE-005: Undefined function usage
+ * - MISTAKE-006: Recursive call pattern
+ */
+
+// IMPROVE-004: Import from non-existent file
+import { something } from './nonexistent.js';
+import { another } from '../fake-module.js';
+
+// MISTAKE-006: Recursive call without base case
+function testMenu() {
+    console.log("Testing recursive pattern");
+    testMenu(); // This will be detected
+}
+
+// MISTAKE-005: Undefined function call
+const data = customSelect();
+
+console.log("CLI Violation Detection Test");
+console.log("This file is used by: npm run example:violations");

package/packages/cli/lib/audit.js

@@ -1,69 +1,154 @@
 #!/usr/bin/env node
 /**
- * Smart Audit Script (The Judge)
+ * Smart Audit Script (Production-Ready)
  * 
- * Orchestrates:
- * 1. Governance Constitution Checks (CoinPika Doctrines)
- * 2. Memory Recall Checks (Past Mistakes)
- * 3. Atomic Rule Checks (Vercel Skills)
+ * The "Judge" - Orchestrates all compliance checks:
+ * 1. Memory Recall (Past Mistakes)
+ * 2. Constitution Checks (Governance)
+ * 3. Real-time Analysis
+ * 
+ * Usage: ag-smart audit [directory]
  */
 
-const { execSync } = require('child_process');
-const path = require('path');
-const fs = require('fs');
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { scanDirectory, loadKnowledge, saveKnowledge, printResults } from "./recall.js";
+import { AGENT_DIR, VERSION } from "./config.js";
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-const PROJECT_ROOT = process.argv[2] || process.cwd();
+// ============================================================================
+// AUDIT CONFIGURATION
+// ============================================================================
 
-console.log(`\n⚖️  SMART AUDIT: Judging code in ${PROJECT_ROOT}...\n`);
+const SCAN_EXTENSIONS = [".js", ".ts", ".tsx", ".jsx", ".mjs"];
 
-let exitCode = 0;
+// ============================================================================
+// GOVERNANCE CHECKS
+// ============================================================================
 
-// 1. Run Memory Recall (The Cortex)
-console.log('🧠 [1/3] Checking Memory Bank...');
-try {
-    // We scan all .js/.ts/.tsx files
-    const findCmd = process.platform === 'win32'
-        ? `Get-ChildItem -Path "${PROJECT_ROOT}" -Recurse -Include *.js,*.ts,*.tsx,*.jsx | ForEach-Object { $_.FullName }`
-        : `find "${PROJECT_ROOT}" -name "*.js" -o -name "*.ts" -o -name "*.tsx" -o -name "*.jsx"`;
+/**
+ * Check if governance files exist
+ * @param {string} projectRoot 
+ * @returns {{ passed: boolean, details: string[] }}
+ */
+function checkGovernance(projectRoot) {
+    const details = [];
+    let passed = true;
 
-    // Simple implementation: Just scan src/ or equivalent. 
-    // For now, let's just check the current directory recursively using git ls-files if available, or finding files.
-    // Using a simpler approach: calling recall.js on modified files would be ideal.
-    // For this Proof of Concept, we will skip full scan to avoid slow perf, 
-    // and assume the user passes a specific file to audit, or we scan a specific folder.
+    const governanceFiles = [
+        { path: path.join(projectRoot, ".agent", "GEMINI.md"), name: "GEMINI.md" },
+        { path: path.join(projectRoot, ".agent", "ARCHITECTURE.md"), name: "ARCHITECTURE.md" }
+    ];
 
-    // Let's implement a "Staged Files" check if inside a git repo, otherwise scan all.
-    // For simplicity of this script, we will just demo the call.
+    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)`);
+        }
+    });
 
-    console.log("   (Skipping full memory scan in demo - run 'ag-smart recall <file>' to check specific files)");
-} catch (e) {
-    console.log('   ⚠️  Memory scan skipped.');
+    // Check for skills
+    const skillsDir = path.join(projectRoot, ".agent", "skills");
+    if (fs.existsSync(skillsDir)) {
+        const skills = fs.readdirSync(skillsDir).filter(f =>
+            fs.statSync(path.join(skillsDir, f)).isDirectory()
+        );
+        details.push(`${pc.green("✓")} ${skills.length} skill(s) loaded`);
+    }
+
+    return { passed, details };
 }
 
-// 2. Run Constitution Checks (The Law)
-console.log('\n📜 [2/3] Checking Constitution...');
-try {
-    // Check if governance scripts exist
-    const govScript = path.join(__dirname, '../skills/governance/scripts/validate_doctrine.js');
-    if (fs.existsSync(govScript)) {
-        // execSync(`node "${govScript}" "${PROJECT_ROOT}"`, { stdio: 'inherit' });
-        console.log("   ✅ Constitution checks passed (Mock).");
+// ============================================================================
+// MAIN AUDIT
+// ============================================================================
+
+/**
+ * Run full audit on a project
+ * @param {string} projectRoot 
+ */
+async function runAudit(projectRoot) {
+    p.intro(pc.cyan(`⚖️  SMART AUDIT v${VERSION}`));
+
+    let exitCode = 0;
+    const startTime = Date.now();
+
+    // Phase 1: Memory Recall
+    const s1 = p.spinner();
+    s1.start("Phase 1: Memory Recall");
+
+    const db = loadKnowledge();
+
+    if (db.lessons.length === 0) {
+        s1.stop("Phase 1: No lessons learned yet");
+    } else {
+        const { results } = scanDirectory(projectRoot, db, SCAN_EXTENSIONS);
+
+        if (results.length > 0) {
+            const stats = printResults(results);
+            saveKnowledge(db);
+
+            if (stats.errors > 0) {
+                exitCode = 1;
+            }
+            s1.stop(`Phase 1: Found ${stats.total} violation(s)`);
+        } else {
+            s1.stop("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"), pc.dim("Governance"));
+
+    // Phase 3: Summary
+    const duration = ((Date.now() - startTime) / 1000).toFixed(2);
+    const totalHits = db.lessons.reduce((sum, l) => sum + (l.hitCount || 0), 0);
+
+    const summaryLines = [
+        `⏱️  Completed in ${duration}s`,
+        `📊 Lessons in memory: ${db.lessons.length}`,
+        `🎯 Total pattern hits: ${totalHits}`
+    ];
+    p.note(summaryLines.join("\n"), pc.dim("Summary"));
+
+    if (exitCode === 0) {
+        p.outro(pc.green("✅ AUDIT PASSED: Code is smart and compliant"));
     } else {
-        console.log("   ⚠️  Governance scripts not found.");
+        p.outro(pc.red("❌ AUDIT FAILED: Please fix ERROR violations"));
     }
-} catch (e) {
-    console.error(`   ❌ Constitution Violation: ${e.message}`);
-    exitCode = 1;
+
+    process.exit(exitCode);
 }
 
-// 3. Run Atomic Rules (The Knowledge)
-console.log('\n📚 [3/3] Checking Atomic Rules...');
-console.log("   ✅ React Best Practices: Verified.");
-console.log("   ✅ UI/Design Rules: Verified.");
+// ============================================================================
+// CLI
+// ============================================================================
+
+const args = process.argv.slice(2);
+const projectRoot = args[0] || process.cwd();
 
-if (exitCode === 0) {
-    console.log('\n✅ AUDIT PASSED: Code is smart and compliant.');
-} else {
-    console.log('\n❌ AUDIT FAILED: Please fix the violations above.');
-    process.exit(1);
+if (args.includes("--help")) {
+    console.log(`
+⚖️  Smart Audit - Compliance Checker
+
+Usage:
+  ag-smart audit [directory]
+
+Options:
+  --help    Show this help
+`);
+    process.exit(0);
 }
+
+runAudit(projectRoot);

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

@@ -0,0 +1,100 @@
+/**
+ * @fileoverview Tests for audit.js functionality
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs";
+import path from "path";
+import os from "os";
+
+const TEST_DIR = path.join(os.tmpdir(), "agent-skill-kit-audit-test");
+const AGENT_DIR = path.join(TEST_DIR, ".agent");
+
+describe("Audit - Governance Check", () => {
+    beforeEach(() => {
+        fs.mkdirSync(AGENT_DIR, { recursive: true });
+    });
+
+    afterEach(() => {
+        fs.rmSync(TEST_DIR, { recursive: true, force: true });
+    });
+
+    it("detects GEMINI.md presence", () => {
+        const geminiPath = path.join(AGENT_DIR, "GEMINI.md");
+
+        // Before creation
+        expect(fs.existsSync(geminiPath)).toBe(false);
+
+        // After creation
+        fs.writeFileSync(geminiPath, "# Test", "utf8");
+        expect(fs.existsSync(geminiPath)).toBe(true);
+    });
+
+    it("detects ARCHITECTURE.md presence", () => {
+        const archPath = path.join(AGENT_DIR, "ARCHITECTURE.md");
+        fs.writeFileSync(archPath, "# Architecture", "utf8");
+
+        expect(fs.existsSync(archPath)).toBe(true);
+    });
+
+    it("counts skills in skills directory", () => {
+        const skillsDir = path.join(AGENT_DIR, "skills");
+        fs.mkdirSync(skillsDir, { recursive: true });
+
+        // Create mock skills
+        fs.mkdirSync(path.join(skillsDir, "skill-1"));
+        fs.mkdirSync(path.join(skillsDir, "skill-2"));
+
+        const skills = fs.readdirSync(skillsDir).filter(f =>
+            fs.statSync(path.join(skillsDir, f)).isDirectory()
+        );
+
+        expect(skills.length).toBe(2);
+    });
+});
+
+describe("Audit - Compliance Results", () => {
+    it("calculates pass/fail status correctly", () => {
+        const results = {
+            errors: 0,
+            warnings: 2,
+            total: 2
+        };
+
+        // Errors = 0 means pass
+        expect(results.errors === 0).toBe(true);
+    });
+
+    it("fails when errors exist", () => {
+        const results = {
+            errors: 1,
+            warnings: 0,
+            total: 1
+        };
+
+        expect(results.errors > 0).toBe(true);
+    });
+
+    it("calculates total correctly", () => {
+        const violations = [
+            { lesson: { severity: "ERROR" }, matches: [1, 2] },
+            { lesson: { severity: "WARNING" }, matches: [1] }
+        ];
+
+        let total = 0;
+        let errors = 0;
+        let warnings = 0;
+
+        violations.forEach(v => {
+            total += v.matches.length;
+            if (v.lesson.severity === "ERROR") {
+                errors += v.matches.length;
+            } else {
+                warnings += v.matches.length;
+            }
+        });
+
+        expect(total).toBe(3);
+        expect(errors).toBe(2);
+        expect(warnings).toBe(1);
+    });
+});

package/packages/cli/lib/auto-learn.js

@@ -17,7 +17,7 @@
 import fs from "fs";
 import path from "path";
 import { execSync, spawnSync } from "child_process";
-import { loadKnowledge, saveKnowledge } from "./recall.v2.js";
+import { loadKnowledge, saveKnowledge } from "./recall.js";
 import { VERSION } from "./config.js";
 
 // ============================================================================

package/packages/cli/lib/backup.js

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview Backup and Restore for Agent Skill Kit
+ * Protects lessons before changes
+ */
+
+import fs from "fs";
+import path from "path";
+import { KNOWLEDGE_DIR, LESSONS_PATH } from "./config.js";
+import { SETTINGS_PATH } from "./settings.js";
+
+/** Backup directory */
+const BACKUPS_DIR = path.join(KNOWLEDGE_DIR, "backups");
+
+/**
+ * Create a timestamped backup of lessons and settings
+ * @returns {{ path: string, timestamp: string } | null}
+ */
+export function createBackup() {
+    try {
+        fs.mkdirSync(BACKUPS_DIR, { recursive: true });
+
+        const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+        const backupDir = path.join(BACKUPS_DIR, timestamp);
+        fs.mkdirSync(backupDir, { recursive: true });
+
+        // Backup lessons
+        if (fs.existsSync(LESSONS_PATH)) {
+            fs.copyFileSync(
+                LESSONS_PATH,
+                path.join(backupDir, "lessons-learned.yaml")
+            );
+        }
+
+        // Backup settings
+        if (fs.existsSync(SETTINGS_PATH)) {
+            fs.copyFileSync(
+                SETTINGS_PATH,
+                path.join(backupDir, "settings.yaml")
+            );
+        }
+
+        return { path: backupDir, timestamp };
+    } catch (e) {
+        console.error("Failed to create backup:", e.message);
+        return null;
+    }
+}
+
+/**
+ * List available backups
+ * @returns {Array<{ name: string, date: Date, path: string }>}
+ */
+export function listBackups() {
+    try {
+        if (!fs.existsSync(BACKUPS_DIR)) {
+            return [];
+        }
+
+        const entries = fs.readdirSync(BACKUPS_DIR, { withFileTypes: true });
+        return entries
+            .filter(e => e.isDirectory())
+            .map(e => ({
+                name: e.name,
+                date: parseBackupDate(e.name),
+                path: path.join(BACKUPS_DIR, e.name)
+            }))
+            .sort((a, b) => b.date - a.date); // Newest first
+    } catch (e) {
+        return [];
+    }
+}
+
+/**
+ * Parse backup folder name to date
+ * @param {string} name - Folder name (ISO timestamp with - instead of :)
+ * @returns {Date}
+ */
+function parseBackupDate(name) {
+    try {
+        // Convert 2026-01-25T17-30-00-000Z back to valid ISO
+        const iso = name.replace(/-(\d{2})-(\d{2})-(\d{3})Z/, ":$1:$2.$3Z");
+        return new Date(iso);
+    } catch (e) {
+        return new Date(0);
+    }
+}
+
+/**
+ * Restore from a backup
+ * @param {string} backupPath - Path to backup folder
+ * @returns {boolean}
+ */
+export function restoreBackup(backupPath) {
+    try {
+        const lessonsBackup = path.join(backupPath, "lessons-learned.yaml");
+        const settingsBackup = path.join(backupPath, "settings.yaml");
+
+        if (fs.existsSync(lessonsBackup)) {
+            fs.copyFileSync(lessonsBackup, LESSONS_PATH);
+        }
+
+        if (fs.existsSync(settingsBackup)) {
+            fs.copyFileSync(settingsBackup, SETTINGS_PATH);
+        }
+
+        return true;
+    } catch (e) {
+        console.error("Failed to restore backup:", e.message);
+        return false;
+    }
+}
+
+/**
+ * Delete old backups, keep last N
+ * @param {number} keep - Number of backups to keep
+ */
+export function pruneBackups(keep = 5) {
+    const backups = listBackups();
+
+    if (backups.length <= keep) return;
+
+    const toDelete = backups.slice(keep);
+    for (const backup of toDelete) {
+        try {
+            fs.rmSync(backup.path, { recursive: true, force: true });
+        } catch (e) {
+            // Ignore deletion errors
+        }
+    }
+}
+
+export default {
+    createBackup,
+    listBackups,
+    restoreBackup,
+    pruneBackups,
+    BACKUPS_DIR
+};