universal-dev-standards 4.1.0 → 5.0.0-beta.10

package/src/hitl/checkpoint.js

@@ -0,0 +1,80 @@
+/**
+ * HITL Checkpoint
+ * Evaluates risk level against configuration to determine action.
+ */
+
+export class Checkpoint {
+  /**
+   * Evaluate an operation risk.
+   * @param {number} riskLevel - 0-4
+   * @param {Object} config - HITL configuration object
+   * @param {string} operation - Operation string (for pattern matching overrides)
+   * @returns {'approve' | 'prompt' | 'deny'} Action
+   */
+  evaluate(riskLevel, config, operation) {
+    const { 
+      threshold = 2, 
+      overrides = [], 
+      'always-prompt': alwaysPrompt = [], 
+      'never-prompt': neverPrompt = [] 
+    } = config;
+
+    // 1. Check explicit string matches (highest priority)
+    // Note: In real implementation, these would be regex patterns from config
+    // Simplified for now: assume config patterns are simple strings or regex strings
+    
+    // Check always-prompt
+    if (this._matchesAny(operation, alwaysPrompt)) {
+      return 'prompt';
+    }
+
+    // Check never-prompt
+    if (this._matchesAny(operation, neverPrompt)) {
+      return 'approve';
+    }
+
+    // 2. Check overrides (Pattern-based threshold adjustment)
+    let effectiveThreshold = threshold;
+    for (const override of overrides) {
+      if (this._matches(operation, override.pattern)) {
+        effectiveThreshold = override.threshold;
+        // Keep checking to find the most specific/last match? 
+        // For now, first match wins or last match wins? Usually last match wins in cascading.
+        // Let's assume the overrides list is ordered by priority.
+      }
+    }
+
+    // 3. Level 4 Restricted Safety Net
+    if (riskLevel >= 4) {
+      // Level 4 always requires explicit prompt or deny, never auto-approve based on standard threshold
+      // Unless explicitly overridden by a specific pattern with threshold 4+
+      return 'prompt'; 
+      // TODO: Should we return 'deny' by default for Level 4?
+      // Spec says: "Block unless override". "Block" usually means Deny.
+      // But for usability, maybe 'prompt' with a scary warning is better?
+      // Let's stick to 'prompt' for now, but the Manager should handle it carefully.
+    }
+
+    // 4. Standard Threshold Check
+    if (riskLevel < effectiveThreshold) {
+      return 'approve';
+    }
+
+    return 'prompt';
+  }
+
+  _matchesAny(text, patterns) {
+    if (!patterns || !Array.isArray(patterns)) return false;
+    return patterns.some(p => this._matches(text, p));
+  }
+
+  _matches(text, pattern) {
+    if (!text || !pattern) return false;
+    try {
+      // Simple includes check or Regex
+      return text.includes(pattern) || new RegExp(pattern).test(text);
+    } catch (e) {
+      return false;
+    }
+  }
+}

package/src/hitl/classifier.js

@@ -0,0 +1,54 @@
+/**
+ * HITL Risk Classifier
+ * Classifies operations into risk levels (0-4) based on patterns.
+ */
+
+export class RiskClassifier {
+  constructor() {
+    this.rules = [
+      // Level 4: Restricted (Destructive & Hard to Recover)
+      { pattern: /^rm\s+-(r|R|rf|fR)/, level: 4 },
+      { pattern: /drop\s+table/i, level: 4 },
+      { pattern: /git\s+push\s+.*--force/, level: 4 },
+      
+      // Level 3: Critical (Destructive or Security Sensitive)
+      { pattern: /^(delete|remove|unlink)/i, level: 3 },
+      { pattern: /^(deploy|publish|release)/i, level: 3 },
+      { pattern: /(auth|secret|password|token|key)/i, level: 3 },
+      { pattern: /^rm\s+/, level: 3 }, // Simple rm
+      
+      // Level 2: Elevated (Changes Config or Env)
+      { pattern: /^(npm|pip|yarn|pnpm)\s+install/, level: 2 },
+      { pattern: /^config\s+set/, level: 2 },
+      { pattern: /^chmod/, level: 2 },
+      
+      // Level 1: Standard (Modifies Files)
+      { pattern: /^(write|edit|modify|touch|mkdir)/i, level: 1 },
+      { pattern: /^git\s+commit/, level: 1 },
+      
+      // Level 0: Routine (Read-only)
+      { pattern: /^(read|cat|ls|grep|find|search)/i, level: 0 }
+    ];
+  }
+
+  /**
+   * Classify an operation string into a risk level.
+   * @param {string} operation - The operation description or command
+   * @returns {number} Risk level (0-4)
+   */
+  classify(operation) {
+    if (!operation || typeof operation !== 'string') {
+      return 1; // Default to Standard if unknown
+    }
+
+    const op = operation.trim();
+
+    for (const rule of this.rules) {
+      if (rule.pattern.test(op)) {
+        return rule.level;
+      }
+    }
+
+    return 1; // Default to Standard
+  }
+}

