scene-capability-engine 3.0.0

package/lib/knowledge/knowledge-manager.js

@@ -0,0 +1,273 @@
+/**
+ * Knowledge Manager
+ * Central coordinator for knowledge base operations
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const EntryManager = require('./entry-manager');
+const IndexManager = require('./index-manager');
+const TemplateManager = require('./template-manager');
+
+class KnowledgeManager {
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    this.knowledgePath = path.join(projectRoot, '.kiro', 'knowledge');
+    
+    this.entryManager = new EntryManager(this.knowledgePath);
+    this.indexManager = new IndexManager(this.knowledgePath);
+    this.templateManager = new TemplateManager(this.knowledgePath);
+  }
+  
+  /**
+   * Initialize knowledge base
+   */
+  async initialize() {
+    // Create directory structure
+    await fs.ensureDir(this.knowledgePath);
+    await fs.ensureDir(path.join(this.knowledgePath, 'patterns'));
+    await fs.ensureDir(path.join(this.knowledgePath, 'lessons'));
+    await fs.ensureDir(path.join(this.knowledgePath, 'workflows'));
+    await fs.ensureDir(path.join(this.knowledgePath, 'checklists'));
+    await fs.ensureDir(path.join(this.knowledgePath, 'references'));
+    await fs.ensureDir(path.join(this.knowledgePath, '.templates'));
+    await fs.ensureDir(path.join(this.knowledgePath, '.backups'));
+    
+    // Create README
+    const readme = `# Knowledge Base
+
+This directory contains your personal knowledge base for this project.
+
+## Structure
+
+- \`patterns/\` - Design patterns and architectural solutions
+- \`lessons/\` - Lessons learned from experience
+- \`workflows/\` - Custom workflows and processes
+- \`checklists/\` - Checklists for common tasks
+- \`references/\` - Reference materials and links
+
+## Usage
+
+\`\`\`bash
+# Add new entry
+kse knowledge add <type> "<title>"
+
+# List all entries
+kse knowledge list
+
+# Search entries
+kse knowledge search <keyword>
+
+# Analyze knowledge base
+kse knowledge analyze
+
+# Integrate knowledge into project
+kse knowledge integrate <id> --target <destination>
+\`\`\`
+
+## Learn More
+
+See \`docs/knowledge-management-guide.md\` for complete documentation.
+`;
+    
+    await fs.writeFile(path.join(this.knowledgePath, 'README.md'), readme, 'utf-8');
+    
+    // Initialize index
+    await this.indexManager.load();
+    await this.indexManager.save();
+  }
+  
+  /**
+   * Check if knowledge base is initialized
+   * @returns {boolean}
+   */
+  async isInitialized() {
+    return fs.pathExists(this.knowledgePath);
+  }
+  
+  /**
+   * Add new entry
+   * @param {string} type - Entry type
+   * @param {string} title - Entry title
+   * @param {Object} options - Additional options
+   * @returns {Object} - Created entry info
+   */
+  async addEntry(type, title, options = {}) {
+    if (!await this.isInitialized()) {
+      throw new Error('Knowledge base not initialized. Run: kse knowledge init');
+    }
+    
+    // Validate type
+    const validTypes = ['pattern', 'lesson', 'workflow', 'checklist', 'reference'];
+    if (!validTypes.includes(type)) {
+      throw new Error(`Invalid type: ${type}. Valid types: ${validTypes.join(', ')}`);
+    }
+    
+    // Get template
+    const template = await this.templateManager.getTemplate(type);
+    
+    // Create entry
+    const result = await this.entryManager.create(type, title, template, {
+      tags: options.tags || [],
+      category: options.category || null
+    });
+    
+    // Update index
+    const entryData = await this.entryManager.read(result.path);
+    await this.indexManager.addEntry({
+      ...entryData.metadata,
+      file: result.file
+    });
+    
+    return result;
+  }
+  
+  /**
+   * Get entry by ID
+   * @param {string} id - Entry ID
+   * @returns {Object} - Entry data
+   */
+  async getEntry(id) {
+    const entry = await this.indexManager.findById(id);
+    if (!entry) {
+      throw new Error(`Entry not found: ${id}`);
+    }
+    
+    const filePath = path.join(this.knowledgePath, entry.file);
+    return this.entryManager.read(filePath);
+  }
+  
+  /**
+   * Update entry
+   * @param {string} id - Entry ID
+   * @param {Object} updates - Updates to apply
+   */
+  async updateEntry(id, updates) {
+    const entry = await this.indexManager.findById(id);
+    if (!entry) {
+      throw new Error(`Entry not found: ${id}`);
+    }
+    
+    const filePath = path.join(this.knowledgePath, entry.file);
+    await this.entryManager.update(filePath, updates.content, updates.metadata);
+    
+    // Update index
+    if (updates.metadata) {
+      await this.indexManager.updateEntry(id, updates.metadata);
+    }
+  }
+  
+  /**
+   * Delete entry
+   * @param {string} id - Entry ID
+   * @param {Object} options - Delete options
+   */
+  async deleteEntry(id, options = {}) {
+    const entry = await this.indexManager.findById(id);
+    if (!entry) {
+      throw new Error(`Entry not found: ${id}`);
+    }
+    
+    const filePath = path.join(this.knowledgePath, entry.file);
+    await this.entryManager.delete(filePath, options.backup !== false);
+    
+    // Update index
+    await this.indexManager.removeEntry(id);
+    
+    return {
+      id,
+      title: entry.title,
+      deleted: true
+    };
+  }
+  
+  /**
+   * List entries
+   * @param {Object} filters - Filter options
+   * @returns {Array} - Filtered entries
+   */
+  async listEntries(filters = {}) {
+    await this.indexManager.load();
+    
+    let entries = this.indexManager.index.entries;
+    
+    // Apply filters
+    if (filters.type) {
+      entries = entries.filter(e => e.type === filters.type);
+    }
+    
+    if (filters.tag) {
+      entries = entries.filter(e => e.tags.includes(filters.tag));
+    }
+    
+    if (filters.status) {
+      entries = entries.filter(e => e.status === filters.status);
+    }
+    
+    // Apply sorting
+    if (filters.sort) {
+      const [field, order = 'asc'] = filters.sort.split(':');
+      entries.sort((a, b) => {
+        const aVal = a[field];
+        const bVal = b[field];
+        const comparison = aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
+        return order === 'desc' ? -comparison : comparison;
+      });
+    }
+    
+    return entries;
+  }
+  
+  /**
+   * Search entries
+   * @param {string} keyword - Search keyword
+   * @param {Object} options - Search options
+   * @returns {Array} - Search results
+   */
+  async search(keyword, options = {}) {
+    // Search in index first
+    const indexResults = await this.indexManager.search(keyword);
+    
+    if (!options.fullText) {
+      return indexResults;
+    }
+    
+    // Full-text search in files
+    const results = [];
+    const lowerKeyword = keyword.toLowerCase();
+    
+    for (const entry of indexResults) {
+      const filePath = path.join(this.knowledgePath, entry.file);
+      const data = await this.entryManager.read(filePath);
+      
+      if (data.content.toLowerCase().includes(lowerKeyword)) {
+        // Extract context snippet
+        const lines = data.content.split('\n');
+        const matchingLines = lines.filter(line => 
+          line.toLowerCase().includes(lowerKeyword)
+        );
+        
+        results.push({
+          ...entry,
+          matches: matchingLines.slice(0, 3),
+          score: matchingLines.length
+        });
+      }
+    }
+    
+    // Sort by relevance
+    results.sort((a, b) => b.score - a.score);
+    
+    return results;
+  }
+  
+  /**
+   * Get statistics
+   * @returns {Object} - Statistics
+   */
+  async getStats() {
+    return this.indexManager.getStats();
+  }
+}
+
+module.exports = KnowledgeManager;

