claude-flow-novice 2.15.3 → 2.15.5

package/dist/lib/skill-cache.js

@@ -0,0 +1,297 @@
+/**
+ * LRU Skill Cache
+ *
+ * Memory-aware LRU (Least Recently Used) cache for skill content.
+ * Tracks memory usage per skill and evicts LRU entries when budget exceeded.
+ *
+ * Features:
+ * - Memory budget enforcement (bytes, not just entry count)
+ * - LRU eviction policy
+ * - Cache statistics (hits, misses, evictions)
+ * - Thread-safe operations
+ * - TTL support (optional)
+ *
+ * @module skill-cache
+ */ import { createLogger } from './logging.js';
+import { StandardError } from './errors.js';
+/**
+ * LRU Skill Cache with memory budget enforcement
+ */ export class LRUSkillCache {
+    cache;
+    maxMemoryBytes;
+    maxEntries;
+    defaultTTLMs;
+    currentMemoryBytes = 0;
+    logger;
+    debug;
+    // Statistics
+    stats = {
+        hits: 0,
+        misses: 0,
+        evictions: 0
+    };
+    constructor(config){
+        this.cache = new Map();
+        this.maxMemoryBytes = config.maxMemoryBytes;
+        this.maxEntries = config.maxEntries ?? Number.MAX_SAFE_INTEGER;
+        this.defaultTTLMs = config.defaultTTLMs;
+        this.logger = config.logger ?? createLogger('lru-skill-cache');
+        this.debug = config.debug ?? false;
+        if (this.debug) {
+            this.logger.info('LRU cache initialized', {
+                maxMemoryBytes: this.maxMemoryBytes,
+                maxMemoryMB: (this.maxMemoryBytes / 1024 / 1024).toFixed(2),
+                maxEntries: this.maxEntries,
+                defaultTTLMs: this.defaultTTLMs
+            });
+        }
+    }
+    /**
+   * Get value from cache
+   *
+   * Updates last access time (LRU tracking).
+   * Returns undefined if not found or expired.
+   */ get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            this.stats.misses++;
+            return undefined;
+        }
+        // Check expiry
+        if (entry.expiresAt && entry.expiresAt < new Date()) {
+            if (this.debug) {
+                this.logger.debug('Cache entry expired', {
+                    key
+                });
+            }
+            this.delete(key);
+            this.stats.misses++;
+            return undefined;
+        }
+        // Update last accessed (LRU tracking)
+        entry.lastAccessed = new Date();
+        this.stats.hits++;
+        if (this.debug) {
+            this.logger.debug('Cache hit', {
+                key,
+                sizeBytes: entry.sizeBytes,
+                age: Date.now() - entry.createdAt.getTime()
+            });
+        }
+        return entry.value;
+    }
+    /**
+   * Set value in cache
+   *
+   * Evicts LRU entries if memory budget would be exceeded.
+   *
+   * @param key - Cache key
+   * @param value - Value to cache
+   * @param sizeBytes - Size of value in bytes
+   * @param ttlMs - TTL in milliseconds (optional, overrides default)
+   */ set(key, value, sizeBytes, ttlMs) {
+        // Check if entry already exists
+        const existing = this.cache.get(key);
+        if (existing) {
+            // Update existing entry
+            this.currentMemoryBytes -= existing.sizeBytes;
+            this.currentMemoryBytes += sizeBytes;
+            existing.value = value;
+            existing.sizeBytes = sizeBytes;
+            existing.lastAccessed = new Date();
+            existing.createdAt = new Date();
+            if (ttlMs !== undefined || this.defaultTTLMs !== undefined) {
+                const ttl = ttlMs ?? this.defaultTTLMs;
+                existing.expiresAt = new Date(Date.now() + ttl);
+            }
+            if (this.debug) {
+                this.logger.debug('Cache entry updated', {
+                    key,
+                    sizeBytes,
+                    memoryUsageBytes: this.currentMemoryBytes
+                });
+            }
+            return;
+        }
+        // Evict entries if needed
+        this.evictIfNeeded(sizeBytes);
+        // Create new entry
+        const entry = {
+            key,
+            value,
+            sizeBytes,
+            lastAccessed: new Date(),
+            createdAt: new Date()
+        };
+        if (ttlMs !== undefined || this.defaultTTLMs !== undefined) {
+            const ttl = ttlMs ?? this.defaultTTLMs;
+            entry.expiresAt = new Date(Date.now() + ttl);
+        }
+        this.cache.set(key, entry);
+        this.currentMemoryBytes += sizeBytes;
+        if (this.debug) {
+            this.logger.debug('Cache entry added', {
+                key,
+                sizeBytes,
+                memoryUsageBytes: this.currentMemoryBytes,
+                memoryUtilization: (this.currentMemoryBytes / this.maxMemoryBytes).toFixed(2)
+            });
+        }
+    }
+    /**
+   * Delete entry from cache
+   */ delete(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return false;
+        }
+        this.cache.delete(key);
+        this.currentMemoryBytes -= entry.sizeBytes;
+        if (this.debug) {
+            this.logger.debug('Cache entry deleted', {
+                key,
+                sizeBytes: entry.sizeBytes,
+                memoryUsageBytes: this.currentMemoryBytes
+            });
+        }
+        return true;
+    }
+    /**
+   * Check if key exists in cache
+   */ has(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return false;
+        }
+        // Check expiry
+        if (entry.expiresAt && entry.expiresAt < new Date()) {
+            this.delete(key);
+            return false;
+        }
+        return true;
+    }
+    /**
+   * Clear all entries
+   */ clear() {
+        this.cache.clear();
+        this.currentMemoryBytes = 0;
+        if (this.debug) {
+            this.logger.debug('Cache cleared');
+        }
+    }
+    /**
+   * Get cache size (number of entries)
+   */ get size() {
+        return this.cache.size;
+    }
+    /**
+   * Get current memory usage (bytes)
+   */ get memoryUsageBytes() {
+        return this.currentMemoryBytes;
+    }
+    /**
+   * Get cache statistics
+   */ getStatistics() {
+        const totalOps = this.stats.hits + this.stats.misses;
+        const hitRate = totalOps > 0 ? this.stats.hits / totalOps : 0;
+        const evictionRate = totalOps > 0 ? this.stats.evictions / totalOps : 0;
+        const memoryUtilization = this.currentMemoryBytes / this.maxMemoryBytes;
+        return {
+            size: this.cache.size,
+            maxSize: this.maxEntries,
+            memoryUsageBytes: this.currentMemoryBytes,
+            maxMemoryBytes: this.maxMemoryBytes,
+            hits: this.stats.hits,
+            misses: this.stats.misses,
+            evictions: this.stats.evictions,
+            hitRate,
+            evictionRate,
+            memoryUtilization
+        };
+    }
+    /**
+   * Reset statistics
+   */ resetStatistics() {
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            evictions: 0
+        };
+    }
+    /**
+   * Get all cache keys
+   */ keys() {
+        return Array.from(this.cache.keys());
+    }
+    /**
+   * Evict entries if needed to fit new entry
+   *
+   * Uses LRU (Least Recently Used) eviction policy.
+   *
+   * @param newEntrySizeBytes - Size of new entry to add
+   */ evictIfNeeded(newEntrySizeBytes) {
+        // Check entry count limit
+        while(this.cache.size >= this.maxEntries){
+            this.evictLRU();
+        }
+        // Check memory budget
+        while(this.currentMemoryBytes + newEntrySizeBytes > this.maxMemoryBytes && this.cache.size > 0){
+            this.evictLRU();
+        }
+        // Final check: if single entry exceeds budget, throw error
+        if (newEntrySizeBytes > this.maxMemoryBytes) {
+            throw new StandardError('CACHE_ENTRY_TOO_LARGE', `Entry size (${newEntrySizeBytes} bytes) exceeds maximum memory budget (${this.maxMemoryBytes} bytes)`, {
+                newEntrySizeBytes,
+                maxMemoryBytes: this.maxMemoryBytes
+            });
+        }
+    }
+    /**
+   * Evict least recently used entry
+   */ evictLRU() {
+        let oldestKey;
+        let oldestTime;
+        // Find LRU entry
+        for (const [key, entry] of this.cache.entries()){
+            if (!oldestTime || entry.lastAccessed < oldestTime) {
+                oldestKey = key;
+                oldestTime = entry.lastAccessed;
+            }
+        }
+        if (oldestKey) {
+            const entry = this.cache.get(oldestKey);
+            this.delete(oldestKey);
+            this.stats.evictions++;
+            if (this.debug) {
+                this.logger.debug('Evicted LRU entry', {
+                    key: oldestKey,
+                    sizeBytes: entry.sizeBytes,
+                    age: Date.now() - entry.createdAt.getTime(),
+                    lastAccessed: entry.lastAccessed.toISOString()
+                });
+            }
+        }
+    }
+    /**
+   * Remove expired entries
+   *
+   * @returns Number of expired entries removed
+   */ cleanupExpired() {
+        const now = new Date();
+        let removed = 0;
+        for (const [key, entry] of this.cache.entries()){
+            if (entry.expiresAt && entry.expiresAt < now) {
+                this.delete(key);
+                removed++;
+            }
+        }
+        if (removed > 0 && this.debug) {
+            this.logger.debug('Cleaned up expired entries', {
+                count: removed
+            });
+        }
+        return removed;
+    }
+}
+
+//# sourceMappingURL=skill-cache.js.map

