@devran-ai/kit 4.1.0

package/lib/hook-system.js

@@ -0,0 +1,256 @@
+/**
+ * Devran AI Kit — Hook Trigger System
+ *
+ * Event-driven lifecycle hook execution based on hooks.json.
+ * Evaluates hook actions and reports results with severity awareness.
+ *
+ * @module lib/hook-system
+ * @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');
+
+const HOOKS_FILE = 'hooks.json';
+
+/**
+ * @typedef {object} ActionResult
+ * @property {string} action - Action description
+ * @property {'critical' | 'high' | 'medium' | 'low'} severity - Action severity
+ * @property {'block' | 'warn' | 'log'} onFailure - Failure behavior
+ * @property {'pass' | 'fail' | 'skip'} status - Evaluation result
+ * @property {string} reason - Reason for status
+ */
+
+/**
+ * @typedef {object} HookEvaluation
+ * @property {string} event - Hook event name
+ * @property {boolean} blocked - Whether any blocking action failed
+ * @property {number} passed - Count of passed actions
+ * @property {number} failed - Count of failed actions
+ * @property {number} skipped - Count of skipped actions
+ * @property {ActionResult[]} results - Individual action results
+ */
+
+/**
+ * Loads hooks definition from hooks.json.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {object} Parsed hooks config
+ */
+function loadHooks(projectRoot) {
+  const hooksPath = path.join(projectRoot, AGENT_DIR, HOOKS_DIR, HOOKS_FILE);
+
+  if (!fs.existsSync(hooksPath)) {
+    return { hooks: [] };
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(hooksPath, 'utf-8'));
+  } catch {
+    return { hooks: [] };
+  }
+}
+
+/**
+ * Gets the action definitions for a specific event.
+ *
+ * @param {string} eventName - Hook event name (e.g., 'session-start')
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {object[]} Action definitions for this event
+ */
+function getHookActions(eventName, projectRoot) {
+  const config = loadHooks(projectRoot);
+  const hook = (config.hooks || []).find((h) => h.event === eventName);
+
+  if (!hook) {
+    return [];
+  }
+
+  return hook.actions || [];
+}
+
+/**
+ * Evaluates a hook event against the current project state.
+ *
+ * This performs a "check" pass — it determines which actions would
+ * pass or fail without actually executing them. Actions are evaluated
+ * based on the existence of required files and configurations.
+ *
+ * @param {string} eventName - Hook event name
+ * @param {object} context - Evaluation context
+ * @param {string} context.projectRoot - Root directory of the project
+ * @param {boolean} [context.gitClean] - Whether git status is clean
+ * @param {boolean} [context.testsPass] - Whether tests pass
+ * @param {boolean} [context.buildPass] - Whether build passes
+ * @param {boolean} [context.lintPass] - Whether lint passes
+ * @returns {HookEvaluation}
+ */
+function evaluateHook(eventName, context) {
+  const projectRoot = context.projectRoot;
+  const actions = getHookActions(eventName, projectRoot);
+
+  if (actions.length === 0) {
+    return { event: eventName, blocked: false, passed: 0, failed: 0, skipped: 0, results: [] };
+  }
+
+  /** @type {ActionResult[]} */
+  const results = [];
+  let blocked = false;
+
+  for (const action of actions) {
+    const result = evaluateAction(action, context);
+    results.push(result);
+
+    if (result.status === 'fail' && action.onFailure === 'block') {
+      blocked = true;
+    }
+  }
+
+  return {
+    event: eventName,
+    blocked,
+    passed: results.filter((r) => r.status === 'pass').length,
+    failed: results.filter((r) => r.status === 'fail').length,
+    skipped: results.filter((r) => r.status === 'skip').length,
+    results,
+  };
+}
+
+/**
+ * Evaluates a single action based on context.
+ *
+ * @param {object} action - Action definition from hooks.json
+ * @param {object} context - Evaluation context
+ * @returns {ActionResult}
+ */
+function evaluateAction(action, context) {
+  const actionLower = action.action.toLowerCase();
+  const projectRoot = context.projectRoot;
+
+  // File existence checks
+  if (actionLower.includes('session-context.md') || actionLower.includes('session-state.json')) {
+    const targetFile = actionLower.includes('session-context.md') ? 'session-context.md' : 'session-state.json';
+    const filePath = path.join(projectRoot, AGENT_DIR, targetFile);
+    const exists = fs.existsSync(filePath);
+
+    return {
+      action: action.action,
+      severity: action.severity,
+      onFailure: action.onFailure,
+      status: exists ? 'pass' : 'fail',
+      reason: exists ? `${targetFile} exists` : `${targetFile} not found`,
+    };
+  }
+
+  if (actionLower.includes('loading-rules.json') || actionLower.includes('workflow-state.json')) {
+    const targetFile = actionLower.includes('loading-rules.json') ? 'loading-rules.json' : 'workflow-state.json';
+    const filePath = path.join(projectRoot, AGENT_DIR, ENGINE_DIR, targetFile);
+    const exists = fs.existsSync(filePath);
+
+    return {
+      action: action.action,
+      severity: action.severity,
+      onFailure: action.onFailure,
+      status: exists ? 'pass' : 'fail',
+      reason: exists ? `${targetFile} exists and readable` : `${targetFile} not found`,
+    };
+  }
+
+  // Git status check
+  if (actionLower.includes('git status')) {
+    const gitClean = context.gitClean !== undefined ? context.gitClean : true;
+    return {
+      action: action.action,
+      severity: action.severity,
+      onFailure: action.onFailure,
+      status: gitClean ? 'pass' : 'fail',
+      reason: gitClean ? 'Git status clean' : 'Git has uncommitted changes',
+    };
+  }
+
+  // Build/test/lint checks
+  if (actionLower.includes('build passes') || actionLower.includes('npm run build')) {
+    return {
+      action: action.action,
+      severity: action.severity,
+      onFailure: action.onFailure,
+      status: context.buildPass ? 'pass' : context.buildPass === false ? 'fail' : 'skip',
+      reason: context.buildPass ? 'Build passes' : context.buildPass === false ? 'Build failed' : 'Build not checked',
+    };
+  }
+
+  if (actionLower.includes('tests pass') || actionLower.includes('npm test')) {
+    return {
+      action: action.action,
+      severity: action.severity,
+      onFailure: action.onFailure,
+      status: context.testsPass ? 'pass' : context.testsPass === false ? 'fail' : 'skip',
+      reason: context.testsPass ? 'Tests pass' : context.testsPass === false ? 'Tests failed' : 'Tests not checked',
+    };
+  }
+
+  if (actionLower.includes('lint passes') || actionLower.includes('npm run lint')) {
+    return {
+      action: action.action,
+      severity: action.severity,
+      onFailure: action.onFailure,
+      status: context.lintPass ? 'pass' : context.lintPass === false ? 'fail' : 'skip',
+      reason: context.lintPass ? 'Lint passes' : context.lintPass === false ? 'Lint failed' : 'Lint not checked',
+    };
+  }
+
+  // Default: skip actions we can't evaluate programmatically
+  return {
+    action: action.action,
+    severity: action.severity,
+    onFailure: action.onFailure,
+    status: 'skip',
+    reason: 'Cannot evaluate programmatically — requires agent execution',
+  };
+}
+
+/**
+ * Lists all available hook events.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {Array<{ event: string, description: string, actionCount: number }>}
+ */
+function listEvents(projectRoot) {
+  const config = loadHooks(projectRoot);
+
+  return (config.hooks || []).map((hook) => ({
+    event: hook.event,
+    description: hook.description,
+    actionCount: (hook.actions || []).length,
+  }));
+}
+
+/**
+ * Generates a full hook readiness report for all events.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {{ events: HookEvaluation[], totalActions: number, readyCount: number }}
+ */
+function getHookReport(projectRoot) {
+  const events = listEvents(projectRoot);
+  const context = { projectRoot };
+
+  const evaluations = events.map((e) => evaluateHook(e.event, context));
+  const totalActions = evaluations.reduce((sum, e) => sum + e.passed + e.failed + e.skipped, 0);
+  const readyCount = evaluations.filter((e) => !e.blocked).length;
+
+  return { events: evaluations, totalActions, readyCount };
+}
+
+module.exports = {
+  getHookActions,
+  evaluateHook,
+  listEvents,
+  getHookReport,
+};

