antigravity-ai-kit 3.1.1 → 3.2.0

package/lib/cli-commands.js

@@ -13,6 +13,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { AGENT_DIR, ENGINE_DIR } = require('./constants');
 
 // ANSI colors (shared with ag-kit.js)
 const colors = {
@@ -133,7 +134,7 @@ function healCommand(projectRoot, options = {}) {
     ciOutput = fs.readFileSync(filePath, 'utf-8');
   } else {
     // Try last-saved CI output
-    const lastCiPath = path.join(projectRoot, '.agent', 'engine', 'last-ci-output.txt');
+    const lastCiPath = path.join(projectRoot, AGENT_DIR, ENGINE_DIR, 'last-ci-output.txt');
     if (fs.existsSync(lastCiPath)) {
       ciOutput = fs.readFileSync(lastCiPath, 'utf-8');
     } else {
@@ -228,8 +229,94 @@ function renderDashboardSections(projectRoot) {
   }
 }
 
+/**
+ * Health check CLI handler.
+ * Aggregates error budget, plugin integrity, config validation, and healing status.
+ *
+ * @param {string} projectRoot - Root directory
+ * @returns {{ healthy: boolean, checks: object[] }}
+ */
+function healthCommand(projectRoot) {
+  const checks = [];
+
+  // Error budget health
+  try {
+    const errorBudget = require('./error-budget');
+    const report = errorBudget.getBudgetReport(projectRoot);
+    checks.push({
+      name: 'Error Budget',
+      status: report.status,
+      healthy: report.status !== 'EXHAUSTED',
+      detail: report.violations.length > 0 ? `Violations: ${report.violations.join(', ')}` : 'All rates within thresholds',
+    });
+  } catch {
+    checks.push({ name: 'Error Budget', status: 'SKIPPED', healthy: true, detail: 'No reliability config found' });
+  }
+
+  // Plugin integrity
+  try {
+    const pluginVerifier = require('./plugin-verifier');
+    const result = pluginVerifier.verifyAllPlugins(projectRoot);
+    const pluginHealthy = result.invalid.length === 0;
+    checks.push({
+      name: 'Plugin Integrity',
+      status: pluginHealthy ? 'PASS' : 'FAIL',
+      healthy: pluginHealthy,
+      detail: `${result.valid} valid, ${result.invalid.length} invalid, ${result.unverified.length} unverified`,
+    });
+  } catch {
+    checks.push({ name: 'Plugin Integrity', status: 'SKIPPED', healthy: true, detail: 'Verifier not available' });
+  }
+
+  // Config validation
+  try {
+    const configValidator = require('./config-validator');
+    const result = configValidator.validateAllConfigs(projectRoot);
+    const invalidCount = result.totalConfigs - result.validConfigs;
+    const configHealthy = invalidCount === 0;
+    checks.push({
+      name: 'Config Validation',
+      status: configHealthy ? 'PASS' : 'FAIL',
+      healthy: configHealthy,
+      detail: `${result.validConfigs} valid, ${invalidCount} invalid of ${result.totalConfigs} configs`,
+    });
+  } catch {
+    checks.push({ name: 'Config Validation', status: 'SKIPPED', healthy: true, detail: 'Validator not available' });
+  }
+
+  // Self-healing status
+  try {
+    const selfHealing = require('./self-healing');
+    const report = selfHealing.getHealingReport(projectRoot);
+    checks.push({
+      name: 'Self-Healing',
+      status: report.pendingPatches > 0 ? 'WARNING' : 'PASS',
+      healthy: true,
+      detail: `${report.totalHeals} heals, ${report.successRate}% success, ${report.pendingPatches} pending`,
+    });
+  } catch {
+    checks.push({ name: 'Self-Healing', status: 'SKIPPED', healthy: true, detail: 'Healer not available' });
+  }
+
+  const healthy = checks.every((c) => c.healthy);
+
+  // Render output
+  console.log(`\n${colors.bright}${colors.blue}═══ Health Check ═══${colors.reset}\n`);
+  for (const check of checks) {
+    const icon = check.status === 'PASS' || check.status === 'HEALTHY' ? '✓' : check.status === 'FAIL' || check.status === 'EXHAUSTED' ? '✗' : '⚠';
+    const color = check.healthy ? 'green' : 'red';
+    console.log(`   ${colors[color]}${icon} ${check.name}: ${check.status}${colors.reset}`);
+    console.log(`     ${check.detail}`);
+  }
+  console.log('');
+  console.log(`   ${healthy ? `${colors.green}✅ All health checks passed` : `${colors.red}❌ Some health checks failed`}${colors.reset}\n`);
+
+  return { healthy, checks };
+}
+
 module.exports = {
   marketCommand,
   healCommand,
+  healthCommand,
   renderDashboardSections,
 };

package/lib/config-validator.js

@@ -0,0 +1,274 @@
+/**
+ * Antigravity AI Kit — Configuration Validator
+ *
+ * Runtime JSON schema validation for engine configuration files.
+ * Catches configuration corruption and drift before they cause
+ * runtime failures.
+ *
+ * @module lib/config-validator
+ * @author Emre Dursun
+ * @since v3.2.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { AGENT_DIR, ENGINE_DIR, HOOKS_DIR } = require('./constants');
+
+/**
+ * @typedef {object} ValidationResult
+ * @property {boolean} valid - Whether the config is valid
+ * @property {string[]} errors - Validation error messages
+ * @property {string[]} warnings - Non-critical warnings
+ */
+
+/**
+ * Schema definitions for engine configuration files.
+ * Each schema defines required fields, their types, and constraints.
+ */
+const SCHEMAS = {
+  'manifest.json': {
+    required: ['schemaVersion', 'kitVersion', 'capabilities'],
+    types: {
+      schemaVersion: 'string',
+      kitVersion: 'string',
+      capabilities: 'object',
+    },
+    nested: {
+      capabilities: {
+        required: ['agents', 'commands', 'skills', 'workflows'],
+        types: {
+          agents: 'object',
+          commands: 'object',
+          skills: 'object',
+          workflows: 'object',
+        },
+      },
+    },
+  },
+
+  'workflow-state.json': {
+    required: ['currentPhase', 'phases', 'transitions'],
+    types: {
+      currentPhase: 'string',
+      phases: 'object',
+      transitions: 'array',
+    },
+    validators: {
+      currentPhase: (value) => {
+        const validPhases = ['IDLE', 'EXPLORE', 'PLAN', 'IMPLEMENT', 'VERIFY', 'REVIEW', 'DEPLOY', 'MAINTAIN'];
+        return validPhases.includes(value) ? null : `Invalid phase: ${value}. Valid: ${validPhases.join(', ')}`;
+      },
+    },
+  },
+
+  'loading-rules.json': {
+    required: ['domainRules', 'contextBudget', 'planningMandates'],
+    types: {
+      domainRules: 'array',
+      contextBudget: 'object',
+      planningMandates: 'object',
+    },
+    nested: {
+      contextBudget: {
+        required: ['maxAgentsPerSession', 'maxSkillsPerSession'],
+        types: {
+          maxAgentsPerSession: 'number',
+          maxSkillsPerSession: 'number',
+        },
+      },
+      planningMandates: {
+        required: ['alwaysLoadRules', 'alwaysLoadSkills', 'crossCuttingSections'],
+        types: {
+          alwaysLoadRules: 'array',
+          alwaysLoadSkills: 'array',
+          crossCuttingSections: 'array',
+          specialistContributors: 'object',
+        },
+      },
+    },
+    arrayItemSchema: {
+      domainRules: {
+        required: ['domain', 'keywords'],
+        types: {
+          domain: 'string',
+          keywords: 'array',
+          loadAgents: 'array',
+          loadSkills: 'array',
+        },
+      },
+    },
+  },
+
+  'reliability-config.json': {
+    required: ['errorBudget'],
+    types: {
+      errorBudget: 'object',
+    },
+    nested: {
+      errorBudget: {
+        required: ['thresholds', 'resetCadence'],
+        types: {
+          thresholds: 'object',
+          resetCadence: 'string',
+        },
+      },
+    },
+  },
+
+  'hooks.json': {
+    required: ['hooks'],
+    types: {
+      hooks: 'array',
+    },
+    arrayItemSchema: {
+      hooks: {
+        required: ['event'],
+        types: {
+          event: 'string',
+        },
+      },
+    },
+  },
+};
+
+/**
+ * Validates a value's type.
+ *
+ * @param {*} value - Value to check
+ * @param {string} expectedType - Expected type string
+ * @returns {boolean}
+ */
+function checkType(value, expectedType) {
+  if (expectedType === 'array') {
+    return Array.isArray(value);
+  }
+  return typeof value === expectedType;
+}
+
+/**
+ * Validates a configuration object against its schema.
+ *
+ * @param {object} config - Parsed configuration object
+ * @param {object} schema - Schema definition
+ * @param {string} [prefix=''] - Field path prefix for nested errors
+ * @returns {ValidationResult}
+ */
+function validateAgainstSchema(config, schema, prefix = '') {
+  const errors = [];
+  const warnings = [];
+
+  // Check required fields
+  for (const field of (schema.required || [])) {
+    const fieldPath = prefix ? `${prefix}.${field}` : field;
+    if (config[field] === undefined || config[field] === null) {
+      errors.push(`Missing required field: ${fieldPath}`);
+    }
+  }
+
+  // Check types
+  for (const [field, expectedType] of Object.entries(schema.types || {})) {
+    const fieldPath = prefix ? `${prefix}.${field}` : field;
+    if (config[field] !== undefined && config[field] !== null) {
+      if (!checkType(config[field], expectedType)) {
+        errors.push(`Invalid type for ${fieldPath}: expected ${expectedType}, got ${Array.isArray(config[field]) ? 'array' : typeof config[field]}`);
+      }
+    }
+  }
+
+  // Run custom validators
+  for (const [field, validator] of Object.entries(schema.validators || {})) {
+    if (config[field] !== undefined) {
+      const error = validator(config[field]);
+      if (error) {
+        errors.push(error);
+      }
+    }
+  }
+
+  // Validate nested schemas
+  for (const [field, nestedSchema] of Object.entries(schema.nested || {})) {
+    if (config[field] && typeof config[field] === 'object' && !Array.isArray(config[field])) {
+      const nestedResult = validateAgainstSchema(config[field], nestedSchema, prefix ? `${prefix}.${field}` : field);
+      errors.push(...nestedResult.errors);
+      warnings.push(...nestedResult.warnings);
+    }
+  }
+
+  // Validate array items
+  for (const [field, itemSchema] of Object.entries(schema.arrayItemSchema || {})) {
+    if (Array.isArray(config[field])) {
+      config[field].forEach((item, index) => {
+        if (typeof item === 'object' && item !== null) {
+          const itemResult = validateAgainstSchema(item, itemSchema, `${field}[${index}]`);
+          errors.push(...itemResult.errors);
+          warnings.push(...itemResult.warnings);
+        }
+      });
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Validates a specific engine configuration file.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {string} configName - Configuration file name (e.g., 'manifest.json')
+ * @returns {ValidationResult}
+ */
+function validateConfig(projectRoot, configName) {
+  const schema = SCHEMAS[configName];
+  if (!schema) {
+    return { valid: false, errors: [`No schema defined for: ${configName}`], warnings: [] };
+  }
+
+  const configDir = configName === 'manifest.json'
+    ? path.join(projectRoot, AGENT_DIR)
+    : configName === 'hooks.json'
+      ? path.join(projectRoot, AGENT_DIR, HOOKS_DIR)
+      : path.join(projectRoot, AGENT_DIR, ENGINE_DIR);
+
+  const configPath = path.join(configDir, configName);
+
+  if (!fs.existsSync(configPath)) {
+    return { valid: false, errors: [`Config file not found: ${configPath}`], warnings: [] };
+  }
+
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  } catch (parseError) {
+    return { valid: false, errors: [`Invalid JSON: ${parseError.message}`], warnings: [] };
+  }
+
+  return validateAgainstSchema(config, schema);
+}
+
+/**
+ * Validates all known engine configuration files.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {{ totalConfigs: number, validConfigs: number, results: Object.<string, ValidationResult> }}
+ */
+function validateAllConfigs(projectRoot) {
+  const entries = Object.keys(SCHEMAS).map(
+    (configName) => [configName, validateConfig(projectRoot, configName)]
+  );
+  const results = Object.fromEntries(entries);
+  const validCount = entries.filter(([, result]) => result.valid).length;
+
+  return {
+    totalConfigs: Object.keys(SCHEMAS).length,
+    validConfigs: validCount,
+    results,
+  };
+}
+
+module.exports = {
+  validateConfig,
+  validateAllConfigs,
+  SCHEMAS,
+};

package/lib/conflict-detector.js

@@ -14,8 +14,8 @@
 const fs = require('fs');
 const path = require('path');
 
-const AGENT_DIR = '.agent';
-const ENGINE_DIR = 'engine';
+const { AGENT_DIR, ENGINE_DIR } = require('./constants');
+const { writeJsonAtomic } = require('./io');
 const FILE_LOCKS_FILE = 'file-locks.json';
 
 /** Default lock TTL in milliseconds (30 minutes) */
@@ -65,10 +65,17 @@ function loadLocks(projectRoot) {
     const now = Date.now();
 
     // Filter out expired locks
-    return locks.filter((lock) => {
+    const activeLocks = locks.filter((lock) => {
       const claimedTime = new Date(lock.claimedAt).getTime();
       return (now - claimedTime) < (lock.ttlMs || DEFAULT_LOCK_TTL_MS);
     });
+
+    // Persist pruned list if stale locks were removed
+    if (activeLocks.length < locks.length) {
+      writeLocks(projectRoot, activeLocks);
+    }
+
+    return activeLocks;
   } catch {
     return [];
   }
@@ -83,21 +90,13 @@ function loadLocks(projectRoot) {
  */
 function writeLocks(projectRoot, locks) {
   const locksPath = resolveLocksPath(projectRoot);
-  const tempPath = `${locksPath}.tmp`;
-  const dir = path.dirname(locksPath);
-
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-
   const data = {
     schemaVersion: '1.0.0',
     lastUpdated: new Date().toISOString(),
     locks,
   };
 
-  fs.writeFileSync(tempPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
-  fs.renameSync(tempPath, locksPath);
+  writeJsonAtomic(locksPath, data);
 }
 
 /**
@@ -128,22 +127,30 @@ function claimFile(projectRoot, filePath, agent, ttlMs) {
     };
   }
 
-  // Update or create lock
+  // Update or create lock immutably
   const existingIndex = locks.findIndex((l) => l.filePath === normalizedPath && l.agent === agent);
+  const now = new Date().toISOString();
 
+  let updatedLocks;
   if (existingIndex !== -1) {
-    locks[existingIndex].claimedAt = new Date().toISOString();
-    locks[existingIndex].ttlMs = lockTtl;
+    updatedLocks = locks.map((l, i) =>
+      i === existingIndex
+        ? { ...l, claimedAt: now, ttlMs: lockTtl }
+        : l
+    );
   } else {
-    locks.push({
-      filePath: normalizedPath,
-      agent,
-      claimedAt: new Date().toISOString(),
-      ttlMs: lockTtl,
-    });
+    updatedLocks = [
+      ...locks,
+      {
+        filePath: normalizedPath,
+        agent,
+        claimedAt: now,
+        ttlMs: lockTtl,
+      },
+    ];
   }
 
-  writeLocks(projectRoot, locks);
+  writeLocks(projectRoot, updatedLocks);
   return { success: true };
 }
 

package/lib/constants.js

@@ -0,0 +1,35 @@
+/**
+ * Antigravity AI Kit — Shared Constants
+ *
+ * Central definition of directory names and paths used across
+ * all runtime modules. Prevents drift from duplicated strings.
+ * Frozen to prevent accidental mutation at runtime.
+ *
+ * @module lib/constants
+ * @since v3.2.0
+ */
+
+'use strict';
+
+/** Root agent configuration directory name */
+const AGENT_DIR = '.agent';
+
+/** Engine subdirectory within .agent */
+const ENGINE_DIR = 'engine';
+
+/** Hooks subdirectory within .agent */
+const HOOKS_DIR = 'hooks';
+
+/** Skills subdirectory within .agent */
+const SKILLS_DIR = 'skills';
+
+/** Plugins subdirectory within .agent */
+const PLUGINS_DIR = 'plugins';
+
+module.exports = Object.freeze({
+  AGENT_DIR,
+  ENGINE_DIR,
+  HOOKS_DIR,
+  SKILLS_DIR,
+  PLUGINS_DIR,
+});

package/lib/engineering-manager.js

@@ -18,8 +18,8 @@ const taskModel = require('./task-model');
 const agentRegistry = require('./agent-registry');
 const agentReputation = require('./agent-reputation');
 
-const AGENT_DIR = '.agent';
-const ENGINE_DIR = 'engine';
+const { AGENT_DIR, ENGINE_DIR } = require('./constants');
+const { writeJsonAtomic } = require('./io');
 const SPRINT_FILE = 'sprint-plans.json';
 
 /** Maximum tasks per sprint suggestion */
@@ -82,15 +82,7 @@ function loadSprintData(projectRoot) {
  */
 function writeSprintData(projectRoot, data) {
   const filePath = resolveSprintPath(projectRoot);
-  const dir = path.dirname(filePath);
-
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-
-  const tempPath = `${filePath}.tmp`;
-  fs.writeFileSync(tempPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
-  fs.renameSync(tempPath, filePath);
+  writeJsonAtomic(filePath, data);
 }
 
 /**
@@ -209,16 +201,11 @@ function generateSprintPlan(projectRoot, options = {}) {
     tasks = [];
   }
 
-  // Priority sort: critical > high > medium > low
-  const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
-  tasks.sort((a, b) => {
-    const aPriority = priorityOrder[a.priority] ?? 2;
-    const bPriority = priorityOrder[b.priority] ?? 2;
-    return aPriority - bPriority;
-  });
+  // Priority sort using shared utility
+  const sortedTasks = taskModel.sortByPriority(tasks);
 
   // Take top N
-  const sprintTasks = tasks.slice(0, maxTasks);
+  const sprintTasks = sortedTasks.slice(0, maxTasks);
 
   // Auto-assign each
   /** @type {TaskAssignment[]} */
@@ -296,15 +283,10 @@ function suggestNextTask(projectRoot) {
     return { task: null, reason: 'No open tasks remaining' };
   }
 
-  // Priority sort
-  const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
-  openTasks.sort((a, b) => {
-    const aPriority = priorityOrder[a.priority] ?? 2;
-    const bPriority = priorityOrder[b.priority] ?? 2;
-    return aPriority - bPriority;
-  });
+  // Priority sort using shared utility
+  const sorted = taskModel.sortByPriority(openTasks);
 
-  const topTask = openTasks[0];
+  const topTask = sorted[0];
   return {
     task: topTask,
     reason: `Highest priority open task (${topTask.priority})`,