antigravity-ai-kit 3.1.1 → 3.2.0

package/lib/workflow-events.js

@@ -0,0 +1,166 @@
+/**
+ * Antigravity AI Kit — Workflow Event Emitter
+ *
+ * Provides an event-driven interface for workflow state transitions.
+ * Enables reactive hook triggering and observability when the
+ * workflow engine changes phases.
+ *
+ * @module lib/workflow-events
+ * @author Emre Dursun
+ * @since v3.2.0
+ */
+
+'use strict';
+
+const { EventEmitter } = require('events');
+
+/**
+ * @typedef {object} WorkflowEvent
+ * @property {string} type - Event type
+ * @property {string} fromPhase - Source phase
+ * @property {string} toPhase - Target phase
+ * @property {string} trigger - What triggered the transition
+ * @property {string} timestamp - ISO timestamp
+ */
+
+/** Singleton workflow event bus */
+const workflowBus = new EventEmitter();
+
+/** Event type constants */
+const EVENTS = {
+  TRANSITION_START: 'workflow:transition:start',
+  TRANSITION_COMPLETE: 'workflow:transition:complete',
+  TRANSITION_FAILED: 'workflow:transition:failed',
+  PHASE_ENTERED: 'workflow:phase:entered',
+  WORKFLOW_RESET: 'workflow:reset',
+};
+
+/**
+ * Emits a transition start event.
+ *
+ * @param {string} fromPhase - Source phase
+ * @param {string} toPhase - Target phase
+ * @param {string} trigger - Transition trigger
+ * @returns {void}
+ */
+function emitTransitionStart(fromPhase, toPhase, trigger) {
+  const event = {
+    type: EVENTS.TRANSITION_START,
+    fromPhase,
+    toPhase,
+    trigger,
+    timestamp: new Date().toISOString(),
+  };
+  workflowBus.emit(EVENTS.TRANSITION_START, event);
+}
+
+/**
+ * Emits a transition complete event.
+ *
+ * @param {string} fromPhase - Source phase
+ * @param {string} toPhase - Target phase
+ * @param {string} trigger - Transition trigger
+ * @returns {void}
+ */
+function emitTransitionComplete(fromPhase, toPhase, trigger) {
+  const event = {
+    type: EVENTS.TRANSITION_COMPLETE,
+    fromPhase,
+    toPhase,
+    trigger,
+    timestamp: new Date().toISOString(),
+  };
+  workflowBus.emit(EVENTS.TRANSITION_COMPLETE, event);
+  workflowBus.emit(EVENTS.PHASE_ENTERED, { ...event, type: EVENTS.PHASE_ENTERED, phase: toPhase });
+}
+
+/**
+ * Emits a transition failed event.
+ *
+ * @param {string} fromPhase - Source phase
+ * @param {string} toPhase - Target phase
+ * @param {string} error - Error message
+ * @returns {void}
+ */
+function emitTransitionFailed(fromPhase, toPhase, error) {
+  const event = {
+    type: EVENTS.TRANSITION_FAILED,
+    fromPhase,
+    toPhase,
+    trigger: '',
+    error,
+    timestamp: new Date().toISOString(),
+  };
+  workflowBus.emit(EVENTS.TRANSITION_FAILED, event);
+}
+
+/**
+ * Emits a workflow reset event.
+ *
+ * @param {string} previousPhase - Phase before reset
+ * @returns {void}
+ */
+function emitWorkflowReset(previousPhase) {
+  const event = {
+    type: EVENTS.WORKFLOW_RESET,
+    fromPhase: previousPhase,
+    toPhase: 'IDLE',
+    trigger: 'reset',
+    timestamp: new Date().toISOString(),
+  };
+  workflowBus.emit(EVENTS.WORKFLOW_RESET, event);
+}
+
+/**
+ * Subscribes to a workflow event.
+ *
+ * @param {string} eventType - Event type from EVENTS
+ * @param {Function} handler - Event handler
+ * @returns {void}
+ */
+function on(eventType, handler) {
+  workflowBus.on(eventType, handler);
+}
+
+/**
+ * Subscribes to a workflow event once.
+ *
+ * @param {string} eventType - Event type from EVENTS
+ * @param {Function} handler - Event handler
+ * @returns {void}
+ */
+function once(eventType, handler) {
+  workflowBus.once(eventType, handler);
+}
+
+/**
+ * Removes an event listener.
+ *
+ * @param {string} eventType - Event type
+ * @param {Function} handler - Handler to remove
+ * @returns {void}
+ */
+function off(eventType, handler) {
+  workflowBus.off(eventType, handler);
+}
+
+/**
+ * Removes all listeners for testing cleanup.
+ *
+ * @returns {void}
+ */
+function removeAllListeners() {
+  workflowBus.removeAllListeners();
+}
+
+module.exports = {
+  EVENTS,
+  emitTransitionStart,
+  emitTransitionComplete,
+  emitTransitionFailed,
+  emitWorkflowReset,
+  on,
+  once,
+  off,
+  removeAllListeners,
+};