package/lib/knowledge/template-manager.js

@@ -0,0 +1,191 @@
+/**
+ * Template Manager
+ * Manages entry templates
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+
+class TemplateManager {
+  constructor(knowledgePath) {
+    this.knowledgePath = knowledgePath;
+    this.templatesDir = path.join(knowledgePath, '.templates');
+    this.builtInTemplatesDir = path.join(__dirname, 'templates');
+  }
+  
+  /**
+   * Get template by type
+   * @param {string} type - Template type
+   * @returns {string} - Template content
+   */
+  async getTemplate(type) {
+    // Check custom template first
+    const customPath = path.join(this.templatesDir, `${type}.md`);
+    if (await fs.pathExists(customPath)) {
+      return fs.readFile(customPath, 'utf-8');
+    }
+    
+    // Fall back to built-in template
+    return this.getDefaultTemplate(type);
+  }
+  
+  /**
+   * List available templates
+   * @returns {Array} - Template names
+   */
+  async listTemplates() {
+    const templates = ['pattern', 'lesson', 'workflow', 'checklist', 'reference'];
+    
+    // Check for custom templates
+    if (await fs.pathExists(this.templatesDir)) {
+      const files = await fs.readdir(this.templatesDir);
+      const customTemplates = files
+        .filter(f => f.endsWith('.md'))
+        .map(f => path.basename(f, '.md'));
+      
+      return [...new Set([...templates, ...customTemplates])];
+    }
+    
+    return templates;
+  }
+  
+  /**
+   * Get default built-in template
+   * @param {string} type - Template type
+   * @returns {string} - Template content
+   */
+  getDefaultTemplate(type) {
+    const templates = {
+      pattern: `## Context
+
+Describe when and where this pattern applies.
+
+## Problem
+
+What problem does this pattern solve?
+
+## Solution
+
+How to implement this pattern.
+
+## Examples
+
+\`\`\`javascript
+// Code example
+\`\`\`
+
+## Trade-offs
+
+Advantages and disadvantages.
+
+## References
+
+- Related patterns
+- External resources
+`,
+      
+      lesson: `## Situation
+
+What was the context or project?
+
+## Challenge
+
+What problem or challenge did you face?
+
+## Action
+
+What did you do to address it?
+
+## Result
+
+What was the outcome?
+
+## Lesson Learned
+
+What did you learn from this experience?
+
+## Application
+
+How can this lesson be applied in the future?
+`,
+      
+      workflow: `## Purpose
+
+What is this workflow for?
+
+## Prerequisites
+
+What needs to be in place before starting?
+
+## Steps
+
+1. First step
+2. Second step
+3. Third step
+
+## Verification
+
+How to verify the workflow completed successfully?
+
+## Troubleshooting
+
+Common issues and solutions.
+
+## References
+
+- Related workflows
+- Documentation links
+`,
+      
+      checklist: `## Purpose
+
+What is this checklist for?
+
+## Checklist Items
+
+- [ ] Item 1
+- [ ] Item 2
+- [ ] Item 3
+
+## Notes
+
+Additional context or tips.
+
+## References
+
+- Related checklists
+- Documentation
+`,
+      
+      reference: `## Overview
+
+Brief description of this reference.
+
+## Key Information
+
+Important details, links, or data.
+
+## Usage
+
+How to use this reference.
+
+## Examples
+
+Practical examples.
+
+## Related
+
+- Related references
+- External links
+`
+    };
+    
+    if (!templates[type]) {
+      throw new Error(`Unknown template type: ${type}`);
+    }
+    
+    return templates[type];
+  }
+}
+
+module.exports = TemplateManager;

