scene-capability-engine 3.0.0

package/lib/operations/index.js

@@ -0,0 +1,23 @@
+/**
+ * Operations Module
+ * 
+ * Core module for DevOps integration foundation
+ * Provides operations spec management, permission control, feedback handling, and audit logging
+ */
+
+module.exports = {
+  // Core managers
+  OperationsManager: require('./operations-manager'),
+  PermissionManager: require('./permission-manager'),
+  FeedbackManager: require('./feedback-manager'),
+  AuditLogger: require('./audit-logger'),
+  
+  // Template system
+  TemplateLoader: require('./template-loader'),
+  
+  // Validation
+  OperationsValidator: require('./operations-validator'),
+  
+  // Data models
+  models: require('./models')
+};

package/lib/operations/models/index.js

@@ -0,0 +1,170 @@
+/**
+ * Data Models for Operations Module
+ * 
+ * Defines core data structures and enums
+ */
+
+/**
+ * Takeover Level Enum
+ * Defines the degree of AI autonomy in executing operations
+ */
+const TakeoverLevel = {
+  L1_OBSERVATION: 'L1_OBSERVATION',
+  L2_SUGGESTION: 'L2_SUGGESTION',
+  L3_SEMI_AUTO: 'L3_SEMI_AUTO',
+  L4_AUTO: 'L4_AUTO',
+  L5_FULLY_AUTONOMOUS: 'L5_FULLY_AUTONOMOUS'
+};
+
+/**
+ * Security Environment Enum
+ * Deployment environment classification
+ */
+const SecurityEnvironment = {
+  DEVELOPMENT: 'development',
+  TEST: 'test',
+  PRE_PRODUCTION: 'pre-production',
+  PRODUCTION: 'production'
+};
+
+/**
+ * Feedback Channel Enum
+ * Methods by which user feedback enters the system
+ */
+const FeedbackChannel = {
+  SUPPORT_TICKET: 'support_ticket',
+  MONITORING_ALERT: 'monitoring_alert',
+  USER_REPORT: 'user_report',
+  API_ENDPOINT: 'api_endpoint',
+  CUSTOMER_SURVEY: 'customer_survey'
+};
+
+/**
+ * Feedback Type Enum
+ * Classification of feedback content
+ */
+const FeedbackType = {
+  BUG_REPORT: 'bug_report',
+  PERFORMANCE_ISSUE: 'performance_issue',
+  FEATURE_REQUEST: 'feature_request',
+  OPERATIONAL_CONCERN: 'operational_concern'
+};
+
+/**
+ * Feedback Severity Enum
+ * Priority level of feedback
+ */
+const FeedbackSeverity = {
+  CRITICAL: 'critical',    // System down
+  HIGH: 'high',            // Degraded performance
+  MEDIUM: 'medium',        // Usability issue
+  LOW: 'low'               // Enhancement
+};
+
+/**
+ * Feedback Status Enum
+ * Resolution lifecycle states
+ */
+const FeedbackStatus = {
+  ACKNOWLEDGED: 'acknowledged',
+  INVESTIGATING: 'investigating',
+  RESOLVED: 'resolved',
+  VERIFIED: 'verified'
+};
+
+/**
+ * Operation Type Enum
+ * Types of operations that can be performed
+ */
+const OperationType = {
+  DEPLOYMENT: 'deployment',
+  CONFIGURATION_CHANGE: 'configuration_change',
+  DATA_MIGRATION: 'data_migration',
+  ROLLBACK: 'rollback',
+  MONITORING_UPDATE: 'monitoring_update',
+  TROUBLESHOOTING: 'troubleshooting',
+  FEEDBACK_RESPONSE: 'feedback_response',
+  PERMISSION_CHANGE: 'permission_change'
+};
+
+/**
+ * Document Type Enum
+ * Types of operations spec documents
+ */
+const DocumentType = {
+  DEPLOYMENT: 'deployment',
+  MONITORING: 'monitoring',
+  OPERATIONS: 'operations',
+  TROUBLESHOOTING: 'troubleshooting',
+  ROLLBACK: 'rollback',
+  CHANGE_IMPACT: 'change-impact',
+  MIGRATION_PLAN: 'migration-plan',
+  FEEDBACK_RESPONSE: 'feedback-response',
+  TOOLS: 'tools'  // AI-driven tools configuration
+};
+
+module.exports = {
+  TakeoverLevel,
+  SecurityEnvironment,
+  FeedbackChannel,
+  FeedbackType,
+  FeedbackSeverity,
+  FeedbackStatus,
+  OperationType,
+  DocumentType
+};
+
+/**
+ * @typedef {Object} IssuePattern
+ * @property {string} pattern - Description of the issue pattern
+ * @property {number} occurrences - Number of times this pattern occurred
+ * @property {FeedbackType} type - Type of feedback
+ * @property {FeedbackSeverity} severity - Severity level
+ * @property {string[]} affectedVersions - Versions where this pattern appears
+ * @property {string} firstSeen - ISO timestamp of first occurrence
+ * @property {string} lastSeen - ISO timestamp of last occurrence
+ */
+
+/**
+ * @typedef {Object} ResolutionTimeStats
+ * @property {number} average - Average resolution time in hours
+ * @property {number} median - Median resolution time in hours
+ * @property {number} min - Minimum resolution time in hours
+ * @property {number} max - Maximum resolution time in hours
+ * @property {Object.<FeedbackSeverity, number>} bySeverity - Average resolution time by severity
+ * @property {Object.<FeedbackType, number>} byType - Average resolution time by type
+ */
+
+/**
+ * @typedef {Object} SatisfactionTrend
+ * @property {string} period - Time period (e.g., "2026-01", "2026-W04")
+ * @property {number} totalFeedback - Total feedback items in period
+ * @property {number} resolvedCount - Number of resolved items
+ * @property {number} resolutionRate - Percentage of resolved items
+ * @property {number} averageResolutionTime - Average time to resolve in hours
+ * @property {Object.<FeedbackSeverity, number>} severityDistribution - Count by severity
+ */
+
+/**
+ * @typedef {Object} VersionIssue
+ * @property {string} version - Project version
+ * @property {number} feedbackCount - Total feedback for this version
+ * @property {IssuePattern[]} topIssues - Most common issues in this version
+ * @property {number} criticalCount - Number of critical issues
+ * @property {number} averageResolutionTime - Average resolution time in hours
+ */
+
+/**
+ * @typedef {Object} FeedbackAnalytics
+ * @property {string} project - Project name
+ * @property {string} generatedAt - ISO timestamp of analytics generation
+ * @property {Object} timeRange - Time range for analytics
+ * @property {string} timeRange.from - Start date (ISO)
+ * @property {string} timeRange.to - End date (ISO)
+ * @property {IssuePattern[]} commonIssues - Most common issue patterns
+ * @property {ResolutionTimeStats} resolutionTimes - Resolution time statistics
+ * @property {SatisfactionTrend[]} satisfactionTrends - Satisfaction trends over time
+ * @property {VersionIssue[]} versionSpecificIssues - Issues by version
+ * @property {number} totalFeedback - Total feedback items analyzed
+ * @property {Object.<FeedbackStatus, number>} statusDistribution - Count by status
+ */

