aios-core 2.1.0

package/.aios-core/infrastructure/scripts/test-utilities-fast.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+
+/**
+ * Fast Framework Utilities Audit Script
+ *
+ * Quick scan version that skips slow integration counting during initial pass
+ * Usage: node test-utilities-fast.js
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const utilsDir = path.join(__dirname);
+let results = [];
+let utilities = [];
+
+/**
+ * Quick test - just try to require and see what happens
+ */
+function quickTest(utilityFile) {
+  const utilityPath = path.join(utilsDir, utilityFile);
+  const result = {
+    name: utilityFile,
+    status: 'UNKNOWN',
+    loadable: false,
+    exports: [],
+    errors: [],
+    recommendation: '',
+  };
+
+  try {
+    // Suppress console output during require
+    const originalLog = console.log;
+    const originalError = console.error;
+    console.log = () => {};
+    console.error = () => {};
+
+    delete require.cache[require.resolve(utilityPath)];
+    const utility = require(utilityPath);
+
+    // Restore console
+    console.log = originalLog;
+    console.error = originalError;
+
+    result.loadable = true;
+    result.exports = Object.keys(utility);
+
+    if (result.exports.length > 0) {
+      result.status = 'WORKING';
+      result.recommendation = 'Functional - verify integration';
+    } else {
+      result.status = 'FIXABLE';
+      result.recommendation = 'Loads but exports nothing';
+    }
+
+  } catch (error) {
+    // Restore console
+    console.log = console.log.bind(console);
+    console.error = console.error.bind(console);
+
+    result.errors.push(error.message);
+
+    if (error.code === 'MODULE_NOT_FOUND' || error.message.includes('Cannot find module')) {
+      result.status = 'FIXABLE';
+      result.recommendation = 'Missing dependencies - installable';
+    } else if (error.message.includes('SyntaxError')) {
+      result.status = 'DEPRECATED';
+      result.recommendation = 'Syntax errors - major rewrite needed';
+    } else {
+      result.status = 'DEPRECATED';
+      result.recommendation = 'Runtime errors - investigation needed';
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Run the fast audit
+ */
+function runFastAudit() {
+  console.log('🔍 Fast Framework Utilities Audit Starting...\n');
+
+  // Get all .js files except test utilities
+  utilities = fs.readdirSync(utilsDir)
+    .filter(f => f.endsWith('.js') && !f.includes('test-utilities'))
+    .sort();
+
+  results = [];
+  console.log(`Found ${utilities.length} utilities to audit\n`);
+
+  // Run quick audit
+  let processed = 0;
+  for (const utility of utilities) {
+    processed++;
+    process.stdout.write(`\r[${processed}/${utilities.length}] ${utility}`.padEnd(80));
+    results.push(quickTest(utility));
+  }
+
+  console.log('\n');
+
+  // Summary
+  const working = results.filter(r => r.status === 'WORKING');
+  const fixable = results.filter(r => r.status === 'FIXABLE');
+  const deprecated = results.filter(r => r.status === 'DEPRECATED');
+
+  console.log('\n📊 QUICK AUDIT SUMMARY\n');
+  console.log(`✅ WORKING:     ${working.length} (${Math.round(working.length / utilities.length * 100)}%)`);
+  console.log(`🔧 FIXABLE:     ${fixable.length} (${Math.round(fixable.length / utilities.length * 100)}%)`);
+  console.log(`🗑️  DEPRECATED:  ${deprecated.length} (${Math.round(deprecated.length / utilities.length * 100)}%)`);
+  console.log(`\n📦 Total: ${utilities.length}`);
+
+  // Save results
+  const outputPath = path.join(process.cwd(), 'utilities-audit-results.json');
+  fs.writeFileSync(outputPath, JSON.stringify(results, null, 2));
+  console.log(`\n💾 Results: ${outputPath}\n`);
+
+  return { results, working: working.length, fixable: fixable.length, deprecated: deprecated.length };
+}
+
+// Run audit if executed directly
+if (require.main === module) {
+  runFastAudit();
+}
+
+module.exports = { runFastAudit, quickTest };

package/.aios-core/infrastructure/scripts/test-utilities.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+
+/**
+ * Framework Utilities Audit Script
+ *
+ * Systematically tests all utilities in .aios-core/scripts/ and classifies them
+ * as WORKING, FIXABLE, or DEPRECATED based on their functional status.
+ *
+ * Usage: node .aios-core/scripts/test-utilities.js
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { exec } = require('child_process');
+const util = require('util');
+const execPromise = util.promisify(exec);
+
+const utilsDir = path.join(__dirname);
+let results = [];
+let utilities = [];
+
+/**
+ * Count integration references for a utility
+ */
+async function countIntegrationReferences(utilityName) {
+  const basename = path.basename(utilityName, '.js');
+  const searchDirs = [
+    '.aios-core/agents',
+    '.aios-core/tasks',
+    'expansion-packs',
+  ];
+
+  let totalCount = 0;
+
+  for (const dir of searchDirs) {
+    if (!fs.existsSync(dir)) continue;
+
+    try {
+      const { stdout } = await execPromise(
+        `grep -r "${basename}" ${dir} 2>/dev/null | wc -l`,
+        { shell: '/bin/bash' },
+      );
+      totalCount += parseInt(stdout.trim()) || 0;
+    } catch (_error) {
+      // Directory doesn't exist or grep failed - not a problem
+    }
+  }
+
+  return totalCount;
+}
+
+/**
+ * Test a single utility
+ */
+async function testUtility(utilityFile) {
+  const utilityPath = path.join(utilsDir, utilityFile);
+  const result = {
+    name: utilityFile,
+    status: 'UNKNOWN',
+    loadable: false,
+    exports: [],
+    testPassed: null,
+    errors: [],
+    integrationCount: 0,
+    recommendation: '',
+  };
+
+  try {
+    // Clear require cache to ensure fresh load
+    delete require.cache[require.resolve(utilityPath)];
+
+    // Test 1: Can it be required?
+    const utility = require(utilityPath);
+    result.loadable = true;
+
+    // Test 2: Does it export functions?
+    result.exports = Object.keys(utility);
+
+    // Test 3: Can we call its test function if it exists?
+    if (typeof utility.test === 'function') {
+      try {
+        await utility.test();
+        result.testPassed = true;
+      } catch (testError) {
+        result.testPassed = false;
+        result.errors.push(`Test function failed: ${testError.message}`);
+      }
+    }
+
+    // Test 4: Count integration references
+    result.integrationCount = await countIntegrationReferences(utilityFile);
+
+    // Classify based on results
+    if (result.errors.length === 0 && result.exports.length > 0) {
+      result.status = 'WORKING';
+      result.recommendation = result.integrationCount > 0
+        ? 'Keep - actively used'
+        : 'Keep but document usage';
+    }
+
+  } catch (_error) {
+    result.errors.push(error.message);
+
+    // Classify error type
+    if (error.code === 'MODULE_NOT_FOUND') {
+      result.status = 'FIXABLE';
+      result.recommendation = 'Install missing dependencies';
+    } else if (error.message.includes('SyntaxError')) {
+      result.status = 'DEPRECATED';
+      result.recommendation = 'Syntax errors - needs major rewrite';
+    } else if (error.message.includes('Cannot find module')) {
+      result.status = 'FIXABLE';
+      result.recommendation = 'Missing local dependencies - <4h fix';
+    } else {
+      result.status = 'DEPRECATED';
+      result.recommendation = 'Execution errors - needs investigation';
+    }
+
+    // Count integration even if broken
+    try {
+      result.integrationCount = await countIntegrationReferences(utilityFile);
+    } catch (_e) {
+      // Ignore counting errors
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Main audit execution
+ */
+async function runAudit() {
+  console.log('🔍 Framework Utilities Audit Starting...\n');
+  console.log(`📁 Scanning directory: ${utilsDir}\n`);
+
+  // Get all .js files except test-utilities.js itself
+  utilities = fs.readdirSync(utilsDir)
+    .filter(f => f.endsWith('.js') && f !== 'test-utilities.js')
+    .sort();
+
+  results = [];
+  console.log(`Found ${utilities.length} utilities to audit\n`);
+  console.log('=' .repeat(80));
+
+  let processed = 0;
+
+  for (const utility of utilities) {
+    processed++;
+    process.stdout.write(`\r[${processed}/${utilities.length}] Testing ${utility}...`.padEnd(80));
+
+    const result = await testUtility(utility);
+    results.push(result);
+  }
+
+  console.log('\n');
+  console.log('=' .repeat(80));
+
+  // Generate summary
+  const working = results.filter(r => r.status === 'WORKING');
+  const fixable = results.filter(r => r.status === 'FIXABLE');
+  const deprecated = results.filter(r => r.status === 'DEPRECATED');
+  const unknown = results.filter(r => r.status === 'UNKNOWN');
+
+  console.log('\n📊 AUDIT SUMMARY\n');
+  console.log(`✅ WORKING:     ${working.length} (${Math.round(working.length / utilities.length * 100)}%)`);
+  console.log(`🔧 FIXABLE:     ${fixable.length} (${Math.round(fixable.length / utilities.length * 100)}%)`);
+  console.log(`🗑️  DEPRECATED:  ${deprecated.length} (${Math.round(deprecated.length / utilities.length * 100)}%)`);
+  console.log(`❓ UNKNOWN:     ${unknown.length} (${Math.round(unknown.length / utilities.length * 100)}%)`);
+  console.log(`\n📦 Total Utilities: ${utilities.length}`);
+
+  // Save detailed results to JSON for report generation
+  const outputPath = path.join(process.cwd(), 'utilities-audit-results.json');
+  fs.writeFileSync(outputPath, JSON.stringify(results, null, 2));
+  console.log(`\n💾 Detailed results saved to: ${outputPath}`);
+
+  return {
+    total: utilities.length,
+    working: working.length,
+    fixable: fixable.length,
+    deprecated: deprecated.length,
+    unknown: unknown.length,
+    results,
+  };
+}
+
+// Run audit if executed directly
+if (require.main === module) {
+  runAudit()
+    .then(() => {
+      console.log('\n✅ Audit complete!\n');
+      process.exit(0);
+    })
+    .catch(error => {
+      console.error('\n❌ Audit failed:', error);
+      process.exit(1);
+    });
+}
+
+module.exports = { runAudit, testUtility, countIntegrationReferences };

package/.aios-core/infrastructure/scripts/tool-resolver.js

@@ -0,0 +1,360 @@
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+const glob = require('glob');
+
+/**
+ * ToolResolver - Resolves and loads AIOS tools from file system
+ *
+ * Features:
+ * - Map-based caching for performance (<5ms cached lookups)
+ * - Search path priority: expansion pack → common → core
+ * - Glob-based file resolution
+ * - Schema validation
+ * - Health checking (tool_call, command, http methods)
+ * - Schema version auto-detection
+ *
+ * Target Performance: <50ms for uncached resolution
+ */
+class ToolResolver {
+  constructor() {
+    // Map-based cache for fast lookups
+    this.cache = new Map();
+
+    // Base search paths (in priority order)
+    this.basePaths = [
+      'aios-core/tools',
+      'common/tools',
+      // Expansion pack paths added dynamically during resolution
+    ];
+  }
+
+  /**
+   * Resolve a tool by name
+   *
+   * @param {string} toolName - Tool identifier (e.g., 'clickup', 'github-cli')
+   * @param {object} context - Resolution context (optional)
+   * @param {string} context.expansionPack - Specific expansion pack to search
+   * @returns {object} Tool definition with schema_version detected
+   * @throws {Error} If tool not found or validation fails
+   */
+  async resolveTool(toolName, context = {}) {
+    // 1. Check cache first (performance: <5ms cached)
+    const cacheKey = `${context.expansionPack || 'core'}:${toolName}`;
+    if (this.cache.has(cacheKey)) {
+      return this.cache.get(cacheKey);
+    }
+
+    // 2. Build search paths (expansion pack → core priority)
+    const searchPaths = [];
+    if (context.expansionPack) {
+      searchPaths.push(`expansion-packs/${context.expansionPack}/tools`);
+    }
+    searchPaths.push(...this.basePaths);
+
+    // 3. Find tool file using glob (searches subdirectories)
+    let toolPath = null;
+    for (const basePath of searchPaths) {
+      const candidates = glob.sync(`${basePath}/**/${toolName}.yaml`);
+      if (candidates.length > 0) {
+        toolPath = candidates[0];
+        break;
+      }
+    }
+
+    if (!toolPath) {
+      throw new Error(`Tool '${toolName}' not found in search paths: ${searchPaths.join(', ')}`);
+    }
+
+    // 4. Load and parse YAML
+    const toolContent = await fs.readFile(toolPath, 'utf8');
+    let toolDef = yaml.load(toolContent);
+
+    // Extract tool object if wrapped (handles both formats)
+    if (toolDef.tool) {
+      toolDef = toolDef.tool;
+    }
+
+    // 5. Validate schema
+    await this.validateToolSchema(toolDef);
+
+    // 6. Detect schema version (auto-detection if not specified)
+    if (!toolDef.schema_version) {
+      toolDef.schema_version = this.detectSchemaVersion(toolDef);
+    }
+
+    // 7. Health check if configured
+    if (toolDef.health_check) {
+      const healthy = await this.checkHealth(toolDef);
+      if (!healthy && toolDef.health_check.required) {
+        throw new Error(`Required tool '${toolName}' health check failed`);
+      }
+      toolDef._healthStatus = healthy ? 'healthy' : 'unhealthy';
+    }
+
+    // 8. Cache and return (target: <50ms total)
+    this.cache.set(cacheKey, toolDef);
+    return toolDef;
+  }
+
+  /**
+   * Validate tool schema structure
+   *
+   * @param {object} tool - Tool definition
+   * @throws {Error} If required fields missing or invalid
+   */
+  async validateToolSchema(tool) {
+    // Required fields for all tools
+    const requiredFields = ['id', 'type', 'name', 'version', 'description'];
+
+    for (const field of requiredFields) {
+      if (!tool[field]) {
+        throw new Error(`Tool missing required field: ${field}`);
+      }
+    }
+
+    // Validate type enum
+    const validTypes = ['mcp', 'cli', 'local', 'meta'];
+    if (!validTypes.includes(tool.type)) {
+      throw new Error(`Invalid tool type '${tool.type}'. Must be one of: ${validTypes.join(', ')}`);
+    }
+
+    // Validate version format (basic semver check)
+    const semverPattern = /^\d+\.\d+\.\d+$/;
+    if (!semverPattern.test(tool.version)) {
+      throw new Error(`Invalid version format '${tool.version}'. Expected semantic versioning (e.g., 1.0.0)`);
+    }
+
+    // Validate schema_version if present (support both string and numeric formats)
+    if (tool.schema_version) {
+      const version = typeof tool.schema_version === 'number'
+        ? tool.schema_version
+        : parseFloat(tool.schema_version);
+
+      if (![1.0, 2.0].includes(version)) {
+        throw new Error(`Invalid schema_version '${tool.schema_version}'. Must be '1.0' or '2.0'`);
+      }
+    }
+
+    // v2.0 specific validation
+    if (tool.schema_version === '2.0' || tool.schema_version === 2.0) {
+      await this.validateV2Schema(tool);
+    }
+  }
+
+  /**
+   * Validate v2.0 schema-specific features
+   *
+   * @param {object} tool - Tool definition
+   * @throws {Error} If v2.0 features are invalid
+   */
+  async validateV2Schema(tool) {
+    // Validate executable_knowledge if present
+    if (tool.executable_knowledge) {
+      const { helpers, processors, validators } = tool.executable_knowledge;
+
+      // Validate helpers
+      if (helpers) {
+        if (!Array.isArray(helpers)) {
+          throw new Error('executable_knowledge.helpers must be an array');
+        }
+        for (const helper of helpers) {
+          if (!helper.id || !helper.language || !helper.function) {
+            throw new Error('Helper must have id, language, and function fields');
+          }
+          if (helper.language !== 'javascript') {
+            throw new Error(`Unsupported helper language: ${helper.language}`);
+          }
+        }
+      }
+
+      // Validate validators
+      if (validators) {
+        if (!Array.isArray(validators)) {
+          throw new Error('executable_knowledge.validators must be an array');
+        }
+        for (const validator of validators) {
+          if (!validator.id || !validator.validates || !validator.function) {
+            throw new Error('Validator must have id, validates, and function fields');
+          }
+        }
+      }
+    }
+
+    // Validate anti_patterns if present
+    if (tool.anti_patterns) {
+      if (!Array.isArray(tool.anti_patterns)) {
+        throw new Error('anti_patterns must be an array');
+      }
+      for (const pattern of tool.anti_patterns) {
+        if (!pattern.pattern || !pattern.description || !pattern.wrong || !pattern.correct) {
+          throw new Error('Anti-pattern must have pattern, description, wrong, and correct fields');
+        }
+      }
+    }
+  }
+
+  /**
+   * Detect schema version from tool features
+   *
+   * @param {object} tool - Tool definition
+   * @returns {number} Detected schema version (1.0 or 2.0)
+   */
+  detectSchemaVersion(tool) {
+    // Check for v2.0 features
+    const hasExecutableKnowledge = !!tool.executable_knowledge;
+    const hasApiComplexity = !!tool.api_complexity;
+    const hasAntiPatterns = !!tool.anti_patterns;
+    const hasEnhancedExamples = tool.examples &&
+      Object.values(tool.examples).some(ex =>
+        ex.some(e => e.scenario && ['success', 'failure_invalid_param'].includes(e.scenario)),
+      );
+
+    if (hasExecutableKnowledge || hasApiComplexity || hasAntiPatterns || hasEnhancedExamples) {
+      return 2.0;
+    }
+
+    // Default to v1.0 (simple tools)
+    return 1.0;
+  }
+
+  /**
+   * Perform health check on tool
+   *
+   * @param {object} tool - Tool definition with health_check config
+   * @returns {boolean} True if healthy, false otherwise
+   */
+  async checkHealth(tool) {
+    const { health_check } = tool;
+
+    if (!health_check || !health_check.method) {
+      return true; // No health check configured = assume healthy
+    }
+
+    try {
+      switch (health_check.method) {
+        case 'tool_call':
+          // Execute a specific tool command and check response
+          // Note: Actual implementation would use ToolExecutor
+          // For now, check if command exists in tool definition
+          return !!tool.commands?.includes(health_check.command);
+
+        case 'command':
+          // Execute shell command and check exit code
+          // Note: Actual implementation would use child_process
+          // For now, return true (not implemented)
+          return true;
+
+        case 'http':
+          // Make HTTP request and check status
+          // Note: Actual implementation would use fetch/axios
+          // For now, return true (not implemented)
+          return true;
+
+        default:
+          console.warn(`Unknown health check method: ${health_check.method}`);
+          return true;
+      }
+    } catch (error) {
+      console.error(`Health check failed for tool '${tool.id}':`, error);
+      return false;
+    }
+  }
+
+  /**
+   * Clear cache (useful for testing or reloading tools)
+   */
+  clearCache() {
+    this.cache.clear();
+  }
+
+  /**
+   * Get cache statistics
+   *
+   * @returns {object} Cache stats
+   */
+  getCacheStats() {
+    return {
+      size: this.cache.size,
+      keys: Array.from(this.cache.keys()),
+    };
+  }
+
+  /**
+   * List all available tools across all search paths
+   *
+   * @returns {Array<string>} Array of tool file paths
+   */
+  listAvailableTools() {
+    const allTools = [];
+    for (const basePath of this.basePaths) {
+      const tools = glob.sync(`${basePath}/**/*.yaml`);
+      allTools.push(...tools);
+    }
+    return allTools;
+  }
+
+  /**
+   * Check if a tool exists without loading it
+   *
+   * @param {string} toolName - Tool identifier
+   * @param {object} context - Resolution context
+   * @returns {boolean} True if tool exists
+   */
+  async toolExists(toolName, context = {}) {
+    const searchPaths = [];
+    if (context.expansionPack) {
+      searchPaths.push(`expansion-packs/${context.expansionPack}/tools`);
+    }
+    searchPaths.push(...this.basePaths);
+
+    for (const basePath of searchPaths) {
+      const candidates = glob.sync(`${basePath}/**/${toolName}.yaml`);
+      if (candidates.length > 0) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Set custom search paths (useful for testing)
+   *
+   * @param {string[]} paths - Array of search paths
+   */
+  setSearchPaths(paths) {
+    this.basePaths = paths;
+  }
+
+  /**
+   * Reset search paths to default
+   */
+  resetSearchPaths() {
+    this.basePaths = [
+      'aios-core/tools',
+      'common/tools',
+    ];
+  }
+}
+
+// Export singleton instance
+const toolResolverInstance = new ToolResolver();
+
+// Save reference to instance method BEFORE it gets overwritten by the export
+const yamlBasedResolveTool = toolResolverInstance.resolveTool.bind(toolResolverInstance);
+
+/**
+ * Simple tool resolution function - delegates to YAML-based tool resolution
+ * All tools (including MCP tools like clickup and github) are loaded from YAML definitions
+ *
+ * @param {string} toolName - Name of the tool (e.g., 'clickup', 'github')
+ * @param {object} context - Resolution context (optional, includes expansionPack)
+ * @returns {object} Tool definition from YAML file
+ */
+async function resolveTool(toolName, context = {}) {
+  // All tools go through YAML-based resolution
+  return await yamlBasedResolveTool(toolName, context);
+}
+
+module.exports = toolResolverInstance;
+module.exports.resolveTool = resolveTool;