agentsys 5.0.0

package/lib/utils/cache-manager.js

@@ -0,0 +1,159 @@
+/**
+ * Cache Manager
+ * Centralized caching abstraction with TTL and size limits
+ *
+ * @module lib/utils/cache-manager
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+/**
+ * Cache manager with TTL and size limits
+ */
+class CacheManager {
+  /**
+   * Create a new cache manager
+   * @param {Object} options - Cache configuration
+   * @param {number} options.maxSize - Maximum number of entries (default: 100)
+   * @param {number} options.ttl - Time-to-live in milliseconds (default: 60000)
+   * @param {number} options.maxValueSize - Maximum size per value in bytes (default: null - unlimited)
+   */
+  constructor(options = {}) {
+    this.maxSize = options.maxSize || 100;
+    this.ttl = options.ttl || 60000; // 1 minute default
+    this.maxValueSize = options.maxValueSize || null;
+
+    // Use Map for insertion-order guarantee (FIFO eviction)
+    this._cache = new Map();
+    this._timestamps = new Map();
+  }
+
+  /**
+   * Get a value from cache
+   * @param {string} key - Cache key
+   * @returns {*} Cached value or undefined if not found/expired
+   */
+  get(key) {
+    if (!this._cache.has(key)) {
+      return undefined;
+    }
+
+    // Check if expired
+    const timestamp = this._timestamps.get(key);
+    if (Date.now() - timestamp > this.ttl) {
+      this.delete(key);
+      return undefined;
+    }
+
+    return this._cache.get(key);
+  }
+
+  /**
+   * Set a value in cache
+   * @param {string} key - Cache key
+   * @param {*} value - Value to cache
+   * @returns {boolean} True if cached, false if value too large
+   */
+  set(key, value) {
+    // Check value size if limit set
+    if (this.maxValueSize !== null && typeof value === 'string') {
+      if (value.length > this.maxValueSize) {
+        return false; // Value too large, don't cache
+      }
+    }
+
+    // Update or add entry
+    this._cache.set(key, value);
+    this._timestamps.set(key, Date.now());
+
+    // Enforce size limit with FIFO eviction
+    this._enforceMaxSize();
+
+    return true;
+  }
+
+  /**
+   * Check if key exists and is not expired
+   * @param {string} key - Cache key
+   * @returns {boolean} True if key exists and is valid
+   */
+  has(key) {
+    return this.get(key) !== undefined;
+  }
+
+  /**
+   * Delete a key from cache
+   * @param {string} key - Cache key
+   * @returns {boolean} True if key existed
+   */
+  delete(key) {
+    this._timestamps.delete(key);
+    return this._cache.delete(key);
+  }
+
+  /**
+   * Clear all cache entries
+   */
+  clear() {
+    this._cache.clear();
+    this._timestamps.clear();
+  }
+
+  /**
+   * Get current cache size
+   * @returns {number} Number of entries
+   */
+  get size() {
+    return this._cache.size;
+  }
+
+  /**
+   * Get cache statistics
+   * @returns {Object} Stats object with size, ttl, maxSize
+   */
+  getStats() {
+    return {
+      size: this._cache.size,
+      maxSize: this.maxSize,
+      ttl: this.ttl,
+      maxValueSize: this.maxValueSize
+    };
+  }
+
+  /**
+   * Enforce maximum cache size using FIFO eviction
+   * @private
+   */
+  _enforceMaxSize() {
+    // Only evict if cache exceeds limit
+    if (this._cache.size <= this.maxSize) {
+      return;
+    }
+
+    // Map maintains insertion order - first key is oldest
+    while (this._cache.size > this.maxSize) {
+      const firstKey = this._cache.keys().next().value;
+      this.delete(firstKey);
+    }
+  }
+
+  /**
+   * Remove expired entries (useful for long-running processes)
+   * @returns {number} Number of entries removed
+   */
+  prune() {
+    let removed = 0;
+    const now = Date.now();
+
+    for (const [key, timestamp] of this._timestamps.entries()) {
+      if (now - timestamp > this.ttl) {
+        this.delete(key);
+        removed++;
+      }
+    }
+
+    return removed;
+  }
+}
+
+module.exports = { CacheManager };

package/lib/utils/context-optimizer.js

