@devran-ai/kit 4.1.0

package/lib/identity.js

@@ -0,0 +1,240 @@
+/**
+ * Devran AI Kit — Developer Identity System
+ *
+ * Local identity management for multi-developer scenarios.
+ * Auto-detects from git config with manual registration fallback.
+ *
+ * @module lib/identity
+ * @author Emre Dursun
+ * @since v3.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execSync } = require('child_process');
+
+const { AGENT_DIR, ENGINE_DIR } = require('./constants');
+const { writeJsonAtomic } = require('./io');
+const IDENTITY_FILE = 'identity.json';
+
+/** @type {readonly string[]} */
+const VALID_ROLES = ['owner', 'contributor', 'reviewer'];
+
+/**
+ * @typedef {object} Identity
+ * @property {string} id - Deterministic developer ID (SHA-256 truncated)
+ * @property {string} name - Developer name
+ * @property {string} email - Developer email
+ * @property {string} role - Developer role
+ * @property {string} registeredAt - ISO timestamp
+ * @property {string} lastActiveAt - ISO timestamp
+ */
+
+/**
+ * Resolves the identity file path.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {string} Absolute path to identity.json
+ */
+function resolveIdentityPath(projectRoot) {
+  return path.join(projectRoot, AGENT_DIR, ENGINE_DIR, IDENTITY_FILE);
+}
+
+/**
+ * Generates a deterministic developer ID from email.
+ *
+ * @param {string} email - Developer email
+ * @returns {string} 12-char hex ID
+ */
+function generateDeveloperId(email) {
+  return crypto
+    .createHash('sha256')
+    .update(email.toLowerCase().trim())
+    .digest('hex')
+    .slice(0, 12);
+}
+
+/**
+ * Loads the identity registry from disk.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {{ developers: Identity[], activeId: string | null }}
+ */
+function loadIdentityRegistry(projectRoot) {
+  const identityPath = resolveIdentityPath(projectRoot);
+
+  if (!fs.existsSync(identityPath)) {
+    return { developers: [], activeId: null };
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(identityPath, 'utf-8'));
+  } catch {
+    return { developers: [], activeId: null };
+  }
+}
+
+/**
+ * Writes the identity registry to disk atomically.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {object} registry - Registry data
+ * @returns {void}
+ */
+function writeIdentityRegistry(projectRoot, registry) {
+  const identityPath = resolveIdentityPath(projectRoot);
+  writeJsonAtomic(identityPath, registry);
+}
+
+/**
+ * Auto-detects developer identity from git config.
+ *
+ * @returns {{ name: string, email: string } | null}
+ */
+function detectFromGit() {
+  try {
+    const name = execSync('git config user.name', { encoding: 'utf-8' }).trim();
+    const email = execSync('git config user.email', { encoding: 'utf-8' }).trim();
+
+    if (name && email) {
+      return { name, email };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Registers a new developer identity.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {object} params - Identity parameters
+ * @param {string} params.name - Developer name
+ * @param {string} params.email - Developer email
+ * @param {string} [params.role] - Developer role (default: 'contributor')
+ * @returns {{ success: boolean, identity: Identity, isNew: boolean }}
+ */
+function registerIdentity(projectRoot, { name, email, role }) {
+  const registry = loadIdentityRegistry(projectRoot);
+  const developerId = generateDeveloperId(email);
+  const now = new Date().toISOString();
+  const identityRole = role && VALID_ROLES.includes(role) ? role : 'contributor';
+
+  // Check if already registered
+  const existingIndex = registry.developers.findIndex((d) => d.id === developerId);
+
+  if (existingIndex !== -1) {
+    // Update last active (immutable)
+    const updatedDev = { ...registry.developers[existingIndex], lastActiveAt: now, name };
+    const updatedRegistry = {
+      ...registry,
+      developers: registry.developers.map((d, i) => (i === existingIndex ? updatedDev : d)),
+      activeId: developerId,
+    };
+    writeIdentityRegistry(projectRoot, updatedRegistry);
+    return { success: true, identity: updatedDev, isNew: false };
+  }
+
+  // First developer becomes owner automatically
+  const assignedRole = registry.developers.length === 0 ? 'owner' : identityRole;
+
+  /** @type {Identity} */
+  const identity = {
+    id: developerId,
+    name,
+    email: email.toLowerCase().trim(),
+    role: assignedRole,
+    registeredAt: now,
+    lastActiveAt: now,
+  };
+
+  const updatedRegistry = {
+    ...registry,
+    developers: [...registry.developers, identity],
+    activeId: developerId,
+  };
+  writeIdentityRegistry(projectRoot, updatedRegistry);
+
+  return { success: true, identity, isNew: true };
+}
+
+/**
+ * Gets the current active developer identity.
+ * Auto-detects and registers from git if no identity exists.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {Identity | null}
+ */
+function getCurrentIdentity(projectRoot) {
+  const registry = loadIdentityRegistry(projectRoot);
+
+  if (registry.activeId) {
+    const identity = registry.developers.find((d) => d.id === registry.activeId);
+    if (identity) {
+      return identity;
+    }
+  }
+
+  // Auto-detect from git
+  const gitInfo = detectFromGit();
+  if (gitInfo) {
+    const result = registerIdentity(projectRoot, { name: gitInfo.name, email: gitInfo.email });
+    return result.identity;
+  }
+
+  return null;
+}
+
+/**
+ * Validates an identity exists and is properly formed.
+ *
+ * @param {string} developerId - Developer ID to validate
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+function validateIdentity(developerId, projectRoot) {
+  const registry = loadIdentityRegistry(projectRoot);
+  /** @type {string[]} */
+  const errors = [];
+
+  const identity = registry.developers.find((d) => d.id === developerId);
+
+  if (!identity) {
+    return { valid: false, errors: [`Identity not found: ${developerId}`] };
+  }
+
+  if (!identity.name || identity.name.trim().length === 0) {
+    errors.push('Identity missing name');
+  }
+  if (!identity.email || !identity.email.includes('@')) {
+    errors.push('Identity missing valid email');
+  }
+  if (!VALID_ROLES.includes(identity.role)) {
+    errors.push(`Invalid role: ${identity.role}`);
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Lists all registered developer identities.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {{ developers: Identity[], activeId: string | null }}
+ */
+function listIdentities(projectRoot) {
+  return loadIdentityRegistry(projectRoot);
+}
+
+module.exports = {
+  registerIdentity,
+  getCurrentIdentity,
+  validateIdentity,
+  listIdentities,
+  generateDeveloperId,
+  detectFromGit,
+};

package/lib/io.js

@@ -0,0 +1,146 @@
+/**
+ * Devran AI Kit — Shared I/O Utilities
+ *
+ * Provides atomic file write operations and safe JSON parsing
+ * used across all runtime modules. Single point for error
+ * handling around filesystem operations.
+ *
+ * @module lib/io
+ * @author Emre Dursun
+ * @since v3.2.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { createLogger } = require('./logger');
+const log = createLogger('io');
+
+/**
+ * Writes JSON data to a file atomically (temp file + rename).
+ * Creates parent directories if they don't exist.
+ *
+ * @param {string} filePath - Target file path
+ * @param {object} data - Data to serialize as JSON
+ * @returns {void}
+ */
+function writeJsonAtomic(filePath, data) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const content = JSON.stringify(data, null, 2) + '\n';
+  const tempPath = `${filePath}.tmp`;
+
+  try {
+    fs.writeFileSync(tempPath, content, 'utf-8');
+  } catch (writeErr) {
+    throw writeErr;
+  }
+
+  // Rename temp → target. On Windows, EPERM/EACCES can occur when
+  // another handle briefly holds the target file (antivirus, prior
+  // read, etc.). Retry up to 3 times with a small delay before
+  // falling back to a direct overwrite.
+  let renamed = false;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      fs.renameSync(tempPath, filePath);
+      renamed = true;
+      break;
+    } catch (renameErr) {
+      const isTransient = renameErr.code === 'EPERM' || renameErr.code === 'EACCES';
+      if (!isTransient || attempt === 2) {
+        // Final attempt failed — fall back to direct write
+        try {
+          fs.writeFileSync(filePath, content, 'utf-8');
+          renamed = true;
+        } catch (fallbackErr) {
+          // Clean up temp file before throwing
+          try { fs.unlinkSync(tempPath); } catch { /* non-critical */ }
+          throw fallbackErr;
+        }
+        break;
+      }
+      // Brief pause before retry (1ms, 5ms)
+      const delay = attempt === 0 ? 1 : 5;
+      const start = Date.now();
+      while (Date.now() - start < delay) { /* spin wait */ }
+    }
+  }
+
+  // Clean up temp file if direct-write fallback was used
+  if (renamed) {
+    try {
+      if (fs.existsSync(tempPath)) {
+        fs.unlinkSync(tempPath);
+      }
+    } catch {
+      // Cleanup failure is non-critical
+    }
+  }
+}
+
+/**
+ * Safely parses a JSON file, returning a default value on failure.
+ *
+ * @param {string} filePath - Path to JSON file
+ * @param {*} defaultValue - Value to return if file doesn't exist or is invalid
+ * @returns {*} Parsed JSON or default value
+ */
+function readJsonSafe(filePath, defaultValue = null) {
+  if (!fs.existsSync(filePath)) {
+    return defaultValue;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch (error) {
+    log.debug('Failed to parse JSON file, returning default', { filePath, error: error.message });
+    return defaultValue;
+  }
+}
+
+/**
+ * Recursively copies a directory, skipping symbolic links for security.
+ *
+ * Symlinks are skipped because they could point outside the intended
+ * scope (e.g., outside .agent/), enabling path traversal attacks.
+ *
+ * @param {string} src - Source directory path
+ * @param {string} dest - Destination directory path
+ * @returns {void}
+ */
+function safeCopyDirSync(src, dest) {
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    // Security: skip symlinks to prevent path traversal
+    const stat = fs.lstatSync(srcPath);
+    if (stat.isSymbolicLink()) {
+      log.debug('Skipping symlink for security', { path: srcPath });
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      safeCopyDirSync(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+module.exports = {
+  writeJsonAtomic,
+  readJsonSafe,
+  safeCopyDirSync,
+};

package/lib/learning-engine.js

@@ -0,0 +1,163 @@
+/**
+ * Devran AI Kit — Learning Engine
+ *
+ * Confidence scoring, pattern clustering, and decay model
+ * for the continuous learning system. Inspired by Netflix's
+ * chaos engineering feedback loop: observe, score, cluster, promote, decay.
+ *
+ * All functions are pure — no I/O, no side effects.
+ *
+ * @module lib/learning-engine
+ * @since v4.1.0
+ */
+
+'use strict';
+
+/** Confidence tier boundaries */
+const TIERS = Object.freeze([
+  { min: 10, score: 5 },
+  { min: 6, score: 4 },
+  { min: 4, score: 3 },
+  { min: 2, score: 2 },
+  { min: 1, score: 1 },
+]);
+
+/** Sessions without reinforcement before 1 point of decay */
+const DECAY_INTERVAL = 10;
+
+/** Minimum high-confidence patterns for skill promotion */
+const SKILL_PROMOTION_THRESHOLD = 3;
+
+/** Minimum confidence score for promotion eligibility */
+const PROMOTION_CONFIDENCE = 4;
+
+/**
+ * Score confidence for a pattern based on reinforcement count.
+ * Scale: 0 (never seen) to 5 (battle-tested, 10+ reinforcements).
+ *
+ * @param {number} reinforcementCount - Times pattern was observed
+ * @returns {number} Confidence score 0-5
+ */
+function scoreConfidence(reinforcementCount) {
+  if (!Number.isFinite(reinforcementCount) || reinforcementCount <= 0) {
+    return 0;
+  }
+  for (const tier of TIERS) {
+    if (reinforcementCount >= tier.min) {
+      return tier.score;
+    }
+  }
+  return 0;
+}
+
+/**
+ * Cluster patterns by domain using loading-rules keyword overlap.
+ *
+ * @param {Array<{id: string, keywords: string[], reinforcements: number}>} patterns
+ * @param {Array<{domain: string, keywords: string[]}>} domainRules
+ * @returns {Map<string, Array>} Patterns grouped by domain
+ */
+function clusterPatterns(patterns, domainRules) {
+  if (!Array.isArray(patterns)) return new Map();
+  if (!Array.isArray(domainRules)) return new Map();
+
+  const clusters = new Map();
+
+  for (const rule of domainRules) {
+    clusters.set(rule.domain, []);
+  }
+  clusters.set('uncategorized', []);
+
+  for (const pattern of patterns) {
+    let matched = false;
+    for (const rule of domainRules) {
+      const hasOverlap = pattern.keywords.some(pk =>
+        rule.keywords.some(rk =>
+          rk.toLowerCase() === pk.toLowerCase()
+        )
+      );
+      if (hasOverlap) {
+        clusters.get(rule.domain).push(pattern);
+        matched = true;
+        break;
+      }
+    }
+    if (!matched) {
+      clusters.get('uncategorized').push(pattern);
+    }
+  }
+
+  return clusters;
+}
+
+/**
+ * Apply decay to patterns based on sessions since last reinforcement.
+ * Loses 1 confidence point per DECAY_INTERVAL unreinforced sessions.
+ * Score 0 marks the pattern as archived.
+ *
+ * @param {Array<{id: string, confidence: number, sessionsSinceReinforcement: number}>} patterns
+ * @returns {Array<{id: string, confidence: number, archived: boolean}>}
+ */
+function decayPatterns(patterns) {
+  if (!Array.isArray(patterns)) return [];
+
+  return patterns.map(p => {
+    const sessions = Number.isFinite(p.sessionsSinceReinforcement) ? p.sessionsSinceReinforcement : 0;
+    const confidence = Number.isFinite(p.confidence) ? p.confidence : 0;
+    const decayAmount = Math.floor(sessions / DECAY_INTERVAL);
+    const newConfidence = Math.max(0, confidence - decayAmount);
+    return {
+      ...p,
+      confidence: newConfidence,
+      archived: newConfidence === 0,
+    };
+  });
+}
+
+/**
+ * Generate recommendations for pattern promotion.
+ * Clusters with 3+ high-confidence patterns suggest skill creation.
+ * Clusters with 1-2 high-confidence patterns suggest rule creation.
+ *
+ * @param {Map<string, Array<{reinforcements: number}>>} clusters
+ * @returns {Array<{domain: string, action: string, reason: string, patterns: Array}>}
+ */
+function getRecommendations(clusters) {
+  const recommendations = [];
+
+  for (const [domain, patterns] of clusters) {
+    if (domain === 'uncategorized') continue;
+
+    const highConfidence = patterns.filter(p =>
+      scoreConfidence(p.reinforcements) >= PROMOTION_CONFIDENCE
+    );
+
+    if (highConfidence.length >= SKILL_PROMOTION_THRESHOLD) {
+      recommendations.push({
+        domain,
+        action: 'promote-to-skill',
+        reason: `${highConfidence.length} battle-tested patterns in ${domain}`,
+        patterns: highConfidence,
+      });
+    } else if (highConfidence.length >= 1) {
+      recommendations.push({
+        domain,
+        action: 'promote-to-rule',
+        reason: `${highConfidence.length} high-confidence pattern(s) in ${domain}`,
+        patterns: highConfidence,
+      });
+    }
+  }
+
+  return recommendations;
+}
+
+module.exports = Object.freeze({
+  scoreConfidence,
+  clusterPatterns,
+  decayPatterns,
+  getRecommendations,
+  DECAY_INTERVAL,
+  SKILL_PROMOTION_THRESHOLD,
+  PROMOTION_CONFIDENCE,
+});