pikakit 1.0.0

package/lib/agent-cli/utils/recovery.js

@@ -0,0 +1,312 @@
+/**
+ * Self-healing Recovery Utility
+ * 
+ * Provides checkpoint and rollback capabilities:
+ * - Save state before risky operations
+ * - Rollback on failure
+ * - Recovery logging
+ * 
+ * Usage:
+ *   import recovery from './recovery.js';
+ *   
+ *   const checkpoint = recovery.save('operation-name', currentState);
+ *   try {
+ *       // risky operation
+ *   } catch (error) {
+ *       recovery.rollback(checkpoint);
+ *   }
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ==================== STORAGE ====================
+
+const checkpoints = new Map();
+const history = [];
+const MAX_CHECKPOINTS = 10;
+
+// ==================== COLORS ====================
+
+const c = {
+    reset: '\x1b[0m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    cyan: '\x1b[36m',
+    gray: '\x1b[90m'
+};
+
+// ==================== CHECKPOINT ====================
+
+/**
+ * Generate checkpoint ID
+ */
+function generateId() {
+    return `CP-${Date.now()}-${Math.random().toString(36).substr(2, 6)}`;
+}
+
+/**
+ * Save a state checkpoint
+ * @param {string} operation - Operation name
+ * @param {any} state - State to save (will be deep cloned)
+ * @param {object} options - Options
+ * @returns {object} Checkpoint reference
+ */
+function save(operation, state, options = {}) {
+    const id = generateId();
+    const checkpoint = {
+        id,
+        operation,
+        state: JSON.parse(JSON.stringify(state)), // Deep clone
+        timestamp: new Date().toISOString(),
+        options
+    };
+
+    checkpoints.set(id, checkpoint);
+    history.push({ type: 'save', id, operation, timestamp: checkpoint.timestamp });
+
+    // Cleanup old checkpoints
+    if (checkpoints.size > MAX_CHECKPOINTS) {
+        const oldest = [...checkpoints.keys()][0];
+        checkpoints.delete(oldest);
+    }
+
+    console.log(`${c.gray}💾 Checkpoint saved: ${operation} (${id})${c.reset}`);
+
+    return checkpoint;
+}
+
+/**
+ * Rollback to a checkpoint
+ * @param {object|string} checkpoint - Checkpoint reference or ID
+ * @returns {any} Restored state
+ */
+function rollback(checkpoint) {
+    const id = typeof checkpoint === 'string' ? checkpoint : checkpoint.id;
+    const saved = checkpoints.get(id);
+
+    if (!saved) {
+        console.error(`${c.red}❌ Checkpoint not found: ${id}${c.reset}`);
+        return null;
+    }
+
+    history.push({
+        type: 'rollback',
+        id,
+        operation: saved.operation,
+        timestamp: new Date().toISOString()
+    });
+
+    console.log(`${c.yellow}⏪ Rolling back: ${saved.operation}${c.reset}`);
+
+    return saved.state;
+}
+
+/**
+ * Get a checkpoint by ID
+ * @param {string} id - Checkpoint ID
+ */
+function get(id) {
+    return checkpoints.get(id);
+}
+
+/**
+ * List all checkpoints
+ */
+function list() {
+    return [...checkpoints.values()].map(cp => ({
+        id: cp.id,
+        operation: cp.operation,
+        timestamp: cp.timestamp
+    }));
+}
+
+// ==================== FILE RECOVERY ====================
+
+/**
+ * Backup a file before modification
+ * @param {string} filePath - File to backup
+ * @returns {object} Backup reference
+ */
+function backupFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return { id: null, exists: false, path: filePath };
+    }
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    const backup = save(`file:${path.basename(filePath)}`, {
+        path: filePath,
+        content,
+        exists: true
+    });
+
+    return backup;
+}
+
+/**
+ * Restore a file from backup
+ * @param {object|string} backup - Backup reference
+ */
+function restoreFile(backup) {
+    const state = rollback(backup);
+
+    if (!state) {
+        return false;
+    }
+
+    if (state.exists) {
+        fs.writeFileSync(state.path, state.content, 'utf8');
+        console.log(`${c.green}✓ Restored: ${state.path}${c.reset}`);
+    } else {
+        // File didn't exist, delete if created
+        if (fs.existsSync(state.path)) {
+            fs.unlinkSync(state.path);
+            console.log(`${c.green}✓ Removed: ${state.path}${c.reset}`);
+        }
+    }
+
+    return true;
+}
+
+// ==================== TRANSACTION ====================
+
+/**
+ * Execute operation with automatic rollback on failure
+ * @param {string} name - Operation name
+ * @param {any} state - State to checkpoint
+ * @param {Function} operation - Operation to execute
+ * @returns {Promise<{success: boolean, result?: any, error?: Error}>}
+ */
+async function withRecovery(name, state, operation) {
+    const checkpoint = save(name, state);
+
+    try {
+        const result = await operation();
+
+        history.push({
+            type: 'success',
+            id: checkpoint.id,
+            operation: name,
+            timestamp: new Date().toISOString()
+        });
+
+        console.log(`${c.green}✓ ${name} completed successfully${c.reset}`);
+
+        return { success: true, result };
+    } catch (error) {
+        const restored = rollback(checkpoint);
+
+        history.push({
+            type: 'failure',
+            id: checkpoint.id,
+            operation: name,
+            error: error.message,
+            timestamp: new Date().toISOString()
+        });
+
+        console.error(`${c.red}❌ ${name} failed, rolled back${c.reset}`);
+        console.error(`${c.gray}   Error: ${error.message}${c.reset}`);
+
+        return { success: false, error, restored };
+    }
+}
+
+// ==================== HISTORY ====================
+
+/**
+ * Get recovery history
+ */
+function getHistory() {
+    return [...history];
+}
+
+/**
+ * Get statistics
+ */
+function getStats() {
+    const stats = {
+        totalCheckpoints: checkpoints.size,
+        totalOperations: history.length,
+        saves: history.filter(h => h.type === 'save').length,
+        rollbacks: history.filter(h => h.type === 'rollback').length,
+        successes: history.filter(h => h.type === 'success').length,
+        failures: history.filter(h => h.type === 'failure').length
+    };
+
+    stats.successRate = stats.successes + stats.failures > 0
+        ? (stats.successes / (stats.successes + stats.failures) * 100).toFixed(1) + '%'
+        : 'N/A';
+
+    return stats;
+}
+
+/**
+ * Print history summary
+ */
+function printHistory() {
+    console.log(`\n${c.cyan}═══ Recovery History ═══${c.reset}\n`);
+
+    if (history.length === 0) {
+        console.log(`${c.gray}No recovery operations yet.${c.reset}`);
+        return;
+    }
+
+    for (const entry of history.slice(-10)) {
+        const icon = {
+            save: '💾',
+            rollback: '⏪',
+            success: '✅',
+            failure: '❌'
+        }[entry.type];
+
+        console.log(`${icon} ${entry.operation} (${entry.type})`);
+    }
+
+    const stats = getStats();
+    console.log(`\n${c.gray}Stats: ${stats.successes} success, ${stats.failures} failures (${stats.successRate})${c.reset}`);
+}
+
+/**
+ * Clear all checkpoints and history
+ */
+function clear() {
+    checkpoints.clear();
+    history.length = 0;
+}
+
+// ==================== EXPORTS ====================
+
+const recovery = {
+    save,
+    rollback,
+    get,
+    list,
+    backupFile,
+    restoreFile,
+    withRecovery,
+    getHistory,
+    getStats,
+    printHistory,
+    clear
+};
+
+export {
+    save,
+    rollback,
+    get,
+    list,
+    backupFile,
+    restoreFile,
+    withRecovery,
+    getHistory,
+    getStats,
+    printHistory,
+    clear
+};
+
+export default recovery;

