@devran-ai/kit 4.1.0

package/lib/task-model.js

@@ -0,0 +1,332 @@
+/**
+ * Devran AI Kit — Task Data Model
+ *
+ * JSON file-backed task CRUD with status FSM tracking.
+ * Provides the data layer for task governance.
+ *
+ * @module lib/task-model
+ * @author Emre Dursun
+ * @since v3.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const { AGENT_DIR, ENGINE_DIR } = require('./constants');
+const { writeJsonAtomic } = require('./io');
+const TASKS_FILE = 'tasks.json';
+
+/** Valid task status values */
+const VALID_STATUSES = ['open', 'in-progress', 'review', 'done', 'blocked'];
+
+/** Valid status transitions */
+const STATUS_TRANSITIONS = {
+  'open': ['in-progress', 'blocked'],
+  'in-progress': ['review', 'blocked', 'open'],
+  'review': ['done', 'in-progress'],
+  'done': ['open'],
+  'blocked': ['open', 'in-progress'],
+};
+
+/** Valid priority levels */
+const VALID_PRIORITIES = ['critical', 'high', 'medium', 'low'];
+
+/**
+ * @typedef {object} Task
+ * @property {string} id - Unique task ID
+ * @property {string} title - Task title
+ * @property {string | null} description - Optional description
+ * @property {string} status - Current status
+ * @property {string} priority - Priority level
+ * @property {string | null} assignee - Assigned agent or person
+ * @property {string} createdAt - ISO timestamp
+ * @property {string} updatedAt - ISO timestamp
+ * @property {string | null} completedAt - Completion timestamp
+ * @property {boolean} deleted - Soft delete flag
+ */
+
+/**
+ * Resolves the tasks file path.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {string} Absolute path to tasks.json
+ */
+function resolveTasksPath(projectRoot) {
+  return path.join(projectRoot, AGENT_DIR, ENGINE_DIR, TASKS_FILE);
+}
+
+/**
+ * Loads all tasks from disk.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {Task[]}
+ */
+function loadTasks(projectRoot) {
+  const tasksPath = resolveTasksPath(projectRoot);
+
+  if (!fs.existsSync(tasksPath)) {
+    return [];
+  }
+
+  try {
+    const data = JSON.parse(fs.readFileSync(tasksPath, 'utf-8'));
+    return data.tasks || [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Writes tasks to disk atomically.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {Task[]} tasks - Tasks array
+ * @returns {void}
+ */
+function writeTasks(projectRoot, tasks) {
+  const tasksPath = resolveTasksPath(projectRoot);
+
+  const data = {
+    schemaVersion: '1.0.0',
+    lastUpdated: new Date().toISOString(),
+    tasks,
+  };
+
+  writeJsonAtomic(tasksPath, data);
+}
+
+/**
+ * Creates a new task.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {object} params - Task parameters
+ * @param {string} params.title - Task title
+ * @param {string} [params.description] - Optional description
+ * @param {string} [params.assignee] - Optional assignee
+ * @param {string} [params.priority] - Priority (default: 'medium')
+ * @returns {Task}
+ */
+function createTask(projectRoot, { title, description, assignee, priority }) {
+  const tasks = loadTasks(projectRoot);
+  const now = new Date().toISOString();
+
+  const taskPriority = priority && VALID_PRIORITIES.includes(priority) ? priority : 'medium';
+
+  /** @type {Task} */
+  const task = {
+    id: `TSK-${crypto.randomUUID().slice(0, 8).toUpperCase()}`,
+    title,
+    description: description || null,
+    status: 'open',
+    priority: taskPriority,
+    assignee: assignee || null,
+    createdAt: now,
+    updatedAt: now,
+    completedAt: null,
+    deleted: false,
+  };
+
+  writeTasks(projectRoot, [...tasks, task]);
+
+  return task;
+}
+
+/**
+ * Retrieves a task by ID.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {string} taskId - Task ID
+ * @returns {Task | null}
+ */
+function getTask(projectRoot, taskId) {
+  const tasks = loadTasks(projectRoot);
+  return tasks.find((t) => t.id === taskId && !t.deleted) || null;
+}
+
+/**
+ * Lists tasks with optional filters.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {object} [filters] - Filter options
+ * @param {string} [filters.status] - Filter by status
+ * @param {string} [filters.priority] - Filter by priority
+ * @param {string} [filters.assignee] - Filter by assignee
+ * @returns {Task[]}
+ */
+function listTasks(projectRoot, filters = {}) {
+  let tasks = loadTasks(projectRoot).filter((t) => !t.deleted);
+
+  if (filters.status) {
+    tasks = tasks.filter((t) => t.status === filters.status);
+  }
+  if (filters.priority) {
+    tasks = tasks.filter((t) => t.priority === filters.priority);
+  }
+  if (filters.assignee) {
+    tasks = tasks.filter((t) => t.assignee === filters.assignee);
+  }
+
+  return tasks;
+}
+
+/**
+ * Updates a task's fields.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {string} taskId - Task ID
+ * @param {object} updates - Fields to update
+ * @returns {{ success: boolean, task: Task | null }}
+ */
+function updateTask(projectRoot, taskId, updates) {
+  const tasks = loadTasks(projectRoot);
+  const taskIndex = tasks.findIndex((t) => t.id === taskId && !t.deleted);
+
+  if (taskIndex === -1) {
+    return { success: false, task: null };
+  }
+
+  const allowedFields = ['title', 'description', 'assignee', 'priority'];
+  const fieldUpdates = {};
+  for (const field of allowedFields) {
+    if (updates[field] !== undefined) {
+      fieldUpdates[field] = updates[field];
+    }
+  }
+
+  const updatedTask = { ...tasks[taskIndex], ...fieldUpdates, updatedAt: new Date().toISOString() };
+  const updatedTasks = tasks.map((t, i) => (i === taskIndex ? updatedTask : t));
+  writeTasks(projectRoot, updatedTasks);
+
+  return { success: true, task: updatedTask };
+}
+
+/**
+ * Transitions a task to a new status following the FSM.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {string} taskId - Task ID
+ * @param {string} newStatus - Target status
+ * @returns {{ success: boolean, error?: string }}
+ */
+function transitionTask(projectRoot, taskId, newStatus) {
+  if (!VALID_STATUSES.includes(newStatus)) {
+    return { success: false, error: `Invalid status: ${newStatus}. Valid: ${VALID_STATUSES.join(', ')}` };
+  }
+
+  const tasks = loadTasks(projectRoot);
+  const taskIndex = tasks.findIndex((t) => t.id === taskId && !t.deleted);
+
+  if (taskIndex === -1) {
+    return { success: false, error: `Task not found: ${taskId}` };
+  }
+
+  const currentStatus = tasks[taskIndex].status;
+  const allowed = STATUS_TRANSITIONS[currentStatus] || [];
+
+  if (!allowed.includes(newStatus)) {
+    return {
+      success: false,
+      error: `Invalid transition: ${currentStatus} → ${newStatus}. Allowed: [${allowed.join(', ')}]`,
+    };
+  }
+
+  const now = new Date().toISOString();
+  const updatedTask = {
+    ...tasks[taskIndex],
+    status: newStatus,
+    updatedAt: now,
+    completedAt: newStatus === 'done' ? now : tasks[taskIndex].completedAt,
+  };
+  const updatedTasks = tasks.map((t, i) => (i === taskIndex ? updatedTask : t));
+  writeTasks(projectRoot, updatedTasks);
+
+  return { success: true };
+}
+
+/**
+ * Soft-deletes a task.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {string} taskId - Task ID
+ * @returns {{ success: boolean }}
+ */
+function deleteTask(projectRoot, taskId) {
+  const tasks = loadTasks(projectRoot);
+  const taskIndex = tasks.findIndex((t) => t.id === taskId);
+
+  if (taskIndex === -1) {
+    return { success: false };
+  }
+
+  const updatedTasks = tasks.map((t, i) =>
+    i === taskIndex ? { ...t, deleted: true, updatedAt: new Date().toISOString() } : t
+  );
+  writeTasks(projectRoot, updatedTasks);
+
+  return { success: true };
+}
+
+/**
+ * Returns task metrics: counts by status, avg cycle time.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {object} Task metrics
+ */
+function getTaskMetrics(projectRoot) {
+  const tasks = loadTasks(projectRoot).filter((t) => !t.deleted);
+
+  const counts = {};
+  for (const status of VALID_STATUSES) {
+    counts[status] = tasks.filter((t) => t.status === status).length;
+  }
+
+  // Calculate average cycle time for completed tasks
+  const completedTasks = tasks.filter((t) => t.status === 'done' && t.completedAt);
+  let avgCycleTimeSeconds = 0;
+
+  if (completedTasks.length > 0) {
+    const totalCycleTime = completedTasks.reduce((sum, t) => {
+      return sum + (new Date(t.completedAt).getTime() - new Date(t.createdAt).getTime());
+    }, 0);
+    avgCycleTimeSeconds = Math.round(totalCycleTime / completedTasks.length / 1000);
+  }
+
+  return {
+    total: tasks.length,
+    counts,
+    avgCycleTimeSeconds,
+    completionRate: tasks.length > 0 ? Math.round((counts.done / tasks.length) * 100) : 0,
+  };
+}
+
+/** Priority sort order: critical > high > medium > low */
+const PRIORITY_ORDER = { critical: 0, high: 1, medium: 2, low: 3 };
+
+/**
+ * Sorts tasks by priority (critical first, low last).
+ *
+ * @param {Task[]} tasks - Tasks to sort
+ * @returns {Task[]} New sorted array (does not mutate input)
+ */
+function sortByPriority(tasks) {
+  return [...tasks].sort((a, b) => {
+    const aPriority = PRIORITY_ORDER[a.priority] ?? 2;
+    const bPriority = PRIORITY_ORDER[b.priority] ?? 2;
+    return aPriority - bPriority;
+  });
+}
+
+module.exports = {
+  createTask,
+  getTask,
+  listTasks,
+  updateTask,
+  transitionTask,
+  deleteTask,
+  getTaskMetrics,
+  sortByPriority,
+  PRIORITY_ORDER,
+};

package/lib/updater.js

@@ -0,0 +1,240 @@
+/**
+ * Devran AI Kit — CLI Updater
+ *
+ * Non-destructive update mechanism that merges new framework
+ * files into an existing .agent/ installation while preserving
+ * user customizations.
+ *
+ * @module lib/updater
+ * @author Emre Dursun
+ * @since v3.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const { AGENT_DIR } = require('./constants');
+
+/**
+ * User data files that should NEVER be overwritten during updates.
+ * These contain project-specific data populated at runtime.
+ */
+const USER_DATA_FILES = new Set([
+  'session-context.md',
+  'session-state.json',
+  'engine/identity.json',
+]);
+
+/**
+ * User data directories whose contents should NEVER be overwritten.
+ * These contain project-specific decisions, context, and customizations.
+ *
+ * Must stay aligned with the Preservation Contract in:
+ *   .agent/rules/agent-upgrade-policy.md § 1
+ */
+const USER_DATA_DIRS = new Set([
+  'decisions',
+  'contexts',
+  'checklists',
+  'rules',
+]);
+
+/**
+ * @typedef {object} UpdateReport
+ * @property {string[]} added - Files that were added (new in source)
+ * @property {string[]} updated - Files that were updated (hash mismatch)
+ * @property {string[]} skipped - Files that were preserved (user customizations)
+ * @property {string[]} unchanged - Files that are identical
+ */
+
+/**
+ * Computes a SHA-256 hash of a file's contents.
+ *
+ * @param {string} filePath - Absolute path to the file
+ * @returns {string} Hex-encoded SHA-256 hash
+ */
+function fileHash(filePath) {
+  const content = fs.readFileSync(filePath);
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * Recursively collects all file paths relative to a root directory.
+ *
+ * @param {string} rootDir - Root directory to scan
+ * @param {string} [prefix=''] - Path prefix for recursion
+ * @returns {string[]} Array of relative paths
+ */
+function collectFiles(rootDir, prefix = '') {
+  /** @type {string[]} */
+  const files = [];
+
+  if (!fs.existsSync(rootDir)) {
+    return files;
+  }
+
+  const entries = fs.readdirSync(rootDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+
+    if (entry.isDirectory()) {
+      files.push(...collectFiles(path.join(rootDir, entry.name), relativePath));
+    } else {
+      files.push(relativePath);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Determines if a relative file path is in the preserved set.
+ *
+ * @param {string} relativePath - Relative path from .agent/ root
+ * @returns {boolean} True if the file should be preserved
+ */
+function isPreservedFile(relativePath) {
+  // Normalize path separators for cross-platform matching
+  const normalizedPath = relativePath.replace(/\\/g, '/');
+
+  // Check exact relative path matches (e.g., 'engine/identity.json')
+  if (USER_DATA_FILES.has(normalizedPath)) {
+    return true;
+  }
+
+  // Check basename matches for root-level files (e.g., 'session-context.md')
+  const basename = path.basename(relativePath);
+  if (USER_DATA_FILES.has(basename)) {
+    return true;
+  }
+
+  // Check if inside a user data directory
+  const parts = normalizedPath.split('/');
+  for (const dir of USER_DATA_DIRS) {
+    if (parts.includes(dir)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Generates a diff report comparing source and target .agent/ directories.
+ *
+ * @param {string} sourceRoot - Root of the package (source .agent/ location)
+ * @param {string} targetRoot - Root of the project (target .agent/ location)
+ * @returns {UpdateReport}
+ */
+function generateDiff(sourceRoot, targetRoot) {
+  const sourceDir = path.join(sourceRoot, AGENT_DIR);
+  const targetDir = path.join(targetRoot, AGENT_DIR);
+
+  const sourceFiles = collectFiles(sourceDir);
+  const targetFiles = new Set(collectFiles(targetDir));
+
+  /** @type {UpdateReport} */
+  const report = {
+    added: [],
+    updated: [],
+    skipped: [],
+    unchanged: [],
+  };
+
+  for (const relativeFile of sourceFiles) {
+    const sourcePath = path.join(sourceDir, relativeFile);
+    const targetPath = path.join(targetDir, relativeFile);
+
+    if (isPreservedFile(relativeFile) && targetFiles.has(relativeFile)) {
+      report.skipped.push(relativeFile);
+      continue;
+    }
+
+    if (!targetFiles.has(relativeFile)) {
+      report.added.push(relativeFile);
+      continue;
+    }
+
+    const sourceHash = fileHash(sourcePath);
+    const targetHash = fileHash(targetPath);
+
+    if (sourceHash !== targetHash) {
+      report.updated.push(relativeFile);
+    } else {
+      report.unchanged.push(relativeFile);
+    }
+  }
+
+  return report;
+}
+
+/**
+ * Applies a non-destructive update from source to target.
+ *
+ * @param {string} sourceRoot - Root of the package
+ * @param {string} targetRoot - Root of the project
+ * @param {boolean} [dryRun=false] - If true, report only without modifying
+ * @returns {UpdateReport}
+ */
+function applyUpdate(sourceRoot, targetRoot, dryRun = false) {
+  const report = generateDiff(sourceRoot, targetRoot);
+
+  if (dryRun) {
+    return report;
+  }
+
+  const sourceDir = path.join(sourceRoot, AGENT_DIR);
+  const targetDir = path.join(targetRoot, AGENT_DIR);
+
+  // Copy new files
+  for (const relativeFile of report.added) {
+    const sourcePath = path.join(sourceDir, relativeFile);
+    const targetPath = path.join(targetDir, relativeFile);
+    const targetDirPath = path.dirname(targetPath);
+
+    if (!fs.existsSync(targetDirPath)) {
+      fs.mkdirSync(targetDirPath, { recursive: true });
+    }
+
+    fs.copyFileSync(sourcePath, targetPath);
+  }
+
+  // Update modified files
+  for (const relativeFile of report.updated) {
+    const sourcePath = path.join(sourceDir, relativeFile);
+    const targetPath = path.join(targetDir, relativeFile);
+
+    fs.copyFileSync(sourcePath, targetPath);
+  }
+
+  // Regenerate IDE configs after .agent/ files are updated
+  try {
+    const { generateAllIdeConfigs, writeIdeConfigs } = require('./ide-generator');
+    const manifestPath = path.join(targetDir, 'manifest.json');
+    const rulesPath = path.join(targetRoot, AGENT_DIR, 'rules.md');
+    if (fs.existsSync(manifestPath) && fs.existsSync(rulesPath)) {
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+      const rulesContent = fs.readFileSync(rulesPath, 'utf-8');
+      const configs = generateAllIdeConfigs(manifest, rulesContent);
+      writeIdeConfigs(targetRoot, configs, { skipExisting: true });
+    }
+  } catch (err) {
+    console.error(`   Error regenerating IDE configs: ${err.message}`);
+    // Non-fatal — IDE configs are optional
+  }
+
+  return report;
+}
+
+module.exports = {
+  generateDiff,
+  applyUpdate,
+  isPreservedFile,
+  collectFiles,
+  USER_DATA_FILES,
+  USER_DATA_DIRS,
+};