@vibecheckai/cli 3.7.0 → 3.9.0

package/bin/runners/lib/missions/schema.js

@@ -0,0 +1,478 @@
+// bin/runners/lib/missions/schema.js
+// ═══════════════════════════════════════════════════════════════════════════════
+// MISSION SCHEMA - Formal definition for Fix Missions V2
+// "Missions, not chaos" - Each mission is a well-defined, reversible operation
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const crypto = require('crypto');
+const {
+  ValidationError,
+  isValidFilePath,
+  isValidConfidence,
+  getAuditTrail,
+} = require('./hardening');
+
+/**
+ * @typedef {object} MissionObjective
+ * @property {string} title - Mission title
+ * @property {string} intent - What we're trying to achieve
+ * @property {string[]} successCriteria - How we know we succeeded
+ * @property {string[]} targetFindingIds - Which findings this resolves
+ * @property {number} findingCount - Number of findings targeted
+ * @property {string} category - Finding category
+ * @property {string} severity - Finding severity
+ */
+
+/**
+ * @typedef {object} MissionScope
+ * @property {string[]} allowedFiles - Files LLM may edit
+ * @property {string[]} readOnlyContext - Files for context only
+ * @property {string} blastRadius - Blast radius category
+ * @property {string|null} primaryFile - Primary file to edit
+ */
+
+/**
+ * @typedef {object} MissionVerification
+ * @property {string} proofType - What to run after (ship|lint|test|custom)
+ * @property {string} expectedOutcome - Expected result
+ * @property {number} timeout - Verification timeout in ms
+ * @property {number} retries - Number of retries attempted
+ */
+
+/**
+ * @typedef {object} MissionSafety
+ * @property {boolean} reversible - Can be rolled back
+ * @property {boolean} requiresApproval - Needs human approval
+ * @property {number} confidence - Combined finding confidence (0-1)
+ * @property {string} riskLevel - Risk level category
+ * @property {string|null} checkpointId - Checkpoint to rollback to
+ */
+
+/**
+ * @typedef {object} MissionTemplate
+ * @property {string|null} intent - Template intent
+ * @property {string[]} do - Actions to take
+ * @property {string[]} dont - Actions to avoid
+ * @property {string[]} success - Success criteria
+ */
+
+/**
+ * @typedef {object} Mission
+ * @property {string} id - Stable mission ID (M_xxx)
+ * @property {string} type - Mission type
+ * @property {string} status - Current status
+ * @property {string} createdAt - ISO timestamp
+ * @property {string} [updatedAt] - ISO timestamp
+ * @property {MissionObjective} objective - Mission objective
+ * @property {MissionScope} scope - Files in scope
+ * @property {MissionVerification} verification - Verification config
+ * @property {MissionSafety} safety - Safety metadata
+ * @property {MissionTemplate} template - LLM prompt template
+ * @property {object[]} evidence - Evidence from findings
+ */
+
+/**
+ * Risk levels for missions
+ */
+const RISK_LEVEL = {
+  LOW: 'low',
+  MEDIUM: 'medium',
+  HIGH: 'high',
+  CRITICAL: 'critical',
+};
+
+/**
+ * Blast radius categories
+ */
+const BLAST_RADIUS = {
+  LOW: 'low',       // 1-2 files
+  MEDIUM: 'medium', // 3-5 files
+  HIGH: 'high',     // 6+ files
+};
+
+/**
+ * Proof types for verification
+ */
+const PROOF_TYPE = {
+  SHIP: 'ship',     // Run vibecheck ship
+  LINT: 'lint',     // Run linter
+  TEST: 'test',     // Run tests
+  CUSTOM: 'custom', // Custom verification
+};
+
+/**
+ * Expected outcomes for verification
+ */
+const EXPECTED_OUTCOME = {
+  FINDING_REMOVED: 'finding_removed',
+  TEST_PASS: 'test_pass',
+  SCORE_DECREASE: 'score_decrease',
+  NO_REGRESSION: 'no_regression',
+};
+
+/**
+ * Mission status
+ */
+const MISSION_STATUS = {
+  PLANNED: 'planned',
+  PENDING: 'pending',
+  IN_PROGRESS: 'in_progress',
+  COMPLETED: 'completed',
+  FAILED: 'failed',
+  ROLLED_BACK: 'rolled_back',
+  SKIPPED: 'skipped',
+};
+
+/**
+ * Generate a stable mission ID from finding IDs
+ * @param {string} type - Mission type
+ * @param {string[]} findingIds - Target finding IDs
+ * @returns {string} Stable mission ID
+ */
+function generateMissionId(type, findingIds) {
+  const sorted = [...findingIds].sort();
+  const hash = crypto
+    .createHash('sha256')
+    .update(`${type}:${sorted.join(',')}`)
+    .digest('hex')
+    .slice(0, 12);
+  return `M_${hash}`;
+}
+
+/**
+ * Calculate blast radius from file count
+ * @param {number} fileCount - Number of files affected
+ * @returns {string} Blast radius category
+ */
+function calculateBlastRadius(fileCount) {
+  if (fileCount <= 2) return BLAST_RADIUS.LOW;
+  if (fileCount <= 5) return BLAST_RADIUS.MEDIUM;
+  return BLAST_RADIUS.HIGH;
+}
+
+/**
+ * Calculate risk level from mission properties
+ * @param {object} params - Mission parameters
+ * @returns {string} Risk level
+ */
+function calculateRiskLevel({ severity, confidence, blastRadius, missionType }) {
+  let score = 0;
+
+  // Severity contribution (0-40 points)
+  if (severity === 'BLOCK') score += 40;
+  else if (severity === 'WARN') score += 20;
+  else score += 5;
+
+  // Confidence inverse contribution (0-20 points)
+  // Lower confidence = higher risk
+  score += Math.round((1 - (confidence || 0.5)) * 20);
+
+  // Blast radius contribution (0-30 points)
+  if (blastRadius === BLAST_RADIUS.HIGH) score += 30;
+  else if (blastRadius === BLAST_RADIUS.MEDIUM) score += 15;
+  else score += 5;
+
+  // Mission type contribution (0-10 points)
+  const criticalTypes = [
+    'FIX_HARDCODED_SECRETS',
+    'REMOVE_OWNER_MODE',
+    'FIX_AUTH_DRIFT',
+    'FIX_STRIPE_WEBHOOKS',
+  ];
+  if (criticalTypes.includes(missionType)) score += 10;
+
+  // Convert score to risk level
+  if (score >= 70) return RISK_LEVEL.CRITICAL;
+  if (score >= 50) return RISK_LEVEL.HIGH;
+  if (score >= 30) return RISK_LEVEL.MEDIUM;
+  return RISK_LEVEL.LOW;
+}
+
+/**
+ * Create a mission object from findings
+ * @param {object} params - Mission creation parameters
+ * @param {string} params.type - Mission type
+ * @param {string} params.title - Mission title
+ * @param {string} params.severity - Finding severity
+ * @param {string} params.category - Finding category
+ * @param {string[]} params.targetFindingIds - IDs of findings to fix
+ * @param {object} [params.template] - Mission template
+ * @param {string[]} [params.allowedFiles] - Files that can be edited
+ * @param {string[]} [params.readOnlyContext] - Files for context only
+ * @param {number} [params.confidence] - Confidence score (0-1)
+ * @param {object[]} [params.evidence] - Evidence from findings
+ * @param {string|null} [params.file] - Primary file
+ * @returns {Mission} Mission object
+ * @throws {ValidationError} If parameters are invalid
+ */
+function createMission({
+  type,
+  title,
+  severity,
+  category,
+  targetFindingIds,
+  template,
+  allowedFiles = [],
+  readOnlyContext = [],
+  confidence = 0.5,
+  evidence = [],
+  file = null,
+}) {
+  const audit = getAuditTrail();
+  
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // INPUT VALIDATION
+  // ═══════════════════════════════════════════════════════════════════════════════
+  
+  // Validate required fields
+  if (!type || typeof type !== 'string') {
+    throw new ValidationError('Mission type is required and must be a string', 'type', type);
+  }
+  
+  if (!targetFindingIds || !Array.isArray(targetFindingIds) || targetFindingIds.length === 0) {
+    throw new ValidationError('targetFindingIds must be a non-empty array', 'targetFindingIds', targetFindingIds);
+  }
+  
+  // Validate confidence
+  if (!isValidConfidence(confidence)) {
+    audit.warn('invalid_confidence', { confidence, default: 0.5 });
+    confidence = 0.5;
+  }
+  
+  // Validate and sanitize file paths
+  const sanitizedAllowedFiles = [];
+  for (const filePath of allowedFiles) {
+    if (isValidFilePath(filePath)) {
+      sanitizedAllowedFiles.push(filePath);
+    } else {
+      audit.warn('invalid_file_path_skipped', { filePath });
+    }
+  }
+  
+  const sanitizedReadOnlyContext = [];
+  for (const filePath of readOnlyContext) {
+    if (isValidFilePath(filePath)) {
+      sanitizedReadOnlyContext.push(filePath);
+    } else {
+      audit.warn('invalid_readonly_path_skipped', { filePath });
+    }
+  }
+  
+  // Validate primary file
+  let sanitizedFile = null;
+  if (file) {
+    if (isValidFilePath(file)) {
+      sanitizedFile = file;
+    } else {
+      audit.warn('invalid_primary_file', { file });
+    }
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // MISSION CONSTRUCTION
+  // ═══════════════════════════════════════════════════════════════════════════════
+  
+  const blastRadius = calculateBlastRadius(sanitizedAllowedFiles.length);
+  const riskLevel = calculateRiskLevel({
+    severity,
+    confidence,
+    blastRadius,
+    missionType: type,
+  });
+
+  const missionId = generateMissionId(type, targetFindingIds);
+  
+  // Sanitize title
+  const sanitizedTitle = (title || `Fix ${type}`).slice(0, 200);
+  
+  // Sanitize severity
+  const validSeverities = ['BLOCK', 'WARN', 'INFO', 'critical', 'high', 'medium', 'low', 'info'];
+  const sanitizedSeverity = validSeverities.includes(severity) ? severity : 'WARN';
+  
+  const mission = {
+    // Identity
+    id: missionId,
+    type,
+    status: MISSION_STATUS.PLANNED,
+    createdAt: new Date().toISOString(),
+
+    // Objective (the "briefing")
+    objective: {
+      title: sanitizedTitle,
+      intent: template?.intent || `Fix ${type} issues`,
+      successCriteria: Array.isArray(template?.success) ? template.success : [`Finding ${targetFindingIds[0]} no longer appears in ship results`],
+      targetFindingIds: [...targetFindingIds], // Defensive copy
+      findingCount: targetFindingIds.length,
+      category: category || 'Unknown',
+      severity: sanitizedSeverity,
+    },
+
+    // Files touched (pre-calculated)
+    scope: {
+      allowedFiles: sanitizedAllowedFiles,
+      readOnlyContext: sanitizedReadOnlyContext,
+      blastRadius,
+      primaryFile: sanitizedFile || sanitizedAllowedFiles[0] || null,
+    },
+
+    // Expected proofs
+    verification: {
+      proofType: PROOF_TYPE.SHIP,
+      expectedOutcome: EXPECTED_OUTCOME.FINDING_REMOVED,
+      timeout: 30000,
+      retries: 0,
+    },
+
+    // Safety metadata
+    safety: {
+      reversible: true,
+      requiresApproval: riskLevel === RISK_LEVEL.CRITICAL,
+      confidence,
+      riskLevel,
+      checkpointId: null, // Set when checkpoint is created
+    },
+
+    // Template for LLM prompt
+    template: {
+      intent: template?.intent || null,
+      do: Array.isArray(template?.do) ? template.do : [],
+      dont: Array.isArray(template?.dont) ? template.dont : [],
+      success: Array.isArray(template?.success) ? template.success : [],
+    },
+
+    // Evidence from findings (defensive copy)
+    evidence: Array.isArray(evidence) ? [...evidence] : [],
+  };
+  
+  audit.debug('mission_created', { 
+    missionId, 
+    type, 
+    findingCount: targetFindingIds.length,
+    fileCount: sanitizedAllowedFiles.length,
+    riskLevel,
+  });
+  
+  return mission;
+}
+
+/**
+ * Validate a mission object
+ * @param {object} mission - Mission to validate
+ * @returns {object} Validation result { valid: boolean, errors: string[] }
+ */
+function validateMission(mission) {
+  const errors = [];
+
+  if (!mission.id || !mission.id.startsWith('M_')) {
+    errors.push('Mission ID must start with "M_"');
+  }
+
+  if (!mission.type) {
+    errors.push('Mission type is required');
+  }
+
+  if (!mission.objective?.targetFindingIds?.length) {
+    errors.push('Mission must target at least one finding');
+  }
+
+  if (!mission.scope?.allowedFiles?.length && !mission.scope?.readOnlyContext?.length) {
+    errors.push('Mission must have at least one file in scope');
+  }
+
+  if (mission.safety?.confidence < 0 || mission.safety?.confidence > 1) {
+    errors.push('Confidence must be between 0 and 1');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Serialize mission to JSON for storage
+ * @param {object} mission - Mission object
+ * @returns {string} JSON string
+ */
+function serializeMission(mission) {
+  return JSON.stringify(mission, null, 2);
+}
+
+/**
+ * Deserialize mission from JSON
+ * @param {string} json - JSON string
+ * @returns {object} Mission object
+ */
+function deserializeMission(json) {
+  const mission = JSON.parse(json);
+  // Ensure all required fields exist with defaults
+  return {
+    ...mission,
+    status: mission.status || MISSION_STATUS.PLANNED,
+    safety: {
+      reversible: true,
+      requiresApproval: false,
+      confidence: 0.5,
+      riskLevel: RISK_LEVEL.MEDIUM,
+      checkpointId: null,
+      ...mission.safety,
+    },
+    verification: {
+      proofType: PROOF_TYPE.SHIP,
+      expectedOutcome: EXPECTED_OUTCOME.FINDING_REMOVED,
+      timeout: 30000,
+      retries: 0,
+      ...mission.verification,
+    },
+  };
+}
+
+/**
+ * Update mission status
+ * @param {object} mission - Mission object
+ * @param {string} status - New status
+ * @param {object} metadata - Additional metadata
+ * @returns {object} Updated mission
+ */
+function updateMissionStatus(mission, status, metadata = {}) {
+  return {
+    ...mission,
+    status,
+    updatedAt: new Date().toISOString(),
+    ...metadata,
+  };
+}
+
+/**
+ * Check if mission is safe to auto-apply
+ * @param {object} mission - Mission object
+ * @returns {boolean} True if safe to auto-apply
+ */
+function isSafeToAutoApply(mission) {
+  return (
+    mission.safety.reversible &&
+    !mission.safety.requiresApproval &&
+    mission.safety.riskLevel !== RISK_LEVEL.CRITICAL &&
+    mission.safety.confidence >= 0.6
+  );
+}
+
+module.exports = {
+  // Constants
+  RISK_LEVEL,
+  BLAST_RADIUS,
+  PROOF_TYPE,
+  EXPECTED_OUTCOME,
+  MISSION_STATUS,
+
+  // Functions
+  generateMissionId,
+  calculateBlastRadius,
+  calculateRiskLevel,
+  createMission,
+  validateMission,
+  serializeMission,
+  deserializeMission,
+  updateMissionStatus,
+  isSafeToAutoApply,
+};