aios-core 2.1.0

package/src/wizard/validation/validators/mcp-health-checker.js

@@ -0,0 +1,310 @@
+/**
+ * MCP Health Checker
+ * Task 1.8.3: MCP health checks (deferred from Story 1.5)
+ *
+ * Validates that installed MCPs are functioning correctly
+ *
+ * @module wizard/validation/validators/mcp-health-checker
+ */
+
+const fs = require('fs');
+
+/**
+ * Validate MCPs with health checks
+ *
+ * @param {Object} mcpContext - MCP installation result
+ * @param {Object} mcpContext.installedMCPs - Map of installed MCPs
+ * @param {string} mcpContext.configPath - Path to .mcp.json
+ * @returns {Promise<Object>} Validation result
+ */
+async function validateMCPs(mcpContext = {}) {
+  const results = {
+    success: true,
+    healthChecks: [],
+    errors: [],
+    warnings: [],
+  };
+
+  if (!mcpContext.installedMCPs || Object.keys(mcpContext.installedMCPs).length === 0) {
+    results.checks = [{
+      component: 'MCPs',
+      status: 'skipped',
+      message: 'No MCPs installed',
+    }];
+    return results;
+  }
+
+  try {
+    // Load .mcp.json to get MCP configurations
+    const mcpConfigPath = mcpContext.configPath || '.mcp.json';
+    if (!fs.existsSync(mcpConfigPath)) {
+      results.warnings.push({
+        severity: 'medium',
+        message: '.mcp.json not found - skipping health checks',
+        code: 'MCP_CONFIG_MISSING',
+      });
+      return results;
+    }
+
+    const mcpConfig = JSON.parse(fs.readFileSync(mcpConfigPath, 'utf8'));
+
+    // Run health checks for each installed MCP
+    const healthCheckPromises = Object.entries(mcpContext.installedMCPs).map(
+      async ([mcpId, installStatus]) => {
+        if (installStatus.status !== 'success') {
+          return {
+            mcp: mcpId,
+            status: 'skipped',
+            message: 'Installation failed - skipping health check',
+          };
+        }
+
+        try {
+          const healthResult = await runHealthCheck(mcpId, mcpConfig.mcpServers[mcpId]);
+          return {
+            mcp: mcpId,
+            status: healthResult.success ? 'success' : 'warning',
+            message: healthResult.message,
+            responseTime: healthResult.duration,
+            details: healthResult.details,
+          };
+        } catch (error) {
+          return {
+            mcp: mcpId,
+            status: 'failed',
+            message: `Health check failed: ${error.message}`,
+            error: error.message,
+          };
+        }
+      },
+    );
+
+    const healthCheckResults = await Promise.all(healthCheckPromises);
+
+    // Process results
+    for (const healthCheck of healthCheckResults) {
+      results.healthChecks.push(healthCheck);
+
+      if (healthCheck.status === 'failed') {
+        results.warnings.push({
+          severity: 'medium',
+          message: `${healthCheck.mcp} health check failed: ${healthCheck.message}`,
+          code: 'MCP_HEALTH_CHECK_FAILED',
+          mcp: healthCheck.mcp,
+        });
+      } else if (healthCheck.status === 'warning') {
+        results.warnings.push({
+          severity: 'low',
+          message: `${healthCheck.mcp} health check warning: ${healthCheck.message}`,
+          code: 'MCP_HEALTH_CHECK_WARNING',
+          mcp: healthCheck.mcp,
+        });
+      }
+    }
+
+    // Overall success if at least one MCP is healthy
+    const healthyCount = healthCheckResults.filter(r => r.status === 'success').length;
+    const failedCount = healthCheckResults.filter(r => r.status === 'failed').length;
+
+    if (healthyCount === 0 && failedCount > 0) {
+      results.success = false;
+      results.errors.push({
+        severity: 'high',
+        message: 'All MCP health checks failed',
+        code: 'ALL_MCP_HEALTH_CHECKS_FAILED',
+      });
+    }
+
+    return results;
+  } catch (error) {
+    results.errors.push({
+      severity: 'medium',
+      message: `MCP health check validation failed: ${error.message}`,
+      code: 'MCP_HEALTH_CHECK_ERROR',
+      details: error.stack,
+    });
+
+    return results;
+  }
+}
+
+/**
+ * Run health check for a specific MCP
+ * @private
+ *
+ * @param {string} mcpId - MCP identifier
+ * @param {Object} mcpConfig - MCP configuration from .mcp.json
+ * @returns {Promise<Object>} Health check result
+ */
+async function runHealthCheck(mcpId, mcpConfig) {
+  const startTime = Date.now();
+
+  try {
+    let result;
+
+    switch (mcpId) {
+      case 'browser':
+        result = await testBrowserMCP(mcpConfig);
+        break;
+
+      case 'context7':
+        result = await testContext7MCP(mcpConfig);
+        break;
+
+      case 'exa':
+        result = await testExaMCP(mcpConfig);
+        break;
+
+      case 'desktop-commander':
+        result = await testDesktopCommanderMCP(mcpConfig);
+        break;
+
+      default:
+        result = {
+          success: true,
+          message: 'Unknown MCP type - basic config validation only',
+          details: { configValid: !!mcpConfig },
+        };
+    }
+
+    return {
+      success: result.success,
+      message: result.message,
+      duration: Date.now() - startTime,
+      details: result.details,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      message: `Health check error: ${error.message}`,
+      duration: Date.now() - startTime,
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * Test Browser MCP (Puppeteer)
+ * @private
+ */
+async function testBrowserMCP(config) {
+  // Basic validation: Check if command is configured
+  if (!config || !config.command) {
+    return {
+      success: false,
+      message: 'Invalid configuration - missing command',
+      details: { configValid: false },
+    };
+  }
+
+  // Note: Full browser test would require spawning puppeteer
+  // For validation, we just check configuration validity
+  return {
+    success: true,
+    message: 'Configuration valid (runtime test requires browser launch)',
+    details: {
+      configValid: true,
+      command: config.command,
+      note: 'Full test deferred to first use',
+    },
+  };
+}
+
+/**
+ * Test Context7 MCP (npx/stdio configuration)
+ * Now uses @upstash/context7-mcp package via npx
+ * @private
+ */
+async function testContext7MCP(config) {
+  // Context7 now uses npx/stdio transport instead of HTTP
+  if (!config || !config.command) {
+    return {
+      success: false,
+      message: 'Invalid configuration - missing command',
+      details: { configValid: false },
+    };
+  }
+
+  // Basic validation: Check if command is configured for npx execution
+  return {
+    success: true,
+    message: 'Configuration valid (runtime test requires MCP server launch)',
+    details: {
+      configValid: true,
+      command: config.command,
+      note: 'Full test deferred to first use',
+    },
+  };
+}
+
+/**
+ * Test Exa MCP (API test)
+ * @private
+ */
+async function testExaMCP(config) {
+  if (!config || !config.env || !config.env.EXA_API_KEY) {
+    return {
+      success: false,
+      message: 'API key not configured in .env',
+      details: {
+        configValid: true,
+        apiKeyConfigured: false,
+        solution: 'Add EXA_API_KEY to .env file',
+      },
+    };
+  }
+
+  // Check if API key is a placeholder
+  const apiKey = config.env.EXA_API_KEY;
+  if (apiKey.includes('${') || apiKey === 'your-api-key-here') {
+    return {
+      success: false,
+      message: 'API key is placeholder - update .env with real key',
+      details: {
+        configValid: true,
+        apiKeyConfigured: false,
+        solution: 'Replace ${EXA_API_KEY} or placeholder in .env',
+      },
+    };
+  }
+
+  return {
+    success: true,
+    message: 'Configuration valid (API test requires real API call)',
+    details: {
+      configValid: true,
+      apiKeyConfigured: true,
+      note: 'Full API test deferred to first use',
+    },
+  };
+}
+
+/**
+ * Test Desktop Commander MCP (File access)
+ * @private
+ */
+async function testDesktopCommanderMCP(config) {
+  if (!config || !config.command) {
+    return {
+      success: false,
+      message: 'Invalid configuration - missing command',
+      details: { configValid: false },
+    };
+  }
+
+  // Basic validation: Check if command is configured
+  return {
+    success: true,
+    message: 'Configuration valid (file access test requires runtime)',
+    details: {
+      configValid: true,
+      command: config.command,
+      note: 'Full test deferred to first use',
+    },
+  };
+}
+
+module.exports = {
+  validateMCPs,
+  runHealthCheck,
+};

package/src/wizard/validators.js

@@ -0,0 +1,274 @@
+/**
+ * Input Validators with Security Best Practices
+ * 
+ * OWASP-compliant validators for all wizard inputs
+ * Protects against: command injection, path traversal, XSS, buffer overflow
+ * 
+ * @see docs/stories/v2.1/sprint-1/story-1.2-interactive-wizard-foundation.md
+ * @module wizard/validators
+ */
+
+const path = require('path');
+
+/**
+ * Maximum input lengths to prevent buffer overflow
+ */
+const INPUT_LIMITS = {
+  projectName: 100,
+  path: 255,
+  generic: 500,
+};
+
+/**
+ * Allowed project types (whitelist)
+ */
+const ALLOWED_PROJECT_TYPES = ['greenfield', 'brownfield'];
+
+/**
+ * Shell-special characters that need escaping/rejection
+ */
+const SHELL_SPECIAL_CHARS = /[;&|$`()\\<>\n]/;
+
+/**
+ * Validate project type against whitelist
+ * 
+ * @param {string} input - User input
+ * @returns {boolean|string} True if valid, error message if invalid
+ */
+function validateProjectType(input) {
+  if (!input || typeof input !== 'string') {
+    return 'Project type is required';
+  }
+
+  const normalized = input.toLowerCase().trim();
+  
+  if (!ALLOWED_PROJECT_TYPES.includes(normalized)) {
+    return `Invalid project type. Must be one of: ${ALLOWED_PROJECT_TYPES.join(', ')}`;
+  }
+
+  return true;
+}
+
+/**
+ * Validate and sanitize path input
+ * Prevents path traversal attacks (../../../etc/passwd)
+ * 
+ * Security policy:
+ * - Cross-drive access is DISALLOWED for security (e.g., C:\ vs D:\ on Windows)
+ * - Path must resolve within baseDir (no up-level traversal)
+ * - Uses path.relative() and root comparison for robust validation across platforms
+ * 
+ * @param {string} input - Path input
+ * @param {string} baseDir - Base directory (default: process.cwd())
+ * @returns {boolean|string} True if valid, error message if invalid
+ */
+function validatePath(input, baseDir = process.cwd()) {
+  if (!input || typeof input !== 'string') {
+    return 'Path is required';
+  }
+
+  // Check length
+  if (input.length > INPUT_LIMITS.path) {
+    return `Path too long (max ${INPUT_LIMITS.path} characters)`;
+  }
+
+  // Reject shell-special characters in paths
+  if (SHELL_SPECIAL_CHARS.test(input)) {
+    return 'Path contains invalid characters';
+  }
+
+  // Resolve and verify path is within base directory
+  // Normalize both paths to handle trailing slashes and relative segments
+  const normalizedBaseDir = path.resolve(baseDir);
+  const resolved = path.resolve(normalizedBaseDir, input);
+  
+  // On Windows, check for cross-drive access (e.g., C:\ vs D:\)
+  // Cross-drive targets are disallowed for security - path must stay within same root
+  const baseRoot = path.parse(normalizedBaseDir).root;
+  const resolvedRoot = path.parse(resolved).root;
+  
+  if (baseRoot !== resolvedRoot) {
+    return 'Path must be within project directory (cross-drive access not allowed)';
+  }
+  
+  // Use path.relative to detect traversal attempts
+  // If resolved is within baseDir, relative path won't start with '..'
+  const relativePath = path.relative(normalizedBaseDir, resolved);
+  
+  // Check for up-level traversal indicators
+  // Empty string means paths are identical, which is valid
+  if (relativePath && (relativePath.startsWith('..') || relativePath.includes('..'))) {
+    return 'Path must be within project directory (path traversal detected)';
+  }
+
+  return true;
+}
+
+/**
+ * Sanitize text input
+ * Removes/escapes shell-special characters
+ * 
+ * @param {string} input - Text input
+ * @param {number} maxLength - Maximum length (default: INPUT_LIMITS.generic)
+ * @returns {boolean|string} True if valid, error message if invalid
+ */
+function validateTextInput(input, maxLength = INPUT_LIMITS.generic) {
+  if (!input || typeof input !== 'string') {
+    return 'Input is required';
+  }
+
+  // Trim whitespace
+  const trimmed = input.trim();
+
+  // Check length
+  if (trimmed.length === 0) {
+    return 'Input cannot be empty';
+  }
+
+  if (trimmed.length > maxLength) {
+    return `Input too long (max ${maxLength} characters)`;
+  }
+
+  // Reject shell-special characters
+  if (SHELL_SPECIAL_CHARS.test(trimmed)) {
+    return 'Input contains invalid characters (shell-special characters not allowed)';
+  }
+
+  // Check for potential command injection patterns
+  const injectionPatterns = [
+    /\$\(/,           // $(command)
+    /`[^`]+`/,        // `command`
+    /&&/,             // command chaining
+    /\|\|/,           // command chaining
+    /<script/i,       // XSS-style
+    /<img/i,          // XSS-style
+  ];
+
+  for (const pattern of injectionPatterns) {
+    if (pattern.test(trimmed)) {
+      return 'Input contains potentially malicious patterns';
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Validate project name
+ * Stricter than generic text - only alphanumeric, dash, underscore
+ * 
+ * @param {string} input - Project name
+ * @returns {boolean|string} True if valid, error message if invalid
+ */
+function validateProjectName(input) {
+  if (!input || typeof input !== 'string') {
+    return 'Project name is required';
+  }
+
+  const trimmed = input.trim();
+
+  // Check length
+  if (trimmed.length === 0) {
+    return 'Project name cannot be empty';
+  }
+
+  if (trimmed.length > INPUT_LIMITS.projectName) {
+    return `Project name too long (max ${INPUT_LIMITS.projectName} characters)`;
+  }
+
+  // Only allow alphanumeric, dash, underscore
+  if (!/^[a-zA-Z0-9_-]+$/.test(trimmed)) {
+    return 'Project name can only contain letters, numbers, dashes, and underscores';
+  }
+
+  // Must start with letter or number
+  if (!/^[a-zA-Z0-9]/.test(trimmed)) {
+    return 'Project name must start with a letter or number';
+  }
+
+  return true;
+}
+
+/**
+ * Create inquirer-compatible validator function
+ * Converts validator return to inquirer format
+ * 
+ * @param {Function} validatorFn - Validator function
+ * @returns {Function} Inquirer-compatible validator
+ */
+function createInquirerValidator(validatorFn) {
+  return (input) => {
+    const result = validatorFn(input);
+    return result === true ? true : result;
+  };
+}
+
+/**
+ * Sanitize string by escaping shell-special characters
+ * Use ONLY if you absolutely need to preserve special chars
+ * Prefer validation/rejection instead
+ * 
+ * @param {string} input - String to sanitize
+ * @returns {string} Sanitized string
+ */
+function sanitizeShellInput(input) {
+  if (typeof input !== 'string') {
+    return '';
+  }
+
+  // Escape shell-special characters
+  const sanitized = input
+    .replace(/\\/g, '\\\\')
+    .replace(/'/g, "\\'")
+    .replace(/"/g, '\\"')
+    .replace(/`/g, '\\`')
+    .replace(/\$/g, '\\$')
+    .replace(/;/g, '\\;')
+    .replace(/&/g, '\\&')
+    .replace(/\|/g, '\\|')
+    .replace(/</g, '\\<')
+    .replace(/>/g, '\\>')
+    .replace(/\(/g, '\\(')
+    .replace(/\)/g, '\\)')
+    .replace(/\n/g, '\\n');
+  
+  return sanitized;
+}
+
+/**
+ * Validate list selection (for IDE, MCP, etc.)
+ * 
+ * @param {string} input - Selected value
+ * @param {string[]} allowedValues - Whitelist of allowed values
+ * @returns {boolean|string} True if valid, error message if invalid
+ */
+function validateListSelection(input, allowedValues) {
+  if (!input || typeof input !== 'string') {
+    return 'Selection is required';
+  }
+
+  if (!allowedValues.includes(input)) {
+    return `Invalid selection. Must be one of: ${allowedValues.join(', ')}`;
+  }
+
+  return true;
+}
+
+module.exports = {
+  // Core validators
+  validateProjectType,
+  validatePath,
+  validateTextInput,
+  validateProjectName,
+  validateListSelection,
+  
+  // Utility functions
+  createInquirerValidator,
+  sanitizeShellInput,
+  
+  // Constants (export for testing)
+  INPUT_LIMITS,
+  ALLOWED_PROJECT_TYPES,
+  SHELL_SPECIAL_CHARS,
+};
+

package/templates/squad/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) {{year}} {{author}}
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/squad/README.md

@@ -0,0 +1,37 @@
+# {{Squad Name}}
+
+{{Brief description of what this Squad does}}
+
+## Installation
+
+```bash
+npm install {{squad-name}}
+```
+
+## Usage
+
+```bash
+# Activate the agent
+@{{agent-name}}
+
+# Use commands
+*{{command-name}}
+```
+
+## Features
+
+- Feature 1
+- Feature 2
+- Feature 3
+
+## Documentation
+
+See the [full documentation](docs/README.md) for detailed usage.
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT License - see [LICENSE](LICENSE)

package/templates/squad/agents/example-agent.yaml

@@ -0,0 +1,36 @@
+# Example Agent Definition
+# Replace placeholders with your agent's details
+
+name: example-agent
+version: 1.0.0
+description: Brief description of what this agent does
+
+persona:
+  name: Example Agent
+  role: Your Agent's Role
+  expertise:
+    - Expertise Area 1
+    - Expertise Area 2
+    - Expertise Area 3
+
+capabilities:
+  - capability-one
+  - capability-two
+
+commands:
+  - name: example-command
+    description: What this command does
+    workflow: example-workflow
+
+system_prompt: |
+  You are Example Agent, specialized in [your domain].
+
+  Your responsibilities:
+  - Responsibility 1
+  - Responsibility 2
+  - Responsibility 3
+
+  Guidelines:
+  - Be helpful and precise
+  - Follow best practices
+  - Ask for clarification when needed

package/templates/squad/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "{{squad-name}}",
+  "version": "0.1.0",
+  "description": "{{description}}",
+  "main": "index.js",
+  "scripts": {
+    "test": "jest",
+    "lint": "eslint src/",
+    "dev": "aios-dev-server"
+  },
+  "keywords": ["aios", "aios-squad"],
+  "author": "{{author}}",
+  "license": "MIT",
+  "devDependencies": {
+    "@aios/testing": "^2.1.0",
+    "jest": "^29.0.0",
+    "eslint": "^8.0.0"
+  }
+}