antigravity-ai-kit 3.1.1 → 3.2.0

package/lib/session-manager.js

@@ -17,7 +17,8 @@ const path = require('path');
 const crypto = require('crypto');
 const { execSync } = require('child_process');
 
-const AGENT_DIR = '.agent';
+const { AGENT_DIR } = require('./constants');
+const { writeJsonAtomic } = require('./io');
 const STATE_FILENAME = 'session-state.json';
 
 /**
@@ -56,12 +57,8 @@ function loadSessionState(projectRoot) {
  */
 function writeSessionState(projectRoot, state) {
   const filePath = resolveStatePath(projectRoot);
-  const tempPath = `${filePath}.tmp`;
-
-  state.lastUpdated = new Date().toISOString();
-
-  fs.writeFileSync(tempPath, JSON.stringify(state, null, 2) + '\n', 'utf-8');
-  fs.renameSync(tempPath, filePath);
+  const updatedState = { ...state, lastUpdated: new Date().toISOString() };
+  writeJsonAtomic(filePath, updatedState);
 }
 
 /**
@@ -113,20 +110,22 @@ function getGitLastCommit(projectRoot) {
  * @returns {{ sessionId: string, state: object }}
  */
 function startSession(projectRoot, focus) {
-  const state = loadSessionState(projectRoot);
+  const loadedState = loadSessionState(projectRoot);
   const sessionId = crypto.randomUUID();
 
-  state.session = {
-    id: sessionId,
-    date: new Date().toISOString(),
-    focus: focus || null,
-    status: 'active',
-  };
-
-  state.repository = {
-    currentBranch: getGitBranch(projectRoot),
-    lastCommit: getGitLastCommit(projectRoot),
-    remoteSynced: false,
+  const state = {
+    ...loadedState,
+    session: {
+      id: sessionId,
+      date: new Date().toISOString(),
+      focus: focus || null,
+      status: 'active',
+    },
+    repository: {
+      currentBranch: getGitBranch(projectRoot),
+      lastCommit: getGitLastCommit(projectRoot),
+      remoteSynced: false,
+    },
   };
 
   writeSessionState(projectRoot, state);
@@ -141,17 +140,18 @@ function startSession(projectRoot, focus) {
  * @returns {{ success: boolean, sessionId: string | null }}
  */
 function endSession(projectRoot) {
-  const state = loadSessionState(projectRoot);
+  const loadedState = loadSessionState(projectRoot);
 
-  if (!state.session || !state.session.id) {
+  if (!loadedState.session || !loadedState.session.id) {
     return { success: false, sessionId: null };
   }
 
-  const sessionId = state.session.id;
-  state.session.status = 'completed';
-
-  // Archive completed tasks count
-  state.notes = `Session ${sessionId} completed at ${new Date().toISOString()}`;
+  const sessionId = loadedState.session.id;
+  const state = {
+    ...loadedState,
+    session: { ...loadedState.session, status: 'completed' },
+    notes: `Session ${sessionId} completed at ${new Date().toISOString()}`,
+  };
 
   writeSessionState(projectRoot, state);
 
@@ -167,7 +167,7 @@ function endSession(projectRoot) {
  * @returns {{ taskId: string }}
  */
 function addTask(projectRoot, title, description) {
-  const state = loadSessionState(projectRoot);
+  const loadedState = loadSessionState(projectRoot);
   const taskId = `TASK-${Date.now().toString(36).toUpperCase()}`;
 
   const task = {
@@ -178,12 +178,12 @@ function addTask(projectRoot, title, description) {
     status: 'open',
   };
 
-  if (!Array.isArray(state.openTasks)) {
-    state.openTasks = [];
-  }
-
-  state.openTasks.push(task);
-  state.currentTask = taskId;
+  const existingTasks = Array.isArray(loadedState.openTasks) ? loadedState.openTasks : [];
+  const state = {
+    ...loadedState,
+    openTasks: [...existingTasks, task],
+    currentTask: taskId,
+  };
 
   writeSessionState(projectRoot, state);
 
@@ -198,32 +198,35 @@ function addTask(projectRoot, title, description) {
  * @returns {{ success: boolean }}
  */
 function completeTask(projectRoot, taskId) {
-  const state = loadSessionState(projectRoot);
+  const loadedState = loadSessionState(projectRoot);
 
-  if (!Array.isArray(state.openTasks)) {
+  if (!Array.isArray(loadedState.openTasks)) {
     return { success: false };
   }
 
-  const taskIndex = state.openTasks.findIndex((task) => task.id === taskId);
+  const taskIndex = loadedState.openTasks.findIndex((task) => task.id === taskId);
 
   if (taskIndex === -1) {
     return { success: false };
   }
 
-  const [task] = state.openTasks.splice(taskIndex, 1);
-  task.status = 'completed';
-  task.completedAt = new Date().toISOString();
-
-  if (!Array.isArray(state.completedTasks)) {
-    state.completedTasks = [];
-  }
+  const completedTask = {
+    ...loadedState.openTasks[taskIndex],
+    status: 'completed',
+    completedAt: new Date().toISOString(),
+  };
 
-  state.completedTasks.push(task);
+  const remainingTasks = loadedState.openTasks.filter((_, i) => i !== taskIndex);
+  const existingCompleted = Array.isArray(loadedState.completedTasks) ? loadedState.completedTasks : [];
 
-  // Update currentTask
-  if (state.currentTask === taskId) {
-    state.currentTask = state.openTasks.length > 0 ? state.openTasks[0].id : null;
-  }
+  const state = {
+    ...loadedState,
+    openTasks: remainingTasks,
+    completedTasks: [...existingCompleted, completedTask],
+    currentTask: loadedState.currentTask === taskId
+      ? (remainingTasks.length > 0 ? remainingTasks[0].id : null)
+      : loadedState.currentTask,
+  };
 
   writeSessionState(projectRoot, state);
 

package/lib/skill-sandbox.js

@@ -14,7 +14,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const AGENT_DIR = '.agent';
+const { AGENT_DIR } = require('./constants');
 const SKILLS_DIR = 'skills';
 
 /** Valid permission levels (ordered from least to most privileged) */

package/lib/task-governance.js

@@ -15,8 +15,8 @@ const fs = require('fs');
 const path = require('path');
 const taskModel = require('./task-model');
 
-const AGENT_DIR = '.agent';
-const ENGINE_DIR = 'engine';
+const { AGENT_DIR, ENGINE_DIR } = require('./constants');
+const { writeJsonAtomic } = require('./io');
 const LOCKS_DIR = 'locks';
 const AUDIT_FILE = 'audit-log.json';
 
@@ -67,6 +67,11 @@ function resolveAuditPath(projectRoot) {
  * @returns {{ success: boolean, error?: string }}
  */
 function lockTask(projectRoot, taskId, identityId, reason) {
+  // Validate taskId format to prevent path traversal (M-12)
+  if (typeof taskId !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(taskId)) {
+    return { success: false, error: `Invalid task ID format: ${taskId}` };
+  }
+
   const task = taskModel.getTask(projectRoot, taskId);
   if (!task) {
     return { success: false, error: `Task not found: ${taskId}` };
@@ -99,9 +104,7 @@ function lockTask(projectRoot, taskId, identityId, reason) {
     reason: reason || 'Working on task',
   };
 
-  const tempPath = `${lockFile}.tmp`;
-  fs.writeFileSync(tempPath, JSON.stringify(lock, null, 2) + '\n', 'utf-8');
-  fs.renameSync(tempPath, lockFile);
+  writeJsonAtomic(lockFile, lock);
 
   appendAudit(projectRoot, {
     taskId,
@@ -239,9 +242,7 @@ function appendAudit(projectRoot, entry) {
 
   auditLog.entries.push(entry);
 
-  const tempPath = `${auditPath}.tmp`;
-  fs.writeFileSync(tempPath, JSON.stringify(auditLog, null, 2) + '\n', 'utf-8');
-  fs.renameSync(tempPath, auditPath);
+  writeJsonAtomic(auditPath, auditLog);
 }
 
 /**
@@ -395,9 +396,7 @@ function recordDecision(projectRoot, { actor, actorType, action, files, outcome,
   // Rotate if needed
   auditLog = rotateIfNeeded(projectRoot, auditLog);
 
-  const tempPath = `${auditPath}.tmp`;
-  fs.writeFileSync(tempPath, JSON.stringify(auditLog, null, 2) + '\n', 'utf-8');
-  fs.renameSync(tempPath, auditPath);
+  writeJsonAtomic(auditPath, auditLog);
 
   return entry;
 }

package/lib/task-model.js

@@ -15,8 +15,8 @@ const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 
-const AGENT_DIR = '.agent';
-const ENGINE_DIR = 'engine';
+const { AGENT_DIR, ENGINE_DIR } = require('./constants');
+const { writeJsonAtomic } = require('./io');
 const TASKS_FILE = 'tasks.json';
 
 /** Valid task status values */
@@ -88,12 +88,6 @@ function loadTasks(projectRoot) {
  */
 function writeTasks(projectRoot, tasks) {
   const tasksPath = resolveTasksPath(projectRoot);
-  const tempPath = `${tasksPath}.tmp`;
-  const dir = path.dirname(tasksPath);
-
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
 
   const data = {
     schemaVersion: '1.0.0',
@@ -101,8 +95,7 @@ function writeTasks(projectRoot, tasks) {
     tasks,
   };
 
-  fs.writeFileSync(tempPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
-  fs.renameSync(tempPath, tasksPath);
+  writeJsonAtomic(tasksPath, data);
 }
 
 /**
@@ -136,8 +129,7 @@ function createTask(projectRoot, { title, description, assignee, priority }) {
     deleted: false,
   };
 
-  tasks.push(task);
-  writeTasks(projectRoot, tasks);
+  writeTasks(projectRoot, [...tasks, task]);
 
   return task;
 }
@@ -197,16 +189,18 @@ function updateTask(projectRoot, taskId, updates) {
   }
 
   const allowedFields = ['title', 'description', 'assignee', 'priority'];
+  const fieldUpdates = {};
   for (const field of allowedFields) {
     if (updates[field] !== undefined) {
-      tasks[taskIndex][field] = updates[field];
+      fieldUpdates[field] = updates[field];
     }
   }
 
-  tasks[taskIndex].updatedAt = new Date().toISOString();
-  writeTasks(projectRoot, tasks);
+  const updatedTask = { ...tasks[taskIndex], ...fieldUpdates, updatedAt: new Date().toISOString() };
+  const updatedTasks = tasks.map((t, i) => (i === taskIndex ? updatedTask : t));
+  writeTasks(projectRoot, updatedTasks);
 
-  return { success: true, task: tasks[taskIndex] };
+  return { success: true, task: updatedTask };
 }
 
 /**
@@ -239,14 +233,15 @@ function transitionTask(projectRoot, taskId, newStatus) {
     };
   }
 
-  tasks[taskIndex].status = newStatus;
-  tasks[taskIndex].updatedAt = new Date().toISOString();
-
-  if (newStatus === 'done') {
-    tasks[taskIndex].completedAt = new Date().toISOString();
-  }
-
-  writeTasks(projectRoot, tasks);
+  const now = new Date().toISOString();
+  const updatedTask = {
+    ...tasks[taskIndex],
+    status: newStatus,
+    updatedAt: now,
+    completedAt: newStatus === 'done' ? now : tasks[taskIndex].completedAt,
+  };
+  const updatedTasks = tasks.map((t, i) => (i === taskIndex ? updatedTask : t));
+  writeTasks(projectRoot, updatedTasks);
 
   return { success: true };
 }
@@ -266,9 +261,10 @@ function deleteTask(projectRoot, taskId) {
     return { success: false };
   }
 
-  tasks[taskIndex].deleted = true;
-  tasks[taskIndex].updatedAt = new Date().toISOString();
-  writeTasks(projectRoot, tasks);
+  const updatedTasks = tasks.map((t, i) =>
+    i === taskIndex ? { ...t, deleted: true, updatedAt: new Date().toISOString() } : t
+  );
+  writeTasks(projectRoot, updatedTasks);
 
   return { success: true };
 }
@@ -306,6 +302,23 @@ function getTaskMetrics(projectRoot) {
   };
 }
 
+/** Priority sort order: critical > high > medium > low */
+const PRIORITY_ORDER = { critical: 0, high: 1, medium: 2, low: 3 };
+
+/**
+ * Sorts tasks by priority (critical first, low last).
+ *
+ * @param {Task[]} tasks - Tasks to sort
+ * @returns {Task[]} New sorted array (does not mutate input)
+ */
+function sortByPriority(tasks) {
+  return [...tasks].sort((a, b) => {
+    const aPriority = PRIORITY_ORDER[a.priority] ?? 2;
+    const bPriority = PRIORITY_ORDER[b.priority] ?? 2;
+    return aPriority - bPriority;
+  });
+}
+
 module.exports = {
   createTask,
   getTask,
@@ -314,4 +327,6 @@ module.exports = {
   transitionTask,
   deleteTask,
   getTaskMetrics,
+  sortByPriority,
+  PRIORITY_ORDER,
 };

package/lib/updater.js

@@ -16,7 +16,7 @@ const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 
-const AGENT_DIR = '.agent';
+const { AGENT_DIR } = require('./constants');
 
 /** Files that should never be overwritten during updates */
 const PRESERVED_FILES = new Set([

package/lib/verify.js

@@ -15,7 +15,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const AGENT_DIR = '.agent';
+const { AGENT_DIR, ENGINE_DIR, HOOKS_DIR } = require('./constants');
 
 /**
  * @typedef {object} CheckResult
@@ -186,14 +186,14 @@ function runAllChecks(projectRoot) {
   // --- Check 10: Engine JSON files valid ---
   const engineFiles = ['workflow-state.json', 'loading-rules.json', 'sdlc-map.json', 'reliability-config.json'];
   for (const engineFile of engineFiles) {
-    results.push(checkJsonFile(path.join(agentDir, 'engine', engineFile), `engine:${engineFile}`));
+    results.push(checkJsonFile(path.join(agentDir, ENGINE_DIR, engineFile), `engine:${engineFile}`));
   }
 
   // --- Check 11: Hooks file valid ---
-  results.push(checkJsonFile(path.join(agentDir, 'hooks', 'hooks.json'), 'hooks-json'));
+  results.push(checkJsonFile(path.join(agentDir, HOOKS_DIR, 'hooks.json'), 'hooks-json'));
 
   // --- Check 12: Cross-reference — loading-rules agents exist in manifest ---
-  const loadingRulesPath = path.join(agentDir, 'engine', 'loading-rules.json');
+  const loadingRulesPath = path.join(agentDir, ENGINE_DIR, 'loading-rules.json');
   if (fs.existsSync(loadingRulesPath)) {
     try {
       const loadingRules = JSON.parse(fs.readFileSync(loadingRulesPath, 'utf-8'));

package/lib/workflow-engine.js

@@ -14,6 +14,10 @@
 
 const fs = require('fs');
 const path = require('path');
+const workflowEvents = require('./workflow-events');
+const { writeJsonAtomic } = require('./io');
+const { createLogger } = require('./logger');
+const log = createLogger('workflow-engine');
 
 /** @typedef {'IDLE' | 'EXPLORE' | 'PLAN' | 'IMPLEMENT' | 'VERIFY' | 'REVIEW' | 'DEPLOY' | 'MAINTAIN'} WorkflowPhase */
 
@@ -37,8 +41,7 @@ const path = require('path');
  */
 
 const WORKFLOW_STATE_FILENAME = 'workflow-state.json';
-const ENGINE_DIR = 'engine';
-const AGENT_DIR = '.agent';
+const { AGENT_DIR, ENGINE_DIR } = require('./constants');
 
 /**
  * Resolves the absolute path to workflow-state.json for a given project root.
@@ -177,9 +180,9 @@ function validateTransition(projectRoot, toPhase) {
  * @returns {TransitionResult} Result of the transition attempt
  */
 function executeTransition(projectRoot, toPhase, triggerOverride) {
-  const { state, filePath } = loadWorkflowState(projectRoot);
-  const currentPhase = state.currentPhase;
-  const transitions = state.transitions || [];
+  const { state: loadedState, filePath } = loadWorkflowState(projectRoot);
+  const currentPhase = loadedState.currentPhase;
+  const transitions = loadedState.transitions || [];
 
   if (currentPhase === toPhase) {
     return {
@@ -212,53 +215,53 @@ function executeTransition(projectRoot, toPhase, triggerOverride) {
   const timestamp = new Date().toISOString();
   const trigger = triggerOverride || match.trigger;
 
+  // Build updated state immutably
+  const updatedPhases = { ...loadedState.phases };
+
   // Update previous phase completion timestamp
-  if (currentPhase !== 'IDLE' && state.phases[currentPhase]) {
-    state.phases[currentPhase].completedAt = timestamp;
-    state.phases[currentPhase].status = 'completed';
+  if (currentPhase !== 'IDLE' && updatedPhases[currentPhase]) {
+    updatedPhases[currentPhase] = {
+      ...updatedPhases[currentPhase],
+      completedAt: timestamp,
+      status: 'completed',
+    };
   }
 
   // Update target phase start timestamp
-  if (state.phases[toPhase]) {
-    state.phases[toPhase].startedAt = timestamp;
-    state.phases[toPhase].status = 'active';
-    state.phases[toPhase].completedAt = null;
-  }
-
-  // Update top-level state
-  state.currentPhase = toPhase;
-
-  if (!state.startedAt && currentPhase === 'IDLE') {
-    state.startedAt = timestamp;
-  }
-
-  // Append to history
-  if (!Array.isArray(state.history)) {
-    state.history = [];
+  if (updatedPhases[toPhase]) {
+    updatedPhases[toPhase] = {
+      ...updatedPhases[toPhase],
+      startedAt: timestamp,
+      status: 'active',
+      completedAt: null,
+    };
   }
 
-  state.history.push({
-    from: currentPhase,
-    to: toPhase,
-    trigger,
-    timestamp,
-  });
+  const existingHistory = Array.isArray(loadedState.history) ? loadedState.history : [];
+
+  const state = {
+    ...loadedState,
+    currentPhase: toPhase,
+    startedAt: (!loadedState.startedAt && currentPhase === 'IDLE') ? timestamp : loadedState.startedAt,
+    phases: updatedPhases,
+    history: [
+      ...existingHistory,
+      {
+        from: currentPhase,
+        to: toPhase,
+        trigger,
+        timestamp,
+      },
+    ],
+  };
 
-  // Atomic write: write to temp file, then rename
-  const tempPath = `${filePath}.tmp`;
+  // Emit transition start event
+  workflowEvents.emitTransitionStart(currentPhase, toPhase, trigger);
 
   try {
-    fs.writeFileSync(tempPath, JSON.stringify(state, null, 2) + '\n', 'utf-8');
-    fs.renameSync(tempPath, filePath);
+    writeJsonAtomic(filePath, state);
   } catch (writeError) {
-    // Clean up temp file if rename failed
-    if (fs.existsSync(tempPath)) {
-      try {
-        fs.unlinkSync(tempPath);
-      } catch {
-        // Swallow cleanup errors
-      }
-    }
+    workflowEvents.emitTransitionFailed(currentPhase, toPhase, writeError.message);
     return {
       success: false,
       fromPhase: currentPhase,
@@ -269,6 +272,9 @@ function executeTransition(projectRoot, toPhase, triggerOverride) {
     };
   }
 
+  // Emit transition complete event
+  workflowEvents.emitTransitionComplete(currentPhase, toPhase, trigger);
+
   return {
     success: true,
     fromPhase: currentPhase,
@@ -287,36 +293,50 @@ function executeTransition(projectRoot, toPhase, triggerOverride) {
  * @returns {{ success: boolean, previousPhase: string }}
  */
 function resetWorkflow(projectRoot, preserveHistory = true) {
-  const { state, filePath } = loadWorkflowState(projectRoot);
-  const previousPhase = state.currentPhase;
-
-  state.currentPhase = 'IDLE';
-  state.startedAt = null;
-
-  // Reset all phase records
-  for (const phaseName of Object.keys(state.phases || {})) {
-    state.phases[phaseName].status = 'pending';
-    state.phases[phaseName].startedAt = null;
-    state.phases[phaseName].completedAt = null;
-    state.phases[phaseName].artifact = null;
-  }
+  const { state: loadedState, filePath } = loadWorkflowState(projectRoot);
+  const previousPhase = loadedState.currentPhase;
+  const timestamp = new Date().toISOString();
 
-  if (!preserveHistory) {
-    state.history = [];
-  } else {
-    // Record the reset in history
-    state.history.push({
-      from: previousPhase,
-      to: 'IDLE',
-      trigger: 'Workflow reset',
-      timestamp: new Date().toISOString(),
-    });
+  // Build reset phases immutably
+  const resetPhases = {};
+  for (const phaseName of Object.keys(loadedState.phases || {})) {
+    resetPhases[phaseName] = {
+      ...loadedState.phases[phaseName],
+      status: 'pending',
+      startedAt: null,
+      completedAt: null,
+      artifact: null,
+    };
   }
 
-  const tempPath = `${filePath}.tmp`;
-  fs.writeFileSync(tempPath, JSON.stringify(state, null, 2) + '\n', 'utf-8');
-  fs.renameSync(tempPath, filePath);
+  const existingHistory = Array.isArray(loadedState.history) ? loadedState.history : [];
+  const history = preserveHistory
+    ? [
+        ...existingHistory,
+        {
+          from: previousPhase,
+          to: 'IDLE',
+          trigger: 'Workflow reset',
+          timestamp,
+        },
+      ]
+    : [];
+
+  const updatedState = {
+    ...loadedState,
+    currentPhase: 'IDLE',
+    startedAt: null,
+    phases: resetPhases,
+    history,
+  };
+
+  try {
+    writeJsonAtomic(filePath, updatedState);
+  } catch (writeError) {
+    return { success: false, previousPhase, error: `Failed to write state: ${writeError.message}` };
+  }
 
+  workflowEvents.emitWorkflowReset(previousPhase);
   return { success: true, previousPhase };
 }