@vibecheckai/cli 3.2.5 → 3.3.0

package/bin/runners/lib/agent-firewall/reality/index.js

@@ -0,0 +1,332 @@
+/**
+ * Reality Engine
+ * 
+ * Entry point for the Reality State Engine.
+ * Provides a unified API for accessing and monitoring repository reality.
+ * 
+ * Usage:
+ *   const { reality } = require('./reality');
+ *   
+ *   // Get current state
+ *   const state = reality.getState(projectRoot);
+ *   
+ *   // Check if something exists
+ *   reality.routeExists(state, 'GET', '/api/users');
+ *   reality.envVarExists(state, 'JWT_SECRET');
+ *   
+ *   // Watch for changes
+ *   const watcher = reality.watch(projectRoot);
+ *   watcher.on('change', ({ state, changes }) => { ... });
+ */
+
+"use strict";
+
+const {
+  buildRealityState,
+  getRealityState,
+  invalidateCache,
+  routeExists,
+  envVarExists,
+  fileExists,
+  getFilesByDomain,
+  getStateSummary,
+  classifyFileDomain,
+  hashFile,
+} = require("./state");
+
+const { RealityWatcher, createWatcher } = require("./watcher");
+
+/**
+ * Reality Engine singleton
+ */
+const reality = {
+  /**
+   * Get the current reality state for a project
+   * @param {string} projectRoot - Project root directory
+   * @param {Object} options - Options
+   * @returns {RealityState} The reality state
+   */
+  getState(projectRoot, options = {}) {
+    return getRealityState(projectRoot, options);
+  },
+  
+  /**
+   * Build a fresh reality state (bypasses cache)
+   * @param {string} projectRoot - Project root directory
+   * @param {Object} options - Options
+   * @returns {RealityState} The reality state
+   */
+  build(projectRoot, options = {}) {
+    return buildRealityState(projectRoot, { ...options, forceRefresh: true });
+  },
+  
+  /**
+   * Invalidate the cached reality state
+   */
+  invalidate() {
+    invalidateCache();
+  },
+  
+  /**
+   * Create a watcher for reality state changes
+   * @param {string} projectRoot - Project root directory
+   * @param {Object} options - Watcher options
+   * @returns {RealityWatcher} The watcher instance
+   */
+  watch(projectRoot, options = {}) {
+    const watcher = createWatcher(projectRoot, options);
+    return watcher;
+  },
+  
+  /**
+   * Check if a route exists in the reality state
+   * @param {RealityState} state - Reality state
+   * @param {string} method - HTTP method
+   * @param {string} path - Route path
+   * @returns {boolean} True if route exists
+   */
+  routeExists(state, method, path) {
+    return routeExists(state, method, path);
+  },
+  
+  /**
+   * Check if an environment variable exists (is declared)
+   * @param {RealityState} state - Reality state
+   * @param {string} varName - Variable name
+   * @returns {boolean} True if env var is declared
+   */
+  envVarExists(state, varName) {
+    return envVarExists(state, varName);
+  },
+  
+  /**
+   * Check if a file exists in the reality state
+   * @param {RealityState} state - Reality state
+   * @param {string} filePath - File path (relative to project root)
+   * @returns {boolean} True if file exists
+   */
+  fileExists(state, filePath) {
+    return fileExists(state, filePath);
+  },
+  
+  /**
+   * Get all files in a specific domain
+   * @param {RealityState} state - Reality state
+   * @param {string} domain - Domain name (auth, payments, routes, etc.)
+   * @returns {Array} Array of file objects
+   */
+  getFilesByDomain(state, domain) {
+    return getFilesByDomain(state, domain);
+  },
+  
+  /**
+   * Get a summary of the reality state
+   * @param {RealityState} state - Reality state
+   * @returns {Object} Summary object
+   */
+  getSummary(state) {
+    return getStateSummary(state);
+  },
+  
+  /**
+   * Classify a file path into a domain
+   * @param {string} filePath - File path
+   * @returns {string} Domain name
+   */
+  classifyDomain(filePath) {
+    return classifyFileDomain(filePath);
+  },
+  
+  /**
+   * Calculate a file's content hash
+   * @param {string} filePath - Absolute file path
+   * @returns {string|null} Hash or null if file can't be read
+   */
+  hashFile(filePath) {
+    return hashFile(filePath);
+  },
+  
+  /**
+   * Validate assumptions against reality
+   * @param {RealityState} state - Reality state
+   * @param {Array} assumptions - Array of assumptions to validate
+   * @returns {Object} Validation results
+   */
+  validateAssumptions(state, assumptions) {
+    const results = {
+      valid: [],
+      invalid: [],
+      unknown: [],
+    };
+    
+    for (const assumption of assumptions) {
+      const result = {
+        assumption,
+        status: "unknown",
+        evidence: null,
+      };
+      
+      switch (assumption.type) {
+        case "env":
+          if (envVarExists(state, assumption.key)) {
+            result.status = "valid";
+            result.evidence = state.envVars.get(assumption.key);
+          } else {
+            result.status = "invalid";
+            result.evidence = `Environment variable '${assumption.key}' is not declared`;
+          }
+          break;
+          
+        case "route":
+          if (routeExists(state, assumption.method || "GET", assumption.path)) {
+            result.status = "valid";
+            const route = state.routes.find(r => 
+              r.path === assumption.path || 
+              r.method.toUpperCase() === (assumption.method || "GET").toUpperCase()
+            );
+            result.evidence = route;
+          } else {
+            result.status = "invalid";
+            result.evidence = `Route '${assumption.method || "GET"} ${assumption.path}' is not registered`;
+          }
+          break;
+          
+        case "file":
+          if (fileExists(state, assumption.path)) {
+            result.status = "valid";
+            result.evidence = state.files.get(assumption.path.replace(/\\/g, "/"));
+          } else {
+            result.status = "invalid";
+            result.evidence = `File '${assumption.path}' does not exist`;
+          }
+          break;
+          
+        case "service":
+          const service = state.services.find(s => 
+            s.name === assumption.name || s.name === assumption.key
+          );
+          if (service) {
+            result.status = "valid";
+            result.evidence = service;
+          } else {
+            result.status = "invalid";
+            result.evidence = `Service '${assumption.name || assumption.key}' is not registered`;
+          }
+          break;
+          
+        default:
+          result.status = "unknown";
+          result.evidence = `Unknown assumption type: ${assumption.type}`;
+      }
+      
+      if (result.status === "valid") {
+        results.valid.push(result);
+      } else if (result.status === "invalid") {
+        results.invalid.push(result);
+      } else {
+        results.unknown.push(result);
+      }
+    }
+    
+    return results;
+  },
+  
+  /**
+   * Get reality diff between two states
+   * @param {RealityState} oldState - Previous state
+   * @param {RealityState} newState - Current state
+   * @returns {Object} Diff object
+   */
+  diff(oldState, newState) {
+    const diff = {
+      files: {
+        added: [],
+        removed: [],
+        modified: [],
+      },
+      routes: {
+        added: [],
+        removed: [],
+      },
+      envVars: {
+        added: [],
+        removed: [],
+      },
+    };
+    
+    // File diff
+    const oldFiles = new Set(oldState.files.keys());
+    const newFiles = new Set(newState.files.keys());
+    
+    for (const file of newFiles) {
+      if (!oldFiles.has(file)) {
+        diff.files.added.push(file);
+      } else {
+        const oldMeta = oldState.files.get(file);
+        const newMeta = newState.files.get(file);
+        if (oldMeta.hash !== newMeta.hash) {
+          diff.files.modified.push(file);
+        }
+      }
+    }
+    
+    for (const file of oldFiles) {
+      if (!newFiles.has(file)) {
+        diff.files.removed.push(file);
+      }
+    }
+    
+    // Route diff
+    const oldRoutes = new Set(oldState.routes.map(r => `${r.method}:${r.path}`));
+    const newRoutes = new Set(newState.routes.map(r => `${r.method}:${r.path}`));
+    
+    for (const route of newState.routes) {
+      const key = `${route.method}:${route.path}`;
+      if (!oldRoutes.has(key)) {
+        diff.routes.added.push(route);
+      }
+    }
+    
+    for (const route of oldState.routes) {
+      const key = `${route.method}:${route.path}`;
+      if (!newRoutes.has(key)) {
+        diff.routes.removed.push(route);
+      }
+    }
+    
+    // Env var diff
+    const oldEnvVars = new Set(oldState.envVars.keys());
+    const newEnvVars = new Set(newState.envVars.keys());
+    
+    for (const varName of newEnvVars) {
+      if (!oldEnvVars.has(varName)) {
+        diff.envVars.added.push(varName);
+      }
+    }
+    
+    for (const varName of oldEnvVars) {
+      if (!newEnvVars.has(varName)) {
+        diff.envVars.removed.push(varName);
+      }
+    }
+    
+    return diff;
+  },
+};
+
+module.exports = {
+  reality,
+  RealityWatcher,
+  createWatcher,
+  // Re-export individual functions for direct access
+  buildRealityState,
+  getRealityState,
+  invalidateCache,
+  routeExists,
+  envVarExists,
+  fileExists,
+  getFilesByDomain,
+  getStateSummary,
+  classifyFileDomain,
+  hashFile,
+};