package/dist/lib/skill-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/skill-cache.ts"],"sourcesContent":["/**\r\n * LRU Skill Cache\r\n *\r\n * Memory-aware LRU (Least Recently Used) cache for skill content.\r\n * Tracks memory usage per skill and evicts LRU entries when budget exceeded.\r\n *\r\n * Features:\r\n * - Memory budget enforcement (bytes, not just entry count)\r\n * - LRU eviction policy\r\n * - Cache statistics (hits, misses, evictions)\r\n * - Thread-safe operations\r\n * - TTL support (optional)\r\n *\r\n * @module skill-cache\r\n */\r\n\r\nimport { createLogger, Logger } from './logging.js';\r\nimport { StandardError } from './errors.js';\r\n\r\n/**\r\n * Cache entry with LRU metadata\r\n */\r\nexport interface CacheEntry<T> {\r\n  /** Cache key (skill ID) */\r\n  key: string;\r\n\r\n  /** Cached value (skill content) */\r\n  value: T;\r\n\r\n  /** Entry size in bytes */\r\n  sizeBytes: number;\r\n\r\n  /** Last access timestamp */\r\n  lastAccessed: Date;\r\n\r\n  /** Creation timestamp */\r\n  createdAt: Date;\r\n\r\n  /** Expiry timestamp (optional) */\r\n  expiresAt?: Date;\r\n}\r\n\r\n/**\r\n * Cache statistics\r\n */\r\nexport interface CacheStatistics {\r\n  /** Current number of entries */\r\n  size: number;\r\n\r\n  /** Maximum number of entries */\r\n  maxSize: number;\r\n\r\n  /** Current memory usage (bytes) */\r\n  memoryUsageBytes: number;\r\n\r\n  /** Maximum memory budget (bytes) */\r\n  maxMemoryBytes: number;\r\n\r\n  /** Total cache hits */\r\n  hits: number;\r\n\r\n  /** Total cache misses */\r\n  misses: number;\r\n\r\n  /** Total evictions */\r\n  evictions: number;\r\n\r\n  /** Cache hit rate (0-1) */\r\n  hitRate: number;\r\n\r\n  /** Eviction rate (evictions / total operations) */\r\n  evictionRate: number;\r\n\r\n  /** Memory utilization (0-1) */\r\n  memoryUtilization: number;\r\n}\r\n\r\n/**\r\n * LRU Cache configuration\r\n */\r\nexport interface LRUCacheConfig {\r\n  /** Maximum memory budget in bytes */\r\n  maxMemoryBytes: number;\r\n\r\n  /** Maximum number of entries (optional, defaults to unlimited) */\r\n  maxEntries?: number;\r\n\r\n  /** Default TTL in milliseconds (optional, defaults to no expiry) */\r\n  defaultTTLMs?: number;\r\n\r\n  /** Logger instance */\r\n  logger?: Logger;\r\n\r\n  /** Enable debug logging */\r\n  debug?: boolean;\r\n}\r\n\r\n/**\r\n * LRU Skill Cache with memory budget enforcement\r\n */\r\nexport class LRUSkillCache<T> {\r\n  private cache: Map<string, CacheEntry<T>>;\r\n  private maxMemoryBytes: number;\r\n  private maxEntries: number;\r\n  private defaultTTLMs?: number;\r\n  private currentMemoryBytes: number = 0;\r\n  private logger: Logger;\r\n  private debug: boolean;\r\n\r\n  // Statistics\r\n  private stats = {\r\n    hits: 0,\r\n    misses: 0,\r\n    evictions: 0,\r\n  };\r\n\r\n  constructor(config: LRUCacheConfig) {\r\n    this.cache = new Map();\r\n    this.maxMemoryBytes = config.maxMemoryBytes;\r\n    this.maxEntries = config.maxEntries ?? Number.MAX_SAFE_INTEGER;\r\n    this.defaultTTLMs = config.defaultTTLMs;\r\n    this.logger = config.logger ?? createLogger('lru-skill-cache');\r\n    this.debug = config.debug ?? false;\r\n\r\n    if (this.debug) {\r\n      this.logger.info('LRU cache initialized', {\r\n        maxMemoryBytes: this.maxMemoryBytes,\r\n        maxMemoryMB: (this.maxMemoryBytes / 1024 / 1024).toFixed(2),\r\n        maxEntries: this.maxEntries,\r\n        defaultTTLMs: this.defaultTTLMs,\r\n      });\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Get value from cache\r\n   *\r\n   * Updates last access time (LRU tracking).\r\n   * Returns undefined if not found or expired.\r\n   */\r\n  get(key: string): T | undefined {\r\n    const entry = this.cache.get(key);\r\n\r\n    if (!entry) {\r\n      this.stats.misses++;\r\n      return undefined;\r\n    }\r\n\r\n    // Check expiry\r\n    if (entry.expiresAt && entry.expiresAt < new Date()) {\r\n      if (this.debug) {\r\n        this.logger.debug('Cache entry expired', { key });\r\n      }\r\n      this.delete(key);\r\n      this.stats.misses++;\r\n      return undefined;\r\n    }\r\n\r\n    // Update last accessed (LRU tracking)\r\n    entry.lastAccessed = new Date();\r\n    this.stats.hits++;\r\n\r\n    if (this.debug) {\r\n      this.logger.debug('Cache hit', {\r\n        key,\r\n        sizeBytes: entry.sizeBytes,\r\n        age: Date.now() - entry.createdAt.getTime(),\r\n      });\r\n    }\r\n\r\n    return entry.value;\r\n  }\r\n\r\n  /**\r\n   * Set value in cache\r\n   *\r\n   * Evicts LRU entries if memory budget would be exceeded.\r\n   *\r\n   * @param key - Cache key\r\n   * @param value - Value to cache\r\n   * @param sizeBytes - Size of value in bytes\r\n   * @param ttlMs - TTL in milliseconds (optional, overrides default)\r\n   */\r\n  set(key: string, value: T, sizeBytes: number, ttlMs?: number): void {\r\n    // Check if entry already exists\r\n    const existing = this.cache.get(key);\r\n    if (existing) {\r\n      // Update existing entry\r\n      this.currentMemoryBytes -= existing.sizeBytes;\r\n      this.currentMemoryBytes += sizeBytes;\r\n\r\n      existing.value = value;\r\n      existing.sizeBytes = sizeBytes;\r\n      existing.lastAccessed = new Date();\r\n      existing.createdAt = new Date();\r\n\r\n      if (ttlMs !== undefined || this.defaultTTLMs !== undefined) {\r\n        const ttl = ttlMs ?? this.defaultTTLMs!;\r\n        existing.expiresAt = new Date(Date.now() + ttl);\r\n      }\r\n\r\n      if (this.debug) {\r\n        this.logger.debug('Cache entry updated', {\r\n          key,\r\n          sizeBytes,\r\n          memoryUsageBytes: this.currentMemoryBytes,\r\n        });\r\n      }\r\n\r\n      return;\r\n    }\r\n\r\n    // Evict entries if needed\r\n    this.evictIfNeeded(sizeBytes);\r\n\r\n    // Create new entry\r\n    const entry: CacheEntry<T> = {\r\n      key,\r\n      value,\r\n      sizeBytes,\r\n      lastAccessed: new Date(),\r\n      createdAt: new Date(),\r\n    };\r\n\r\n    if (ttlMs !== undefined || this.defaultTTLMs !== undefined) {\r\n      const ttl = ttlMs ?? this.defaultTTLMs!;\r\n      entry.expiresAt = new Date(Date.now() + ttl);\r\n    }\r\n\r\n    this.cache.set(key, entry);\r\n    this.currentMemoryBytes += sizeBytes;\r\n\r\n    if (this.debug) {\r\n      this.logger.debug('Cache entry added', {\r\n        key,\r\n        sizeBytes,\r\n        memoryUsageBytes: this.currentMemoryBytes,\r\n        memoryUtilization: (this.currentMemoryBytes / this.maxMemoryBytes).toFixed(2),\r\n      });\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Delete entry from cache\r\n   */\r\n  delete(key: string): boolean {\r\n    const entry = this.cache.get(key);\r\n    if (!entry) {\r\n      return false;\r\n    }\r\n\r\n    this.cache.delete(key);\r\n    this.currentMemoryBytes -= entry.sizeBytes;\r\n\r\n    if (this.debug) {\r\n      this.logger.debug('Cache entry deleted', {\r\n        key,\r\n        sizeBytes: entry.sizeBytes,\r\n        memoryUsageBytes: this.currentMemoryBytes,\r\n      });\r\n    }\r\n\r\n    return true;\r\n  }\r\n\r\n  /**\r\n   * Check if key exists in cache\r\n   */\r\n  has(key: string): boolean {\r\n    const entry = this.cache.get(key);\r\n    if (!entry) {\r\n      return false;\r\n    }\r\n\r\n    // Check expiry\r\n    if (entry.expiresAt && entry.expiresAt < new Date()) {\r\n      this.delete(key);\r\n      return false;\r\n    }\r\n\r\n    return true;\r\n  }\r\n\r\n  /**\r\n   * Clear all entries\r\n   */\r\n  clear(): void {\r\n    this.cache.clear();\r\n    this.currentMemoryBytes = 0;\r\n\r\n    if (this.debug) {\r\n      this.logger.debug('Cache cleared');\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Get cache size (number of entries)\r\n   */\r\n  get size(): number {\r\n    return this.cache.size;\r\n  }\r\n\r\n  /**\r\n   * Get current memory usage (bytes)\r\n   */\r\n  get memoryUsageBytes(): number {\r\n    return this.currentMemoryBytes;\r\n  }\r\n\r\n  /**\r\n   * Get cache statistics\r\n   */\r\n  getStatistics(): CacheStatistics {\r\n    const totalOps = this.stats.hits + this.stats.misses;\r\n    const hitRate = totalOps > 0 ? this.stats.hits / totalOps : 0;\r\n    const evictionRate = totalOps > 0 ? this.stats.evictions / totalOps : 0;\r\n    const memoryUtilization = this.currentMemoryBytes / this.maxMemoryBytes;\r\n\r\n    return {\r\n      size: this.cache.size,\r\n      maxSize: this.maxEntries,\r\n      memoryUsageBytes: this.currentMemoryBytes,\r\n      maxMemoryBytes: this.maxMemoryBytes,\r\n      hits: this.stats.hits,\r\n      misses: this.stats.misses,\r\n      evictions: this.stats.evictions,\r\n      hitRate,\r\n      evictionRate,\r\n      memoryUtilization,\r\n    };\r\n  }\r\n\r\n  /**\r\n   * Reset statistics\r\n   */\r\n  resetStatistics(): void {\r\n    this.stats = {\r\n      hits: 0,\r\n      misses: 0,\r\n      evictions: 0,\r\n    };\r\n  }\r\n\r\n  /**\r\n   * Get all cache keys\r\n   */\r\n  keys(): string[] {\r\n    return Array.from(this.cache.keys());\r\n  }\r\n\r\n  /**\r\n   * Evict entries if needed to fit new entry\r\n   *\r\n   * Uses LRU (Least Recently Used) eviction policy.\r\n   *\r\n   * @param newEntrySizeBytes - Size of new entry to add\r\n   */\r\n  private evictIfNeeded(newEntrySizeBytes: number): void {\r\n    // Check entry count limit\r\n    while (this.cache.size >= this.maxEntries) {\r\n      this.evictLRU();\r\n    }\r\n\r\n    // Check memory budget\r\n    while (\r\n      this.currentMemoryBytes + newEntrySizeBytes > this.maxMemoryBytes &&\r\n      this.cache.size > 0\r\n    ) {\r\n      this.evictLRU();\r\n    }\r\n\r\n    // Final check: if single entry exceeds budget, throw error\r\n    if (newEntrySizeBytes > this.maxMemoryBytes) {\r\n      throw new StandardError(\r\n        'CACHE_ENTRY_TOO_LARGE',\r\n        `Entry size (${newEntrySizeBytes} bytes) exceeds maximum memory budget (${this.maxMemoryBytes} bytes)`,\r\n        { newEntrySizeBytes, maxMemoryBytes: this.maxMemoryBytes }\r\n      );\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Evict least recently used entry\r\n   */\r\n  private evictLRU(): void {\r\n    let oldestKey: string | undefined;\r\n    let oldestTime: Date | undefined;\r\n\r\n    // Find LRU entry\r\n    for (const [key, entry] of this.cache.entries()) {\r\n      if (!oldestTime || entry.lastAccessed < oldestTime) {\r\n        oldestKey = key;\r\n        oldestTime = entry.lastAccessed;\r\n      }\r\n    }\r\n\r\n    if (oldestKey) {\r\n      const entry = this.cache.get(oldestKey)!;\r\n      this.delete(oldestKey);\r\n      this.stats.evictions++;\r\n\r\n      if (this.debug) {\r\n        this.logger.debug('Evicted LRU entry', {\r\n          key: oldestKey,\r\n          sizeBytes: entry.sizeBytes,\r\n          age: Date.now() - entry.createdAt.getTime(),\r\n          lastAccessed: entry.lastAccessed.toISOString(),\r\n        });\r\n      }\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Remove expired entries\r\n   *\r\n   * @returns Number of expired entries removed\r\n   */\r\n  cleanupExpired(): number {\r\n    const now = new Date();\r\n    let removed = 0;\r\n\r\n    for (const [key, entry] of this.cache.entries()) {\r\n      if (entry.expiresAt && entry.expiresAt < now) {\r\n        this.delete(key);\r\n        removed++;\r\n      }\r\n    }\r\n\r\n    if (removed > 0 && this.debug) {\r\n      this.logger.debug('Cleaned up expired entries', { count: removed });\r\n    }\r\n\r\n    return removed;\r\n  }\r\n}\r\n"],"names":["createLogger","StandardError","LRUSkillCache","cache","maxMemoryBytes","maxEntries","defaultTTLMs","currentMemoryBytes","logger","debug","stats","hits","misses","evictions","config","Map","Number","MAX_SAFE_INTEGER","info","maxMemoryMB","toFixed","get","key","entry","undefined","expiresAt","Date","delete","lastAccessed","sizeBytes","age","now","createdAt","getTime","value","set","ttlMs","existing","ttl","memoryUsageBytes","evictIfNeeded","memoryUtilization","has","clear","size","getStatistics","totalOps","hitRate","evictionRate","maxSize","resetStatistics","keys","Array","from","newEntrySizeBytes","evictLRU","oldestKey","oldestTime","entries","toISOString","cleanupExpired","removed","count"],"mappings":"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"}

package/dist/lib/skill-content-manager.js

@@ -0,0 +1,337 @@
+/**
+ * Skill Content Manager
+ *
+ * Manages standardized skill content storage, organization, and versioning
+ * Enforces directory structure, validates required files, tracks versions
+ *
+ * @module skill-content-manager
+ * @version 1.0.0
+ */ import { join, basename } from 'path';
+import { stat, readdir, access, chmod, readFile, writeFile, mkdir } from 'fs/promises';
+import { constants } from 'fs';
+import { StandardError } from './errors.js';
+import { parseFrontmatter, validateFrontmatter, parseAndValidate, updateFrontmatter, createSkillDocument } from './skill-frontmatter-parser.js';
+import { calculateFileHash, getCommitMetadata, getVersionHistory, commitFile, hasUncommittedChanges, verifyContentIntegrity, getFileCreationDate, getFileModificationDate } from './skill-git-integration.js';
+/**
+ * Required files in skill directory
+ */ export const REQUIRED_SKILL_FILES = [
+    'SKILL.md',
+    'execute.sh',
+    'test.sh',
+    'validate.sh',
+    'package.json'
+];
+/**
+ * Skill content manager error
+ */ export class SkillContentError extends StandardError {
+    context;
+    constructor(message, context){
+        super('SKILL_CONTENT_ERROR', message, context), this.context = context;
+        this.name = 'SkillContentError';
+    }
+}
+/**
+ * Validate skill directory structure
+ *
+ * @param skillPath - Path to skill directory
+ * @returns Validation result with details
+ */ export async function validateSkillStructure(skillPath) {
+    const skillName = basename(skillPath);
+    const missingFiles = [];
+    const invalidPermissions = [];
+    const errors = [];
+    const warnings = [];
+    try {
+        // Check if directory exists
+        const dirStat = await stat(skillPath);
+        if (!dirStat.isDirectory()) {
+            errors.push(`${skillPath} is not a directory`);
+            return {
+                valid: false,
+                skillName,
+                skillPath,
+                missingFiles,
+                invalidPermissions,
+                errors,
+                warnings
+            };
+        }
+    } catch (error) {
+        errors.push(`Skill directory does not exist: ${skillPath}`);
+        return {
+            valid: false,
+            skillName,
+            skillPath,
+            missingFiles,
+            invalidPermissions,
+            errors,
+            warnings
+        };
+    }
+    // Check required files
+    for (const fileName of REQUIRED_SKILL_FILES){
+        const filePath = join(skillPath, fileName);
+        try {
+            await access(filePath, constants.F_OK);
+            // Check execute permission for .sh files
+            if (fileName.endsWith('.sh')) {
+                try {
+                    await access(filePath, constants.X_OK);
+                } catch  {
+                    invalidPermissions.push(fileName);
+                    errors.push(`${fileName} is not executable`);
+                }
+            }
+        } catch  {
+            missingFiles.push(fileName);
+            errors.push(`Required file missing: ${fileName}`);
+        }
+    }
+    // Validate SKILL.md frontmatter if exists
+    const skillMdPath = join(skillPath, 'SKILL.md');
+    try {
+        await access(skillMdPath, constants.F_OK);
+        const content = await readFile(skillMdPath, 'utf-8');
+        try {
+            const parsed = parseFrontmatter(content);
+            const validation = validateFrontmatter(parsed.frontmatter);
+            if (!validation.valid) {
+                errors.push(...validation.errors);
+            }
+            warnings.push(...validation.warnings);
+        } catch (error) {
+            errors.push(`SKILL.md frontmatter error: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    } catch  {
+    // Already reported as missing file
+    }
+    return {
+        valid: errors.length === 0,
+        skillName,
+        skillPath,
+        missingFiles,
+        invalidPermissions,
+        errors,
+        warnings
+    };
+}
+/**
+ * Fix skill file permissions
+ *
+ * @param skillPath - Path to skill directory
+ * @returns Array of files that were fixed
+ */ export async function fixSkillPermissions(skillPath) {
+    const fixed = [];
+    for (const fileName of REQUIRED_SKILL_FILES){
+        if (fileName.endsWith('.sh')) {
+            const filePath = join(skillPath, fileName);
+            try {
+                await access(filePath, constants.F_OK);
+                await chmod(filePath, 0o755); // rwxr-xr-x
+                fixed.push(fileName);
+            } catch  {
+            // File doesn't exist, skip
+            }
+        }
+    }
+    return fixed;
+}
+/**
+ * Load skill metadata with git integration
+ *
+ * @param skillPath - Path to skill directory
+ * @param includeHistory - Include version history (default: false)
+ * @returns Complete skill metadata
+ */ export async function loadSkillMetadata(skillPath, includeHistory = false) {
+    const skillMdPath = join(skillPath, 'SKILL.md');
+    try {
+        // Read and parse SKILL.md
+        const content = await readFile(skillMdPath, 'utf-8');
+        const parsed = parseAndValidate(content);
+        // Calculate content hash
+        const contentHash = calculateFileHash(skillMdPath);
+        // Get git metadata (graceful fallback if not in git repo)
+        let gitMetadata;
+        let versionHistory;
+        let hasChanges;
+        let fileCreated;
+        let fileModified;
+        try {
+            gitMetadata = await getCommitMetadata(skillMdPath);
+            hasChanges = await hasUncommittedChanges(skillMdPath);
+            fileCreated = await getFileCreationDate(skillMdPath);
+            fileModified = await getFileModificationDate(skillMdPath);
+            if (includeHistory) {
+                versionHistory = await getVersionHistory(skillMdPath);
+            }
+        } catch  {
+        // Not in git repo or no git history - continue without git data
+        }
+        return {
+            ...parsed.frontmatter,
+            skillPath,
+            contentHash: await contentHash,
+            gitMetadata,
+            versionHistory,
+            hasUncommittedChanges: hasChanges,
+            fileCreated,
+            fileModified
+        };
+    } catch (error) {
+        throw new SkillContentError(`Failed to load skill metadata from ${skillPath}`, {
+            error: error instanceof Error ? error.message : String(error)
+        });
+    }
+}
+/**
+ * Update skill frontmatter
+ *
+ * @param skillPath - Path to skill directory
+ * @param updates - Partial frontmatter updates
+ * @param options - Update options
+ * @returns Updated skill metadata
+ */ export async function updateSkillFrontmatter(skillPath, updates, options = {}) {
+    const { autoCommit = false, commitMessage, updateTimestamp = true, validateStructure = true } = options;
+    const skillMdPath = join(skillPath, 'SKILL.md');
+    try {
+        // Validate structure first if requested
+        if (validateStructure) {
+            const validation = await validateSkillStructure(skillPath);
+            if (!validation.valid) {
+                throw new SkillContentError('Skill structure validation failed', {
+                    errors: validation.errors
+                });
+            }
+        }
+        // Read current content
+        const currentContent = await readFile(skillMdPath, 'utf-8');
+        // Update frontmatter
+        const updatedContent = updateFrontmatter(currentContent, updates);
+        // Write updated content
+        await writeFile(skillMdPath, updatedContent, 'utf-8');
+        // Auto-commit if requested
+        if (autoCommit) {
+            const message = commitMessage || `Update ${basename(skillPath)} frontmatter`;
+            await commitFile(skillMdPath, message);
+        }
+        // Return updated metadata
+        return await loadSkillMetadata(skillPath);
+    } catch (error) {
+        throw new SkillContentError(`Failed to update skill frontmatter for ${skillPath}`, {
+            error: error instanceof Error ? error.message : String(error)
+        });
+    }
+}
+/**
+ * Create new skill directory with standard structure
+ *
+ * @param parentDir - Parent directory for skills
+ * @param skillName - Name of skill to create
+ * @param frontmatter - Initial frontmatter
+ * @param content - Initial SKILL.md content
+ * @returns Created skill metadata
+ */ export async function createSkill(parentDir, skillName, frontmatter, content = '') {
+    const skillPath = join(parentDir, skillName);
+    try {
+        // Create skill directory
+        await mkdir(skillPath, {
+            recursive: true
+        });
+        // Create SKILL.md
+        const skillMdPath = join(skillPath, 'SKILL.md');
+        const skillDocument = createSkillDocument(frontmatter, content);
+        await writeFile(skillMdPath, skillDocument, 'utf-8');
+        // Create placeholder files
+        const executeSh = `#!/bin/bash
+# ${frontmatter.name} - Execution Script
+# Version: ${frontmatter.version}
+
+set -euo pipefail
+
+echo "Executing ${frontmatter.name}..."
+# Add implementation here
+`;
+        const testSh = `#!/bin/bash
+# ${frontmatter.name} - Test Script
+# Version: ${frontmatter.version}
+
+set -euo pipefail
+
+echo "Testing ${frontmatter.name}..."
+# Add tests here
+`;
+        const validateSh = `#!/bin/bash
+# ${frontmatter.name} - Validation Script
+# Version: ${frontmatter.version}
+
+set -euo pipefail
+
+echo "Validating ${frontmatter.name}..."
+# Add validation here
+`;
+        const packageJson = {
+            name: skillName,
+            version: frontmatter.version,
+            description: frontmatter.description,
+            scripts: {
+                execute: './execute.sh',
+                test: './test.sh',
+                validate: './validate.sh'
+            }
+        };
+        await writeFile(join(skillPath, 'execute.sh'), executeSh, 'utf-8');
+        await writeFile(join(skillPath, 'test.sh'), testSh, 'utf-8');
+        await writeFile(join(skillPath, 'validate.sh'), validateSh, 'utf-8');
+        await writeFile(join(skillPath, 'package.json'), JSON.stringify(packageJson, null, 2), 'utf-8');
+        // Fix permissions
+        await fixSkillPermissions(skillPath);
+        // Return metadata
+        return await loadSkillMetadata(skillPath);
+    } catch (error) {
+        throw new SkillContentError(`Failed to create skill ${skillName}`, {
+            error: error instanceof Error ? error.message : String(error)
+        });
+    }
+}
+/**
+ * Scan directory for all skills
+ *
+ * @param skillsDir - Path to skills directory
+ * @returns Array of skill paths
+ */ export async function scanSkills(skillsDir) {
+    try {
+        const entries = await readdir(skillsDir, {
+            withFileTypes: true
+        });
+        const skillPaths = [];
+        for (const entry of entries){
+            if (entry.isDirectory()) {
+                const skillPath = join(skillsDir, entry.name);
+                const skillMdPath = join(skillPath, 'SKILL.md');
+                try {
+                    await access(skillMdPath, constants.F_OK);
+                    skillPaths.push(skillPath);
+                } catch  {
+                // Not a valid skill directory, skip
+                }
+            }
+        }
+        return skillPaths.sort();
+    } catch (error) {
+        throw new SkillContentError(`Failed to scan skills directory ${skillsDir}`, {
+            error: error instanceof Error ? error.message : String(error)
+        });
+    }
+}
+/**
+ * Verify skill content integrity
+ *
+ * @param skillPath - Path to skill directory
+ * @param expectedHash - Expected content hash
+ * @returns True if content matches expected hash
+ */ export async function verifySkillIntegrity(skillPath, expectedHash) {
+    const skillMdPath = join(skillPath, 'SKILL.md');
+    return await verifyContentIntegrity(skillMdPath, expectedHash);
+}
+
+//# sourceMappingURL=skill-content-manager.js.map