@@ -0,0 +1,300 @@
+/**
+ * Context Optimizer Utilities
+ * Provides optimized git commands to minimize token usage while gathering context
+ *
+ * Target: Keep command execution under 50k tokens
+ *
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+const {
+  escapeShell,
+  escapeSingleQuotes,
+  sanitizeExtension
+} = require('./shell-escape');
+
+/**
+ * Validate git branch name to prevent command injection
+ * @param {string} branch - Branch name to validate
+ * @returns {string} Validated branch name
+ * @throws {Error} If branch name contains invalid characters
+ */
+function validateBranchName(branch) {
+  if (typeof branch !== 'string' || branch.length === 0) {
+    throw new Error('Branch name must be a non-empty string');
+  }
+  if (branch.length > 255) {
+    throw new Error('Branch name too long (max 255 characters)');
+  }
+  // Allow alphanumeric, underscore, hyphen, forward slash, and dot
+  if (!/^[a-zA-Z0-9/_.-]+$/.test(branch)) {
+    throw new Error('Branch name contains invalid characters');
+  }
+  // Prevent git option injection
+  if (branch.startsWith('-')) {
+    throw new Error('Branch name cannot start with hyphen');
+  }
+  return branch;
+}
+
+/**
+ * Validate git reference to prevent command injection
+ * @param {string} ref - Git reference to validate
+ * @returns {string} Validated reference
+ * @throws {Error} If reference contains invalid characters
+ */
+function validateGitRef(ref) {
+  if (typeof ref !== 'string' || ref.length === 0) {
+    throw new Error('Git reference must be a non-empty string');
+  }
+  if (ref.length > 255) {
+    throw new Error('Git reference too long (max 255 characters)');
+  }
+  // Allow alphanumeric, tilde, caret, dot, hyphen, underscore, forward slash
+  if (!/^[a-zA-Z0-9~^._/-]+$/.test(ref)) {
+    throw new Error('Git reference contains invalid characters');
+  }
+  // Prevent git option injection
+  if (ref.startsWith('-')) {
+    throw new Error('Git reference cannot start with hyphen');
+  }
+  return ref;
+}
+
+/**
+ * Validate numeric limit parameter
+ * @param {number} limit - Limit value to validate
+ * @param {number} max - Maximum allowed value (default: 1000)
+ * @returns {number} Validated limit
+ * @throws {Error} If limit is invalid
+ */
+function validateLimit(limit, max = 1000) {
+  // Strict type check - must be number or numeric string
+  if (typeof limit === 'string') {
+    // Only allow pure numeric strings
+    if (!/^\d+$/.test(limit)) {
+      throw new Error('Limit must be a positive integer');
+    }
+  }
+  const num = typeof limit === 'number' ? limit : parseInt(limit, 10);
+  if (!Number.isInteger(num) || num < 1) {
+    throw new Error('Limit must be a positive integer');
+  }
+  if (num > max) {
+    throw new Error(`Limit cannot exceed ${max}`);
+  }
+  return num;
+}
+
+/**
+ * Git command optimization utilities for context efficiency
+ */
+const contextOptimizer = {
+  /**
+   * Get recent commits with minimal formatting
+   * @param {number} limit - Number of commits to retrieve (default: 10)
+   * @returns {string} Git command
+   */
+  recentCommits: (limit = 10) => {
+    const safeLimit = validateLimit(limit);
+    return `git log --oneline --no-decorate -${safeLimit} --format="%h %s"`;
+  },
+
+  /**
+   * Get compact git status (untracked files excluded)
+   * @returns {string} Git command
+   */
+  compactStatus: () =>
+    'git status -uno --porcelain',
+
+  /**
+   * Get file changes between refs
+   * @param {string} ref - Reference to compare from (default: 'HEAD~5')
+   * @returns {string} Git command
+   */
+  fileChanges: (ref = 'HEAD~5') => {
+    const safeRef = validateGitRef(ref);
+    return `git diff ${safeRef}..HEAD --name-status`;
+  },
+
+  /**
+   * Get current branch name
+   * @returns {string} Git command
+   */
+  currentBranch: () =>
+    'git branch --show-current',
+
+  /**
+   * Get remote information (limited to 2 lines)
+   * @returns {string} Git command
+   */
+  remoteInfo: () =>
+    'git remote -v | head -2',
+
+  /**
+   * Check if there are stashed changes
+   * @returns {string} Git command
+   */
+  hasStashes: () =>
+    'git stash list --oneline | wc -l',
+
+  /**
+   * Get worktree list in porcelain format
+   * @returns {string} Git command
+   */
+  worktreeList: () =>
+    'git worktree list --porcelain',
+
+  /**
+   * Get the age of a specific line (for TODO checking)
+   * @param {string} file - File path
+   * @param {number} line - Line number
+   * @returns {string} Git command
+   */
+  lineAge: (file, line) => {
+    // Validate line is a positive integer with reasonable bounds
+    const lineNum = parseInt(line, 10);
+    const MAX_LINE_NUMBER = 10000000; // 10 million lines - reasonable upper bound
+    if (!Number.isInteger(lineNum) || lineNum < 1) {
+      throw new Error('Line must be a positive integer');
+    }
+    if (lineNum > MAX_LINE_NUMBER) {
+      throw new Error(`Line number cannot exceed ${MAX_LINE_NUMBER}`);
+    }
+    // Escape file path for safe shell usage
+    const safeFile = escapeShell(file);
+    return `git blame -L ${lineNum},${lineNum} "${safeFile}" --porcelain | grep '^committer-time' | cut -d' ' -f2`;
+  },
+
+  /**
+   * Find source files by extension
+   * @param {string} extension - File extension (e.g., 'ts', 'py', 'rs')
+   * @returns {string} Git command
+   */
+  findSourceFiles: (extension = 'ts') => {
+    const safeExt = sanitizeExtension(extension);
+    return `git ls-files | grep '\\.${safeExt}$'`;
+  },
+
+  /**
+   * Get diff stat summary
+   * @param {string} ref - Reference to compare from (default: 'HEAD~5')
+   * @returns {string} Git command
+   */
+  diffStat: (ref = 'HEAD~5') => {
+    const safeRef = validateGitRef(ref);
+    return `git diff ${safeRef}..HEAD --stat | head -20`;
+  },
+
+  /**
+   * Get contributors list (limited to top 10)
+   * @returns {string} Git command
+   */
+  contributors: () =>
+    'git shortlog -sn --no-merges | head -10',
+
+  /**
+   * Get last commit message
+   * @returns {string} Git command
+   */
+  lastCommitMessage: () =>
+    'git log -1 --format=%s',
+
+  /**
+   * Get files changed in last commit
+   * @returns {string} Git command
+   */
+  lastCommitFiles: () =>
+    'git diff-tree --no-commit-id --name-only -r HEAD',
+
+  /**
+   * Get branch list (local only, limited)
+   * @param {number} limit - Number of branches (default: 10)
+   * @returns {string} Git command
+   */
+  branches: (limit = 10) => {
+    const safeLimit = validateLimit(limit);
+    return `git branch --format='%(refname:short)' | head -${safeLimit}`;
+  },
+
+  /**
+   * Get tags list (limited)
+   * @param {number} limit - Number of tags (default: 10)
+   * @returns {string} Git command
+   */
+  tags: (limit = 10) => {
+    const safeLimit = validateLimit(limit);
+    return `git tag --sort=-creatordate | head -${safeLimit}`;
+  },
+
+  /**
+   * Get count of commits on current branch since branching from main
+   * @param {string} mainBranch - Main branch name (default: 'main')
+   * @returns {string} Git command
+   */
+  commitsSinceBranch: (mainBranch = 'main') => {
+    const safeBranch = validateBranchName(mainBranch);
+    return `git rev-list --count ${safeBranch}..HEAD`;
+  },
+
+  /**
+   * Check if working directory is clean
+   * @returns {string} Git command
+   */
+  isClean: () =>
+    'git status --porcelain | wc -l',
+
+  /**
+   * Get merge base with main branch
+   * @param {string} mainBranch - Main branch name (default: 'main')
+   * @returns {string} Git command
+   */
+  mergeBase: (mainBranch = 'main') => {
+    const safeBranch = validateBranchName(mainBranch);
+    return `git merge-base ${safeBranch} HEAD`;
+  },
+
+  /**
+   * Get files modified in current branch (since branching)
+   * @param {string} mainBranch - Main branch name (default: 'main')
+   * @returns {string} Git command
+   */
+  branchChangedFiles: (mainBranch = 'main') => {
+    const safeBranch = validateBranchName(mainBranch);
+    return `git diff ${safeBranch}...HEAD --name-only`;
+  },
+
+  /**
+   * Get commit count by author
+   * @param {string} author - Author name or email
+   * @returns {string} Git command
+   */
+  authorCommitCount: (author) => {
+    const safeAuthor = escapeShell(author);
+    return `git log --author="${safeAuthor}" --oneline | wc -l`;
+  },
+
+  /**
+   * Check if file exists in repository
+   * @param {string} file - File path
+   * @returns {string} Git command
+   */
+  fileExists: (file) => {
+    const safeFile = escapeSingleQuotes(file);
+    return `git ls-files | grep -q '${safeFile}' && echo 'true' || echo 'false'`;
+  }
+};
+
+// Export main API
+module.exports = contextOptimizer;
+
+// Export internal functions for testing
+module.exports._internal = {
+  escapeShell,
+  escapeSingleQuotes,
+  sanitizeExtension,
+  validateBranchName,
+  validateGitRef,
+  validateLimit
+};

