@agentskillkit/agent-skills 1.0.1 → 3.2.2

package/packages/cli/lib/knowledge-retention.js

@@ -0,0 +1,398 @@
+#!/usr/bin/env node
+/**
+ * Knowledge Retention Runner
+ * 
+ * Executes retention policies defined in retention.yaml.
+ * Archives or soft-deletes stale lessons based on policy rules.
+ * 
+ * Usage:
+ *   ag-smart retention --dry-run    # Preview what would be cleaned
+ *   ag-smart retention --apply      # Execute cleanup (with confirmation)
+ *   ag-smart retention --status     # Show retention policy status
+ */
+
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import { KNOWLEDGE_DIR } from './config.js';
+
+const RETENTION_PATH = path.join(KNOWLEDGE_DIR, 'retention.yaml');
+const BACKUP_DIR = path.join(KNOWLEDGE_DIR, 'backups');
+
+/**
+ * Load retention policy
+ * @returns {Object|null}
+ */
+function loadPolicy() {
+    if (!fs.existsSync(RETENTION_PATH)) {
+        return null;
+    }
+    
+    try {
+        return yaml.load(fs.readFileSync(RETENTION_PATH, 'utf8'));
+    } catch (e) {
+        console.error(`❌ Failed to load retention.yaml: ${e.message}`);
+        return null;
+    }
+}
+
+/**
+ * Load all lessons from knowledge files
+ * @returns {{ mistakes: Array, improvements: Array }}
+ */
+function loadAllLessons() {
+    const mistakes = [];
+    const improvements = [];
+    
+    const mistakesPath = path.join(KNOWLEDGE_DIR, 'mistakes.yaml');
+    if (fs.existsSync(mistakesPath)) {
+        const data = yaml.load(fs.readFileSync(mistakesPath, 'utf8'));
+        if (data?.mistakes) mistakes.push(...data.mistakes.map(m => ({ ...m, _source: 'mistakes' })));
+    }
+    
+    const improvementsPath = path.join(KNOWLEDGE_DIR, 'improvements.yaml');
+    if (fs.existsSync(improvementsPath)) {
+        const data = yaml.load(fs.readFileSync(improvementsPath, 'utf8'));
+        if (data?.improvements) improvements.push(...data.improvements.map(i => ({ ...i, _source: 'improvements' })));
+    }
+    
+    return { mistakes, improvements };
+}
+
+/**
+ * Evaluate a single condition against a lesson
+ * @param {Object} lesson
+ * @param {Object} condition - { field, operator, value }
+ * @returns {boolean}
+ */
+function evaluateCondition(lesson, condition) {
+    const { field, operator, value } = condition;
+    
+    // Get nested field value (e.g., 'cognitive.confidence')
+    const fieldValue = field.split('.').reduce((obj, key) => obj?.[key], lesson);
+    
+    switch (operator) {
+        case 'equals':
+            return fieldValue === value;
+        case 'notEquals':
+            return fieldValue !== value;
+        case 'greaterThan':
+            return (fieldValue || 0) > value;
+        case 'lessThan':
+            return (fieldValue || 0) < value;
+        case 'isNull':
+            return fieldValue === null || fieldValue === undefined;
+        case 'contains':
+            return Array.isArray(fieldValue) && fieldValue.includes(value);
+        case 'olderThan': {
+            if (!lesson.addedAt) return false;
+            const addedTime = new Date(lesson.addedAt).getTime();
+            const thresholdTime = Date.now() - (value * 24 * 60 * 60 * 1000);
+            return addedTime < thresholdTime;
+        }
+        case 'newerThan': {
+            if (!lesson.addedAt) return false;
+            const addedTime = new Date(lesson.addedAt).getTime();
+            const thresholdTime = Date.now() - (value * 24 * 60 * 60 * 1000);
+            return addedTime > thresholdTime;
+        }
+        default:
+            return false;
+    }
+}
+
+/**
+ * Evaluate policy conditions (all/any)
+ * @param {Object} lesson
+ * @param {Object} conditionGroup - { all?: [], any?: [] }
+ * @returns {boolean}
+ */
+function matchesConditions(lesson, conditionGroup) {
+    if (conditionGroup.all) {
+        return conditionGroup.all.every(cond => evaluateCondition(lesson, cond));
+    }
+    if (conditionGroup.any) {
+        return conditionGroup.any.some(cond => evaluateCondition(lesson, cond));
+    }
+    return false;
+}
+
+/**
+ * Check if lesson is protected by high-priority policy
+ * @param {Object} lesson
+ * @param {Array} policies
+ * @returns {boolean}
+ */
+function isProtected(lesson, policies) {
+    const protectPolicy = policies.find(p => p.action?.type === 'protect' && p.enabled);
+    if (!protectPolicy) return false;
+    return matchesConditions(lesson, protectPolicy.condition);
+}
+
+/**
+ * Run retention analysis (dry-run)
+ * @returns {{ toArchive: Array, toDelete: Array, toFlag: Array, protected: Array }}
+ */
+export function analyzeRetention() {
+    const policy = loadPolicy();
+    
+    if (!policy || !policy.settings?.enabled) {
+        return { 
+            toArchive: [], 
+            toDelete: [], 
+            toFlag: [], 
+            protected: [],
+            disabled: true 
+        };
+    }
+    
+    const { mistakes, improvements } = loadAllLessons();
+    const allLessons = [...mistakes, ...improvements];
+    const policies = policy.policies?.filter(p => p.enabled) || [];
+    
+    const result = {
+        toArchive: [],
+        toDelete: [],
+        toFlag: [],
+        protected: []
+    };
+    
+    for (const lesson of allLessons) {
+        // Check protection first
+        if (isProtected(lesson, policies)) {
+            result.protected.push({ id: lesson.id, reason: 'high_value_protection' });
+            continue;
+        }
+        
+        // Check other policies (sorted by priority)
+        const sortedPolicies = policies
+            .filter(p => p.action?.type !== 'protect')
+            .sort((a, b) => (a.priority || 0) - (b.priority || 0));
+        
+        for (const pol of sortedPolicies) {
+            if (pol.condition?.custom === 'detectDuplicatePatterns') {
+                // Skip custom functions for now
+                continue;
+            }
+            
+            // Check exceptions
+            const hasException = (pol.exceptions || []).some(exc => 
+                evaluateCondition(lesson, exc)
+            );
+            
+            if (hasException) continue;
+            
+            if (matchesConditions(lesson, pol.condition)) {
+                const entry = { 
+                    id: lesson.id, 
+                    pattern: lesson.pattern,
+                    source: lesson._source,
+                    policy: pol.name,
+                    reason: pol.description
+                };
+                
+                switch (pol.action?.type) {
+                    case 'archive':
+                        result.toArchive.push(entry);
+                        break;
+                    case 'soft_delete':
+                        result.toDelete.push(entry);
+                        break;
+                    case 'flag':
+                        result.toFlag.push(entry);
+                        break;
+                }
+                break; // Stop at first matching policy
+            }
+        }
+    }
+    
+    return result;
+}
+
+/**
+ * Execute retention cleanup
+ * @param {{ toArchive: Array, toDelete: Array }} analysis
+ * @returns {{ archived: number, deleted: number }}
+ */
+export function executeRetention(analysis) {
+    const policy = loadPolicy();
+    
+    // Safety check
+    if (!policy?.settings?.enabled) {
+        console.log('❌ Retention is disabled. Enable in settings.yaml first.');
+        return { archived: 0, deleted: 0 };
+    }
+    
+    const limits = policy.limits || {};
+    let archived = 0;
+    let deleted = 0;
+    
+    // Ensure backup dir exists
+    if (!fs.existsSync(BACKUP_DIR)) {
+        fs.mkdirSync(BACKUP_DIR, { recursive: true });
+    }
+    
+    // Archive lessons
+    const archiveItems = analysis.toArchive.slice(0, limits.maxArchivePerRun || 50);
+    if (archiveItems.length > 0) {
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const archivePath = path.join(BACKUP_DIR, `retention_archive_${timestamp}.yaml`);
+        
+        fs.writeFileSync(archivePath, yaml.dump({
+            archivedAt: new Date().toISOString(),
+            items: archiveItems
+        }), 'utf8');
+        
+        archived = archiveItems.length;
+        console.log(`📦 Archived ${archived} lessons to ${path.basename(archivePath)}`);
+    }
+    
+    // Note: Actual removal from source files requires more careful handling
+    // For now, we just log what would be removed
+    
+    return { archived, deleted };
+}
+
+/**
+ * Display status
+ */
+function displayStatus() {
+    const policy = loadPolicy();
+    
+    console.log(`
+📋 Retention Policy Status
+${'─'.repeat(50)}
+
+Settings:
+   Enabled:              ${policy?.settings?.enabled ? '✅ Yes' : '❌ No'}
+   Dry-run default:      ${policy?.settings?.dryRunDefault ? 'Yes' : 'No'}
+   Backup before cleanup: ${policy?.settings?.backupBeforeCleanup ? 'Yes' : 'No'}
+   Confirmation required: ${policy?.settings?.confirmationRequired ? 'Yes' : 'No'}
+
+Policies:`);
+
+    const policies = policy?.policies || [];
+    for (const pol of policies) {
+        const status = pol.enabled ? '✅' : '⏸️';
+        console.log(`   ${status} ${pol.name} (priority ${pol.priority || 0})`);
+        console.log(`      Action: ${pol.action?.type || 'unknown'}`);
+    }
+
+    console.log(`
+Limits:
+   Max delete/run:       ${policy?.limits?.maxDeletePerRun || 10}
+   Max archive/run:      ${policy?.limits?.maxArchivePerRun || 50}
+   Approval threshold:   ${policy?.limits?.requireApprovalAbove || 5}
+`);
+}
+
+/**
+ * Display dry-run results
+ * @param {Object} analysis
+ */
+function displayDryRun(analysis) {
+    if (analysis.disabled) {
+        console.log(`
+⚠️  Retention is DISABLED
+
+To enable, set in .agent/knowledge/settings.yaml:
+   retention:
+     enabled: true
+`);
+        return;
+    }
+
+    console.log(`
+🔍 Retention Dry-Run Analysis
+${'─'.repeat(50)}
+
+📦 To Archive (${analysis.toArchive.length}):`);
+
+    for (const item of analysis.toArchive) {
+        console.log(`   • ${item.id}: ${item.reason}`);
+    }
+
+    console.log(`
+🗑️  To Delete (${analysis.toDelete.length}):`);
+
+    for (const item of analysis.toDelete) {
+        console.log(`   • ${item.id}: ${item.reason}`);
+    }
+
+    console.log(`
+🚩 To Flag for Review (${analysis.toFlag.length}):`);
+
+    for (const item of analysis.toFlag) {
+        console.log(`   • ${item.id}: ${item.reason}`);
+    }
+
+    console.log(`
+🛡️  Protected (${analysis.protected.length}):`);
+
+    for (const item of analysis.protected) {
+        console.log(`   • ${item.id}: ${item.reason}`);
+    }
+
+    const total = analysis.toArchive.length + analysis.toDelete.length;
+    console.log(`
+${'─'.repeat(50)}
+📊 Total actions: ${total}
+${total > 0 ? '💡 Run with --apply to execute (requires confirmation)\n' : '✨ No cleanup needed!\n'}
+`);
+}
+
+/**
+ * CLI entry point
+ */
+async function main() {
+    const args = process.argv.slice(2);
+    
+    if (args.includes('--status') || args.length === 0) {
+        displayStatus();
+        return;
+    }
+    
+    if (args.includes('--dry-run')) {
+        const analysis = analyzeRetention();
+        displayDryRun(analysis);
+        return;
+    }
+    
+    if (args.includes('--apply')) {
+        const policy = loadPolicy();
+        
+        if (!policy?.settings?.enabled) {
+            console.log('❌ Retention is disabled. Enable in settings.yaml first.');
+            process.exit(1);
+        }
+        
+        console.log('🔄 Running retention analysis...');
+        const analysis = analyzeRetention();
+        displayDryRun(analysis);
+        
+        const total = analysis.toArchive.length + analysis.toDelete.length;
+        if (total === 0) {
+            console.log('✨ No actions needed. Exiting.');
+            return;
+        }
+        
+        // In a real scenario, prompt for confirmation
+        console.log('⚠️  Confirmation required. This is a dry-run preview.');
+        console.log('   To actually execute, implement interactive confirmation.\n');
+        
+        return;
+    }
+    
+    displayStatus();
+}
+
+// Run if called directly
+if (process.argv[1]?.includes('knowledge-retention')) {
+    main();
+}
+
+export default {
+    analyzeRetention,
+    executeRetention
+};

