antigravity-ai-kit 2.1.0 → 3.0.1

package/lib/verify.js

@@ -0,0 +1,240 @@
+/**
+ * Antigravity AI Kit — Manifest Verification
+ *
+ * Validates the integrity of the .agent/ framework by checking
+ * manifest ↔ filesystem consistency, JSON validity, and
+ * cross-reference integrity.
+ *
+ * @module lib/verify
+ * @author Emre Dursun
+ * @since v3.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const AGENT_DIR = '.agent';
+
+/**
+ * @typedef {object} CheckResult
+ * @property {string} name - Check name
+ * @property {'pass' | 'fail' | 'warn'} status - Result status
+ * @property {string} message - Human-readable result message
+ */
+
+/**
+ * @typedef {object} VerificationReport
+ * @property {number} passed - Number of passed checks
+ * @property {number} failed - Number of failed checks
+ * @property {number} warnings - Number of warnings
+ * @property {CheckResult[]} results - Individual check results
+ */
+
+/**
+ * Checks that a JSON file exists and is valid.
+ *
+ * @param {string} filePath - Absolute path to JSON file
+ * @param {string} checkName - Name for the check result
+ * @returns {CheckResult}
+ */
+function checkJsonFile(filePath, checkName) {
+  if (!fs.existsSync(filePath)) {
+    return { name: checkName, status: 'fail', message: `File not found: ${filePath}` };
+  }
+
+  try {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    JSON.parse(raw);
+    return { name: checkName, status: 'pass', message: `Valid JSON: ${path.basename(filePath)}` };
+  } catch (parseError) {
+    return { name: checkName, status: 'fail', message: `Invalid JSON: ${parseError.message}` };
+  }
+}
+
+/**
+ * Runs all manifest integrity checks.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {VerificationReport}
+ */
+function runAllChecks(projectRoot) {
+  const agentDir = path.join(projectRoot, AGENT_DIR);
+  /** @type {CheckResult[]} */
+  const results = [];
+
+  // --- Check 1: Manifest exists and is valid JSON ---
+  const manifestPath = path.join(agentDir, 'manifest.json');
+  results.push(checkJsonFile(manifestPath, 'manifest-exists'));
+
+  if (!fs.existsSync(manifestPath)) {
+    return buildReport(results);
+  }
+
+  /** @type {object} */
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return buildReport(results);
+  }
+
+  // --- Check 2: Schema version is valid ---
+  const schemaVersion = manifest.schemaVersion || '';
+  const semverPattern = /^\d+\.\d+\.\d+$/;
+  results.push({
+    name: 'schema-version',
+    status: semverPattern.test(schemaVersion) ? 'pass' : 'fail',
+    message: semverPattern.test(schemaVersion)
+      ? `Schema version valid: ${schemaVersion}`
+      : `Invalid schema version: "${schemaVersion}"`,
+  });
+
+  // --- Check 3: Agent files exist ---
+  const agents = manifest.capabilities?.agents?.items || [];
+  for (const agent of agents) {
+    const agentPath = path.join(agentDir, agent.file);
+    const exists = fs.existsSync(agentPath);
+    results.push({
+      name: `agent-file:${agent.name}`,
+      status: exists ? 'pass' : 'fail',
+      message: exists ? `Agent exists: ${agent.name}` : `Missing agent file: ${agent.file}`,
+    });
+  }
+
+  // --- Check 4: Agent count matches ---
+  const agentCountManifest = manifest.capabilities?.agents?.count || 0;
+  const agentCountFS = fs.existsSync(path.join(agentDir, 'agents'))
+    ? fs.readdirSync(path.join(agentDir, 'agents')).filter((f) => f.endsWith('.md') && f !== 'README.md').length
+    : 0;
+  results.push({
+    name: 'agent-count',
+    status: agentCountManifest === agentCountFS ? 'pass' : 'fail',
+    message:
+      agentCountManifest === agentCountFS
+        ? `Agent count matches: ${agentCountFS}`
+        : `Agent count mismatch: manifest=${agentCountManifest}, filesystem=${agentCountFS}`,
+  });
+
+  // --- Check 5: Skill directories and SKILL.md exist ---
+  const skills = manifest.capabilities?.skills?.items || [];
+  for (const skill of skills) {
+    const skillPath = path.join(agentDir, skill.directory, 'SKILL.md');
+    const exists = fs.existsSync(skillPath);
+    results.push({
+      name: `skill-file:${skill.name}`,
+      status: exists ? 'pass' : 'fail',
+      message: exists ? `Skill exists: ${skill.name}` : `Missing SKILL.md: ${skill.directory}SKILL.md`,
+    });
+  }
+
+  // --- Check 6: Skill count matches ---
+  const skillCountManifest = manifest.capabilities?.skills?.count || 0;
+  const skillCountFS = fs.existsSync(path.join(agentDir, 'skills'))
+    ? fs.readdirSync(path.join(agentDir, 'skills'), { withFileTypes: true }).filter((d) => d.isDirectory()).length
+    : 0;
+  results.push({
+    name: 'skill-count',
+    status: skillCountManifest === skillCountFS ? 'pass' : 'fail',
+    message:
+      skillCountManifest === skillCountFS
+        ? `Skill count matches: ${skillCountFS}`
+        : `Skill count mismatch: manifest=${skillCountManifest}, filesystem=${skillCountFS}`,
+  });
+
+  // --- Check 7: Workflow files exist ---
+  const workflows = manifest.capabilities?.workflows?.items || [];
+  for (const workflow of workflows) {
+    const wfPath = path.join(agentDir, workflow.file);
+    const exists = fs.existsSync(wfPath);
+    results.push({
+      name: `workflow-file:${workflow.name}`,
+      status: exists ? 'pass' : 'fail',
+      message: exists ? `Workflow exists: ${workflow.name}` : `Missing workflow: ${workflow.file}`,
+    });
+  }
+
+  // --- Check 8: Workflow count matches ---
+  const wfCountManifest = manifest.capabilities?.workflows?.count || 0;
+  const wfCountFS = fs.existsSync(path.join(agentDir, 'workflows'))
+    ? fs.readdirSync(path.join(agentDir, 'workflows')).filter((f) => f.endsWith('.md') && f !== 'README.md').length
+    : 0;
+  results.push({
+    name: 'workflow-count',
+    status: wfCountManifest === wfCountFS ? 'pass' : 'fail',
+    message:
+      wfCountManifest === wfCountFS
+        ? `Workflow count matches: ${wfCountFS}`
+        : `Workflow count mismatch: manifest=${wfCountManifest}, filesystem=${wfCountFS}`,
+  });
+
+  // --- Check 9: Command count matches ---
+  const cmdCountManifest = manifest.capabilities?.commands?.count || 0;
+  const cmdCountFS = fs.existsSync(path.join(agentDir, 'commands'))
+    ? fs.readdirSync(path.join(agentDir, 'commands')).filter((f) => f.endsWith('.md') && f !== 'README.md').length
+    : 0;
+  results.push({
+    name: 'command-count',
+    status: cmdCountManifest === cmdCountFS ? 'pass' : 'fail',
+    message:
+      cmdCountManifest === cmdCountFS
+        ? `Command count matches: ${cmdCountFS}`
+        : `Command count mismatch: manifest=${cmdCountManifest}, filesystem=${cmdCountFS}`,
+  });
+
+  // --- 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}`));
+  }
+
+  // --- Check 11: Hooks file valid ---
+  results.push(checkJsonFile(path.join(agentDir, 'hooks', 'hooks.json'), 'hooks-json'));
+
+  // --- Check 12: Cross-reference — loading-rules agents exist in manifest ---
+  const loadingRulesPath = path.join(agentDir, 'engine', 'loading-rules.json');
+  if (fs.existsSync(loadingRulesPath)) {
+    try {
+      const loadingRules = JSON.parse(fs.readFileSync(loadingRulesPath, 'utf-8'));
+      const manifestAgentNames = new Set(agents.map((agent) => agent.name));
+      const domainRules = loadingRules.domainRules || [];
+
+      for (const rule of domainRules) {
+        for (const agentName of (rule.loadAgents || [])) {
+          const exists = manifestAgentNames.has(agentName);
+          results.push({
+            name: `xref:loading-rules:${agentName}`,
+            status: exists ? 'pass' : 'warn',
+            message: exists
+              ? `Loading-rules agent "${agentName}" exists in manifest`
+              : `Loading-rules references agent "${agentName}" not in manifest`,
+          });
+        }
+      }
+    } catch {
+      results.push({ name: 'xref:loading-rules', status: 'warn', message: 'Could not parse loading-rules.json for cross-reference check' });
+    }
+  }
+
+  return buildReport(results);
+}
+
+/**
+ * Builds a summary report from individual check results.
+ *
+ * @param {CheckResult[]} results - Array of individual check results
+ * @returns {VerificationReport}
+ */
+function buildReport(results) {
+  const passed = results.filter((result) => result.status === 'pass').length;
+  const failed = results.filter((result) => result.status === 'fail').length;
+  const warnings = results.filter((result) => result.status === 'warn').length;
+
+  return { passed, failed, warnings, results };
+}
+
+module.exports = {
+  runAllChecks,
+  checkJsonFile,
+};