package/lib/operations/operations-manager.js

@@ -0,0 +1,151 @@
+/**
+ * Operations Manager
+ * 
+ * Manages operations specs lifecycle
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const TemplateLoader = require('./template-loader');
+const OperationsValidator = require('./operations-validator');
+const { DocumentType } = require('./models');
+
+class OperationsManager {
+  constructor(projectRoot = process.cwd()) {
+    this.projectRoot = projectRoot;
+    this.templateLoader = new TemplateLoader();
+    this.validator = new OperationsValidator();
+  }
+  
+  /**
+   * Create operations spec from template
+   * 
+   * @param {string} projectName - Project name
+   * @param {string} version - Project version
+   * @param {string} templateName - Template to use (default: 'default')
+   * @returns {Promise<string>} Path to created operations directory
+   */
+  async createOperationsSpec(projectName, version = '1.0.0', templateName = 'default') {
+    const operationsPath = path.join(
+      this.projectRoot,
+      '.kiro/specs',
+      projectName,
+      'operations'
+    );
+    
+    // Create operations directory
+    await fs.ensureDir(operationsPath);
+    
+    // Load all templates
+    const templates = await this.templateLoader.loadAllTemplates(templateName);
+    
+    // Write each template to file
+    const documentTypes = Object.values(DocumentType);
+    
+    for (const docType of documentTypes) {
+      const template = templates[docType];
+      if (template) {
+        const fileName = docType === DocumentType.TOOLS ? 'tools.yaml' : `${docType}.md`;
+        const filePath = path.join(operationsPath, fileName);
+        await fs.writeFile(filePath, template, 'utf8');
+      }
+    }
+    
+    // Create version metadata file
+    const metadata = {
+      project: projectName,
+      version: version,
+      created: new Date().toISOString(),
+      template: templateName
+    };
+    
+    await fs.writeFile(
+      path.join(operationsPath, '.metadata.json'),
+      JSON.stringify(metadata, null, 2),
+      'utf8'
+    );
+    
+    return operationsPath;
+  }
+  
+  /**
+   * Load operations spec
+   * 
+   * @param {string} projectName - Project name
+   * @returns {Promise<Object>} Operations spec object
+   */
+  async loadOperationsSpec(projectName) {
+    const operationsPath = path.join(
+      this.projectRoot,
+      '.kiro/specs',
+      projectName,
+      'operations'
+    );
+    
+    // Check if operations directory exists
+    const exists = await fs.pathExists(operationsPath);
+    if (!exists) {
+      throw new Error(`Operations spec not found for project: ${projectName}`);
+    }
+    
+    // Load metadata
+    const metadataPath = path.join(operationsPath, '.metadata.json');
+    let metadata = {};
+    if (await fs.pathExists(metadataPath)) {
+      try {
+        metadata = await fs.readJson(metadataPath);
+      } catch (error) {
+        // If metadata is corrupted, use empty object
+        console.warn(`Warning: Could not parse metadata file: ${error.message}`);
+        metadata = {};
+      }
+    }
+    
+    return {
+      project: projectName,
+      path: operationsPath,
+      metadata
+    };
+  }
+  
+  /**
+   * Validate operations spec
+   * 
+   * @param {string} projectName - Project name
+   * @returns {Promise<Object>} Validation result
+   */
+  async validateOperationsSpec(projectName) {
+    const spec = await this.loadOperationsSpec(projectName);
+    return await this.validator.validateComplete(spec.path);
+  }
+  
+  /**
+   * List all operations specs
+   * 
+   * @returns {Promise<string[]>} Array of project names with operations specs
+   */
+  async listOperationsSpecs() {
+    const specsPath = path.join(this.projectRoot, '.kiro/specs');
+    
+    const exists = await fs.pathExists(specsPath);
+    if (!exists) {
+      return [];
+    }
+    
+    const entries = await fs.readdir(specsPath, { withFileTypes: true });
+    const projects = [];
+    
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const operationsPath = path.join(specsPath, entry.name, 'operations');
+        if (await fs.pathExists(operationsPath)) {
+          projects.push(entry.name);
+        }
+      }
+    }
+    
+    return projects;
+  }
+}
+
+module.exports = OperationsManager;