package/packages/cli/lib/knowledge-validator.js

@@ -0,0 +1,312 @@
+#!/usr/bin/env node
+/**
+ * Knowledge Schema Validator
+ * 
+ * Validates knowledge files against JSON schemas before save/load.
+ * Ensures data integrity and prevents corruption.
+ * 
+ * Usage:
+ *   ag-smart validate               # Validate all knowledge files
+ *   ag-smart validate --fix         # Auto-fix minor issues
+ *   ag-smart validate --json        # JSON output for CI
+ */
+
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+import { KNOWLEDGE_DIR } from './config.js';
+
+const SCHEMA_DIR = path.join(KNOWLEDGE_DIR, 'schema');
+
+// Initialize AJV with formats (date-time, etc.)
+const ajv = new Ajv({ allErrors: true, strict: false });
+addFormats(ajv);
+
+// Cache compiled validators
+const validators = {};
+
+/**
+ * Load and compile schema
+ * @param {string} schemaName - Schema filename without extension
+ * @returns {Function} Compiled validator
+ */
+function getValidator(schemaName) {
+    if (validators[schemaName]) {
+        return validators[schemaName];
+    }
+    
+    const schemaPath = path.join(SCHEMA_DIR, `${schemaName}.schema.json`);
+    if (!fs.existsSync(schemaPath)) {
+        return null;
+    }
+    
+    const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+    validators[schemaName] = ajv.compile(schema);
+    return validators[schemaName];
+}
+
+/**
+ * Validate a knowledge file against its schema
+ * @param {string} filename - File to validate (e.g., 'mistakes.yaml')
+ * @returns {{ valid: boolean, errors: Array, file: string }}
+ */
+export function validateFile(filename) {
+    const filePath = path.join(KNOWLEDGE_DIR, filename);
+    
+    if (!fs.existsSync(filePath)) {
+        return { valid: true, errors: [], file: filename, skipped: true };
+    }
+    
+    // Determine schema name from filename
+    const baseName = path.basename(filename, path.extname(filename));
+    const schemaName = baseName.replace(/-/g, ''); // mistakes, improvements, etc.
+    
+    // Map to correct schema names
+    const schemaMap = {
+        'mistakes': 'mistakes',
+        'improvements': 'improvements',
+        'evolutionsignals': 'evolution-signals',
+        'settings': 'settings'
+    };
+    
+    const mappedSchema = schemaMap[schemaName] || schemaName;
+    const validator = getValidator(mappedSchema);
+    
+    if (!validator) {
+        return { valid: true, errors: [], file: filename, noSchema: true };
+    }
+    
+    try {
+        let data;
+        const ext = path.extname(filename).toLowerCase();
+        const content = fs.readFileSync(filePath, 'utf8');
+        
+        if (ext === '.yaml' || ext === '.yml') {
+            data = yaml.load(content);
+        } else if (ext === '.json') {
+            data = JSON.parse(content);
+        } else {
+            return { valid: true, errors: [], file: filename, unsupportedFormat: true };
+        }
+        
+        const valid = validator(data);
+        
+        if (!valid) {
+            return {
+                valid: false,
+                errors: validator.errors.map(err => ({
+                    path: err.instancePath || '/',
+                    message: err.message,
+                    keyword: err.keyword,
+                    params: err.params
+                })),
+                file: filename
+            };
+        }
+        
+        return { valid: true, errors: [], file: filename };
+        
+    } catch (e) {
+        return {
+            valid: false,
+            errors: [{ path: '/', message: `Parse error: ${e.message}`, keyword: 'parse' }],
+            file: filename
+        };
+    }
+}
+
+/**
+ * Validate all knowledge files
+ * @returns {{ results: Array, summary: { total: number, valid: number, invalid: number } }}
+ */
+export function validateAll() {
+    const files = [
+        'mistakes.yaml',
+        'improvements.yaml',
+        'evolution-signals.json',
+        'settings.yaml'
+    ];
+    
+    const results = [];
+    
+    for (const file of files) {
+        const result = validateFile(file);
+        results.push(result);
+    }
+    
+    const valid = results.filter(r => r.valid).length;
+    const invalid = results.filter(r => !r.valid).length;
+    
+    return {
+        results,
+        summary: {
+            total: results.length,
+            valid,
+            invalid
+        }
+    };
+}
+
+/**
+ * Auto-fix common issues
+ * @param {string} filename - File to fix
+ * @returns {{ fixed: boolean, changes: string[] }}
+ */
+export function autoFix(filename) {
+    const filePath = path.join(KNOWLEDGE_DIR, filename);
+    const changes = [];
+    
+    if (!fs.existsSync(filePath)) {
+        return { fixed: false, changes: [] };
+    }
+    
+    try {
+        const ext = path.extname(filename).toLowerCase();
+        const content = fs.readFileSync(filePath, 'utf8');
+        let data;
+        
+        if (ext === '.yaml' || ext === '.yml') {
+            data = yaml.load(content);
+        } else if (ext === '.json') {
+            data = JSON.parse(content);
+        } else {
+            return { fixed: false, changes: [] };
+        }
+        
+        // Auto-fix: Ensure version field
+        if (data && typeof data.version === 'undefined') {
+            data.version = 1;
+            changes.push('Added missing version field');
+        }
+        
+        // Auto-fix: Ensure arrays exist
+        if (filename === 'mistakes.yaml' && !Array.isArray(data.mistakes)) {
+            data.mistakes = [];
+            changes.push('Initialized empty mistakes array');
+        }
+        if (filename === 'improvements.yaml' && !Array.isArray(data.improvements)) {
+            data.improvements = [];
+            changes.push('Initialized empty improvements array');
+        }
+        if (filename === 'evolution-signals.json' && !Array.isArray(data.signals)) {
+            data.signals = [];
+            changes.push('Initialized empty signals array');
+        }
+        
+        // Auto-fix: Default cognitive values
+        const items = data.mistakes || data.improvements || [];
+        for (const item of items) {
+            if (!item.cognitive) {
+                item.cognitive = { maturity: 'learning', confidence: 0.3 };
+                changes.push(`Added default cognitive for ${item.id}`);
+            }
+            if (typeof item.hitCount === 'undefined') {
+                item.hitCount = 0;
+                changes.push(`Added default hitCount for ${item.id}`);
+            }
+        }
+        
+        if (changes.length > 0) {
+            // Save fixed file
+            if (ext === '.yaml' || ext === '.yml') {
+                fs.writeFileSync(filePath, yaml.dump(data, { lineWidth: -1 }), 'utf8');
+            } else {
+                fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf8');
+            }
+        }
+        
+        return { fixed: changes.length > 0, changes };
+        
+    } catch (e) {
+        return { fixed: false, changes: [], error: e.message };
+    }
+}
+
+/**
+ * Display validation results
+ * @param {{ results: Array, summary: Object }} validation
+ */
+function displayResults(validation) {
+    console.log(`
+📋 Knowledge Schema Validation
+${'─'.repeat(50)}
+`);
+
+    for (const result of validation.results) {
+        if (result.skipped) {
+            console.log(`⏭️  ${result.file} - Skipped (not found)`);
+        } else if (result.noSchema) {
+            console.log(`📄 ${result.file} - No schema (skipped)`);
+        } else if (result.valid) {
+            console.log(`✅ ${result.file} - Valid`);
+        } else {
+            console.log(`❌ ${result.file} - Invalid`);
+            for (const err of result.errors) {
+                console.log(`   └─ ${err.path}: ${err.message}`);
+            }
+        }
+    }
+
+    console.log(`
+${'─'.repeat(50)}
+📊 Summary: ${validation.summary.valid}/${validation.summary.total} valid
+`);
+
+    if (validation.summary.invalid > 0) {
+        console.log('💡 Tip: Run with --fix to auto-fix common issues\n');
+    }
+}
+
+/**
+ * CLI entry point
+ */
+async function main() {
+    const args = process.argv.slice(2);
+    const jsonMode = args.includes('--json');
+    const fixMode = args.includes('--fix');
+    
+    if (fixMode) {
+        console.log('🔧 Auto-fixing knowledge files...\n');
+        
+        const files = ['mistakes.yaml', 'improvements.yaml', 'evolution-signals.json', 'settings.yaml'];
+        let totalChanges = 0;
+        
+        for (const file of files) {
+            const result = autoFix(file);
+            if (result.fixed) {
+                console.log(`✅ Fixed ${file}:`);
+                result.changes.forEach(c => console.log(`   └─ ${c}`));
+                totalChanges += result.changes.length;
+            }
+        }
+        
+        if (totalChanges === 0) {
+            console.log('✨ No issues to fix!\n');
+        } else {
+            console.log(`\n🔧 Made ${totalChanges} fixes. Re-validating...\n`);
+        }
+    }
+    
+    const validation = validateAll();
+    
+    if (jsonMode) {
+        console.log(JSON.stringify(validation, null, 2));
+        process.exit(validation.summary.invalid > 0 ? 1 : 0);
+    }
+    
+    displayResults(validation);
+    process.exit(validation.summary.invalid > 0 ? 1 : 0);
+}
+
+// Run if called directly
+if (process.argv[1]?.includes('knowledge-validator')) {
+    main();
+}
+
+export default {
+    validateFile,
+    validateAll,
+    autoFix
+};