@devran-ai/kit 4.1.0

package/lib/session-manager.js

@@ -0,0 +1,264 @@
+/**
+ * Devran AI Kit — Session Manager
+ *
+ * Automates session-state.json updates so it is no longer
+ * a blank template. Tracks active sessions, tasks, and
+ * repository state.
+ *
+ * @module lib/session-manager
+ * @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 } = require('./constants');
+const { writeJsonAtomic } = require('./io');
+const STATE_FILENAME = 'session-state.json';
+
+/**
+ * Resolves the absolute path to session-state.json.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {string} Absolute path to session-state.json
+ */
+function resolveStatePath(projectRoot) {
+  return path.join(projectRoot, AGENT_DIR, STATE_FILENAME);
+}
+
+/**
+ * Loads session state from disk.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {object} Parsed session state
+ */
+function loadSessionState(projectRoot) {
+  const filePath = resolveStatePath(projectRoot);
+
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Session state file not found: ${filePath}`);
+  }
+
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  return JSON.parse(raw);
+}
+
+/**
+ * Writes session state to disk atomically.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {object} state - Session state object to write
+ * @returns {void}
+ */
+function writeSessionState(projectRoot, state) {
+  const filePath = resolveStatePath(projectRoot);
+  const updatedState = { ...state, lastUpdated: new Date().toISOString() };
+  writeJsonAtomic(filePath, updatedState);
+}
+
+/**
+ * Retrieves current Git branch name safely.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {string | null} Branch name or null if not a git repo
+ */
+function getGitBranch(projectRoot) {
+  try {
+    const result = execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd: projectRoot,
+      encoding: 'utf-8',
+      timeout: 5000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return result.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Retrieves the last Git commit SHA safely.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {string | null} Commit SHA or null
+ */
+function getGitLastCommit(projectRoot) {
+  try {
+    const result = execSync('git log -1 --format=%H', {
+      cwd: projectRoot,
+      encoding: 'utf-8',
+      timeout: 5000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return result.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Starts a new session. Generates a session ID, populates
+ * date, Git info, and sets status to "active".
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {string} [focus] - Optional session focus description
+ * @returns {{ sessionId: string, state: object }}
+ */
+function startSession(projectRoot, focus) {
+  const loadedState = loadSessionState(projectRoot);
+  const sessionId = crypto.randomUUID();
+
+  const state = {
+    ...loadedState,
+    session: {
+      id: sessionId,
+      date: new Date().toISOString(),
+      focus: focus || null,
+      status: 'active',
+    },
+    repository: {
+      currentBranch: getGitBranch(projectRoot),
+      lastCommit: getGitLastCommit(projectRoot),
+      remoteSynced: false,
+    },
+  };
+
+  writeSessionState(projectRoot, state);
+
+  return { sessionId, state };
+}
+
+/**
+ * Ends the current session. Sets status to "completed".
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {{ success: boolean, sessionId: string | null }}
+ */
+function endSession(projectRoot) {
+  const loadedState = loadSessionState(projectRoot);
+
+  if (!loadedState.session || !loadedState.session.id) {
+    return { success: false, sessionId: null };
+  }
+
+  const sessionId = loadedState.session.id;
+  const state = {
+    ...loadedState,
+    session: { ...loadedState.session, status: 'completed' },
+    notes: `Session ${sessionId} completed at ${new Date().toISOString()}`,
+  };
+
+  writeSessionState(projectRoot, state);
+
+  return { success: true, sessionId };
+}
+
+/**
+ * Adds a task to the open tasks list.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {string} title - Task title
+ * @param {string} [description] - Optional description
+ * @returns {{ taskId: string }}
+ */
+function addTask(projectRoot, title, description) {
+  const loadedState = loadSessionState(projectRoot);
+  const taskId = `TASK-${Date.now().toString(36).toUpperCase()}`;
+
+  const task = {
+    id: taskId,
+    title,
+    description: description || null,
+    createdAt: new Date().toISOString(),
+    status: 'open',
+  };
+
+  const existingTasks = Array.isArray(loadedState.openTasks) ? loadedState.openTasks : [];
+  const state = {
+    ...loadedState,
+    openTasks: [...existingTasks, task],
+    currentTask: taskId,
+  };
+
+  writeSessionState(projectRoot, state);
+
+  return { taskId };
+}
+
+/**
+ * Marks a task as completed, moving it from openTasks to completedTasks.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {string} taskId - ID of the task to complete
+ * @returns {{ success: boolean }}
+ */
+function completeTask(projectRoot, taskId) {
+  const loadedState = loadSessionState(projectRoot);
+
+  if (!Array.isArray(loadedState.openTasks)) {
+    return { success: false };
+  }
+
+  const taskIndex = loadedState.openTasks.findIndex((task) => task.id === taskId);
+
+  if (taskIndex === -1) {
+    return { success: false };
+  }
+
+  const completedTask = {
+    ...loadedState.openTasks[taskIndex],
+    status: 'completed',
+    completedAt: new Date().toISOString(),
+  };
+
+  const remainingTasks = loadedState.openTasks.filter((_, i) => i !== taskIndex);
+  const existingCompleted = Array.isArray(loadedState.completedTasks) ? loadedState.completedTasks : [];
+
+  const state = {
+    ...loadedState,
+    openTasks: remainingTasks,
+    completedTasks: [...existingCompleted, completedTask],
+    currentTask: loadedState.currentTask === taskId
+      ? (remainingTasks.length > 0 ? remainingTasks[0].id : null)
+      : loadedState.currentTask,
+  };
+
+  writeSessionState(projectRoot, state);
+
+  return { success: true };
+}
+
+/**
+ * Returns a summary of the current session state.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {object} Session summary
+ */
+function getSessionSummary(projectRoot) {
+  const state = loadSessionState(projectRoot);
+
+  return {
+    sessionId: state.session?.id || null,
+    status: state.session?.status || 'new',
+    focus: state.session?.focus || null,
+    branch: state.repository?.currentBranch || null,
+    openTaskCount: Array.isArray(state.openTasks) ? state.openTasks.length : 0,
+    completedTaskCount: Array.isArray(state.completedTasks) ? state.completedTasks.length : 0,
+    currentTask: state.currentTask || null,
+    lastUpdated: state.lastUpdated || null,
+  };
+}
+
+module.exports = {
+  loadSessionState,
+  startSession,
+  endSession,
+  addTask,
+  completeTask,
+  getSessionSummary,
+};

package/lib/skill-sandbox.js

@@ -0,0 +1,244 @@
+/**
+ * Devran AI Kit — Skill Sandboxing
+ *
+ * Enforces allowed-tools declarations from skill SKILL.md frontmatter.
+ * Validates that skills only reference tools within their permission set.
+ *
+ * @module lib/skill-sandbox
+ * @author Emre Dursun
+ * @since v3.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { AGENT_DIR } = require('./constants');
+const SKILLS_DIR = 'skills';
+
+/** Valid permission levels (ordered from least to most privileged) */
+const PERMISSION_LEVELS = ['read-only', 'read-write', 'execute', 'network'];
+
+/** Tool patterns that indicate permission level requirements */
+const TOOL_PERMISSION_MAP = {
+  'network': [
+    /\bfetch\b/i, /\bhttp\b/i, /\bapi\b/i, /\bcurl\b/i, /\brequest\b/i,
+    /\bwebhook\b/i, /\bsocket\b/i, /\bdownload\b/i, /\bupload\b/i,
+  ],
+  'execute': [
+    /\bexec\b/i, /\bspawn\b/i, /\bchild_process\b/i, /\bshell\b/i,
+    /\brun_command\b/i, /\bterminal\b/i, /\bscript\b/i,
+  ],
+  'read-write': [
+    /\bwrite\b/i, /\bcreate\b/i, /\bdelete\b/i, /\bmodify\b/i,
+    /\bedit\b/i, /\bsave\b/i, /\bremove\b/i, /\bupdate\b/i,
+  ],
+};
+
+/**
+ * @typedef {object} SkillPermissions
+ * @property {string} skillName - Name of the skill
+ * @property {string[]} allowedTools - Declared allowed tools
+ * @property {string} permissionLevel - Highest permission level
+ * @property {boolean} hasFrontmatter - Whether frontmatter was found
+ */
+
+/**
+ * @typedef {object} SandboxViolation
+ * @property {string} skillName - Skill that violated
+ * @property {string} violation - Description of violation
+ * @property {'critical' | 'high' | 'medium' | 'low'} severity - Violation severity
+ * @property {string} file - File where violation was found
+ * @property {number} [line] - Line number (if applicable)
+ */
+
+/**
+ * Extracts permissions from a SKILL.md frontmatter.
+ *
+ * @param {string} content - Raw SKILL.md content
+ * @returns {{ allowedTools: string[], permissionLevel: string }}
+ */
+function extractPermissionsFromFrontmatter(content) {
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+
+  if (!frontmatterMatch) {
+    return { allowedTools: [], permissionLevel: 'read-only' };
+  }
+
+  const frontmatter = frontmatterMatch[1];
+  /** @type {string[]} */
+  const allowedTools = [];
+  let permissionLevel = 'read-only';
+
+  // Parse allowed-tools from frontmatter
+  const toolsMatch = frontmatter.match(/allowed-tools:\s*\[(.*?)\]/);
+  if (toolsMatch) {
+    const toolsList = toolsMatch[1].split(',').map((t) => t.trim().replace(/['"]/g, '')).filter(Boolean);
+    allowedTools.push(...toolsList);
+  }
+
+  // Parse permission-level from frontmatter
+  const permMatch = frontmatter.match(/permission-level:\s*(\S+)/);
+  if (permMatch && PERMISSION_LEVELS.includes(permMatch[1])) {
+    permissionLevel = permMatch[1];
+  }
+
+  return { allowedTools, permissionLevel };
+}
+
+/**
+ * Gets the permissions declared by a specific skill.
+ *
+ * @param {string} skillName - Name of the skill
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {SkillPermissions}
+ */
+function getSkillPermissions(skillName, projectRoot) {
+  const skillPath = path.join(projectRoot, AGENT_DIR, SKILLS_DIR, skillName, 'SKILL.md');
+
+  if (!fs.existsSync(skillPath)) {
+    return {
+      skillName,
+      allowedTools: [],
+      permissionLevel: 'read-only',
+      hasFrontmatter: false,
+    };
+  }
+
+  const content = fs.readFileSync(skillPath, 'utf-8');
+  const { allowedTools, permissionLevel } = extractPermissionsFromFrontmatter(content);
+  const hasFrontmatter = content.startsWith('---');
+
+  return { skillName, allowedTools, permissionLevel, hasFrontmatter };
+}
+
+/**
+ * Scans a skill's content for tool usage that exceeds its declared permissions.
+ *
+ * @param {string} skillName - Name of the skill
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {SandboxViolation[]}
+ */
+function validateSkillPermissions(skillName, projectRoot) {
+  const permissions = getSkillPermissions(skillName, projectRoot);
+  const skillDir = path.join(projectRoot, AGENT_DIR, SKILLS_DIR, skillName);
+  /** @type {SandboxViolation[]} */
+  const violations = [];
+
+  if (!fs.existsSync(skillDir)) {
+    violations.push({
+      skillName,
+      violation: `Skill directory not found: ${skillName}`,
+      severity: 'critical',
+      file: skillDir,
+    });
+    return violations;
+  }
+
+  // Get the permission level index for comparison
+  const declaredLevelIndex = PERMISSION_LEVELS.indexOf(permissions.permissionLevel);
+
+  // Scan all files in the skill directory
+  const files = scanSkillFiles(skillDir);
+
+  for (const file of files) {
+    const content = fs.readFileSync(file, 'utf-8');
+    const lines = content.split('\n');
+
+    for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+      const line = lines[lineIndex];
+
+      // Check each permission level higher than declared
+      for (const [level, patterns] of Object.entries(TOOL_PERMISSION_MAP)) {
+        const levelIndex = PERMISSION_LEVELS.indexOf(level);
+
+        if (levelIndex > declaredLevelIndex) {
+          for (const pattern of patterns) {
+            if (pattern.test(line)) {
+              violations.push({
+                skillName,
+                violation: `Uses ${level}-level tool pattern "${pattern.source}" but declared permission is "${permissions.permissionLevel}"`,
+                severity: levelIndex - declaredLevelIndex >= 2 ? 'critical' : 'high',
+                file: path.relative(projectRoot, file),
+                line: lineIndex + 1,
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Recursively scans a skill directory for readable files.
+ *
+ * @param {string} dirPath - Directory to scan
+ * @returns {string[]} Array of file paths
+ */
+function scanSkillFiles(dirPath) {
+  /** @type {string[]} */
+  const files = [];
+
+  if (!fs.existsSync(dirPath)) {
+    return files;
+  }
+
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...scanSkillFiles(fullPath));
+    } else if (entry.isFile() && (entry.name.endsWith('.md') || entry.name.endsWith('.json') || entry.name.endsWith('.js'))) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Enforces allowed-tools compliance across all skills.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {{ total: number, compliant: number, violations: SandboxViolation[] }}
+ */
+function enforceAllowedTools(projectRoot) {
+  const skillsDir = path.join(projectRoot, AGENT_DIR, SKILLS_DIR);
+
+  if (!fs.existsSync(skillsDir)) {
+    return { total: 0, compliant: 0, violations: [] };
+  }
+
+  const skillDirs = fs.readdirSync(skillsDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name);
+
+  /** @type {SandboxViolation[]} */
+  const allViolations = [];
+
+  for (const skillName of skillDirs) {
+    const violations = validateSkillPermissions(skillName, projectRoot);
+    allViolations.push(...violations);
+  }
+
+  const violatedSkills = new Set(allViolations.map((v) => v.skillName));
+
+  return {
+    total: skillDirs.length,
+    compliant: skillDirs.length - violatedSkills.size,
+    violations: allViolations,
+  };
+}
+
+module.exports = {
+  getSkillPermissions,
+  validateSkillPermissions,
+  enforceAllowedTools,
+  extractPermissionsFromFrontmatter,
+};