musubi-sdd 3.8.0 → 3.9.0

package/bin/musubi-validate.js

@@ -11,12 +11,20 @@
  *   musubi-validate article <1-9>   # Validate specific article
  *   musubi-validate gates           # Validate Phase -1 Gates
  *   musubi-validate complexity      # Validate complexity limits
+ *   musubi-validate guardrails      # Validate content with guardrails
  *   musubi-validate all             # Run all validations
  */
 
 const { Command } = require('commander');
 const chalk = require('chalk');
 const ConstitutionValidator = require('../src/validators/constitution');
+const {
+  createInputGuardrail,
+  createOutputGuardrail,
+  createSafetyCheckGuardrail,
+  GuardrailChain,
+  SafetyLevel
+} = require('../src/orchestration/guardrails');
 
 const program = new Command();
 
@@ -107,6 +115,134 @@ program
     }
   });
 
+// Guardrails validation
+program
+  .command('guardrails')
+  .description('Validate content with input/output guardrails')
+  .argument('[content]', 'Content to validate (or use --file)')
+  .option('--file <path>', 'Read content from file')
+  .option('-t, --type <type>', 'Guardrail type (input|output|safety)', 'input')
+  .option('-l, --level <level>', 'Safety level (basic|standard|strict|paranoid)', 'standard')
+  .option('--constitutional', 'Enable constitutional compliance checks')
+  .option('--redact', 'Enable redaction for output guardrails')
+  .option('-f, --format <type>', 'Output format (console|json)', 'console')
+  .action(async (content, options) => {
+    try {
+      // Get content from argument, file, or stdin
+      let inputContent = content;
+      
+      if (options.file) {
+        const fs = require('fs');
+        const path = require('path');
+        const filePath = path.resolve(process.cwd(), options.file);
+        inputContent = fs.readFileSync(filePath, 'utf-8');
+      } else if (!inputContent && !process.stdin.isTTY) {
+        // Read from stdin
+        const chunks = [];
+        for await (const chunk of process.stdin) {
+          chunks.push(chunk);
+        }
+        inputContent = Buffer.concat(chunks).toString('utf-8');
+      }
+
+      if (!inputContent) {
+        console.error(chalk.red('✗ No content provided. Use --file or pipe content.'));
+        process.exit(1);
+      }
+
+      let guardrail;
+      const guardrailType = options.type.toLowerCase();
+
+      switch (guardrailType) {
+        case 'input':
+          guardrail = createInputGuardrail('userInput', {
+            sanitize: true
+          });
+          break;
+        
+        case 'output':
+          guardrail = createOutputGuardrail(options.redact ? 'redact' : 'safe');
+          break;
+        
+        case 'safety':
+          guardrail = createSafetyCheckGuardrail(options.level, {
+            enforceConstitution: options.constitutional
+          });
+          break;
+        
+        default:
+          console.error(chalk.red(`✗ Unknown guardrail type: ${guardrailType}`));
+          process.exit(1);
+      }
+
+      console.log(chalk.dim(`\n🛡️  Running ${guardrailType} guardrail validation...\n`));
+
+      const result = await guardrail.run(inputContent);
+
+      displayGuardrailResults(result, options);
+      process.exit(result.passed ? 0 : 1);
+    } catch (error) {
+      console.error(chalk.red('✗ Guardrail validation error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// Guardrails chain validation
+program
+  .command('guardrails-chain')
+  .description('Run a chain of guardrails on content')
+  .argument('[content]', 'Content to validate')
+  .option('--file <path>', 'Read content from file')
+  .option('--parallel', 'Run guardrails in parallel')
+  .option('--stop-on-failure', 'Stop on first failure')
+  .option('-f, --format <type>', 'Output format (console|json)', 'console')
+  .action(async (content, options) => {
+    try {
+      // Get content
+      let inputContent = content;
+      
+      if (options.file) {
+        const fs = require('fs');
+        const path = require('path');
+        const filePath = path.resolve(process.cwd(), options.file);
+        inputContent = fs.readFileSync(filePath, 'utf-8');
+      } else if (!inputContent && !process.stdin.isTTY) {
+        const chunks = [];
+        for await (const chunk of process.stdin) {
+          chunks.push(chunk);
+        }
+        inputContent = Buffer.concat(chunks).toString('utf-8');
+      }
+
+      if (!inputContent) {
+        console.error(chalk.red('✗ No content provided. Use --file or pipe content.'));
+        process.exit(1);
+      }
+
+      // Create guardrail chain
+      const chain = new GuardrailChain({
+        name: 'ValidationChain',
+        parallel: options.parallel || false,
+        stopOnFirstFailure: options.stopOnFailure || false
+      });
+
+      // Add default guardrails
+      chain.add(createInputGuardrail('security'));
+      chain.add(createSafetyCheckGuardrail('standard'));
+      chain.add(createOutputGuardrail('safe'));
+
+      console.log(chalk.dim('\n🔗 Running guardrail chain validation...\n'));
+
+      const result = await chain.run(inputContent);
+
+      displayChainResults(result, options);
+      process.exit(result.passed ? 0 : 1);
+    } catch (error) {
+      console.error(chalk.red('✗ Guardrail chain error:'), error.message);
+      process.exit(1);
+    }
+  });
+
 // Score validation (numeric score output for CI/CD)
 program
   .command('score')
@@ -345,6 +481,104 @@ function displayMarkdown(title, results) {
   }
 }
 
+/**
+ * Display guardrail validation results
+ */
+function displayGuardrailResults(result, options) {
+  if (options.format === 'json') {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(chalk.bold('Guardrail Validation Results'));
+  console.log(chalk.bold('━'.repeat(50)));
+
+  if (result.passed) {
+    console.log(chalk.green(`\n✓ PASSED - ${result.guardrailName}\n`));
+  } else {
+    console.log(chalk.red(`\n✗ FAILED - ${result.guardrailName}\n`));
+  }
+
+  if (result.message) {
+    console.log(chalk.dim(`Message: ${result.message}`));
+  }
+
+  console.log(chalk.dim(`Execution time: ${result.executionTimeMs}ms\n`));
+
+  if (result.violations && result.violations.length > 0) {
+    console.log(chalk.bold.red('Violations:'));
+    result.violations.forEach(violation => {
+      const severityIcon = violation.severity === 'error' ? '✗' : 
+                           violation.severity === 'warning' ? '⚠' : 'ℹ';
+      const severityColor = violation.severity === 'error' ? chalk.red :
+                            violation.severity === 'warning' ? chalk.yellow : chalk.blue;
+      console.log(severityColor(`  ${severityIcon} [${violation.code}] ${violation.message}`));
+    });
+    console.log();
+  }
+
+  // Show metadata if redaction was applied
+  if (result.metadata?.redactionApplied) {
+    console.log(chalk.bold.blue('Redaction Applied:'));
+    console.log(chalk.dim(`  ${result.metadata.redactionCount} item(s) redacted`));
+    if (result.metadata.redactions) {
+      result.metadata.redactions.forEach(r => {
+        console.log(chalk.dim(`    - ${r.type}: ${r.count}`));
+      });
+    }
+    console.log();
+  }
+
+  // Show quality scores if available
+  if (result.metadata?.qualityScores) {
+    console.log(chalk.bold.blue('Quality Scores:'));
+    Object.entries(result.metadata.qualityScores).forEach(([name, score]) => {
+      console.log(chalk.dim(`  ${name}: ${(score * 100).toFixed(1)}%`));
+    });
+    console.log();
+  }
+}
+
+/**
+ * Display guardrail chain results
+ */
+function displayChainResults(result, options) {
+  if (options.format === 'json') {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(chalk.bold('Guardrail Chain Results'));
+  console.log(chalk.bold('━'.repeat(50)));
+
+  if (result.passed) {
+    console.log(chalk.green(`\n✓ PASSED - ${result.chainName}\n`));
+  } else {
+    console.log(chalk.red(`\n✗ FAILED - ${result.chainName}\n`));
+  }
+
+  console.log(chalk.dim(`Guardrails executed: ${result.executedCount}/${result.guardrailCount}`));
+  console.log(chalk.dim(`Total time: ${result.executionTimeMs}ms\n`));
+
+  // Show individual guardrail results
+  console.log(chalk.bold('Individual Results:'));
+  result.results.forEach((r, index) => {
+    const icon = r.passed ? chalk.green('✓') : chalk.red('✗');
+    console.log(`  ${icon} ${r.guardrailName} (${r.executionTimeMs}ms)`);
+  });
+  console.log();
+
+  // Show all violations
+  if (result.violations && result.violations.length > 0) {
+    console.log(chalk.bold.red('All Violations:'));
+    result.violations.forEach(violation => {
+      const severityColor = violation.severity === 'error' ? chalk.red : chalk.yellow;
+      console.log(severityColor(`  • [${violation.code}] ${violation.message}`));
+    });
+    console.log();
+  }
+}
+
 // Parse arguments
 program.parse(process.argv);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "musubi-sdd",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "description": "Ultimate Specification Driven Development Tool with 27 Agents for 7 AI Coding Platforms + MCP Integration (Claude Code, GitHub Copilot, Cursor, Gemini CLI, Windsurf, Codex, Qwen Code)",
   "main": "src/index.js",
   "bin": {

package/src/orchestration/guardrails/base-guardrail.js

@@ -0,0 +1,358 @@
+/**
+ * @fileoverview Base Guardrail class for MUSUBI Orchestration
+ * 
+ * Guardrails provide safety checks for agent inputs and outputs.
+ * Inspired by OpenAI Agents SDK guardrails pattern.
+ * 
+ * @module orchestration/guardrails/base-guardrail
+ * @version 3.9.0
+ */
+
+'use strict';
+
+/**
+ * Guardrail execution result
+ * @typedef {Object} GuardrailResult
+ * @property {boolean} passed - Whether the guardrail check passed
+ * @property {string} guardrailName - Name of the guardrail that was executed
+ * @property {string} [message] - Optional message describing the result
+ * @property {Array<GuardrailViolation>} violations - List of violations found
+ * @property {Object} [metadata] - Additional metadata from the check
+ * @property {number} executionTimeMs - Time taken to execute the guardrail
+ */
+
+/**
+ * Guardrail violation details
+ * @typedef {Object} GuardrailViolation
+ * @property {string} code - Violation code (e.g., 'PII_DETECTED', 'PROHIBITED_CONTENT')
+ * @property {string} message - Human-readable description
+ * @property {string} severity - 'error' | 'warning' | 'info'
+ * @property {Object} [context] - Additional context about the violation
+ */
+
+/**
+ * Guardrail configuration options
+ * @typedef {Object} GuardrailConfig
+ * @property {string} name - Unique name for the guardrail
+ * @property {string} [description] - Description of what the guardrail checks
+ * @property {boolean} [enabled=true] - Whether the guardrail is enabled
+ * @property {boolean} [failFast=false] - Stop on first violation
+ * @property {string} [severity='error'] - Default severity level
+ * @property {Object} [options] - Guardrail-specific options
+ */
+
+/**
+ * Tripwire exception - thrown when guardrail fails and tripwire is enabled
+ * @class
+ */
+class GuardrailTripwireException extends Error {
+  /**
+   * @param {string} message - Error message
+   * @param {GuardrailResult} result - The guardrail result that triggered the tripwire
+   */
+  constructor(message, result) {
+    super(message);
+    this.name = 'GuardrailTripwireException';
+    this.result = result;
+    this.violations = result.violations;
+  }
+}
+
+/**
+ * Base class for all guardrails
+ * @abstract
+ */
+class BaseGuardrail {
+  /**
+   * @param {GuardrailConfig} config - Guardrail configuration
+   */
+  constructor(config) {
+    if (new.target === BaseGuardrail) {
+      throw new Error('BaseGuardrail is abstract and cannot be instantiated directly');
+    }
+
+    this.name = config.name || this.constructor.name;
+    this.description = config.description || '';
+    this.enabled = config.enabled !== false;
+    this.failFast = config.failFast || false;
+    this.defaultSeverity = config.severity || 'error';
+    this.options = config.options || {};
+    
+    // Tripwire: if true, throws exception on failure instead of returning result
+    this.tripwireEnabled = config.tripwireEnabled || false;
+  }
+
+  /**
+   * Execute the guardrail check
+   * @abstract
+   * @param {*} input - Input to validate
+   * @param {Object} [context] - Execution context
+   * @returns {Promise<GuardrailResult>}
+   */
+  async check(input, context = {}) {
+    throw new Error('Subclasses must implement check() method');
+  }
+
+  /**
+   * Run the guardrail with timing and error handling
+   * @param {*} input - Input to validate
+   * @param {Object} [context] - Execution context
+   * @returns {Promise<GuardrailResult>}
+   */
+  async run(input, context = {}) {
+    if (!this.enabled) {
+      return this.createResult(true, [], 'Guardrail is disabled');
+    }
+
+    const startTime = Date.now();
+    
+    try {
+      const result = await this.check(input, context);
+      result.executionTimeMs = Date.now() - startTime;
+      result.guardrailName = this.name;
+      
+      // Handle tripwire
+      if (this.tripwireEnabled && !result.passed) {
+        throw new GuardrailTripwireException(
+          `Guardrail '${this.name}' triggered tripwire: ${result.message || 'Validation failed'}`,
+          result
+        );
+      }
+      
+      return result;
+    } catch (error) {
+      if (error instanceof GuardrailTripwireException) {
+        throw error; // Re-throw tripwire exceptions
+      }
+      
+      // Wrap unexpected errors
+      return this.createResult(
+        false,
+        [{
+          code: 'GUARDRAIL_ERROR',
+          message: error.message,
+          severity: 'error',
+          context: { errorName: error.name, stack: error.stack }
+        }],
+        `Guardrail execution failed: ${error.message}`,
+        Date.now() - startTime
+      );
+    }
+  }
+
+  /**
+   * Create a standardized guardrail result
+   * @protected
+   * @param {boolean} passed - Whether the check passed
+   * @param {Array<GuardrailViolation>} [violations=[]] - List of violations
+   * @param {string} [message] - Optional message
+   * @param {number} [executionTimeMs=0] - Execution time
+   * @param {Object} [metadata] - Additional metadata
+   * @returns {GuardrailResult}
+   */
+  createResult(passed, violations = [], message = undefined, executionTimeMs = 0, metadata = {}) {
+    return {
+      passed,
+      guardrailName: this.name,
+      message,
+      violations,
+      metadata,
+      executionTimeMs
+    };
+  }
+
+  /**
+   * Create a violation object
+   * @protected
+   * @param {string} code - Violation code
+   * @param {string} message - Human-readable message
+   * @param {string} [severity] - Severity level
+   * @param {Object} [context] - Additional context
+   * @returns {GuardrailViolation}
+   */
+  createViolation(code, message, severity = null, context = {}) {
+    return {
+      code,
+      message,
+      severity: severity || this.defaultSeverity,
+      context
+    };
+  }
+
+  /**
+   * Enable the guardrail
+   */
+  enable() {
+    this.enabled = true;
+  }
+
+  /**
+   * Disable the guardrail
+   */
+  disable() {
+    this.enabled = false;
+  }
+
+  /**
+   * Enable tripwire mode
+   */
+  enableTripwire() {
+    this.tripwireEnabled = true;
+  }
+
+  /**
+   * Disable tripwire mode
+   */
+  disableTripwire() {
+    this.tripwireEnabled = false;
+  }
+
+  /**
+   * Get guardrail info
+   * @returns {Object}
+   */
+  getInfo() {
+    return {
+      name: this.name,
+      description: this.description,
+      enabled: this.enabled,
+      failFast: this.failFast,
+      tripwireEnabled: this.tripwireEnabled,
+      defaultSeverity: this.defaultSeverity
+    };
+  }
+}
+
+/**
+ * Guardrail chain for running multiple guardrails
+ */
+class GuardrailChain {
+  /**
+   * @param {Object} [options] - Chain options
+   * @param {boolean} [options.parallel=false] - Run guardrails in parallel
+   * @param {boolean} [options.stopOnFirstFailure=false] - Stop on first failure
+   * @param {string} [options.name='GuardrailChain'] - Chain name
+   */
+  constructor(options = {}) {
+    this.name = options.name || 'GuardrailChain';
+    this.parallel = options.parallel || false;
+    this.stopOnFirstFailure = options.stopOnFirstFailure || false;
+    this.guardrails = [];
+  }
+
+  /**
+   * Add a guardrail to the chain
+   * @param {BaseGuardrail} guardrail - Guardrail to add
+   * @returns {GuardrailChain} this for chaining
+   */
+  add(guardrail) {
+    if (!(guardrail instanceof BaseGuardrail)) {
+      throw new Error('Can only add BaseGuardrail instances to the chain');
+    }
+    this.guardrails.push(guardrail);
+    return this;
+  }
+
+  /**
+   * Add multiple guardrails to the chain
+   * @param {Array<BaseGuardrail>} guardrails - Guardrails to add
+   * @returns {GuardrailChain} this for chaining
+   */
+  addAll(guardrails) {
+    guardrails.forEach(g => this.add(g));
+    return this;
+  }
+
+  /**
+   * Run all guardrails in the chain
+   * @param {*} input - Input to validate
+   * @param {Object} [context] - Execution context
+   * @returns {Promise<Object>} Combined result
+   */
+  async run(input, context = {}) {
+    const startTime = Date.now();
+    const results = [];
+    const allViolations = [];
+    let overallPassed = true;
+
+    if (this.parallel) {
+      // Parallel execution with optional early termination
+      const promises = this.guardrails.map(g => g.run(input, context));
+      
+      if (this.stopOnFirstFailure) {
+        // Use Promise.race pattern for early termination
+        const settledResults = await Promise.allSettled(promises);
+        
+        for (const settled of settledResults) {
+          if (settled.status === 'fulfilled') {
+            const result = settled.value;
+            results.push(result);
+            
+            if (!result.passed) {
+              overallPassed = false;
+              allViolations.push(...result.violations);
+            }
+          } else {
+            // Handle rejected promise (tripwire or error)
+            throw settled.reason;
+          }
+        }
+      } else {
+        const resolvedResults = await Promise.all(promises);
+        for (const result of resolvedResults) {
+          results.push(result);
+          if (!result.passed) {
+            overallPassed = false;
+            allViolations.push(...result.violations);
+          }
+        }
+      }
+    } else {
+      // Sequential execution
+      for (const guardrail of this.guardrails) {
+        const result = await guardrail.run(input, context);
+        results.push(result);
+        
+        if (!result.passed) {
+          overallPassed = false;
+          allViolations.push(...result.violations);
+          
+          if (this.stopOnFirstFailure) {
+            break;
+          }
+        }
+      }
+    }
+
+    return {
+      passed: overallPassed,
+      chainName: this.name,
+      results,
+      violations: allViolations,
+      guardrailCount: this.guardrails.length,
+      executedCount: results.length,
+      executionTimeMs: Date.now() - startTime
+    };
+  }
+
+  /**
+   * Get list of guardrails in the chain
+   * @returns {Array<Object>}
+   */
+  getGuardrails() {
+    return this.guardrails.map(g => g.getInfo());
+  }
+
+  /**
+   * Clear all guardrails from the chain
+   */
+  clear() {
+    this.guardrails = [];
+  }
+}
+
+module.exports = {
+  BaseGuardrail,
+  GuardrailChain,
+  GuardrailTripwireException
+};