package/lib/ide-generator.js

@@ -0,0 +1,434 @@
+/**
+ * Devran AI Kit — IDE Configuration Generator
+ *
+ * Generates IDE-specific configuration files from manifest.json
+ * for Cursor, OpenCode, and Codex. Single source of truth ensures
+ * all IDE configs stay in sync with the agent manifest.
+ *
+ * @module lib/ide-generator
+ * @since v4.1.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { CURSOR_DIR, OPENCODE_DIR, CODEX_DIR } = require('./constants');
+
+/**
+ * @typedef {object} IdeFile
+ * @property {string} path - Relative path from project root
+ * @property {string} content - File content to write
+ */
+
+/**
+ * @typedef {object} IdeConfig
+ * @property {IdeFile[]} files - Array of files to generate
+ */
+
+/**
+ * @typedef {object} WriteResult
+ * @property {string[]} written - Files that were written
+ * @property {string[]} skipped - Files that were skipped (already exist)
+ */
+
+/**
+ * Condenses rules.md content to fit under 4K characters.
+ * Extracts operating constraints, coding style, and security requirements.
+ *
+ * @param {string} rulesContent - Full rules.md content
+ * @returns {string} Condensed rules content
+ */
+function condenseRules(rulesContent) {
+  const sections = [];
+
+  sections.push('# Devran AI Kit Governance\n');
+
+  // Extract operating constraints table
+  const constraintsMatch = rulesContent.match(
+    /### Operating Constraints[\s\S]*?\n\n/
+  );
+  if (constraintsMatch) {
+    sections.push(constraintsMatch[0].trim());
+  }
+
+  // Extract key protocols by matching the heading format generically
+  const protocolRegex = /### [A-Z]\. [\s\S]*?(?=###|$)/g;
+  let protocolMatch;
+  while ((protocolMatch = protocolRegex.exec(rulesContent)) !== null) {
+    const trimmed = protocolMatch[0].trim().split('\n').slice(0, 5).join('\n');
+    sections.push(trimmed);
+  }
+
+  // Extract technical standards
+  const techMatch = rulesContent.match(
+    /## .* TECHNICAL STANDARDS[\s\S]*?(?=## |$)/
+  );
+  if (techMatch) {
+    sections.push(techMatch[0].trim().split('\n').slice(0, 12).join('\n'));
+  }
+
+  const result = sections.join('\n\n');
+  // Enforce 4K limit
+  return result.length > 4000 ? result.slice(0, 3997) + '...' : result;
+}
+
+/**
+ * Generates Cursor IDE configuration with governance rules.
+ *
+ * @param {object} _manifest - Parsed manifest.json
+ * @param {string} rulesContent - Raw rules.md content
+ * @returns {IdeConfig}
+ */
+function generateCursorConfig(_manifest, rulesContent) {
+  const condensed = condenseRules(rulesContent);
+  const mdcContent = [
+    '---',
+    'description: "Devran AI Kit - Trust-Grade AI governance and coding standards"',
+    'alwaysApply: true',
+    '---',
+    '',
+    condensed,
+    '',
+  ].join('\n');
+
+  return Object.freeze({
+    files: Object.freeze([
+      Object.freeze({
+        path: `${CURSOR_DIR}/rules/kit-governance.mdc`,
+        content: mdcContent,
+      }),
+    ]),
+  });
+}
+
+/**
+ * Extracts agent descriptions from manifest for IDE config.
+ *
+ * @param {object} manifest - Parsed manifest.json
+ * @returns {{ planner: string, reviewer: string }}
+ */
+function extractAgentDescriptions(manifest) {
+  const agents = manifest?.capabilities?.agents?.items || [];
+  const plannerAgent = agents.find((a) => a.name === 'planner');
+  const reviewerAgent = agents.find((a) => a.name === 'code-reviewer');
+
+  return {
+    planner: plannerAgent?.domain || 'Implementation planning specialist',
+    reviewer: reviewerAgent?.domain || 'Code review and security analysis',
+  };
+}
+
+/**
+ * Generates OpenCode IDE configuration.
+ *
+ * @param {object} manifest - Parsed manifest.json
+ * @returns {IdeConfig}
+ */
+function generateOpenCodeConfig(manifest) {
+  const descriptions = extractAgentDescriptions(manifest);
+
+  const config = {
+    $schema: 'https://opencode.ai/config.json',
+    model: 'anthropic/claude-sonnet-4-5',
+    small_model: 'anthropic/claude-haiku-4-5',
+    instructions: ['.agent/rules.md'],
+    agent: {
+      build: {
+        description: 'Primary development agent with Devran AI Kit governance',
+        model: 'anthropic/claude-sonnet-4-5',
+      },
+      planner: {
+        description: descriptions.planner,
+        model: 'anthropic/claude-sonnet-4-5',
+      },
+      reviewer: {
+        description: descriptions.reviewer,
+        model: 'anthropic/claude-sonnet-4-5',
+      },
+    },
+  };
+
+  return Object.freeze({
+    files: Object.freeze([
+      Object.freeze({
+        path: `${OPENCODE_DIR}/opencode.json`,
+        content: JSON.stringify(config, null, 2) + '\n',
+      }),
+    ]),
+  });
+}
+
+/**
+ * Serializes a value to TOML format.
+ *
+ * @param {string|number|boolean|string[]} value - Value to serialize
+ * @returns {string} TOML-formatted value
+ */
+function serializeTomlValue(value) {
+  if (typeof value === 'string') {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+  }
+  if (typeof value === 'boolean' || typeof value === 'number') {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    const items = value.map(v => serializeTomlValue(v));
+    return `[${items.join(', ')}]`;
+  }
+  return `"${String(value)}"`;
+}
+
+/**
+ * Minimal TOML serializer for IDE config generation.
+ *
+ * Intentionally limited to the subset needed by Codex config:
+ * strings, numbers, booleans, arrays, and single-level nested objects.
+ * Full TOML spec (inline tables, arrays of tables, multi-line strings)
+ * is not supported. This is a zero-dependency design decision — we avoid
+ * adding @iarna/toml to maintain the zero-dependency guarantee.
+ *
+ * @param {object} obj - Object to serialize
+ * @returns {string} TOML-formatted string
+ */
+function serializeToml(obj) {
+  const lines = [];
+  const sections = [];
+
+  // First pass: top-level scalars
+  for (const [key, value] of Object.entries(obj)) {
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      sections.push([key, value]);
+    } else {
+      lines.push(`${key} = ${serializeTomlValue(value)}`);
+    }
+  }
+
+  // Second pass: nested sections
+  for (const [sectionKey, sectionValue] of sections) {
+    lines.push('');
+
+    // Check if section contains further nested objects
+    const hasNestedObjects = Object.values(sectionValue).some(
+      (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+    );
+
+    if (hasNestedObjects) {
+      // Emit section header once for top-level scalars
+      const scalars = Object.entries(sectionValue).filter(
+        ([, v]) => v === null || typeof v !== 'object' || Array.isArray(v)
+      );
+      if (scalars.length > 0) {
+        lines.push(`[${sectionKey}]`);
+        for (const [subKey, subValue] of scalars) {
+          lines.push(`${subKey} = ${serializeTomlValue(subValue)}`);
+        }
+        lines.push('');
+      }
+      // Then nested subsections
+      for (const [subKey, subValue] of Object.entries(sectionValue)) {
+        if (subValue !== null && typeof subValue === 'object' && !Array.isArray(subValue)) {
+          lines.push(`[${sectionKey}.${subKey}]`);
+          for (const [innerKey, innerValue] of Object.entries(subValue)) {
+            lines.push(`${innerKey} = ${serializeTomlValue(innerValue)}`);
+          }
+          lines.push('');
+        }
+      }
+    } else {
+      lines.push(`[${sectionKey}]`);
+      for (const [innerKey, innerValue] of Object.entries(sectionValue)) {
+        lines.push(`${innerKey} = ${serializeTomlValue(innerValue)}`);
+      }
+    }
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Generates Codex IDE configuration.
+ *
+ * @param {object} manifest - Parsed manifest.json
+ * @returns {IdeConfig}
+ */
+function generateCodexConfig(manifest) {
+  const descriptions = extractAgentDescriptions(manifest);
+
+  const config = {
+    approval_policy: 'suggest',
+    sandbox_mode: 'workspace-write',
+    model: {
+      default: 'anthropic/claude-sonnet-4-5',
+    },
+    agents: {
+      planner: {
+        description: descriptions.planner,
+        model: 'anthropic/claude-sonnet-4-5',
+      },
+      reviewer: {
+        description: descriptions.reviewer,
+        model: 'anthropic/claude-sonnet-4-5',
+      },
+    },
+  };
+
+  const tomlHeader = [
+    '# Devran AI Kit — Codex Configuration',
+    '# Generated by kit init — do not edit manually',
+    '',
+    '',
+  ].join('\n');
+
+  return Object.freeze({
+    files: Object.freeze([
+      Object.freeze({
+        path: `${CODEX_DIR}/config.toml`,
+        content: tomlHeader + serializeToml(config),
+      }),
+    ]),
+  });
+}
+
+/**
+ * Validates that a file path resolves under the project root.
+ * Prevents path traversal attacks.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {string} filePath - Relative file path to validate
+ * @returns {string} Resolved absolute path
+ * @throws {Error} If path resolves outside project root
+ */
+function validatePath(projectRoot, filePath) {
+  if (typeof filePath !== 'string' || filePath.includes('\0')) {
+    throw new Error(`Invalid file path: ${filePath}`);
+  }
+  const resolved = path.resolve(projectRoot, filePath);
+  const normalizedRoot = path.resolve(projectRoot) + path.sep;
+
+  if (!resolved.startsWith(normalizedRoot)) {
+    throw new Error(`Path traversal detected: ${filePath}`);
+  }
+
+  return resolved;
+}
+
+/**
+ * Writes a file atomically using temp-file-then-rename pattern.
+ * Falls back to direct write on Windows EPERM/EACCES errors.
+ *
+ * @param {string} absolutePath - Absolute destination path
+ * @param {string} content - File content
+ */
+function atomicWriteFile(absolutePath, content) {
+  const dir = path.dirname(absolutePath);
+  const tempPath = `${absolutePath}.tmp`;
+
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  try {
+    fs.writeFileSync(tempPath, content, 'utf-8');
+    fs.renameSync(tempPath, absolutePath);
+  } catch (renameErr) {
+    const isTransient = renameErr.code === 'EPERM' || renameErr.code === 'EACCES';
+    if (isTransient) {
+      fs.writeFileSync(absolutePath, content, 'utf-8');
+    } else {
+      throw renameErr;
+    }
+  } finally {
+    // Ensure temp file is always cleaned up
+    try {
+      if (fs.existsSync(tempPath)) fs.unlinkSync(tempPath);
+    } catch { /* non-critical */ }
+  }
+}
+
+/**
+ * Rolls back previously written files during transactional failure.
+ *
+ * @param {string} projectRoot - Absolute project root
+ * @param {string[]} writtenPaths - Relative paths of written files
+ */
+function rollbackWrittenFiles(projectRoot, writtenPaths) {
+  for (const writtenPath of writtenPaths) {
+    try {
+      const abs = path.resolve(projectRoot, writtenPath);
+      if (fs.existsSync(abs)) fs.unlinkSync(abs);
+    } catch { /* rollback failure is non-critical */ }
+  }
+}
+
+/**
+ * Writes IDE configuration files to the project directory.
+ * Uses atomic write pattern (write to .tmp, then rename).
+ * Transactional: rolls back all written files if any write fails.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {IdeConfig[]} configs - Array of IDE configurations
+ * @param {object} [options={}] - Write options
+ * @param {boolean} [options.force=false] - Overwrite existing files
+ * @param {boolean} [options.skipExisting=false] - Silently skip existing
+ * @returns {WriteResult}
+ */
+function writeIdeConfigs(projectRoot, configs, options = {}) {
+  if (typeof projectRoot !== 'string' || !path.isAbsolute(projectRoot)) {
+    throw new TypeError('projectRoot must be an absolute path string');
+  }
+  if (!Array.isArray(configs)) {
+    throw new TypeError('configs must be an array');
+  }
+
+  const { force = false, skipExisting = false } = options;
+  const written = [];
+  const skipped = [];
+
+  // Collect all files from all configs
+  const allFiles = configs.flatMap((config) => config.files || []);
+
+  for (const file of allFiles) {
+    const absolutePath = validatePath(projectRoot, file.path);
+
+    if (fs.existsSync(absolutePath) && !force) {
+      skipped.push(file.path);
+      continue;
+    }
+
+    try {
+      atomicWriteFile(absolutePath, file.content);
+      written.push(file.path);
+    } catch (err) {
+      rollbackWrittenFiles(projectRoot, written);
+      throw new Error(`Failed to write ${file.path}: ${err.message}`);
+    }
+  }
+
+  return Object.freeze({ written: Object.freeze([...written]), skipped: Object.freeze([...skipped]) });
+}
+
+/**
+ * Generates all IDE configurations from manifest and rules.
+ *
+ * @param {object} manifest - Parsed manifest.json
+ * @param {string} rulesContent - Raw rules.md content
+ * @returns {IdeConfig[]}
+ */
+function generateAllIdeConfigs(manifest, rulesContent) {
+  return [
+    generateCursorConfig(manifest, rulesContent),
+    generateOpenCodeConfig(manifest),
+    generateCodexConfig(manifest),
+  ];
+}
+
+module.exports = Object.freeze({
+  generateCursorConfig,
+  generateOpenCodeConfig,
+  generateCodexConfig,
+  generateAllIdeConfigs,
+  writeIdeConfigs,
+  serializeToml,
+  condenseRules,
+});