aios-core 2.1.0

package/.aios-core/quality/seed-metrics.js

@@ -0,0 +1,336 @@
+/**
+ * Quality Metrics Seed Data Generator
+ *
+ * Generates realistic seed data for testing the metrics dashboard.
+ * Creates 30 days of historical data with realistic patterns.
+ *
+ * @module quality/seed-metrics
+ * @version 1.0.0
+ * @story 3.11a - Quality Gates Metrics Collector
+ */
+
+const { MetricsCollector, createEmptyMetrics } = require('./metrics-collector');
+
+/**
+ * Generate a random integer between min and max (inclusive)
+ * @param {number} min - Minimum value
+ * @param {number} max - Maximum value
+ * @returns {number} Random integer
+ */
+function randomInt(min, max) {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+/**
+ * Generate a random boolean with given probability of true
+ * @param {number} probability - Probability of true (0-1)
+ * @returns {boolean} Random boolean
+ */
+function randomBool(probability = 0.5) {
+  return Math.random() < probability;
+}
+
+/**
+ * Generate realistic Layer 1 (pre-commit) run
+ * @param {Date} timestamp - Run timestamp
+ * @returns {Object} Run data
+ */
+function generateLayer1Run(timestamp) {
+  // Layer 1 has high pass rate (90-95%)
+  const passed = randomBool(0.92);
+
+  // Duration varies: passed runs are faster
+  const baseDuration = passed ? randomInt(2000, 5000) : randomInt(4000, 8000);
+
+  // Findings: 0-2 for passed, 1-5 for failed
+  const findingsCount = passed ? randomInt(0, 2) : randomInt(1, 5);
+
+  return {
+    timestamp: timestamp.toISOString(),
+    layer: 1,
+    passed,
+    durationMs: baseDuration,
+    findingsCount,
+    metadata: {
+      triggeredBy: randomBool(0.8) ? 'hook' : 'cli',
+    },
+  };
+}
+
+/**
+ * Generate realistic Layer 2 (PR automation) run
+ * @param {Date} timestamp - Run timestamp
+ * @returns {Object} Run data
+ */
+function generateLayer2Run(timestamp) {
+  // Layer 2 has moderate pass rate (85-90%)
+  const passed = randomBool(0.87);
+
+  // PR reviews take longer
+  const baseDuration = randomInt(120000, 600000); // 2-10 minutes
+
+  // CodeRabbit findings distribution
+  const crActive = randomBool(0.95); // CodeRabbit active 95% of time
+  const crCritical = passed ? 0 : randomInt(0, 2);
+  const crHigh = passed ? randomInt(0, 1) : randomInt(1, 4);
+  const crMedium = randomInt(0, 5);
+  const crLow = randomInt(1, 8);
+  const crTotal = crCritical + crHigh + crMedium + crLow;
+
+  // Quinn findings
+  const quinnFindings = randomInt(0, 6);
+  const categories = [
+    'test-coverage',
+    'documentation',
+    'error-handling',
+    'performance',
+    'security',
+    'code-style',
+    'maintainability',
+  ];
+  const topCategories = categories
+    .sort(() => Math.random() - 0.5)
+    .slice(0, randomInt(1, 3));
+
+  return {
+    timestamp: timestamp.toISOString(),
+    layer: 2,
+    passed,
+    durationMs: baseDuration,
+    findingsCount: crTotal + quinnFindings,
+    metadata: {
+      triggeredBy: 'pr',
+      coderabbit: crActive ? {
+        findingsCount: crTotal,
+        severityBreakdown: {
+          critical: crCritical,
+          high: crHigh,
+          medium: crMedium,
+          low: crLow,
+        },
+      } : null,
+      quinn: {
+        findingsCount: quinnFindings,
+        topCategories,
+      },
+    },
+  };
+}
+
+/**
+ * Generate realistic Layer 3 (human review) run
+ * @param {Date} timestamp - Run timestamp
+ * @returns {Object} Run data
+ */
+function generateLayer3Run(timestamp) {
+  // Layer 3 has highest pass rate (95-98%)
+  const passed = randomBool(0.96);
+
+  // Human reviews vary widely in time
+  const baseDuration = randomInt(300000, 1800000); // 5-30 minutes
+
+  // Findings are usually minimal at this stage
+  const findingsCount = passed ? randomInt(0, 1) : randomInt(1, 3);
+
+  return {
+    timestamp: timestamp.toISOString(),
+    layer: 3,
+    passed,
+    durationMs: baseDuration,
+    findingsCount,
+    metadata: {
+      triggeredBy: 'manual',
+      reviewer: randomBool(0.7) ? 'human' : 'team-lead',
+    },
+  };
+}
+
+/**
+ * Generate seed data for a specified number of days
+ * @param {Object} options - Generation options
+ * @param {number} [options.days=30] - Number of days of history
+ * @param {number} [options.runsPerDay=8] - Average runs per day
+ * @param {boolean} [options.weekendReduction=true] - Reduce weekend activity
+ * @returns {Object} Generated metrics data
+ */
+function generateSeedData(options = {}) {
+  const days = options.days || 30;
+  const runsPerDay = options.runsPerDay || 8;
+  const weekendReduction = options.weekendReduction !== false;
+
+  const metrics = createEmptyMetrics();
+  const history = [];
+
+  const now = new Date();
+
+  // Generate history for each day
+  for (let d = days; d >= 0; d--) {
+    const dayDate = new Date(now);
+    dayDate.setDate(dayDate.getDate() - d);
+    dayDate.setHours(9, 0, 0, 0); // Start at 9 AM
+
+    const dayOfWeek = dayDate.getDay();
+    const isWeekend = dayOfWeek === 0 || dayOfWeek === 6;
+
+    // Reduce runs on weekends
+    const dayRuns = isWeekend && weekendReduction
+      ? Math.floor(runsPerDay * 0.3)
+      : runsPerDay + randomInt(-2, 2);
+
+    for (let r = 0; r < Math.max(1, dayRuns); r++) {
+      // Spread runs throughout the workday (9 AM - 6 PM)
+      const runTime = new Date(dayDate);
+      runTime.setHours(9 + randomInt(0, 9), randomInt(0, 59), randomInt(0, 59));
+
+      // Layer distribution: Layer 1 most common, Layer 3 least common
+      const layerRoll = Math.random();
+      let layer;
+      if (layerRoll < 0.6) {
+        layer = 1;
+      } else if (layerRoll < 0.9) {
+        layer = 2;
+      } else {
+        layer = 3;
+      }
+
+      let run;
+      switch (layer) {
+        case 1:
+          run = generateLayer1Run(runTime);
+          break;
+        case 2:
+          run = generateLayer2Run(runTime);
+          break;
+        case 3:
+          run = generateLayer3Run(runTime);
+          break;
+      }
+
+      history.push(run);
+    }
+  }
+
+  // Sort history by timestamp
+  history.sort((a, b) => new Date(a.timestamp) - new Date(b.timestamp));
+  metrics.history = history;
+
+  // Calculate layer aggregates
+  for (let layer = 1; layer <= 3; layer++) {
+    const layerKey = `layer${layer}`;
+    const layerRuns = history.filter((r) => r.layer === layer);
+
+    if (layerRuns.length > 0) {
+      const passedRuns = layerRuns.filter((r) => r.passed).length;
+      const totalDuration = layerRuns.reduce((sum, r) => sum + r.durationMs, 0);
+
+      metrics.layers[layerKey].passRate = passedRuns / layerRuns.length;
+      metrics.layers[layerKey].avgTimeMs = Math.round(totalDuration / layerRuns.length);
+      metrics.layers[layerKey].totalRuns = layerRuns.length;
+      metrics.layers[layerKey].lastRun = layerRuns[layerRuns.length - 1].timestamp;
+    }
+  }
+
+  // Calculate Layer 2 specific metrics
+  const layer2Runs = history.filter((r) => r.layer === 2);
+  if (layer2Runs.length > 0) {
+    let totalCrFindings = 0;
+    let crCritical = 0, crHigh = 0, crMedium = 0, crLow = 0;
+    let quinnFindings = 0;
+    const allCategories = [];
+
+    layer2Runs.forEach((r) => {
+      if (r.metadata?.coderabbit) {
+        const cr = r.metadata.coderabbit;
+        totalCrFindings += cr.findingsCount || 0;
+        crCritical += cr.severityBreakdown?.critical || 0;
+        crHigh += cr.severityBreakdown?.high || 0;
+        crMedium += cr.severityBreakdown?.medium || 0;
+        crLow += cr.severityBreakdown?.low || 0;
+      }
+      if (r.metadata?.quinn) {
+        quinnFindings += r.metadata.quinn.findingsCount || 0;
+        allCategories.push(...(r.metadata.quinn.topCategories || []));
+      }
+    });
+
+    // Top categories by frequency
+    const categoryCount = {};
+    allCategories.forEach((cat) => {
+      categoryCount[cat] = (categoryCount[cat] || 0) + 1;
+    });
+    const topCategories = Object.entries(categoryCount)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 5)
+      .map(([cat]) => cat);
+
+    metrics.layers.layer2.autoCatchRate = totalCrFindings / layer2Runs.length;
+    metrics.layers.layer2.coderabbit = {
+      active: true,
+      findingsCount: totalCrFindings,
+      severityBreakdown: {
+        critical: crCritical,
+        high: crHigh,
+        medium: crMedium,
+        low: crLow,
+      },
+    };
+    metrics.layers.layer2.quinn = {
+      findingsCount: quinnFindings,
+      topCategories,
+    };
+  }
+
+  // Generate trend data
+  const trendDays = Math.min(days, 30);
+  for (let d = trendDays; d >= 0; d--) {
+    const trendDate = new Date(now);
+    trendDate.setDate(trendDate.getDate() - d);
+    const dateStr = trendDate.toISOString().split('T')[0];
+
+    // Daily pass rate
+    const dayRuns = history.filter((r) =>
+      r.timestamp.startsWith(dateStr),
+    );
+    if (dayRuns.length > 0) {
+      const passedToday = dayRuns.filter((r) => r.passed).length;
+      metrics.trends.passRates.push({
+        date: dateStr,
+        value: passedToday / dayRuns.length,
+      });
+    }
+
+    // Daily auto-catch rate (Layer 2)
+    const layer2DayRuns = dayRuns.filter((r) => r.layer === 2);
+    if (layer2DayRuns.length > 0) {
+      const findings = layer2DayRuns.reduce((sum, r) => sum + (r.findingsCount || 0), 0);
+      metrics.trends.autoCatchRate.push({
+        date: dateStr,
+        value: findings / layer2DayRuns.length,
+      });
+    }
+  }
+
+  metrics.lastUpdated = new Date().toISOString();
+
+  return metrics;
+}
+
+/**
+ * Seed the metrics file with generated data
+ * @param {Object} options - Seed options
+ * @returns {Promise<Object>} Generated metrics
+ */
+async function seedMetrics(options = {}) {
+  const collector = new MetricsCollector(options);
+  const metrics = generateSeedData(options);
+  await collector.save(metrics);
+  return metrics;
+}
+
+module.exports = {
+  generateSeedData,
+  seedMetrics,
+  generateLayer1Run,
+  generateLayer2Run,
+  generateLayer3Run,
+};