package/lib/utils/deprecation.js

@@ -0,0 +1,37 @@
+/**
+ * Deprecation Warning Utility
+ * Centralized utility for handling deprecation warnings across the codebase
+ *
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+// Track which functions have already shown deprecation warnings (once per function)
+const _deprecationWarned = new Set();
+
+/**
+ * Show deprecation warning for sync functions (once per function name)
+ * @param {string} funcName - Name of the deprecated sync function
+ * @param {string} asyncAlt - Name of the async alternative
+ */
+function warnDeprecation(funcName, asyncAlt) {
+  if (_deprecationWarned.has(funcName)) return;
+  _deprecationWarned.add(funcName);
+  console.warn(
+    `DEPRECATED: ${funcName}() is synchronous and blocks the event loop. ` +
+    `Use ${asyncAlt}() instead. Will be removed in v3.0.0.`
+  );
+}
+
+/**
+ * Reset deprecation warnings (for testing only)
+ * @private
+ */
+function _resetDeprecationWarnings() {
+  _deprecationWarned.clear();
+}
+
+module.exports = {
+  warnDeprecation,
+  _resetDeprecationWarnings
+};

package/lib/utils/shell-escape.js

@@ -0,0 +1,88 @@
+/**
+ * Shell Escaping Utilities
+ * Centralized string escaping functions for safe shell command construction
+ *
+ * @module lib/utils/shell-escape
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+/**
+ * Escape shell special characters for safe command interpolation
+ * Handles all dangerous shell metacharacters including command injection vectors
+ * Optimized: uses single regex test instead of multiple .includes() calls
+ * @param {string} str - String to escape
+ * @returns {string} Escaped string safe for shell use
+ * @throws {Error} If string contains null bytes or newlines
+ */
+function escapeShell(str) {
+  if (typeof str !== 'string') return '';
+
+  // Reject null bytes and newlines which could be used for injection
+  // Optimized: single regex test instead of 3 separate .includes() scans
+  // Use \x00 instead of \0 for better portability across JS engines
+  if (/[\x00\n\r]/.test(str)) {
+    throw new Error('Input contains invalid characters (null bytes or newlines)');
+  }
+
+  // Escape all shell metacharacters: " $ ` \ ! ; | & > < ( ) { } [ ] * ? ~ # ' space tab
+  return str.replace(/["\$`\\!;|&><(){}[\]*?~#'\s]/g, '\\$&');
+}
+
+/**
+ * Escape single quotes for shell (replace ' with '\''
+ * Use this for strings that will be wrapped in single quotes
+ * @param {string} str - String to escape
+ * @returns {string} Escaped string safe for single-quoted shell use
+ */
+function escapeSingleQuotes(str) {
+  if (typeof str !== 'string') return '';
+  return str.replace(/'/g, "'\\''");
+}
+
+/**
+ * Validate and sanitize file extension
+ * Removes all non-alphanumeric characters
+ * @param {string} ext - Extension to validate
+ * @returns {string} Safe extension (alphanumeric only), defaults to 'ts' if empty
+ */
+function sanitizeExtension(ext) {
+  if (typeof ext !== 'string') return 'ts';
+  const safe = ext.replace(/[^a-zA-Z0-9]/g, '');
+  return safe || 'ts';
+}
+
+/**
+ * Escape a string for use in a double-quoted shell context
+ * More permissive than escapeShell but still safe
+ * @param {string} str - String to escape
+ * @returns {string} Escaped string safe for double-quoted shell use
+ */
+function escapeDoubleQuotes(str) {
+  if (typeof str !== 'string') return '';
+
+  // In double quotes, we need to escape: $ ` " \ and newlines
+  return str.replace(/[$`"\\\n]/g, '\\$&');
+}
+
+/**
+ * Quote a string for safe shell use
+ * Wraps in single quotes and escapes any embedded single quotes
+ * This is often safer than escapeShell for complex strings
+ * @param {string} str - String to quote
+ * @returns {string} Safely quoted string
+ */
+function quoteShell(str) {
+  if (typeof str !== 'string') return "''";
+
+  // Wrap in single quotes and escape any embedded single quotes
+  return "'" + str.replace(/'/g, "'\\''") + "'";
+}
+
+module.exports = {
+  escapeShell,
+  escapeSingleQuotes,
+  sanitizeExtension,
+  escapeDoubleQuotes,
+  quoteShell
+};