@devran-ai/kit 4.1.0

package/lib/workflow-events.js

@@ -0,0 +1,166 @@
+/**
+ * Devran 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

@@ -0,0 +1,160 @@
+/**
+ * Devran AI Kit — Workflow Persistence
+ *
+ * Extends the workflow engine with checkpoint/resume capability.
+ * Workflow state survives across agent sessions via JSON file snapshots.
+ *
+ * @module lib/workflow-persistence
+ * @author Emre Dursun
+ * @since v3.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const workflowEngine = require('./workflow-engine');
+
+const { AGENT_DIR, ENGINE_DIR } = require('./constants');
+const { writeJsonAtomic } = require('./io');
+const CHECKPOINTS_DIR = 'checkpoints';
+
+/**
+ * Resolves the checkpoints directory path.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {string} Absolute path to checkpoints directory
+ */
+function resolveCheckpointsDir(projectRoot) {
+  return path.join(projectRoot, AGENT_DIR, ENGINE_DIR, CHECKPOINTS_DIR);
+}
+
+/**
+ * Creates a checkpoint of the current workflow state.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {string} [label] - Optional human-readable label
+ * @returns {{ checkpointId: string, filePath: string, timestamp: string }}
+ */
+function createCheckpoint(projectRoot, label) {
+  const { state } = workflowEngine.loadWorkflowState(projectRoot);
+  const checkpointsDir = resolveCheckpointsDir(projectRoot);
+
+  const timestamp = new Date().toISOString();
+  const checkpointId = crypto.randomUUID().slice(0, 8);
+
+  const checkpoint = {
+    id: checkpointId,
+    label: label || `Checkpoint at ${state.currentPhase}`,
+    timestamp,
+    phase: state.currentPhase,
+    state: JSON.parse(JSON.stringify(state)),
+  };
+
+  const filePath = path.join(checkpointsDir, `${checkpointId}.json`);
+  writeJsonAtomic(filePath, checkpoint);
+
+  return { checkpointId, filePath, timestamp };
+}
+
+/**
+ * Lists all available checkpoints, sorted by timestamp (newest first).
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {Array<{ id: string, label: string, phase: string, timestamp: string }>}
+ */
+function listCheckpoints(projectRoot) {
+  const checkpointsDir = resolveCheckpointsDir(projectRoot);
+
+  if (!fs.existsSync(checkpointsDir)) {
+    return [];
+  }
+
+  const files = fs.readdirSync(checkpointsDir).filter((f) => f.endsWith('.json'));
+
+  return files
+    .map((file) => {
+      try {
+        const data = JSON.parse(fs.readFileSync(path.join(checkpointsDir, file), 'utf-8'));
+        return { id: data.id, label: data.label, phase: data.phase, timestamp: data.timestamp };
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+}
+
+/**
+ * Restores workflow state from a checkpoint.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {string} checkpointId - ID of the checkpoint to restore
+ * @returns {{ success: boolean, restoredPhase: string }}
+ */
+function resumeFromCheckpoint(projectRoot, checkpointId) {
+  const checkpointsDir = resolveCheckpointsDir(projectRoot);
+  const filePath = path.join(checkpointsDir, `${checkpointId}.json`);
+
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Checkpoint not found: ${checkpointId}`);
+  }
+
+  const checkpoint = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  const statePath = path.join(projectRoot, AGENT_DIR, ENGINE_DIR, 'workflow-state.json');
+
+  // 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 };
+}
+
+/**
+ * Returns a rich summary of the current workflow state.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {object} Workflow summary with phase durations and checkpoint count
+ */
+function getWorkflowSummary(projectRoot) {
+  const { state } = workflowEngine.loadWorkflowState(projectRoot);
+  const checkpoints = listCheckpoints(projectRoot);
+  const history = state.history || [];
+
+  const phaseDurations = {};
+  for (const [phaseName, phaseData] of Object.entries(state.phases || {})) {
+    if (phaseData.startedAt && phaseData.completedAt) {
+      const duration = new Date(phaseData.completedAt).getTime() - new Date(phaseData.startedAt).getTime();
+      phaseDurations[phaseName] = Math.round(duration / 1000);
+    }
+  }
+
+  return {
+    currentPhase: state.currentPhase,
+    startedAt: state.startedAt,
+    transitionCount: history.length,
+    checkpointCount: checkpoints.length,
+    phaseDurations,
+    lastTransition: history.length > 0 ? history[history.length - 1] : null,
+  };
+}
+
+module.exports = {
+  createCheckpoint,
+  listCheckpoints,
+  resumeFromCheckpoint,
+  getWorkflowSummary,
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@devran-ai/kit",
+  "version": "4.1.0",
+  "description": "Trust-grade AI development framework — zero-dependency runtime engine for agent orchestration, workflow governance, and skill management.",
+  "main": "bin/kit.js",
+  "bin": {
+    "kit": "./bin/kit.js"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "preversion": "npm test",
+    "version": "node scripts/sync-version.js && git add -A -- . ':!.agent/engine/identity.json'",
+    "prepublishOnly": "node scripts/clean-identity.js",
+    "postinstall": "echo 'Devran AI Kit installed. Run: kit init'"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "gemini",
+    "claude",
+    "devran-ai",
+    "kit",
+    "governance",
+    "development",
+    "workflow",
+    "skills",
+    "commands",
+    "devtools",
+    "productivity",
+    "cli"
+  ],
+  "author": "Emre Dursun <info.emredursun@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/devran-ai/kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/devran-ai/kit/issues"
+  },
+  "homepage": "https://github.com/devran-ai/kit#readme",
+  "engines": {
+    "node": ">=18.0.0",
+    "npm": ">=9.0.0"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    ".agent/",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "vitest": "^4.1.0"
+  }
+}