package/lib/workflow-persistence.js

@@ -16,8 +16,8 @@ const path = require('path');
 const crypto = require('crypto');
 const workflowEngine = require('./workflow-engine');
 
-const AGENT_DIR = '.agent';
-const ENGINE_DIR = 'engine';
+const { AGENT_DIR, ENGINE_DIR } = require('./constants');
+const { writeJsonAtomic } = require('./io');
 const CHECKPOINTS_DIR = 'checkpoints';
 
 /**
@@ -41,10 +41,6 @@ function createCheckpoint(projectRoot, label) {
   const { state } = workflowEngine.loadWorkflowState(projectRoot);
   const checkpointsDir = resolveCheckpointsDir(projectRoot);
 
-  if (!fs.existsSync(checkpointsDir)) {
-    fs.mkdirSync(checkpointsDir, { recursive: true });
-  }
-
   const timestamp = new Date().toISOString();
   const checkpointId = crypto.randomUUID().slice(0, 8);
 
@@ -57,7 +53,7 @@ function createCheckpoint(projectRoot, label) {
   };
 
   const filePath = path.join(checkpointsDir, `${checkpointId}.json`);
-  fs.writeFileSync(filePath, JSON.stringify(checkpoint, null, 2) + '\n', 'utf-8');
+  writeJsonAtomic(filePath, checkpoint);
 
   return { checkpointId, filePath, timestamp };
 }
@@ -107,18 +103,22 @@ function resumeFromCheckpoint(projectRoot, checkpointId) {
 
   const checkpoint = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
   const statePath = path.join(projectRoot, AGENT_DIR, ENGINE_DIR, 'workflow-state.json');
-  const tempPath = `${statePath}.tmp`;
-
-  // Append restore event to history
-  checkpoint.state.history.push({
-    from: 'RESTORED',
-    to: checkpoint.state.currentPhase,
-    trigger: `Restored from checkpoint ${checkpointId}`,
-    timestamp: new Date().toISOString(),
-  });
-
-  fs.writeFileSync(tempPath, JSON.stringify(checkpoint.state, null, 2) + '\n', 'utf-8');
-  fs.renameSync(tempPath, statePath);
+
+  // Create restored state with appended history (H-9: immutable — no mutation of checkpoint)
+  const restoredState = {
+    ...checkpoint.state,
+    history: [
+      ...(checkpoint.state.history || []),
+      {
+        from: 'RESTORED',
+        to: checkpoint.state.currentPhase,
+        trigger: `Restored from checkpoint ${checkpointId}`,
+        timestamp: new Date().toISOString(),
+      },
+    ],
+  };
+
+  writeJsonAtomic(statePath, restoredState);
 
   return { success: true, restoredPhase: checkpoint.state.currentPhase };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "antigravity-ai-kit",
-  "version": "3.1.1",
-  "description": "🚀 Trust-Grade AI development framework with a 21-module runtime engine — 19 Agents, 31 Skills, 31 Commands, 14 Workflows, 261 Tests. Workflow enforcement, task governance, agent reputation, self-healing, and skill marketplace.",
+  "version": "3.2.0",
+  "description": "🚀 Trust-Grade AI development framework with a 29-module runtime engine — 19 Agents, 32 Skills, 31 Commands, 14 Workflows, 327 Tests. Workflow enforcement, task governance, agent reputation, self-healing, and skill marketplace.",
   "main": "bin/ag-kit.js",
   "bin": {
     "ag-kit": "./bin/ag-kit.js"