package/lib/lock/index.js

@@ -0,0 +1,21 @@
+/**
+ * Lock module exports
+ * @module lib/lock
+ */
+
+const { LockManager, DEFAULT_TIMEOUT_HOURS } = require('./lock-manager');
+const { MachineIdentifier } = require('./machine-identifier');
+const { LockFile, LOCK_FILE_NAME, LOCK_VERSION } = require('./lock-file');
+const { TaskLockManager } = require('./task-lock-manager');
+const { SteeringFileLock } = require('./steering-file-lock');
+
+module.exports = {
+  LockManager,
+  MachineIdentifier,
+  LockFile,
+  DEFAULT_TIMEOUT_HOURS,
+  LOCK_FILE_NAME,
+  LOCK_VERSION,
+  TaskLockManager,
+  SteeringFileLock
+};

package/lib/lock/lock-file.js

@@ -0,0 +1,192 @@
+/**
+ * LockFile - Manages lock file I/O operations
+ * @module lib/lock/lock-file
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+
+const LOCK_FILE_NAME = '.lock';
+const LOCK_VERSION = '1.0.0';
+
+class LockFile {
+  /**
+   * @param {string} specsDir - Path to specs directory
+   */
+  constructor(specsDir) {
+    this.specsDir = specsDir;
+  }
+
+  /**
+   * Get lock file path for a spec
+   * @param {string} specName - Name of the Spec
+   * @returns {string}
+   * @private
+   */
+  _getLockPath(specName) {
+    return path.join(this.specsDir, specName, LOCK_FILE_NAME);
+  }
+
+  /**
+   * Read lock metadata from a Spec
+   * @param {string} specName - Name of the Spec
+   * @returns {Promise<LockMetadata|null>}
+   */
+  async read(specName) {
+    const lockPath = this._getLockPath(specName);
+    
+    try {
+      const data = await fs.readFile(lockPath, 'utf8');
+      const metadata = JSON.parse(data);
+      
+      if (!this._isValidMetadata(metadata)) {
+        return null; // Corrupted lock file
+      }
+      
+      return this._normalizeMetadata(metadata);
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        return null; // No lock file
+      }
+      if (error instanceof SyntaxError) {
+        return null; // Invalid JSON - corrupted
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Write lock metadata to a Spec
+   * @param {string} specName - Name of the Spec
+   * @param {LockMetadata} metadata - Lock metadata to write
+   * @returns {Promise<void>}
+   */
+  async write(specName, metadata) {
+    const lockPath = this._getLockPath(specName);
+    const specDir = path.dirname(lockPath);
+    
+    // Ensure spec directory exists
+    await fs.mkdir(specDir, { recursive: true });
+    
+    const normalizedMetadata = {
+      ...metadata,
+      version: metadata.version || LOCK_VERSION
+    };
+    
+    if (!this._isValidMetadata(normalizedMetadata)) {
+      throw new Error('Invalid lock metadata: missing required fields');
+    }
+    
+    // Atomic write using temp file
+    const tempPath = `${lockPath}.tmp`;
+    const content = JSON.stringify(normalizedMetadata, null, 2);
+    
+    await fs.writeFile(tempPath, content, 'utf8');
+    await fs.rename(tempPath, lockPath);
+  }
+
+
+  /**
+   * Delete lock file from a Spec
+   * @param {string} specName - Name of the Spec
+   * @returns {Promise<boolean>}
+   */
+  async delete(specName) {
+    const lockPath = this._getLockPath(specName);
+    
+    try {
+      await fs.unlink(lockPath);
+      return true;
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        return false; // Already deleted
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Check if lock file exists
+   * @param {string} specName - Name of the Spec
+   * @returns {Promise<boolean>}
+   */
+  async exists(specName) {
+    const lockPath = this._getLockPath(specName);
+    
+    try {
+      await fs.access(lockPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * List all Specs with lock files
+   * @returns {Promise<string[]>}
+   */
+  async listLockedSpecs() {
+    const lockedSpecs = [];
+    
+    try {
+      const entries = await fs.readdir(this.specsDir, { withFileTypes: true });
+      
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const lockPath = path.join(this.specsDir, entry.name, LOCK_FILE_NAME);
+          try {
+            await fs.access(lockPath);
+            lockedSpecs.push(entry.name);
+          } catch {
+            // No lock file
+          }
+        }
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        throw error;
+      }
+    }
+    
+    return lockedSpecs;
+  }
+
+  /**
+   * Validate lock metadata structure
+   * @param {Object} metadata
+   * @returns {boolean}
+   * @private
+   */
+  _isValidMetadata(metadata) {
+    return (
+      metadata &&
+      typeof metadata.owner === 'string' &&
+      typeof metadata.machineId === 'string' &&
+      typeof metadata.hostname === 'string' &&
+      typeof metadata.timestamp === 'string' &&
+      typeof metadata.timeout === 'number' &&
+      metadata.owner.length > 0 &&
+      metadata.machineId.length > 0
+    );
+  }
+
+  /**
+   * Normalize metadata with default values for optional fields
+   * @param {Object} metadata
+   * @returns {LockMetadata}
+   * @private
+   */
+  _normalizeMetadata(metadata) {
+    return {
+      owner: metadata.owner,
+      machineId: metadata.machineId,
+      hostname: metadata.hostname,
+      timestamp: metadata.timestamp,
+      reason: metadata.reason || null,
+      timeout: metadata.timeout,
+      version: metadata.version || LOCK_VERSION
+    };
+  }
+}
+
+module.exports = { LockFile, LOCK_FILE_NAME, LOCK_VERSION };