package/.aios-core/scripts/README.md

@@ -0,0 +1,354 @@
+# AIOS Utils - Utility Scripts Library
+
+This directory contains 68+ utility scripts that provide automation, validation, and helper functions for AIOS-FULLSTACK agents and workflows.
+
+## Categories
+
+### 🔍 **Core Validation & Analysis**
+Scripts for validating AIOS structures and analyzing code quality.
+
+- **aios-validator.js** - Validates AIOS structures (agents, tasks, workflows, stories)
+- **capability-analyzer.js** - Analyzes agent capabilities and requirements
+- **compatibility-checker.js** - Checks compatibility between components
+- **coverage-analyzer.js** - Analyzes test coverage metrics
+- **dependency-analyzer.js** - Analyzes dependencies and their impacts
+- **dependency-impact-analyzer.js** - Predicts impact of dependency changes
+
+### 📋 **Story & Task Management**
+Tools for managing development stories, tasks, and workflows.
+
+- **story-manager.js** - Complete story lifecycle management
+  - Create, update, delete stories
+  - Track progress and status
+  - Manage checkboxes and file lists
+  - Integration with ClickUp
+
+- **batch-creator.js** - Batch creation of stories/tasks
+- **task-router.js** - Routes tasks to appropriate agents
+- **workflow-orchestrator.js** - Orchestrates multi-step workflows
+
+### 🔧 **Tool & Integration Management**
+Scripts for managing tools, MCPs, and external integrations.
+
+- **tool-resolver.js** - Discovers and validates available tools
+  - CLI tools detection
+  - MCP server validation
+  - Capability matching
+  - Environment verification
+
+- **clickup-helpers.js** - ClickUp API utility functions
+  - Task operations
+  - Sprint management
+  - Custom fields handling
+  - Webhook utilities
+
+### 🧩 **Component Generation**
+Generators for creating various component types.
+
+- **component-generator.js** - Generates React/Vue/Angular components
+- **component-metadata.js** - Extracts component metadata
+- **component-preview.js** - Generates component previews
+- **component-search.js** - Searches for components in codebase
+- **test-generator.js** - Generates test suites
+- **migration-generator.js** - Generates database migrations
+- **schema-generator.js** - Generates schema definitions
+
+### 📝 **Documentation & Code Quality**
+Tools for maintaining documentation and code quality.
+
+- **documentation-synchronizer.js** - Syncs documentation with code
+- **code-quality-improver.js** - Suggests code quality improvements
+- **commit-message-generator.js** - Generates semantic commit messages
+- **changelog-generator.js** - Generates CHANGELOG entries
+- **diff-generator.js** - Generates structured diffs
+
+### 🔄 **Version Control & Git**
+Git workflow automation and version control helpers.
+
+- **branch-manager.js** - Manages Git branches
+- **conflict-manager.js** - Handles merge conflicts
+- **conflict-resolver.js** - Resolves common conflict patterns
+- **pr-validator.js** - Validates pull requests
+- **release-manager.js** - Manages releases and versioning
+
+### 💾 **Backup & Recovery**
+Data backup and recovery utilities.
+
+- **backup-manager.js** - Automated backups
+  - Story backups
+  - Configuration backups
+  - Code snapshots
+  - Rollback capabilities
+
+- **recovery-manager.js** - Recovery operations
+- **snapshot-manager.js** - Manages code snapshots
+
+### 🎯 **Workflow Automation**
+Scripts for automating development workflows.
+
+- **approval-workflow.js** - Handles approval workflows
+- **change-propagation-predictor.js** - Predicts change impacts
+- **elicitation-engine.js** - Interactive requirement gathering
+- **qa-automation.js** - Automated QA workflows
+- **test-orchestrator.js** - Orchestrates test execution
+
+### 🔌 **API & Integration**
+API helpers and integration utilities.
+
+- **api-client-generator.js** - Generates API clients
+- **webhook-manager.js** - Manages webhooks
+- **supabase-helpers.js** - Supabase utility functions
+- **railway-helpers.js** - Railway deployment helpers
+
+### 🧪 **Testing Utilities**
+Testing support and test data management.
+
+- **test-data-generator.js** - Generates test data
+- **mock-generator.js** - Generates mocks and stubs
+- **performance-profiler.js** - Profiles performance
+- **security-scanner.js** - Scans for security issues
+
+### 🗄️ **Data Management**
+Data transformation and management tools.
+
+- **yaml-parser.js** - YAML parsing with validation
+- **json-transformer.js** - JSON transformation utilities
+- **markdown-processor.js** - Markdown processing
+- **template-engine.js** - Template rendering engine
+
+### 🔐 **Security & Validation**
+Security scanning and input validation.
+
+- **secret-scanner.js** - Scans for exposed secrets
+- **input-validator.js** - Validates user inputs
+- **permission-checker.js** - Checks permissions
+- **rate-limiter.js** - Rate limiting utilities
+
+### 📊 **Monitoring & Logging**
+Logging, monitoring, and observability tools.
+
+- **logger.js** - Structured logging
+- **metrics-collector.js** - Collects metrics
+- **health-checker.js** - Health check utilities
+- **error-tracker.js** - Error tracking and reporting
+
+### 🎨 **UI & Presentation**
+UI generation and formatting utilities.
+
+- **markdown-renderer.js** - Renders Markdown to HTML
+- **syntax-highlighter.js** - Syntax highlighting
+- **diagram-generator.js** - Generates diagrams
+- **report-formatter.js** - Formats reports
+
+## Usage Examples
+
+### Story Management
+
+```javascript
+const { StoryManager } = require('./story-manager');
+
+// Create new story
+const story = await StoryManager.create({
+  title: 'Implement user authentication',
+  epic: 'User Management',
+  assignee: '@dev'
+});
+
+// Update story progress
+await story.updateTask(taskId, { status: 'completed' });
+
+// Get story status
+const status = await story.getStatus();
+```
+
+### Tool Discovery
+
+```javascript
+const { resolveTools } = require('./tool-resolver');
+
+// Get all available tools
+const tools = await resolveTools();
+
+// Get specific tool category
+const mcpServers = await resolveTools({
+  category: 'mcp',
+  required: true
+});
+
+// Check tool availability
+const isAvailable = await resolveTools.checkTool('gh');
+```
+
+### Component Generation
+
+```javascript
+const { generateComponent } = require('./component-generator');
+
+// Generate React component
+await generateComponent({
+  name: 'UserProfile',
+  type: 'react',
+  props: ['user', 'onEdit'],
+  features: ['typescript', 'tests']
+});
+```
+
+### Validation
+
+```javascript
+const { validate } = require('./aios-validator');
+
+// Validate agent definition
+const result = await validate.agent('path/to/agent.yaml');
+
+// Validate story structure
+const storyValid = await validate.story('docs/stories/1.1-feature.md');
+
+// Validate workflow
+const workflowValid = await validate.workflow('workflows/deploy.yaml');
+```
+
+## Best Practices
+
+### 1. Error Handling
+
+All utilities use consistent error handling:
+
+```javascript
+try {
+  const result = await utility.operation();
+  return result;
+} catch (error) {
+  if (error.code === 'VALIDATION_ERROR') {
+    // Handle validation errors
+  }
+  throw error;
+}
+```
+
+### 2. Configuration
+
+Utilities read configuration from `core-config.yaml`:
+
+```javascript
+const config = require('../core-config.yaml');
+const utilsLocation = config.utilsLocation;
+```
+
+### 3. Logging
+
+Use the built-in logger for consistent output:
+
+```javascript
+const logger = require('./logger');
+
+logger.info('Operation started', { context });
+logger.error('Operation failed', { error });
+```
+
+### 4. Testing
+
+Each utility should have corresponding tests:
+
+```javascript
+// Example: aios-validator.test.js
+describe('aios-validator', () => {
+  it('validates agent structure', async () => {
+    const result = await validate.agent(validAgent);
+    expect(result.valid).toBe(true);
+  });
+});
+```
+
+## Adding New Utilities
+
+### Structure
+
+```javascript
+/**
+ * @file utility-name.js
+ * @description Brief description of what this utility does
+ */
+
+const config = require('../core-config.yaml');
+const logger = require('./logger');
+
+class UtilityName {
+  constructor(options = {}) {
+    this.options = options;
+  }
+
+  async mainOperation(params) {
+    try {
+      // Implementation
+      logger.info('Operation successful');
+      return result;
+    } catch (error) {
+      logger.error('Operation failed', { error });
+      throw error;
+    }
+  }
+}
+
+module.exports = UtilityName;
+```
+
+### Documentation
+
+1. Add JSDoc comments
+2. Include usage examples
+3. Document all parameters
+4. List error codes
+5. Update this README
+
+### Testing
+
+1. Create corresponding `.test.js` file
+2. Test happy path
+3. Test error cases
+4. Test edge cases
+5. Run: `npm test utils/utility-name.test.js`
+
+## Troubleshooting
+
+### Utility Not Found
+
+```bash
+# Verify utility exists
+ls -la .aios-core/scripts/utility-name.js
+
+# Check require path
+node -e "require('./.aios-core/scripts/utility-name')"
+```
+
+### Permission Errors
+
+```bash
+# Check file permissions
+chmod +x .aios-core/scripts/*.js
+
+# Check directory permissions
+ls -ld .aios-core/scripts/
+```
+
+### Configuration Issues
+
+```bash
+# Validate core-config.yaml
+node .aios-core/scripts/aios-validator.js --config
+
+# Check utilsLocation setting
+grep utilsLocation .aios-core/core-config.yaml
+```
+
+## Related Documentation
+
+- [Tools Directory](../tools/README.md)
+- [Agent Development Guide](../../docs/agent-guide.md)
+- [Core Configuration](../core-config.yaml)
+- [Testing Guide](../../docs/testing-guide.md)
+
+---
+
+*Last updated: 2025-10-22 - Documentation Sync Initiative*
+*Total utilities: 68 scripts*