antigravity-ai-kit 3.1.1 → 3.2.0

package/lib/error-budget.js

@@ -15,8 +15,10 @@
 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 { createLogger } = require('./logger');
+const log = createLogger('error-budget');
 const RELIABILITY_CONFIG = 'reliability-config.json';
 const METRICS_FILE = 'metrics.json';
 
@@ -133,12 +135,13 @@ function createEmptyMetrics() {
  */
 function writeMetrics(projectRoot, metrics) {
   const metricsPath = resolveMetricsPath(projectRoot);
-  const tempPath = `${metricsPath}.tmp`;
 
-  metrics.lastUpdated = new Date().toISOString();
+  const updatedMetrics = {
+    ...metrics,
+    lastUpdated: new Date().toISOString(),
+  };
 
-  fs.writeFileSync(tempPath, JSON.stringify(metrics, null, 2) + '\n', 'utf-8');
-  fs.renameSync(tempPath, metricsPath);
+  writeJsonAtomic(metricsPath, updatedMetrics);
 }
 
 /**
@@ -151,9 +154,11 @@ function writeMetrics(projectRoot, metrics) {
  */
 function recordTestResult(projectRoot, passed, failed) {
   const metrics = loadMetrics(projectRoot);
-  metrics.testsPassed += passed;
-  metrics.testsFailed += failed;
-  writeMetrics(projectRoot, metrics);
+  writeMetrics(projectRoot, {
+    ...metrics,
+    testsPassed: metrics.testsPassed + passed,
+    testsFailed: metrics.testsFailed + failed,
+  });
 }
 
 /**
@@ -165,14 +170,11 @@ function recordTestResult(projectRoot, passed, failed) {
  */
 function recordBuildResult(projectRoot, success) {
   const metrics = loadMetrics(projectRoot);
-
-  if (success) {
-    metrics.buildsSucceeded += 1;
-  } else {
-    metrics.buildsFailed += 1;
-  }
-
-  writeMetrics(projectRoot, metrics);
+  writeMetrics(projectRoot, {
+    ...metrics,
+    buildsSucceeded: metrics.buildsSucceeded + (success ? 1 : 0),
+    buildsFailed: metrics.buildsFailed + (success ? 0 : 1),
+  });
 }
 
 /**
@@ -185,16 +187,11 @@ function recordBuildResult(projectRoot, success) {
  */
 function recordDeployResult(projectRoot, success, rolledBack = false) {
   const metrics = loadMetrics(projectRoot);
-
-  if (success && !rolledBack) {
-    metrics.deploysSucceeded += 1;
-  }
-
-  if (rolledBack) {
-    metrics.deploysRolledBack += 1;
-  }
-
-  writeMetrics(projectRoot, metrics);
+  writeMetrics(projectRoot, {
+    ...metrics,
+    deploysSucceeded: metrics.deploysSucceeded + (success && !rolledBack ? 1 : 0),
+    deploysRolledBack: metrics.deploysRolledBack + (rolledBack ? 1 : 0),
+  });
 }
 
 /**
@@ -273,14 +270,91 @@ function getBudgetReport(projectRoot) {
   };
 }
 
+/**
+ * Archives current metrics before resetting.
+ * Preserves historical data for trend analysis.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {{ archived: boolean, archivePath: string | null }}
+ */
+function archiveMetrics(projectRoot) {
+  const metrics = loadMetrics(projectRoot);
+  const hasData = metrics.testsPassed + metrics.testsFailed +
+    metrics.buildsSucceeded + metrics.buildsFailed +
+    metrics.deploysSucceeded + metrics.deploysRolledBack > 0;
+
+  if (!hasData) {
+    return { archived: false, archivePath: null };
+  }
+
+  const archiveDir = path.join(projectRoot, AGENT_DIR, ENGINE_DIR, 'metrics-archive');
+  if (!fs.existsSync(archiveDir)) {
+    fs.mkdirSync(archiveDir, { recursive: true });
+  }
+
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const archivePath = path.join(archiveDir, `metrics-${timestamp}.json`);
+
+  const report = getBudgetReport(projectRoot);
+  const archiveEntry = {
+    ...metrics,
+    archivedAt: new Date().toISOString(),
+    budgetStatus: report.status,
+    rates: report.rates,
+  };
+
+  fs.writeFileSync(archivePath, JSON.stringify(archiveEntry, null, 2) + '\n', 'utf-8');
+
+  return { archived: true, archivePath };
+}
+
 /**
  * Resets metrics for a new tracking period.
+ * Automatically archives previous period's data before resetting.
  *
  * @param {string} projectRoot - Root directory of the project
- * @returns {void}
+ * @param {object} [options] - Reset options
+ * @param {boolean} [options.skipArchive=false] - Skip archival
+ * @returns {{ archived: boolean, archivePath: string | null }}
  */
-function resetMetrics(projectRoot) {
+function resetMetrics(projectRoot, options = {}) {
+  let archiveResult = { archived: false, archivePath: null };
+
+  if (!options.skipArchive) {
+    archiveResult = archiveMetrics(projectRoot);
+  }
+
   writeMetrics(projectRoot, createEmptyMetrics());
+  return archiveResult;
+}
+
+/**
+ * Returns historical metrics from the archive.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {number} [limit=10] - Maximum entries to return
+ * @returns {object[]}
+ */
+function getMetricsHistory(projectRoot, limit = 10) {
+  const archiveDir = path.join(projectRoot, AGENT_DIR, ENGINE_DIR, 'metrics-archive');
+
+  if (!fs.existsSync(archiveDir)) {
+    return [];
+  }
+
+  const files = fs.readdirSync(archiveDir)
+    .filter((f) => f.startsWith('metrics-') && f.endsWith('.json'))
+    .sort()
+    .reverse()
+    .slice(0, limit);
+
+  return files.map((file) => {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(archiveDir, file), 'utf-8'));
+    } catch {
+      return null;
+    }
+  }).filter(Boolean);
 }
 
 module.exports = {
@@ -291,4 +365,6 @@ module.exports = {
   recordDeployResult,
   getBudgetReport,
   resetMetrics,
+  archiveMetrics,
+  getMetricsHistory,
 };

package/lib/hook-system.js

@@ -14,8 +14,8 @@
 const fs = require('fs');
 const path = require('path');
 
-const AGENT_DIR = '.agent';
-const HOOKS_DIR = 'hooks';
+const { AGENT_DIR, ENGINE_DIR, HOOKS_DIR } = require('./constants');
+
 const HOOKS_FILE = 'hooks.json';
 
 /**
@@ -50,7 +50,11 @@ function loadHooks(projectRoot) {
     return { hooks: [] };
   }
 
-  return JSON.parse(fs.readFileSync(hooksPath, 'utf-8'));
+  try {
+    return JSON.parse(fs.readFileSync(hooksPath, 'utf-8'));
+  } catch {
+    return { hooks: [] };
+  }
 }
 
 /**
@@ -146,7 +150,7 @@ function evaluateAction(action, context) {
 
   if (actionLower.includes('loading-rules.json') || actionLower.includes('workflow-state.json')) {
     const targetFile = actionLower.includes('loading-rules.json') ? 'loading-rules.json' : 'workflow-state.json';
-    const filePath = path.join(projectRoot, AGENT_DIR, 'engine', targetFile);
+    const filePath = path.join(projectRoot, AGENT_DIR, ENGINE_DIR, targetFile);
     const exists = fs.existsSync(filePath);
 
     return {

package/lib/identity.js

@@ -16,8 +16,8 @@ const path = require('path');
 const crypto = require('crypto');
 const { execSync } = require('child_process');
 
-const AGENT_DIR = '.agent';
-const ENGINE_DIR = 'engine';
+const { AGENT_DIR, ENGINE_DIR } = require('./constants');
+const { writeJsonAtomic } = require('./io');
 const IDENTITY_FILE = 'identity.json';
 
 /** @type {readonly string[]} */
@@ -86,15 +86,7 @@ function loadIdentityRegistry(projectRoot) {
  */
 function writeIdentityRegistry(projectRoot, registry) {
   const identityPath = resolveIdentityPath(projectRoot);
-  const tempPath = `${identityPath}.tmp`;
-  const dir = path.dirname(identityPath);
-
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-
-  fs.writeFileSync(tempPath, JSON.stringify(registry, null, 2) + '\n', 'utf-8');
-  fs.renameSync(tempPath, identityPath);
+  writeJsonAtomic(identityPath, registry);
 }
 
 /**
@@ -136,33 +128,36 @@ function registerIdentity(projectRoot, { name, email, role }) {
   const existingIndex = registry.developers.findIndex((d) => d.id === developerId);
 
   if (existingIndex !== -1) {
-    // Update last active
-    registry.developers[existingIndex].lastActiveAt = now;
-    registry.developers[existingIndex].name = name;
-    registry.activeId = developerId;
-    writeIdentityRegistry(projectRoot, registry);
-    return { success: true, identity: registry.developers[existingIndex], isNew: false };
+    // Update last active (immutable)
+    const updatedDev = { ...registry.developers[existingIndex], lastActiveAt: now, name };
+    const updatedRegistry = {
+      ...registry,
+      developers: registry.developers.map((d, i) => (i === existingIndex ? updatedDev : d)),
+      activeId: developerId,
+    };
+    writeIdentityRegistry(projectRoot, updatedRegistry);
+    return { success: true, identity: updatedDev, isNew: false };
   }
 
+  // First developer becomes owner automatically
+  const assignedRole = registry.developers.length === 0 ? 'owner' : identityRole;
+
   /** @type {Identity} */
   const identity = {
     id: developerId,
     name,
     email: email.toLowerCase().trim(),
-    role: identityRole,
+    role: assignedRole,
     registeredAt: now,
     lastActiveAt: now,
   };
 
-  registry.developers.push(identity);
-
-  // First developer becomes owner automatically
-  if (registry.developers.length === 1) {
-    identity.role = 'owner';
-  }
-
-  registry.activeId = developerId;
-  writeIdentityRegistry(projectRoot, registry);
+  const updatedRegistry = {
+    ...registry,
+    developers: [...registry.developers, identity],
+    activeId: developerId,
+  };
+  writeIdentityRegistry(projectRoot, updatedRegistry);
 
   return { success: true, identity, isNew: true };
 }

package/lib/io.js

@@ -0,0 +1,74 @@
+/**
+ * Antigravity AI Kit — Shared I/O Utilities
+ *
+ * Provides atomic file write operations and safe JSON parsing
+ * used across all runtime modules. Single point for error
+ * handling around filesystem operations.
+ *
+ * @module lib/io
+ * @author Emre Dursun
+ * @since v3.2.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { createLogger } = require('./logger');
+const log = createLogger('io');
+
+/**
+ * Writes JSON data to a file atomically (temp file + rename).
+ * Creates parent directories if they don't exist.
+ *
+ * @param {string} filePath - Target file path
+ * @param {object} data - Data to serialize as JSON
+ * @returns {void}
+ */
+function writeJsonAtomic(filePath, data) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const tempPath = `${filePath}.tmp`;
+  try {
+    fs.writeFileSync(tempPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+    fs.renameSync(tempPath, filePath);
+  } catch (err) {
+    // Clean up temp file on failure
+    try {
+      if (fs.existsSync(tempPath)) {
+        fs.unlinkSync(tempPath);
+      }
+    } catch {
+      // Cleanup failure is non-critical
+    }
+    throw err;
+  }
+}
+
+/**
+ * Safely parses a JSON file, returning a default value on failure.
+ *
+ * @param {string} filePath - Path to JSON file
+ * @param {*} defaultValue - Value to return if file doesn't exist or is invalid
+ * @returns {*} Parsed JSON or default value
+ */
+function readJsonSafe(filePath, defaultValue = null) {
+  if (!fs.existsSync(filePath)) {
+    return defaultValue;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch (error) {
+    log.debug('Failed to parse JSON file, returning default', { filePath, error: error.message });
+    return defaultValue;
+  }
+}
+
+module.exports = {
+  writeJsonAtomic,
+  readJsonSafe,
+};