package/lib/agent-cli/utils/telemetry.js

@@ -0,0 +1,290 @@
+/**
+ * Telemetry Utility - Local Metrics Collection
+ * 
+ * Provides opt-in anonymous metrics collection:
+ * - Local storage only (no external transmission)
+ * - Error frequency tracking
+ * - Usage patterns
+ * - Performance metrics
+ * 
+ * Usage:
+ *   import telemetry from './telemetry.js';
+ *   telemetry.track('error_detected', { type: 'test' });
+ *   telemetry.report();
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ==================== CONFIGURATION ====================
+
+const config = {
+    enabled: true,          // Master switch
+    storeLocally: true,     // Store to file
+    maxEvents: 1000,        // Max events to keep
+    maxAge: 30 * 24 * 60 * 60 * 1000, // 30 days
+    storagePath: null       // Will be set dynamically
+};
+
+// ==================== STORAGE ====================
+
+const events = [];
+const counters = new Map();
+const gauges = new Map();
+
+// ==================== HELPERS ====================
+
+/**
+ * Get storage path
+ */
+function getStoragePath() {
+    if (config.storagePath) return config.storagePath;
+
+    // Try to find project root
+    let dir = process.cwd();
+    while (dir !== path.dirname(dir)) {
+        if (fs.existsSync(path.join(dir, 'package.json'))) {
+            return path.join(dir, '.agent', 'knowledge', 'telemetry.json');
+        }
+        dir = path.dirname(dir);
+    }
+
+    return path.join(process.cwd(), '.agent', 'knowledge', 'telemetry.json');
+}
+
+/**
+ * Load existing telemetry data
+ */
+function load() {
+    const storagePath = getStoragePath();
+    if (!fs.existsSync(storagePath)) return;
+
+    try {
+        const data = JSON.parse(fs.readFileSync(storagePath, 'utf8'));
+        if (data.events) events.push(...data.events);
+        if (data.counters) {
+            for (const [k, v] of Object.entries(data.counters)) {
+                counters.set(k, v);
+            }
+        }
+    } catch (e) {
+        // Ignore parse errors
+    }
+}
+
+/**
+ * Save telemetry data
+ */
+function save() {
+    if (!config.storeLocally) return;
+
+    const storagePath = getStoragePath();
+    const dir = path.dirname(storagePath);
+
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+
+    const data = {
+        events: events.slice(-config.maxEvents),
+        counters: Object.fromEntries(counters),
+        gauges: Object.fromEntries(gauges),
+        savedAt: new Date().toISOString()
+    };
+
+    fs.writeFileSync(storagePath, JSON.stringify(data, null, 2));
+}
+
+// ==================== TRACKING ====================
+
+/**
+ * Track an event
+ * @param {string} name - Event name
+ * @param {object} properties - Event properties
+ */
+function track(name, properties = {}) {
+    if (!config.enabled) return;
+
+    const event = {
+        name,
+        properties,
+        timestamp: new Date().toISOString()
+    };
+
+    events.push(event);
+
+    // Increment counter
+    increment(name);
+
+    // Cleanup old events
+    if (events.length > config.maxEvents) {
+        events.splice(0, events.length - config.maxEvents);
+    }
+}
+
+/**
+ * Increment a counter
+ * @param {string} name - Counter name
+ * @param {number} value - Value to add (default: 1)
+ */
+function increment(name, value = 1) {
+    if (!config.enabled) return;
+    counters.set(name, (counters.get(name) || 0) + value);
+}
+
+/**
+ * Set a gauge value
+ * @param {string} name - Gauge name
+ * @param {number} value - Value to set
+ */
+function gauge(name, value) {
+    if (!config.enabled) return;
+    gauges.set(name, value);
+}
+
+// ==================== TIMING ====================
+
+/**
+ * Time an operation
+ * @param {string} name - Operation name
+ */
+function startTimer(name) {
+    const start = Date.now();
+    return {
+        end: () => {
+            const duration = Date.now() - start;
+            track(`${name}_duration`, { duration });
+            return duration;
+        }
+    };
+}
+
+// ==================== REPORTING ====================
+
+/**
+ * Get summary statistics
+ */
+function getSummary() {
+    const now = Date.now();
+    const cutoff = now - 24 * 60 * 60 * 1000; // Last 24 hours
+
+    const recentEvents = events.filter(e =>
+        new Date(e.timestamp).getTime() > cutoff
+    );
+
+    const byName = {};
+    for (const event of recentEvents) {
+        byName[event.name] = (byName[event.name] || 0) + 1;
+    }
+
+    return {
+        totalEvents: events.length,
+        last24h: recentEvents.length,
+        counters: Object.fromEntries(counters),
+        gauges: Object.fromEntries(gauges),
+        byEvent: byName
+    };
+}
+
+/**
+ * Print telemetry report
+ */
+function report() {
+    const summary = getSummary();
+
+    console.log('\n📊 Telemetry Report');
+    console.log('═══════════════════\n');
+
+    console.log(`Total Events: ${summary.totalEvents}`);
+    console.log(`Last 24h: ${summary.last24h}`);
+
+    if (Object.keys(summary.counters).length > 0) {
+        console.log('\nCounters:');
+        for (const [name, count] of Object.entries(summary.counters)) {
+            console.log(`  ${name}: ${count}`);
+        }
+    }
+
+    if (Object.keys(summary.byEvent).length > 0) {
+        console.log('\nRecent Events (24h):');
+        const sorted = Object.entries(summary.byEvent)
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 10);
+
+        for (const [name, count] of sorted) {
+            console.log(`  ${name}: ${count}`);
+        }
+    }
+}
+
+// ==================== CONFIGURATION ====================
+
+/**
+ * Enable telemetry
+ */
+function enable() {
+    config.enabled = true;
+}
+
+/**
+ * Disable telemetry
+ */
+function disable() {
+    config.enabled = false;
+}
+
+/**
+ * Check if enabled
+ */
+function isEnabled() {
+    return config.enabled;
+}
+
+/**
+ * Clear all telemetry data
+ */
+function clear() {
+    events.length = 0;
+    counters.clear();
+    gauges.clear();
+}
+
+// ==================== EXPORTS ====================
+
+const telemetry = {
+    track,
+    increment,
+    gauge,
+    startTimer,
+    getSummary,
+    report,
+    enable,
+    disable,
+    isEnabled,
+    clear,
+    save,
+    load,
+    config
+};
+
+export {
+    track,
+    increment,
+    gauge,
+    startTimer,
+    getSummary,
+    report,
+    enable,
+    disable,
+    isEnabled,
+    clear,
+    save,
+    load,
+    config
+};
+
+export default telemetry;

package/lib/agentskillskit-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.