@vibecheckai/cli 3.8.0 → 3.9.0

package/bin/runners/lib/agent-firewall/intent/schema.js

@@ -1,352 +1,352 @@
-/**
- * Intent Schema v2 - Enforcement-Grade Intent Declaration
- * 
- * ═══════════════════════════════════════════════════════════════════════════════
- * AGENT FIREWALL™ - INTENT DECLARATION SYSTEM
- * ═══════════════════════════════════════════════════════════════════════════════
- * 
- * Intent is the foundation of the Agent Firewall enforcement model.
- * All AI actions MUST be checked against declared intent.
- * 
- * Properties:
- * - Intent is explicit, human-written, short, and structured
- * - Intent is captured BEFORE any AI code generation
- * - Intent is IMMUTABLE during a session unless explicitly updated
- * - If intent is missing → Agent Firewall defaults to BLOCK
- * 
- * @module intent/schema
- * @version 2.0.0
- */
-
-"use strict";
-
-const crypto = require("crypto");
-
-/**
- * Intent Declaration JSON Schema
- */
-const INTENT_SCHEMA = {
-  $schema: "http://json-schema.org/draft-07/schema#",
-  $id: "https://vibecheckai.dev/schemas/intent/v2",
-  type: "object",
-  required: ["summary", "constraints", "created_at", "hash"],
-  properties: {
-    // Core required fields
-    summary: {
-      type: "string",
-      description: "Human-written summary of what the change intends to accomplish",
-      minLength: 10,
-      maxLength: 500,
-    },
-    constraints: {
-      type: "array",
-      description: "Explicit constraints that MUST be respected. Violations = BLOCK.",
-      items: {
-        type: "string",
-        minLength: 5,
-      },
-      minItems: 0,
-    },
-    allowed_changes: {
-      type: "array",
-      description: "Explicit list of allowed modifications (files, routes, env vars)",
-      items: {
-        type: "object",
-        required: ["type", "target"],
-        properties: {
-          type: {
-            type: "string",
-            enum: ["file_create", "file_modify", "file_delete", "route_add", "route_modify", "env_add", "permission_modify", "config_change"],
-            description: "Type of allowed change",
-          },
-          target: {
-            type: "string",
-            description: "Target of the change (file path, route pattern, env var name)",
-          },
-          pattern: {
-            type: "string",
-            description: "Glob pattern for matching multiple targets",
-          },
-          reason: {
-            type: "string",
-            description: "Why this change is allowed",
-          },
-        },
-      },
-    },
-    created_at: {
-      type: "string",
-      format: "date-time",
-      description: "ISO timestamp when intent was declared",
-    },
-    hash: {
-      type: "string",
-      pattern: "^[a-f0-9]{64}$",
-      description: "SHA-256 hash of intent content for immutability verification",
-    },
-    
-    // Optional metadata
-    session_id: {
-      type: "string",
-      description: "Session identifier for tracking",
-    },
-    author: {
-      type: "string",
-      description: "Who declared the intent (user identifier)",
-    },
-    version: {
-      type: "number",
-      description: "Intent version (increments on explicit update)",
-      minimum: 1,
-    },
-    parent_hash: {
-      type: "string",
-      description: "Hash of parent intent if this is an update",
-    },
-    expires_at: {
-      type: "string",
-      format: "date-time",
-      description: "Optional expiration time for the intent",
-    },
-    scope: {
-      type: "object",
-      description: "Scope restrictions for the intent",
-      properties: {
-        directories: {
-          type: "array",
-          items: { type: "string" },
-          description: "Allowed directories for changes",
-        },
-        file_patterns: {
-          type: "array",
-          items: { type: "string" },
-          description: "Allowed file glob patterns",
-        },
-        domains: {
-          type: "array",
-          items: { 
-            type: "string",
-            enum: ["auth", "payments", "routes", "contracts", "ui", "database", "config", "general"],
-          },
-          description: "Allowed domains for changes",
-        },
-        excluded_paths: {
-          type: "array",
-          items: { type: "string" },
-          description: "Explicitly excluded paths",
-        },
-      },
-    },
-  },
-  additionalProperties: false,
-};
-
-/**
- * Compute content hash for intent immutability verification
- * @param {Object} intent - Intent object (without hash)
- * @returns {string} SHA-256 hash
- */
-function computeIntentHash(intent) {
-  // Normalize intent for consistent hashing
-  const normalized = {
-    summary: intent.summary?.trim() || "",
-    constraints: (intent.constraints || []).map(c => c.trim()).sort(),
-    allowed_changes: (intent.allowed_changes || [])
-      .map(c => ({ type: c.type, target: c.target, pattern: c.pattern }))
-      .sort((a, b) => `${a.type}:${a.target}`.localeCompare(`${b.type}:${b.target}`)),
-    created_at: intent.created_at,
-  };
-  
-  const content = JSON.stringify(normalized, null, 0);
-  return crypto.createHash("sha256").update(content).digest("hex");
-}
-
-/**
- * Create a new intent declaration
- * @param {Object} params - Intent parameters
- * @param {string} params.summary - Human-readable summary
- * @param {string[]} params.constraints - Constraints to enforce
- * @param {Object[]} params.allowed_changes - Explicitly allowed changes
- * @param {Object} params.scope - Scope restrictions
- * @param {string} params.author - Who declared the intent
- * @param {string} params.session_id - Session identifier
- * @returns {Object} Complete intent object with hash
- */
-function createIntent({
-  summary,
-  constraints = [],
-  allowed_changes = [],
-  scope = null,
-  author = null,
-  session_id = null,
-}) {
-  const created_at = new Date().toISOString();
-  
-  const intent = {
-    summary: summary?.trim(),
-    constraints: constraints.map(c => c.trim()).filter(Boolean),
-    allowed_changes,
-    created_at,
-    version: 1,
-    hash: "", // Placeholder
-  };
-  
-  // Add optional fields
-  if (scope) intent.scope = scope;
-  if (author) intent.author = author;
-  if (session_id) intent.session_id = session_id;
-  
-  // Compute and set hash
-  intent.hash = computeIntentHash(intent);
-  
-  return intent;
-}
-
-/**
- * Verify intent has not been tampered with
- * @param {Object} intent - Intent to verify
- * @returns {Object} Verification result { valid, computed_hash, stored_hash }
- */
-function verifyIntentIntegrity(intent) {
-  if (!intent || !intent.hash) {
-    return {
-      valid: false,
-      reason: "MISSING_HASH",
-      computed_hash: null,
-      stored_hash: null,
-    };
-  }
-  
-  const computed = computeIntentHash(intent);
-  const stored = intent.hash;
-  
-  return {
-    valid: computed === stored,
-    reason: computed === stored ? "VERIFIED" : "HASH_MISMATCH",
-    computed_hash: computed,
-    stored_hash: stored,
-  };
-}
-
-/**
- * Update an existing intent (creates new version with parent reference)
- * @param {Object} currentIntent - Current intent
- * @param {Object} updates - Fields to update
- * @returns {Object} New intent with incremented version
- */
-function updateIntent(currentIntent, updates) {
-  const parent_hash = currentIntent.hash;
-  const version = (currentIntent.version || 1) + 1;
-  
-  const newIntent = {
-    ...currentIntent,
-    ...updates,
-    created_at: new Date().toISOString(),
-    version,
-    parent_hash,
-    hash: "", // Will be recomputed
-  };
-  
-  // Ensure constraints are clean
-  if (newIntent.constraints) {
-    newIntent.constraints = newIntent.constraints.map(c => c.trim()).filter(Boolean);
-  }
-  
-  // Recompute hash
-  newIntent.hash = computeIntentHash(newIntent);
-  
-  return newIntent;
-}
-
-/**
- * Check if intent is expired
- * @param {Object} intent - Intent to check
- * @returns {boolean} True if expired
- */
-function isIntentExpired(intent) {
-  if (!intent.expires_at) return false;
-  return new Date(intent.expires_at) < new Date();
-}
-
-/**
- * Create a minimal blocking intent (for when no intent is declared)
- * This intent blocks ALL changes by having no allowed_changes.
- * @returns {Object} Blocking intent
- */
-function createBlockingIntent() {
-  return createIntent({
-    summary: "NO INTENT DECLARED - ALL CHANGES BLOCKED BY DEFAULT",
-    constraints: [
-      "No changes allowed without explicit intent declaration",
-      "All file operations blocked",
-      "All route additions blocked",
-      "All env var references blocked",
-    ],
-    allowed_changes: [],
-    scope: {
-      directories: [],
-      file_patterns: [],
-      domains: [],
-    },
-  });
-}
-
-/**
- * Intent constraint types for enforcement
- */
-const CONSTRAINT_TYPES = {
-  NO_NEW_ROUTES: "no_new_routes",
-  NO_AUTH_CHANGES: "no_auth_changes",
-  NO_PAYMENT_CHANGES: "no_payment_changes",
-  NO_DATABASE_MIGRATIONS: "no_database_migrations",
-  NO_ENV_ADDITIONS: "no_env_additions",
-  NO_PERMISSION_CHANGES: "no_permission_changes",
-  NO_EXTERNAL_CALLS: "no_external_calls",
-  NO_FILE_DELETIONS: "no_file_deletions",
-  SINGLE_FILE_ONLY: "single_file_only",
-  TESTS_REQUIRED: "tests_required",
-  REVIEW_REQUIRED: "review_required",
-};
-
-/**
- * Pre-built constraint templates
- */
-const CONSTRAINT_TEMPLATES = {
-  STRICT_BUGFIX: [
-    "No new routes allowed",
-    "No auth logic changes",
-    "No new environment variables",
-    "Changes limited to specified file(s)",
-    "No new dependencies",
-  ],
-  FEATURE_ADDITION: [
-    "New routes must be documented in intent",
-    "No changes to existing auth logic",
-    "New env vars must be declared",
-    "Tests required for new functionality",
-  ],
-  REFACTOR: [
-    "No behavior changes",
-    "No new routes",
-    "No API contract changes",
-    "No auth boundary changes",
-  ],
-  SECURITY_PATCH: [
-    "Auth changes must be explicit in intent",
-    "No new external endpoints",
-    "No permission relaxation",
-    "Review required before ship",
-  ],
-};
-
-module.exports = {
-  INTENT_SCHEMA,
-  createIntent,
-  computeIntentHash,
-  verifyIntentIntegrity,
-  updateIntent,
-  isIntentExpired,
-  createBlockingIntent,
-  CONSTRAINT_TYPES,
-  CONSTRAINT_TEMPLATES,
-};
+/**
+ * Intent Schema v2 - Enforcement-Grade Intent Declaration
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * AGENT FIREWALL™ - INTENT DECLARATION SYSTEM
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * Intent is the foundation of the Agent Firewall enforcement model.
+ * All AI actions MUST be checked against declared intent.
+ * 
+ * Properties:
+ * - Intent is explicit, human-written, short, and structured
+ * - Intent is captured BEFORE any AI code generation
+ * - Intent is IMMUTABLE during a session unless explicitly updated
+ * - If intent is missing → Agent Firewall defaults to BLOCK
+ * 
+ * @module intent/schema
+ * @version 2.0.0
+ */
+
+"use strict";
+
+const crypto = require("crypto");
+
+/**
+ * Intent Declaration JSON Schema
+ */
+const INTENT_SCHEMA = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://vibecheckai.dev/schemas/intent/v2",
+  type: "object",
+  required: ["summary", "constraints", "created_at", "hash"],
+  properties: {
+    // Core required fields
+    summary: {
+      type: "string",
+      description: "Human-written summary of what the change intends to accomplish",
+      minLength: 10,
+      maxLength: 500,
+    },
+    constraints: {
+      type: "array",
+      description: "Explicit constraints that MUST be respected. Violations = BLOCK.",
+      items: {
+        type: "string",
+        minLength: 5,
+      },
+      minItems: 0,
+    },
+    allowed_changes: {
+      type: "array",
+      description: "Explicit list of allowed modifications (files, routes, env vars)",
+      items: {
+        type: "object",
+        required: ["type", "target"],
+        properties: {
+          type: {
+            type: "string",
+            enum: ["file_create", "file_modify", "file_delete", "route_add", "route_modify", "env_add", "permission_modify", "config_change"],
+            description: "Type of allowed change",
+          },
+          target: {
+            type: "string",
+            description: "Target of the change (file path, route pattern, env var name)",
+          },
+          pattern: {
+            type: "string",
+            description: "Glob pattern for matching multiple targets",
+          },
+          reason: {
+            type: "string",
+            description: "Why this change is allowed",
+          },
+        },
+      },
+    },
+    created_at: {
+      type: "string",
+      format: "date-time",
+      description: "ISO timestamp when intent was declared",
+    },
+    hash: {
+      type: "string",
+      pattern: "^[a-f0-9]{64}$",
+      description: "SHA-256 hash of intent content for immutability verification",
+    },
+    
+    // Optional metadata
+    session_id: {
+      type: "string",
+      description: "Session identifier for tracking",
+    },
+    author: {
+      type: "string",
+      description: "Who declared the intent (user identifier)",
+    },
+    version: {
+      type: "number",
+      description: "Intent version (increments on explicit update)",
+      minimum: 1,
+    },
+    parent_hash: {
+      type: "string",
+      description: "Hash of parent intent if this is an update",
+    },
+    expires_at: {
+      type: "string",
+      format: "date-time",
+      description: "Optional expiration time for the intent",
+    },
+    scope: {
+      type: "object",
+      description: "Scope restrictions for the intent",
+      properties: {
+        directories: {
+          type: "array",
+          items: { type: "string" },
+          description: "Allowed directories for changes",
+        },
+        file_patterns: {
+          type: "array",
+          items: { type: "string" },
+          description: "Allowed file glob patterns",
+        },
+        domains: {
+          type: "array",
+          items: { 
+            type: "string",
+            enum: ["auth", "payments", "routes", "contracts", "ui", "database", "config", "general"],
+          },
+          description: "Allowed domains for changes",
+        },
+        excluded_paths: {
+          type: "array",
+          items: { type: "string" },
+          description: "Explicitly excluded paths",
+        },
+      },
+    },
+  },
+  additionalProperties: false,
+};
+
+/**
+ * Compute content hash for intent immutability verification
+ * @param {Object} intent - Intent object (without hash)
+ * @returns {string} SHA-256 hash
+ */
+function computeIntentHash(intent) {
+  // Normalize intent for consistent hashing
+  const normalized = {
+    summary: intent.summary?.trim() || "",
+    constraints: (intent.constraints || []).map(c => c.trim()).sort(),
+    allowed_changes: (intent.allowed_changes || [])
+      .map(c => ({ type: c.type, target: c.target, pattern: c.pattern }))
+      .sort((a, b) => `${a.type}:${a.target}`.localeCompare(`${b.type}:${b.target}`)),
+    created_at: intent.created_at,
+  };
+  
+  const content = JSON.stringify(normalized, null, 0);
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+/**
+ * Create a new intent declaration
+ * @param {Object} params - Intent parameters
+ * @param {string} params.summary - Human-readable summary
+ * @param {string[]} params.constraints - Constraints to enforce
+ * @param {Object[]} params.allowed_changes - Explicitly allowed changes
+ * @param {Object} params.scope - Scope restrictions
+ * @param {string} params.author - Who declared the intent
+ * @param {string} params.session_id - Session identifier
+ * @returns {Object} Complete intent object with hash
+ */
+function createIntent({
+  summary,
+  constraints = [],
+  allowed_changes = [],
+  scope = null,
+  author = null,
+  session_id = null,
+}) {
+  const created_at = new Date().toISOString();
+  
+  const intent = {
+    summary: summary?.trim(),
+    constraints: constraints.map(c => c.trim()).filter(Boolean),
+    allowed_changes,
+    created_at,
+    version: 1,
+    hash: "", // Placeholder
+  };
+  
+  // Add optional fields
+  if (scope) intent.scope = scope;
+  if (author) intent.author = author;
+  if (session_id) intent.session_id = session_id;
+  
+  // Compute and set hash
+  intent.hash = computeIntentHash(intent);
+  
+  return intent;
+}
+
+/**
+ * Verify intent has not been tampered with
+ * @param {Object} intent - Intent to verify
+ * @returns {Object} Verification result { valid, computed_hash, stored_hash }
+ */
+function verifyIntentIntegrity(intent) {
+  if (!intent || !intent.hash) {
+    return {
+      valid: false,
+      reason: "MISSING_HASH",
+      computed_hash: null,
+      stored_hash: null,
+    };
+  }
+  
+  const computed = computeIntentHash(intent);
+  const stored = intent.hash;
+  
+  return {
+    valid: computed === stored,
+    reason: computed === stored ? "VERIFIED" : "HASH_MISMATCH",
+    computed_hash: computed,
+    stored_hash: stored,
+  };
+}
+
+/**
+ * Update an existing intent (creates new version with parent reference)
+ * @param {Object} currentIntent - Current intent
+ * @param {Object} updates - Fields to update
+ * @returns {Object} New intent with incremented version
+ */
+function updateIntent(currentIntent, updates) {
+  const parent_hash = currentIntent.hash;
+  const version = (currentIntent.version || 1) + 1;
+  
+  const newIntent = {
+    ...currentIntent,
+    ...updates,
+    created_at: new Date().toISOString(),
+    version,
+    parent_hash,
+    hash: "", // Will be recomputed
+  };
+  
+  // Ensure constraints are clean
+  if (newIntent.constraints) {
+    newIntent.constraints = newIntent.constraints.map(c => c.trim()).filter(Boolean);
+  }
+  
+  // Recompute hash
+  newIntent.hash = computeIntentHash(newIntent);
+  
+  return newIntent;
+}
+
+/**
+ * Check if intent is expired
+ * @param {Object} intent - Intent to check
+ * @returns {boolean} True if expired
+ */
+function isIntentExpired(intent) {
+  if (!intent.expires_at) return false;
+  return new Date(intent.expires_at) < new Date();
+}
+
+/**
+ * Create a minimal blocking intent (for when no intent is declared)
+ * This intent blocks ALL changes by having no allowed_changes.
+ * @returns {Object} Blocking intent
+ */
+function createBlockingIntent() {
+  return createIntent({
+    summary: "NO INTENT DECLARED - ALL CHANGES BLOCKED BY DEFAULT",
+    constraints: [
+      "No changes allowed without explicit intent declaration",
+      "All file operations blocked",
+      "All route additions blocked",
+      "All env var references blocked",
+    ],
+    allowed_changes: [],
+    scope: {
+      directories: [],
+      file_patterns: [],
+      domains: [],
+    },
+  });
+}
+
+/**
+ * Intent constraint types for enforcement
+ */
+const CONSTRAINT_TYPES = {
+  NO_NEW_ROUTES: "no_new_routes",
+  NO_AUTH_CHANGES: "no_auth_changes",
+  NO_PAYMENT_CHANGES: "no_payment_changes",
+  NO_DATABASE_MIGRATIONS: "no_database_migrations",
+  NO_ENV_ADDITIONS: "no_env_additions",
+  NO_PERMISSION_CHANGES: "no_permission_changes",
+  NO_EXTERNAL_CALLS: "no_external_calls",
+  NO_FILE_DELETIONS: "no_file_deletions",
+  SINGLE_FILE_ONLY: "single_file_only",
+  TESTS_REQUIRED: "tests_required",
+  REVIEW_REQUIRED: "review_required",
+};
+
+/**
+ * Pre-built constraint templates
+ */
+const CONSTRAINT_TEMPLATES = {
+  STRICT_BUGFIX: [
+    "No new routes allowed",
+    "No auth logic changes",
+    "No new environment variables",
+    "Changes limited to specified file(s)",
+    "No new dependencies",
+  ],
+  FEATURE_ADDITION: [
+    "New routes must be documented in intent",
+    "No changes to existing auth logic",
+    "New env vars must be declared",
+    "Tests required for new functionality",
+  ],
+  REFACTOR: [
+    "No behavior changes",
+    "No new routes",
+    "No API contract changes",
+    "No auth boundary changes",
+  ],
+  SECURITY_PATCH: [
+    "Auth changes must be explicit in intent",
+    "No new external endpoints",
+    "No permission relaxation",
+    "Review required before ship",
+  ],
+};
+
+module.exports = {
+  INTENT_SCHEMA,
+  createIntent,
+  computeIntentHash,
+  verifyIntentIntegrity,
+  updateIntent,
+  isIntentExpired,
+  createBlockingIntent,
+  CONSTRAINT_TYPES,
+  CONSTRAINT_TEMPLATES,
+};