@devran-ai/kit 4.1.0

package/lib/verify.js

@@ -0,0 +1,279 @@
+/**
+ * Devran 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, ENGINE_DIR, HOOKS_DIR } = require('./constants');
+
+/**
+ * @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_DIR, engineFile), `engine:${engineFile}`));
+  }
+
+  // --- Check 10a: Rule files exist ---
+  const manifestRules = manifest.capabilities?.rules?.items || [];
+  for (const rule of manifestRules) {
+    const rulePath = path.join(agentDir, rule.file);
+    const exists = fs.existsSync(rulePath);
+    results.push({
+      name: `rule-file:${rule.name}`,
+      status: exists ? 'pass' : 'fail',
+      message: exists ? `Rule exists: ${rule.name}` : `Missing rule file: ${rule.file}`,
+    });
+  }
+
+  // --- Check 10b: Rule count matches ---
+  const ruleCountManifest = manifest.capabilities?.rules?.count || 0;
+  const ruleCountFS = fs.existsSync(path.join(agentDir, 'rules'))
+    ? fs.readdirSync(path.join(agentDir, 'rules')).filter((f) => f.endsWith('.md') && f !== 'README.md').length
+    : 0;
+  results.push({
+    name: 'rule-count',
+    status: ruleCountManifest === ruleCountFS ? 'pass' : 'fail',
+    message:
+      ruleCountManifest === ruleCountFS
+        ? `Rule count matches: ${ruleCountFS}`
+        : `Rule count mismatch: manifest=${ruleCountManifest}, filesystem=${ruleCountFS}`,
+  });
+
+  // --- Check 11: Hooks file valid ---
+  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_DIR, '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`,
+          });
+        }
+      }
+      // --- Check 13: Cross-reference — alwaysLoadRules files exist ---
+      const mandatoryRules = loadingRules.planningMandates?.alwaysLoadRules || [];
+      for (const ruleName of mandatoryRules) {
+        const rulePath = path.join(agentDir, 'rules', `${ruleName}.md`);
+        const ruleExists = fs.existsSync(rulePath);
+        results.push({
+          name: `xref:mandatory-rule:${ruleName}`,
+          status: ruleExists ? 'pass' : 'fail',
+          message: ruleExists
+            ? `Mandatory rule "${ruleName}" exists`
+            : `Mandatory rule "${ruleName}" referenced in alwaysLoadRules but file missing: rules/${ruleName}.md`,
+        });
+      }
+    } 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,373 @@
+/**
+ * Devran 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');
+const workflowEvents = require('./workflow-events');
+const { writeJsonAtomic } = require('./io');
+const { createLogger } = require('./logger');
+const log = createLogger('workflow-engine');
+
+/** @typedef {'IDLE' | 'EXPLORE' | 'PLAN' | 'IMPLEMENT' | 'VERIFY' | 'CHECKPOINT' | '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 { AGENT_DIR, ENGINE_DIR } = require('./constants');
+
+/**
+ * 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: loadedState, filePath } = loadWorkflowState(projectRoot);
+  const currentPhase = loadedState.currentPhase;
+  const transitions = loadedState.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;
+
+  // Build updated state immutably
+  const updatedPhases = { ...loadedState.phases };
+
+  // Update previous phase completion timestamp
+  if (currentPhase !== 'IDLE' && updatedPhases[currentPhase]) {
+    updatedPhases[currentPhase] = {
+      ...updatedPhases[currentPhase],
+      completedAt: timestamp,
+      status: 'completed',
+    };
+  }
+
+  // Update target phase start timestamp
+  if (updatedPhases[toPhase]) {
+    updatedPhases[toPhase] = {
+      ...updatedPhases[toPhase],
+      startedAt: timestamp,
+      status: 'active',
+      completedAt: null,
+    };
+  }
+
+  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,
+      },
+    ],
+  };
+
+  // Emit transition start event
+  workflowEvents.emitTransitionStart(currentPhase, toPhase, trigger);
+
+  try {
+    writeJsonAtomic(filePath, state);
+  } catch (writeError) {
+    workflowEvents.emitTransitionFailed(currentPhase, toPhase, writeError.message);
+    return {
+      success: false,
+      fromPhase: currentPhase,
+      toPhase,
+      trigger,
+      guard: match.guard,
+      error: `Failed to write state: ${writeError.message}`,
+    };
+  }
+
+  // Emit transition complete event
+  workflowEvents.emitTransitionComplete(currentPhase, toPhase, trigger);
+
+  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: loadedState, filePath } = loadWorkflowState(projectRoot);
+  const previousPhase = loadedState.currentPhase;
+  const 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 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 };
+}
+
+/**
+ * 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,
+};