package/lib/workflow-engine.js

@@ -0,0 +1,353 @@
+/**
+ * Antigravity AI Kit — Workflow Engine
+ *
+ * Runtime module that enforces workflow-state.json transitions.
+ * This is the first true runtime enforcement layer — transitions
+ * are validated against the defined state machine before being applied.
+ *
+ * @module lib/workflow-engine
+ * @author Emre Dursun
+ * @since v3.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/** @typedef {'IDLE' | 'EXPLORE' | 'PLAN' | 'IMPLEMENT' | 'VERIFY' | 'REVIEW' | 'DEPLOY' | 'MAINTAIN'} WorkflowPhase */
+
+/**
+ * @typedef {object} TransitionResult
+ * @property {boolean} success - Whether the transition was applied
+ * @property {string} fromPhase - Phase before transition
+ * @property {string} toPhase - Target phase
+ * @property {string} trigger - What triggered the transition
+ * @property {string} guard - Guard condition for this transition
+ * @property {string} [timestamp] - ISO timestamp of when transition occurred
+ * @property {string} [error] - Error message if transition failed
+ */
+
+/**
+ * @typedef {object} HistoryEntry
+ * @property {string} from - Source phase
+ * @property {string} to - Target phase
+ * @property {string} trigger - Transition trigger
+ * @property {string} timestamp - ISO timestamp
+ */
+
+const WORKFLOW_STATE_FILENAME = 'workflow-state.json';
+const ENGINE_DIR = 'engine';
+const AGENT_DIR = '.agent';
+
+/**
+ * Resolves the absolute path to workflow-state.json for a given project root.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {string} Absolute path to workflow-state.json
+ */
+function resolveStatePath(projectRoot) {
+  return path.join(projectRoot, AGENT_DIR, ENGINE_DIR, WORKFLOW_STATE_FILENAME);
+}
+
+/**
+ * Loads and parses the workflow state from disk.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {{ state: object, filePath: string }}
+ * @throws {Error} If file does not exist or contains invalid JSON
+ */
+function loadWorkflowState(projectRoot) {
+  const filePath = resolveStatePath(projectRoot);
+
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Workflow state file not found: ${filePath}`);
+  }
+
+  const raw = fs.readFileSync(filePath, 'utf-8');
+
+  try {
+    const state = JSON.parse(raw);
+    return { state, filePath };
+  } catch (parseError) {
+    throw new Error(`Invalid JSON in workflow state file: ${parseError.message}`);
+  }
+}
+
+/**
+ * Returns the current workflow phase for a project.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {string} Current phase name (e.g., 'IDLE', 'PLAN')
+ */
+function getCurrentPhase(projectRoot) {
+  const { state } = loadWorkflowState(projectRoot);
+  return state.currentPhase;
+}
+
+/**
+ * Returns the full transition history.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {HistoryEntry[]} Array of historical transitions
+ */
+function getTransitionHistory(projectRoot) {
+  const { state } = loadWorkflowState(projectRoot);
+  return state.history || [];
+}
+
+/**
+ * Finds a matching transition definition from the state machine.
+ *
+ * @param {object[]} transitions - Array of transition definitions
+ * @param {string} fromPhase - Source phase
+ * @param {string} toPhase - Target phase
+ * @returns {object | null} Matching transition or null
+ */
+function findTransition(transitions, fromPhase, toPhase) {
+  return transitions.find(
+    (transition) => transition.from === fromPhase && transition.to === toPhase
+  ) || null;
+}
+
+/**
+ * Validates whether a transition from the current phase to the target phase
+ * is permitted by the state machine definition.
+ *
+ * Does NOT execute the transition — use executeTransition() for that.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {string} toPhase - Target phase to transition to
+ * @returns {TransitionResult} Validation result (success does not mean executed)
+ */
+function validateTransition(projectRoot, toPhase) {
+  const { state } = loadWorkflowState(projectRoot);
+  const currentPhase = state.currentPhase;
+  const transitions = state.transitions || [];
+
+  if (currentPhase === toPhase) {
+    return {
+      success: false,
+      fromPhase: currentPhase,
+      toPhase,
+      trigger: '',
+      guard: '',
+      error: `Already in phase ${toPhase} — no transition needed`,
+    };
+  }
+
+  const match = findTransition(transitions, currentPhase, toPhase);
+
+  if (!match) {
+    const validTargets = transitions
+      .filter((transition) => transition.from === currentPhase)
+      .map((transition) => transition.to);
+
+    return {
+      success: false,
+      fromPhase: currentPhase,
+      toPhase,
+      trigger: '',
+      guard: '',
+      error: `Invalid transition: ${currentPhase} → ${toPhase}. Valid targets from ${currentPhase}: [${validTargets.join(', ')}]`,
+    };
+  }
+
+  return {
+    success: true,
+    fromPhase: currentPhase,
+    toPhase,
+    trigger: match.trigger,
+    guard: match.guard,
+  };
+}
+
+/**
+ * Executes a workflow transition atomically.
+ *
+ * 1. Validates the transition is permitted
+ * 2. Updates the current phase
+ * 3. Records timestamps on phase records
+ * 4. Appends to history
+ * 5. Writes updated state to disk
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {string} toPhase - Target phase to transition to
+ * @param {string} [triggerOverride] - Optional override for the trigger description
+ * @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 || [];
+
+  if (currentPhase === toPhase) {
+    return {
+      success: false,
+      fromPhase: currentPhase,
+      toPhase,
+      trigger: '',
+      guard: '',
+      error: `Already in phase ${toPhase} — no transition needed`,
+    };
+  }
+
+  const match = findTransition(transitions, currentPhase, toPhase);
+
+  if (!match) {
+    const validTargets = transitions
+      .filter((transition) => transition.from === currentPhase)
+      .map((transition) => transition.to);
+
+    return {
+      success: false,
+      fromPhase: currentPhase,
+      toPhase,
+      trigger: '',
+      guard: '',
+      error: `Invalid transition: ${currentPhase} → ${toPhase}. Valid targets from ${currentPhase}: [${validTargets.join(', ')}]`,
+    };
+  }
+
+  const timestamp = new Date().toISOString();
+  const trigger = triggerOverride || match.trigger;
+
+  // Update previous phase completion timestamp
+  if (currentPhase !== 'IDLE' && state.phases[currentPhase]) {
+    state.phases[currentPhase].completedAt = timestamp;
+    state.phases[currentPhase].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 = [];
+  }
+
+  state.history.push({
+    from: currentPhase,
+    to: toPhase,
+    trigger,
+    timestamp,
+  });
+
+  // Atomic write: write to temp file, then rename
+  const tempPath = `${filePath}.tmp`;
+
+  try {
+    fs.writeFileSync(tempPath, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+    fs.renameSync(tempPath, filePath);
+  } catch (writeError) {
+    // Clean up temp file if rename failed
+    if (fs.existsSync(tempPath)) {
+      try {
+        fs.unlinkSync(tempPath);
+      } catch {
+        // Swallow cleanup errors
+      }
+    }
+    return {
+      success: false,
+      fromPhase: currentPhase,
+      toPhase,
+      trigger,
+      guard: match.guard,
+      error: `Failed to write state: ${writeError.message}`,
+    };
+  }
+
+  return {
+    success: true,
+    fromPhase: currentPhase,
+    toPhase,
+    trigger,
+    guard: match.guard,
+    timestamp,
+  };
+}
+
+/**
+ * Resets the workflow to IDLE state with clean phase records.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {boolean} [preserveHistory=true] - Whether to keep transition history
+ * @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;
+  }
+
+  if (!preserveHistory) {
+    state.history = [];
+  } else {
+    // Record the reset in history
+    state.history.push({
+      from: previousPhase,
+      to: 'IDLE',
+      trigger: 'Workflow reset',
+      timestamp: new Date().toISOString(),
+    });
+  }
+
+  const tempPath = `${filePath}.tmp`;
+  fs.writeFileSync(tempPath, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+  fs.renameSync(tempPath, filePath);
+
+  return { success: true, previousPhase };
+}
+
+/**
+ * Returns all valid transitions from the current phase.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {{ currentPhase: string, validTransitions: object[] }}
+ */
+function getAvailableTransitions(projectRoot) {
+  const { state } = loadWorkflowState(projectRoot);
+  const currentPhase = state.currentPhase;
+  const transitions = state.transitions || [];
+
+  const validTransitions = transitions
+    .filter((transition) => transition.from === currentPhase)
+    .map((transition) => ({
+      to: transition.to,
+      trigger: transition.trigger,
+      guard: transition.guard,
+    }));
+
+  return { currentPhase, validTransitions };
+}
+
+module.exports = {
+  loadWorkflowState,
+  getCurrentPhase,
+  getTransitionHistory,
+  validateTransition,
+  executeTransition,
+  resetWorkflow,
+  getAvailableTransitions,
+};