package/src/hitl/manager.js

@@ -0,0 +1,88 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { RiskClassifier } from './classifier.js';
+import { Checkpoint } from './checkpoint.js';
+import { config } from '../utils/config-manager.js';
+
+export class HitlManager {
+  constructor() {
+    this.classifier = new RiskClassifier();
+    this.checkpoint = new Checkpoint();
+  }
+
+  /**
+   * Enforce HITL protocol for an operation.
+   * @param {string} operation - Operation description (e.g. "delete file src/main.js")
+   * @param {Object} context - Additional context
+   * @returns {Promise<boolean>} true if allowed, false if blocked
+   */
+  async enforce(operation, context = {}) {
+    const riskLevel = this.classifier.classify(operation);
+    const hitlConfig = config.get('hitl', { threshold: 2 });
+    
+    const decision = this.checkpoint.evaluate(riskLevel, hitlConfig, operation);
+
+    if (decision === 'approve') {
+      // Auto-approve logic could log here if needed
+      return true;
+    }
+
+    if (decision === 'deny') {
+      console.log(chalk.red(''));
+      console.log(chalk.red(`⛔ Operation Blocked (Risk Level ${riskLevel})`));
+      console.log(chalk.gray(`   Operation: ${operation}`));
+      console.log(chalk.gray(`   Reason: HITL threshold is ${hitlConfig.threshold} (Strict)`));
+      return false;
+    }
+
+    // Prompt user
+    return this._promptUser(operation, riskLevel, context);
+  }
+
+  async _promptUser(operation, riskLevel, context) {
+    // Check if we are in non-interactive mode (e.g. CI)
+    if (process.env.CI || process.env.UDS_NON_INTERACTIVE) {
+      console.log(chalk.yellow(''));
+      console.log(chalk.yellow('HITL Checkpoint triggered in non-interactive mode.'));
+      console.log(chalk.gray(`   Operation: ${operation}`));
+      console.log(chalk.red('   Action: Blocked (Safety First)'));
+      return false;
+    }
+
+    console.log(chalk.yellow(''));
+    console.log(chalk.yellow(`⚠️  HITL Checkpoint (Risk Level ${riskLevel})`));
+    console.log(chalk.bold(`   Operation: ${operation}`));
+    
+    if (context.reason) {
+      console.log(chalk.gray(`   Reason: ${context.reason}`));
+    }
+
+    const { action } = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'action',
+        message: 'How would you like to proceed?',
+        choices: [
+          { name: 'Approve', value: 'approve' },
+          { name: 'Deny', value: 'deny' },
+          { name: 'Show Details', value: 'details' }
+        ]
+      }
+    ]);
+
+    if (action === 'details') {
+      console.log(chalk.gray(''));
+      console.log(chalk.gray('--- Operation Details ---'));
+      console.log(chalk.gray(JSON.stringify(context, null, 2)));
+      console.log(chalk.gray('-------------------------'));
+      console.log('');
+      // Recursive call to prompt again
+      return this._promptUser(operation, riskLevel, context);
+    }
+
+    return action === 'approve';
+  }
+}
+
+// Singleton instance
+export const hitl = new HitlManager();