vibecodingmachine-core 2026.2.20-438 → 2026.2.26-1642

package/src/rui/commands/AgentCommandParser.js

@@ -0,0 +1,600 @@
+/**
+ * RUI Agent Command Parser
+ * 
+ * Parses and validates REST-based agent commands.
+ * Follows constitutional requirements: <555 lines, test-first approach.
+ */
+
+/**
+ * RUI Agent Command Parser class
+ */
+class AgentCommandParser {
+  /**
+   * Create command parser instance
+   * @param {Object} options - Parser options
+   */
+  constructor(options = {}) {
+    this.caseSensitive = options.caseSensitive || false;
+    this.allowShortcuts = options.allowShortcuts !== false;
+    this.strictMode = options.strictMode || false;
+    
+    // Define command mappings
+    this.commandMap = this.initializeCommandMap();
+    this.shortcutMap = this.initializeShortcutMap();
+    this.parameterDefinitions = this.initializeParameterDefinitions();
+  }
+
+  /**
+   * Parse command string into components
+   * @param {string} commandString - Raw command string
+   * @returns {Object} - Parsed command object
+   */
+  parse(commandString) {
+    if (!commandString || typeof commandString !== 'string') {
+      throw new Error('Command string is required and must be a string');
+    }
+
+    try {
+      const tokens = this.tokenize(commandString);
+      const { verb, resource, params } = this.extractComponents(tokens);
+      
+      const normalizedVerb = this.normalizeVerb(verb);
+      const validatedCommand = this.validateCommand(normalizedVerb, resource, params);
+      
+      return {
+        ...validatedCommand,
+        original: commandString,
+        tokens,
+        parsed: true
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message,
+        original: commandString,
+        parsed: false
+      };
+    }
+  }
+
+  /**
+   * Tokenize command string
+   * @param {string} commandString - Command string to tokenize
+   * @returns {Array} - Array of tokens
+   */
+  tokenize(commandString) {
+    // Handle quoted strings and parameters
+    const tokens = [];
+    let current = '';
+    let inQuotes = false;
+    let quoteChar = '';
+    
+    for (let i = 0; i < commandString.length; i++) {
+      const char = commandString[i];
+      
+      if ((char === '"' || char === "'") && !inQuotes) {
+        inQuotes = true;
+        quoteChar = char;
+      } else if (char === quoteChar && inQuotes) {
+        inQuotes = false;
+        quoteChar = '';
+      } else if (char === ' ' && !inQuotes) {
+        if (current.trim()) {
+          tokens.push(current.trim());
+          current = '';
+        }
+      } else {
+        current += char;
+      }
+    }
+    
+    if (current.trim()) {
+      tokens.push(current.trim());
+    }
+    
+    return tokens;
+  }
+
+  /**
+   * Extract verb, resource, and parameters from tokens
+   * @param {Array} tokens - Command tokens
+   * @returns {Object} - Extracted components
+   */
+  extractComponents(tokens) {
+    if (tokens.length === 0) {
+      throw new Error('Empty command');
+    }
+
+    let verb = tokens[0];
+    let resource = '';
+    let params = {};
+
+    // Handle shortcuts (2-character commands)
+    if (this.allowShortcuts && tokens.length >= 2 && tokens[0].length <= 3) {
+      verb = tokens[0];
+      resource = tokens[1];
+      
+      // Extract parameters from remaining tokens
+      for (let i = 2; i < tokens.length; i++) {
+        this.parseParameter(tokens[i], params);
+      }
+    } 
+    // Handle full commands
+    else if (tokens.length >= 2) {
+      verb = tokens[0];
+      resource = tokens[1];
+      
+      // Extract parameters from remaining tokens
+      for (let i = 2; i < tokens.length; i++) {
+        this.parseParameter(tokens[i], params);
+      }
+    } else {
+      // Single token - might be verb only or verb+resource
+      const parts = tokens[0].split(/\s+/);
+      if (parts.length >= 2) {
+        verb = parts[0];
+        resource = parts[1];
+      }
+    }
+
+    return { verb, resource, params };
+  }
+
+  /**
+   * Parse parameter token
+   * @param {string} token - Parameter token
+   * @param {Object} params - Parameters object to update
+   */
+  parseParameter(token, params) {
+    // Handle flag parameters (--flag)
+    if (token.startsWith('--')) {
+      const flag = token.substring(2);
+      params[flag] = true;
+    }
+    // Handle short flags (-f)
+    else if (token.startsWith('-') && !token.startsWith('--')) {
+      const flag = token.substring(1);
+      params[flag] = true;
+    }
+    // Handle key=value parameters (--key=value)
+    else if (token.includes('=')) {
+      const [key, value] = token.split('=', 2);
+      const cleanKey = key.startsWith('--') ? key.substring(2) : key.startsWith('-') ? key.substring(1) : key;
+      params[cleanKey] = this.parseValue(value);
+    }
+    // Handle key value parameters (--key value)
+    else if (token.startsWith('--')) {
+      const key = token.substring(2);
+      params[key] = true; // Will be updated with next token if it's a value
+    }
+    // Positional parameter
+    else {
+      if (!params.positional) {
+        params.positional = [];
+      }
+      params.positional.push(this.parseValue(token));
+    }
+  }
+
+  /**
+   * Parse parameter value
+   * @param {string} value - Raw value
+   * @returns {*} - Parsed value
+   */
+  parseValue(value) {
+    // Remove quotes if present
+    if ((value.startsWith('"') && value.endsWith('"')) || 
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+
+    // Parse as JSON if possible
+    try {
+      return JSON.parse(value);
+    } catch {
+      // Return as string if not valid JSON
+      return value;
+    }
+  }
+
+  /**
+   * Normalize verb using command map
+   * @param {string} verb - Raw verb
+   * @returns {string} - Normalized verb
+   */
+  normalizeVerb(verb) {
+    if (!verb) return verb;
+
+    const normalized = this.caseSensitive ? verb : verb.toUpperCase();
+    
+    // Check shortcuts first
+    if (this.allowShortcuts && this.shortcutMap[normalized]) {
+      return this.shortcutMap[normalized];
+    }
+    
+    // Check full commands
+    if (this.commandMap[normalized]) {
+      return this.commandMap[normalized];
+    }
+    
+    return normalized;
+  }
+
+  /**
+   * Validate command components
+   * @param {string} verb - Command verb
+   * @param {string} resource - Command resource
+   * @param {Object} params - Command parameters
+   * @returns {Object} - Validation result
+   */
+  validateCommand(verb, resource, params) {
+    const validation = {
+      success: true,
+      verb,
+      resource,
+      params,
+      errors: [],
+      warnings: []
+    };
+
+    // Validate verb
+    if (!this.isValidVerb(verb)) {
+      validation.success = false;
+      validation.errors.push(`Unknown command: ${verb}`);
+      return validation;
+    }
+
+    // Validate resource based on verb
+    const resourceValidation = this.validateResource(verb, resource);
+    if (!resourceValidation.valid) {
+      validation.success = false;
+      validation.errors.push(...resourceValidation.errors);
+    }
+
+    // Validate parameters
+    const paramValidation = this.validateParameters(verb, resource, params);
+    if (!paramValidation.valid) {
+      validation.success = false;
+      validation.errors.push(...paramValidation.errors);
+    }
+
+    validation.warnings.push(...paramValidation.warnings);
+
+    return validation;
+  }
+
+  /**
+   * Check if verb is valid
+   * @param {string} verb - Verb to check
+   * @returns {boolean} - Whether verb is valid
+   */
+  isValidVerb(verb) {
+    const validVerbs = new Set([
+      'GET', 'LIST', 'POST', 'CHECK', 'PUT', 'UPDATE', 'DELETE', 'REMOVE',
+      'ENABLE', 'DISABLE', 'STATUS', 'HELP'
+    ]);
+    
+    return validVerbs.has(verb);
+  }
+
+  /**
+   * Validate resource for given verb
+   * @param {string} verb - Command verb
+   * @param {string} resource - Resource to validate
+   * @returns {Object} - Validation result
+   */
+  validateResource(verb, resource) {
+    const validation = { valid: true, errors: [] };
+
+    // Verbs that require resource
+    const resourceRequiredVerbs = new Set(['GET', 'PUT', 'UPDATE', 'DELETE', 'REMOVE', 'ENABLE', 'DISABLE']);
+    
+    if (resourceRequiredVerbs.has(verb) && !resource) {
+      validation.valid = false;
+      validation.errors.push('Resource is required for this command');
+    }
+
+    // Validate resource format
+    if (resource && !this.isValidResource(resource)) {
+      validation.valid = false;
+      validation.errors.push(`Invalid resource: ${resource}`);
+    }
+
+    return validation;
+  }
+
+  /**
+   * Check if resource is valid
+   * @param {string} resource - Resource to check
+   * @returns {boolean} - Whether resource is valid
+   */
+  isValidResource(resource) {
+    const validResources = ['agents', 'agent'];
+    return validResources.includes(resource.toLowerCase()) || 
+           resource.toLowerCase().startsWith('agent-');
+  }
+
+  /**
+   * Validate command parameters
+   * @param {string} verb - Command verb
+   * @param {string} resource - Command resource
+   * @param {Object} params - Parameters to validate
+   * @returns {Object} - Validation result
+   */
+  validateParameters(verb, resource, params) {
+    const validation = { valid: true, errors: [], warnings: [] };
+
+    // Get parameter definitions for this verb
+    const paramDefs = this.parameterDefinitions[verb] || {};
+    
+    // Validate each parameter
+    for (const [paramName, paramValue] of Object.entries(params)) {
+      if (paramName === 'positional') continue;
+
+      const paramDef = paramDefs[paramName];
+      if (!paramDef) {
+        if (this.strictMode) {
+          validation.valid = false;
+          validation.errors.push(`Unknown parameter: ${paramName}`);
+        }
+        continue;
+      }
+
+      // Type validation
+      if (paramDef.type && !this.validateParameterType(paramValue, paramDef.type)) {
+        validation.valid = false;
+        validation.errors.push(`Invalid type for parameter ${paramName}: expected ${paramDef.type}`);
+      }
+
+      // Value validation
+      if (paramDef.validValues && !paramDef.validValues.includes(paramValue)) {
+        validation.valid = false;
+        validation.errors.push(`Invalid value for parameter ${paramName}: ${paramValue}. Valid values: ${paramDef.validValues.join(', ')}`);
+      }
+    }
+
+    // Check for required parameters
+    for (const [paramName, paramDef] of Object.entries(paramDefs)) {
+      if (paramDef.required && !(paramName in params)) {
+        validation.valid = false;
+        validation.errors.push(`Required parameter missing: ${paramName}`);
+      }
+    }
+
+    // Add warnings for special cases
+    if (verb === 'DELETE' && !params.confirm) {
+      validation.warnings.push('DELETE command requires confirmation (confirm=true)');
+    }
+
+    if (verb === 'CHECK' && params.timeout && params.timeout < 0) {
+      validation.warnings.push('Timeout should be positive');
+    }
+
+    return validation;
+  }
+
+  /**
+   * Validate parameter type
+   * @param {*} value - Parameter value
+   * @param {string} type - Expected type
+   * @returns {boolean} - Whether type is valid
+   */
+  validateParameterType(value, type) {
+    switch (type) {
+      case 'boolean':
+        return typeof value === 'boolean' || value === true || value === false;
+      case 'number':
+        return !isNaN(Number(value));
+      case 'string':
+        return typeof value === 'string';
+      case 'array':
+        return Array.isArray(value);
+      default:
+        return true; // Unknown type, assume valid
+    }
+  }
+
+  /**
+   * Initialize command mappings
+   * @returns {Object} - Command map
+   */
+  initializeCommandMap() {
+    return {
+      'GET': 'GET',
+      'LIST': 'GET',
+      'POST': 'POST',
+      'CHECK': 'POST',
+      'PUT': 'PUT',
+      'UPDATE': 'PUT',
+      'DELETE': 'DELETE',
+      'REMOVE': 'DELETE',
+      'ENABLE': 'PUT',
+      'DISABLE': 'PUT',
+      'STATUS': 'GET',
+      'HELP': 'GET'
+    };
+  }
+
+  /**
+   * Initialize shortcut mappings
+   * @returns {Object} - Shortcut map
+   */
+  initializeShortcutMap() {
+    return {
+      'LA': 'GET',      // List agents
+      'LI': 'GET',      // List agents
+      'CH': 'POST',     // Check agents
+      'CA': 'POST',     // Check agents
+      'GE': 'GET',      // Get agent
+      'UP': 'PUT',      // Update agent
+      'EN': 'PUT',      // Enable agent
+      'DI': 'PUT',      // Disable agent
+      'RE': 'DELETE',   // Remove agent
+      'RM': 'DELETE',   // Remove agent
+      'ST': 'GET',      // Status
+      'HE': 'GET'       // Help
+    };
+  }
+
+  /**
+   * Initialize parameter definitions
+   * @returns {Object} - Parameter definitions
+   */
+  initializeParameterDefinitions() {
+    return {
+      'GET': {
+        'includeDisabled': { type: 'boolean', default: false },
+        'includeStatus': { type: 'boolean', default: true },
+        'includeLogs': { type: 'boolean', default: false },
+        'format': { type: 'string', validValues: ['table', 'json', 'csv'] },
+        'sort': { type: 'string', validValues: ['name', 'status', 'type', 'priority'] },
+        'status': { type: 'string' },
+        'limit': { type: 'number' },
+        'offset': { type: 'number' }
+      },
+      'POST': {
+        'agentIds': { type: 'array' },
+        'forceReinstall': { type: 'boolean', default: false },
+        'skipVerification': { type: 'boolean', default: false },
+        'timeout': { type: 'number', default: 300000 },
+        'parallel': { type: 'boolean', default: true },
+        'maxConcurrency': { type: 'number', default: 2 }
+      },
+      'PUT': {
+        'enabled': { type: 'boolean' },
+        'status': { type: 'string' },
+        'message': { type: 'string' }
+      },
+      'DELETE': {
+        'confirm': { type: 'boolean', required: true }
+      }
+    };
+  }
+
+  /**
+   * Get command suggestions
+   * @param {string} partial - Partial command
+   * @returns {Array} - Suggestions
+   */
+  getSuggestions(partial) {
+    if (!partial) return [];
+
+    const normalized = this.caseSensitive ? partial : partial.toUpperCase();
+    const suggestions = [];
+
+    // Command suggestions
+    for (const [command, normalizedCommand] of Object.entries(this.commandMap)) {
+      if (normalizedCommand.startsWith(normalized)) {
+        suggestions.push({
+          type: 'command',
+          value: command,
+          description: this.getCommandDescription(command)
+        });
+      }
+    }
+
+    // Shortcut suggestions
+    if (this.allowShortcuts) {
+      for (const [shortcut, command] of Object.entries(this.shortcutMap)) {
+        if (shortcut.startsWith(normalized)) {
+          suggestions.push({
+            type: 'shortcut',
+            value: shortcut,
+            description: this.getCommandDescription(command)
+          });
+        }
+      }
+    }
+
+    return suggestions;
+  }
+
+  /**
+   * Get command description
+   * @param {string} command - Command
+   * @returns {string} - Description
+   */
+  getCommandDescription(command) {
+    const descriptions = {
+      'GET': 'Get agent or list agents',
+      'POST': 'Check agents',
+      'PUT': 'Update agent (enable/disable)',
+      'DELETE': 'Remove agent',
+      'LIST': 'List agents',
+      'CHECK': 'Check agents',
+      'ENABLE': 'Enable agent',
+      'DISABLE': 'Disable agent',
+      'REMOVE': 'Remove agent',
+      'STATUS': 'Get agent status',
+      'HELP': 'Show help'
+    };
+
+    return descriptions[command] || 'Unknown command';
+  }
+
+  /**
+   * Format command for display
+   * @param {Object} parsedCommand - Parsed command object
+   * @returns {string} - Formatted command
+   */
+  formatCommand(parsedCommand) {
+    if (!parsedCommand || !parsedCommand.verb) {
+      return '';
+    }
+
+    let command = parsedCommand.verb;
+    
+    if (parsedCommand.resource) {
+      command += ' ' + parsedCommand.resource;
+    }
+
+    // Add parameters
+    for (const [param, value] of Object.entries(parsedCommand.params || {})) {
+      if (param === 'positional') continue;
+      
+      if (typeof value === 'boolean' && value === true) {
+        command += ` --${param}`;
+      } else if (typeof value === 'string' && value.includes(' ')) {
+        command += ` --${param}="${value}"`;
+      } else {
+        command += ` --${param}=${value}`;
+      }
+    }
+
+    // Add positional parameters
+    if (parsedCommand.params && parsedCommand.params.positional) {
+      for (const param of parsedCommand.params.positional) {
+        command += ` ${param}`;
+      }
+    }
+
+    return command;
+  }
+
+  /**
+   * Get parser information
+   * @returns {Object} - Parser info
+   */
+  getInfo() {
+    return {
+      name: 'RUI Agent Command Parser',
+      version: '1.0.0',
+      caseSensitive: this.caseSensitive,
+      allowShortcuts: this.allowShortcuts,
+      strictMode: this.strictMode,
+      supportedVerbs: Object.keys(this.commandMap),
+      supportedShortcuts: Object.keys(this.shortcutMap),
+      features: [
+        'command parsing',
+        'parameter validation',
+        'shortcut support',
+        'type checking',
+        'auto-completion',
+        'error handling',
+        'command formatting'
+      ]
+    };
+  }
+}
+
+module.exports = AgentCommandParser;