package/lib/operations/operations-validator.js

@@ -0,0 +1,280 @@
+/**
+ * Operations Spec Validator
+ * 
+ * Validates operations spec completeness and structure
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const { DocumentType } = require('./models');
+
+// Required sections for each document type
+const REQUIRED_SECTIONS = {
+  [DocumentType.DEPLOYMENT]: [
+    'Prerequisites',
+    'Deployment Steps',
+    'Environment Variables',
+    'Health Checks',
+    'Rollback Procedure'
+  ],
+  [DocumentType.MONITORING]: [
+    'Metrics',
+    'Thresholds',
+    'Alert Rules',
+    'Response Procedures'
+  ],
+  [DocumentType.OPERATIONS]: [
+    'Daily Tasks',
+    'Maintenance Procedures',
+    'Backup Procedures'
+  ],
+  [DocumentType.TROUBLESHOOTING]: [
+    'Common Issues',
+    'Diagnostic Commands',
+    'Resolution Steps'
+  ],
+  [DocumentType.ROLLBACK]: [
+    'Rollback Triggers',
+    'Rollback Steps',
+    'Data Recovery Procedures'
+  ],
+  [DocumentType.CHANGE_IMPACT]: [
+    'Change Classification',
+    'Affected Systems',
+    'Risk Assessment'
+  ],
+  [DocumentType.MIGRATION_PLAN]: [
+    'Migration Strategy',
+    'Data Mapping',
+    'Validation Steps',
+    'Rollback Plan'
+  ],
+  [DocumentType.FEEDBACK_RESPONSE]: [
+    'Feedback Classification Rules',
+    'Response Procedures',
+    'Escalation Paths',
+    'Resolution Tracking'
+  ]
+};
+
+class OperationsValidator {
+  /**
+   * Validate operations spec directory structure
+   * 
+   * @param {string} operationsPath - Path to operations directory
+   * @returns {Promise<Object>} Validation result
+   */
+  async validateStructure(operationsPath) {
+    const errors = [];
+    const warnings = [];
+    const missingDocuments = [];
+    const presentDocuments = [];
+    
+    // Check if operations directory exists
+    const exists = await fs.pathExists(operationsPath);
+    if (!exists) {
+      errors.push({
+        type: 'missing_directory',
+        message: `Operations directory not found: ${operationsPath}`
+      });
+      
+      return {
+        valid: false,
+        errors,
+        warnings,
+        missingDocuments: Object.values(DocumentType),
+        presentDocuments: []
+      };
+    }
+    
+    // Check for all required documents
+    const documentTypes = Object.values(DocumentType);
+    
+    for (const docType of documentTypes) {
+      // tools.yaml is a YAML file, others are markdown
+      const fileName = docType === DocumentType.TOOLS ? `${docType}.yaml` : `${docType}.md`;
+      const docPath = path.join(operationsPath, fileName);
+      const docExists = await fs.pathExists(docPath);
+      
+      if (docExists) {
+        presentDocuments.push(docType);
+      } else {
+        missingDocuments.push(docType);
+        errors.push({
+          type: 'missing_document',
+          documentType: docType,
+          message: `Required document missing: ${fileName}`
+        });
+      }
+    }
+    
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+      missingDocuments,
+      presentDocuments,
+      totalRequired: documentTypes.length,
+      totalPresent: presentDocuments.length
+    };
+  }
+  
+  /**
+   * Validate document content (sections)
+   * 
+   * @param {string} documentPath - Path to document file
+   * @param {string} documentType - Type of document
+   * @returns {Promise<Object>} Validation result
+   */
+  async validateDocumentContent(documentPath, documentType) {
+    const errors = [];
+    const warnings = [];
+    
+    // Check if document exists
+    const exists = await fs.pathExists(documentPath);
+    if (!exists) {
+      errors.push({
+        type: 'file_not_found',
+        message: `Document not found: ${documentPath}`
+      });
+      
+      return {
+        valid: false,
+        errors,
+        warnings,
+        missingSections: REQUIRED_SECTIONS[documentType] || [],
+        presentSections: []
+      };
+    }
+    
+    // Read document content
+    const content = await fs.readFile(documentPath, 'utf8');
+    
+    // Get required sections for this document type
+    const requiredSections = REQUIRED_SECTIONS[documentType];
+    if (!requiredSections) {
+      warnings.push({
+        type: 'unknown_document_type',
+        message: `No validation rules for document type: ${documentType}`
+      });
+      
+      return {
+        valid: true,
+        errors,
+        warnings,
+        missingSections: [],
+        presentSections: []
+      };
+    }
+    
+    // Parse sections from markdown
+    const sections = this.parseSections(content);
+    const missingSections = [];
+    const presentSections = [];
+    
+    // Check for required sections
+    for (const requiredSection of requiredSections) {
+      const found = sections.some(section => 
+        section.toLowerCase().includes(requiredSection.toLowerCase())
+      );
+      
+      if (found) {
+        presentSections.push(requiredSection);
+      } else {
+        missingSections.push(requiredSection);
+        errors.push({
+          type: 'missing_section',
+          section: requiredSection,
+          message: `Required section missing: ${requiredSection}`
+        });
+      }
+    }
+    
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+      missingSections,
+      presentSections,
+      totalRequired: requiredSections.length,
+      totalPresent: presentSections.length
+    };
+  }
+  
+  /**
+   * Validate complete operations spec
+   * 
+   * @param {string} operationsPath - Path to operations directory
+   * @returns {Promise<Object>} Complete validation result
+   */
+  async validateComplete(operationsPath) {
+    // First validate structure
+    const structureResult = await this.validateStructure(operationsPath);
+    
+    if (!structureResult.valid) {
+      return {
+        valid: false,
+        structureValid: false,
+        contentValid: false,
+        structure: structureResult,
+        content: {}
+      };
+    }
+    
+    // Then validate content of each document
+    const contentResults = {};
+    let allContentValid = true;
+    
+    for (const docType of structureResult.presentDocuments) {
+      const docPath = path.join(operationsPath, `${docType}.md`);
+      const contentResult = await this.validateDocumentContent(docPath, docType);
+      
+      contentResults[docType] = contentResult;
+      
+      if (!contentResult.valid) {
+        allContentValid = false;
+      }
+    }
+    
+    return {
+      valid: structureResult.valid && allContentValid,
+      structureValid: structureResult.valid,
+      contentValid: allContentValid,
+      structure: structureResult,
+      content: contentResults
+    };
+  }
+  
+  /**
+   * Parse markdown sections (## headers)
+   * 
+   * @param {string} content - Markdown content
+   * @returns {string[]} Array of section titles
+   */
+  parseSections(content) {
+    const sections = [];
+    const lines = content.split('\n');
+    
+    for (const line of lines) {
+      // Match ## Section Title
+      const match = line.match(/^##\s+(.+)$/);
+      if (match) {
+        sections.push(match[1].trim());
+      }
+    }
+    
+    return sections;
+  }
+  
+  /**
+   * Get required sections for a document type
+   * 
+   * @param {string} documentType - Type of document
+   * @returns {string[]} Array of required section names
+   */
+  getRequiredSections(documentType) {
+    return REQUIRED_SECTIONS[documentType] || [];
+  }
+}
+
+module.exports = OperationsValidator;