@devran-ai/kit 4.1.0

package/lib/config-validator.js

@@ -0,0 +1,274 @@
+/**
+ * Devran AI Kit — Configuration Validator
+ *
+ * Runtime JSON schema validation for engine configuration files.
+ * Catches configuration corruption and drift before they cause
+ * runtime failures.
+ *
+ * @module lib/config-validator
+ * @author Emre Dursun
+ * @since v3.2.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { AGENT_DIR, ENGINE_DIR, HOOKS_DIR } = require('./constants');
+
+/**
+ * @typedef {object} ValidationResult
+ * @property {boolean} valid - Whether the config is valid
+ * @property {string[]} errors - Validation error messages
+ * @property {string[]} warnings - Non-critical warnings
+ */
+
+/**
+ * Schema definitions for engine configuration files.
+ * Each schema defines required fields, their types, and constraints.
+ */
+const SCHEMAS = {
+  'manifest.json': {
+    required: ['schemaVersion', 'kitVersion', 'capabilities'],
+    types: {
+      schemaVersion: 'string',
+      kitVersion: 'string',
+      capabilities: 'object',
+    },
+    nested: {
+      capabilities: {
+        required: ['agents', 'commands', 'skills', 'workflows'],
+        types: {
+          agents: 'object',
+          commands: 'object',
+          skills: 'object',
+          workflows: 'object',
+        },
+      },
+    },
+  },
+
+  'workflow-state.json': {
+    required: ['currentPhase', 'phases', 'transitions'],
+    types: {
+      currentPhase: 'string',
+      phases: 'object',
+      transitions: 'array',
+    },
+    validators: {
+      currentPhase: (value) => {
+        const validPhases = ['IDLE', 'EXPLORE', 'PLAN', 'IMPLEMENT', 'VERIFY', 'REVIEW', 'DEPLOY', 'MAINTAIN'];
+        return validPhases.includes(value) ? null : `Invalid phase: ${value}. Valid: ${validPhases.join(', ')}`;
+      },
+    },
+  },
+
+  'loading-rules.json': {
+    required: ['domainRules', 'contextBudget', 'planningMandates'],
+    types: {
+      domainRules: 'array',
+      contextBudget: 'object',
+      planningMandates: 'object',
+    },
+    nested: {
+      contextBudget: {
+        required: ['maxAgentsPerSession', 'maxSkillsPerSession'],
+        types: {
+          maxAgentsPerSession: 'number',
+          maxSkillsPerSession: 'number',
+        },
+      },
+      planningMandates: {
+        required: ['alwaysLoadRules', 'alwaysLoadSkills', 'crossCuttingSections'],
+        types: {
+          alwaysLoadRules: 'array',
+          alwaysLoadSkills: 'array',
+          crossCuttingSections: 'array',
+          specialistContributors: 'object',
+        },
+      },
+    },
+    arrayItemSchema: {
+      domainRules: {
+        required: ['domain', 'keywords'],
+        types: {
+          domain: 'string',
+          keywords: 'array',
+          loadAgents: 'array',
+          loadSkills: 'array',
+        },
+      },
+    },
+  },
+
+  'reliability-config.json': {
+    required: ['errorBudget'],
+    types: {
+      errorBudget: 'object',
+    },
+    nested: {
+      errorBudget: {
+        required: ['thresholds', 'resetCadence'],
+        types: {
+          thresholds: 'object',
+          resetCadence: 'string',
+        },
+      },
+    },
+  },
+
+  'hooks.json': {
+    required: ['hooks'],
+    types: {
+      hooks: 'array',
+    },
+    arrayItemSchema: {
+      hooks: {
+        required: ['event'],
+        types: {
+          event: 'string',
+        },
+      },
+    },
+  },
+};
+
+/**
+ * Validates a value's type.
+ *
+ * @param {*} value - Value to check
+ * @param {string} expectedType - Expected type string
+ * @returns {boolean}
+ */
+function checkType(value, expectedType) {
+  if (expectedType === 'array') {
+    return Array.isArray(value);
+  }
+  return typeof value === expectedType;
+}
+
+/**
+ * Validates a configuration object against its schema.
+ *
+ * @param {object} config - Parsed configuration object
+ * @param {object} schema - Schema definition
+ * @param {string} [prefix=''] - Field path prefix for nested errors
+ * @returns {ValidationResult}
+ */
+function validateAgainstSchema(config, schema, prefix = '') {
+  const errors = [];
+  const warnings = [];
+
+  // Check required fields
+  for (const field of (schema.required || [])) {
+    const fieldPath = prefix ? `${prefix}.${field}` : field;
+    if (config[field] === undefined || config[field] === null) {
+      errors.push(`Missing required field: ${fieldPath}`);
+    }
+  }
+
+  // Check types
+  for (const [field, expectedType] of Object.entries(schema.types || {})) {
+    const fieldPath = prefix ? `${prefix}.${field}` : field;
+    if (config[field] !== undefined && config[field] !== null) {
+      if (!checkType(config[field], expectedType)) {
+        errors.push(`Invalid type for ${fieldPath}: expected ${expectedType}, got ${Array.isArray(config[field]) ? 'array' : typeof config[field]}`);
+      }
+    }
+  }
+
+  // Run custom validators
+  for (const [field, validator] of Object.entries(schema.validators || {})) {
+    if (config[field] !== undefined) {
+      const error = validator(config[field]);
+      if (error) {
+        errors.push(error);
+      }
+    }
+  }
+
+  // Validate nested schemas
+  for (const [field, nestedSchema] of Object.entries(schema.nested || {})) {
+    if (config[field] && typeof config[field] === 'object' && !Array.isArray(config[field])) {
+      const nestedResult = validateAgainstSchema(config[field], nestedSchema, prefix ? `${prefix}.${field}` : field);
+      errors.push(...nestedResult.errors);
+      warnings.push(...nestedResult.warnings);
+    }
+  }
+
+  // Validate array items
+  for (const [field, itemSchema] of Object.entries(schema.arrayItemSchema || {})) {
+    if (Array.isArray(config[field])) {
+      config[field].forEach((item, index) => {
+        if (typeof item === 'object' && item !== null) {
+          const itemResult = validateAgainstSchema(item, itemSchema, `${field}[${index}]`);
+          errors.push(...itemResult.errors);
+          warnings.push(...itemResult.warnings);
+        }
+      });
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Validates a specific engine configuration file.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {string} configName - Configuration file name (e.g., 'manifest.json')
+ * @returns {ValidationResult}
+ */
+function validateConfig(projectRoot, configName) {
+  const schema = SCHEMAS[configName];
+  if (!schema) {
+    return { valid: false, errors: [`No schema defined for: ${configName}`], warnings: [] };
+  }
+
+  const configDir = configName === 'manifest.json'
+    ? path.join(projectRoot, AGENT_DIR)
+    : configName === 'hooks.json'
+      ? path.join(projectRoot, AGENT_DIR, HOOKS_DIR)
+      : path.join(projectRoot, AGENT_DIR, ENGINE_DIR);
+
+  const configPath = path.join(configDir, configName);
+
+  if (!fs.existsSync(configPath)) {
+    return { valid: false, errors: [`Config file not found: ${configPath}`], warnings: [] };
+  }
+
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  } catch (parseError) {
+    return { valid: false, errors: [`Invalid JSON: ${parseError.message}`], warnings: [] };
+  }
+
+  return validateAgainstSchema(config, schema);
+}
+
+/**
+ * Validates all known engine configuration files.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {{ totalConfigs: number, validConfigs: number, results: Object.<string, ValidationResult> }}
+ */
+function validateAllConfigs(projectRoot) {
+  const entries = Object.keys(SCHEMAS).map(
+    (configName) => [configName, validateConfig(projectRoot, configName)]
+  );
+  const results = Object.fromEntries(entries);
+  const validCount = entries.filter(([, result]) => result.valid).length;
+
+  return {
+    totalConfigs: Object.keys(SCHEMAS).length,
+    validConfigs: validCount,
+    results,
+  };
+}
+
+module.exports = {
+  validateConfig,
+  validateAllConfigs,
+  SCHEMAS,
+};

package/lib/conflict-detector.js

@@ -0,0 +1,252 @@
+/**
+ * Devran AI Kit — Agent Conflict Detection
+ *
+ * Tracks file ownership by agents and detects concurrent modifications.
+ * Uses JSON-based locks for cross-platform compatibility.
+ *
+ * @module lib/conflict-detector
+ * @author Emre Dursun
+ * @since v3.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { AGENT_DIR, ENGINE_DIR } = require('./constants');
+const { writeJsonAtomic } = require('./io');
+const FILE_LOCKS_FILE = 'file-locks.json';
+
+/** Default lock TTL in milliseconds (30 minutes) */
+const DEFAULT_LOCK_TTL_MS = 30 * 60 * 1000;
+
+/**
+ * @typedef {object} FileLock
+ * @property {string} filePath - Relative path to the claimed file
+ * @property {string} agent - Agent name holding the lock
+ * @property {string} claimedAt - ISO timestamp
+ * @property {number} ttlMs - Time-to-live in milliseconds
+ */
+
+/**
+ * @typedef {object} ConflictReport
+ * @property {string} filePath - Path with conflict
+ * @property {string[]} agents - Agents claiming this file
+ * @property {'warning' | 'blocking'} severity - Conflict severity
+ */
+
+/**
+ * Resolves the file locks path.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {string}
+ */
+function resolveLocksPath(projectRoot) {
+  return path.join(projectRoot, AGENT_DIR, ENGINE_DIR, FILE_LOCKS_FILE);
+}
+
+/**
+ * Loads current file locks, filtering out stale ones.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {FileLock[]}
+ */
+function loadLocks(projectRoot) {
+  const locksPath = resolveLocksPath(projectRoot);
+
+  if (!fs.existsSync(locksPath)) {
+    return [];
+  }
+
+  try {
+    const data = JSON.parse(fs.readFileSync(locksPath, 'utf-8'));
+    const locks = data.locks || [];
+    const now = Date.now();
+
+    // Filter out expired locks
+    const activeLocks = locks.filter((lock) => {
+      const claimedTime = new Date(lock.claimedAt).getTime();
+      return (now - claimedTime) < (lock.ttlMs || DEFAULT_LOCK_TTL_MS);
+    });
+
+    // Persist pruned list if stale locks were removed
+    if (activeLocks.length < locks.length) {
+      writeLocks(projectRoot, activeLocks);
+    }
+
+    return activeLocks;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Writes locks to disk atomically.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {FileLock[]} locks - Current locks
+ * @returns {void}
+ */
+function writeLocks(projectRoot, locks) {
+  const locksPath = resolveLocksPath(projectRoot);
+  const data = {
+    schemaVersion: '1.0.0',
+    lastUpdated: new Date().toISOString(),
+    locks,
+  };
+
+  writeJsonAtomic(locksPath, data);
+}
+
+/**
+ * Claims a file for an agent.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {string} filePath - Relative path to file
+ * @param {string} agent - Agent name
+ * @param {number} [ttlMs] - Lock TTL in milliseconds
+ * @returns {{ success: boolean, conflict?: ConflictReport }}
+ */
+function claimFile(projectRoot, filePath, agent, ttlMs) {
+  const locks = loadLocks(projectRoot);
+  const normalizedPath = filePath.replace(/\\/g, '/');
+  const lockTtl = ttlMs || DEFAULT_LOCK_TTL_MS;
+
+  // Check for existing claim by a different agent
+  const existingLock = locks.find((l) => l.filePath === normalizedPath && l.agent !== agent);
+
+  if (existingLock) {
+    return {
+      success: false,
+      conflict: {
+        filePath: normalizedPath,
+        agents: [existingLock.agent, agent],
+        severity: 'blocking',
+      },
+    };
+  }
+
+  // Update or create lock immutably
+  const existingIndex = locks.findIndex((l) => l.filePath === normalizedPath && l.agent === agent);
+  const now = new Date().toISOString();
+
+  let updatedLocks;
+  if (existingIndex !== -1) {
+    updatedLocks = locks.map((l, i) =>
+      i === existingIndex
+        ? { ...l, claimedAt: now, ttlMs: lockTtl }
+        : l
+    );
+  } else {
+    updatedLocks = [
+      ...locks,
+      {
+        filePath: normalizedPath,
+        agent,
+        claimedAt: now,
+        ttlMs: lockTtl,
+      },
+    ];
+  }
+
+  writeLocks(projectRoot, updatedLocks);
+  return { success: true };
+}
+
+/**
+ * Releases a file lock held by an agent.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {string} filePath - Relative path to file
+ * @param {string} agent - Agent name
+ * @returns {{ success: boolean }}
+ */
+function releaseFile(projectRoot, filePath, agent) {
+  const locks = loadLocks(projectRoot);
+  const normalizedPath = filePath.replace(/\\/g, '/');
+  const filteredLocks = locks.filter((l) => !(l.filePath === normalizedPath && l.agent === agent));
+
+  if (filteredLocks.length === locks.length) {
+    return { success: false };
+  }
+
+  writeLocks(projectRoot, filteredLocks);
+  return { success: true };
+}
+
+/**
+ * Detects all current file conflicts.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {ConflictReport[]}
+ */
+function detectConflicts(projectRoot) {
+  const locks = loadLocks(projectRoot);
+  /** @type {Map<string, string[]>} */
+  const fileAgents = new Map();
+
+  for (const lock of locks) {
+    const agents = fileAgents.get(lock.filePath) || [];
+    if (!agents.includes(lock.agent)) {
+      agents.push(lock.agent);
+    }
+    fileAgents.set(lock.filePath, agents);
+  }
+
+  /** @type {ConflictReport[]} */
+  const conflicts = [];
+
+  for (const [filePath, agents] of fileAgents.entries()) {
+    if (agents.length > 1) {
+      conflicts.push({
+        filePath,
+        agents,
+        severity: agents.length > 2 ? 'blocking' : 'warning',
+      });
+    }
+  }
+
+  return conflicts;
+}
+
+/**
+ * Gets file ownership information.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {Array<{ filePath: string, agent: string, claimedAt: string }>}
+ */
+function getFileOwnership(projectRoot) {
+  const locks = loadLocks(projectRoot);
+
+  return locks.map((lock) => ({
+    filePath: lock.filePath,
+    agent: lock.agent,
+    claimedAt: lock.claimedAt,
+  }));
+}
+
+/**
+ * Generates a full conflict report with metrics.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {{ activeLocks: number, conflicts: ConflictReport[], hasBlockingConflict: boolean }}
+ */
+function reportConflicts(projectRoot) {
+  const locks = loadLocks(projectRoot);
+  const conflicts = detectConflicts(projectRoot);
+
+  return {
+    activeLocks: locks.length,
+    conflicts,
+    hasBlockingConflict: conflicts.some((c) => c.severity === 'blocking'),
+  };
+}
+
+module.exports = {
+  claimFile,
+  releaseFile,
+  detectConflicts,
+  getFileOwnership,
+  reportConflicts,
+};

package/lib/constants.js

@@ -0,0 +1,47 @@
+/**
+ * Devran AI Kit — Shared Constants
+ *
+ * Central definition of directory names and paths used across
+ * all runtime modules. Prevents drift from duplicated strings.
+ * Frozen to prevent accidental mutation at runtime.
+ *
+ * @module lib/constants
+ * @since v3.2.0
+ */
+
+'use strict';
+
+/** Root agent configuration directory name */
+const AGENT_DIR = '.agent';
+
+/** Engine subdirectory within .agent */
+const ENGINE_DIR = 'engine';
+
+/** Hooks subdirectory within .agent */
+const HOOKS_DIR = 'hooks';
+
+/** Skills subdirectory within .agent */
+const SKILLS_DIR = 'skills';
+
+/** Plugins subdirectory within .agent */
+const PLUGINS_DIR = 'plugins';
+
+/** Cursor IDE configuration directory */
+const CURSOR_DIR = '.cursor';
+
+/** OpenCode IDE configuration directory */
+const OPENCODE_DIR = '.opencode';
+
+/** Codex IDE configuration directory */
+const CODEX_DIR = '.codex';
+
+module.exports = Object.freeze({
+  AGENT_DIR,
+  ENGINE_DIR,
+  HOOKS_DIR,
+  SKILLS_DIR,
+  PLUGINS_DIR,
+  CURSOR_DIR,
+  OPENCODE_DIR,
+  CODEX_DIR,
+});