@paths.design/caws-cli 10.1.0 → 11.0.0

package/dist/tool-validator.js

@@ -1,393 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * @fileoverview CAWS Tool Validator - Security validation for dynamically loaded tools
- * Validates tools against allowlists, scans for security violations, and ensures safe execution
- * @author @darianrosebrook
- */
-
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-
-/**
- * Tool Validator - Security validation and allowlist enforcement
- */
-class ToolValidator {
-  constructor(options = {}) {
-    // Check new location first, fall back to legacy location
-    const newAllowlistPath = path.join(process.cwd(), '.caws/tools-allow.json');
-    const legacyAllowlistPath = path.join(process.cwd(), 'apps/tools/caws/tools-allow.json');
-    const defaultAllowlistPath = fs.existsSync(newAllowlistPath)
-      ? newAllowlistPath
-      : legacyAllowlistPath;
-
-    this.options = {
-      allowlistPath: options.allowlistPath || defaultAllowlistPath,
-      strictMode: options.strictMode !== false,
-      maxFileSize: options.maxFileSize || 1024 * 1024, // 1MB
-      ...options,
-    };
-
-    this.allowlist = null;
-    this.validationCache = new Map();
-  }
-
-  /**
-   * Load and parse the tools allowlist
-   * @returns {Promise<Array<string>>} Array of allowed commands/patterns
-   */
-  async loadAllowlist() {
-    if (this.allowlist) return this.allowlist;
-
-    try {
-      if (!fs.existsSync(this.options.allowlistPath)) {
-        throw new Error(`Allowlist file not found: ${this.options.allowlistPath}`);
-      }
-
-      const content = await fs.promises.readFile(this.options.allowlistPath, 'utf8');
-      this.allowlist = JSON.parse(content);
-
-      if (!Array.isArray(this.allowlist)) {
-        throw new Error('Allowlist must be an array of strings');
-      }
-
-      return this.allowlist;
-    } catch (error) {
-      throw new Error(`Failed to load allowlist: ${error.message}`);
-    }
-  }
-
-  /**
-   * Validate a tool against security requirements
-   * @param {Object} tool - Tool object with module and metadata
-   * @returns {Promise<Object>} Validation result
-   */
-  async validateTool(tool) {
-    const toolId = tool.metadata?.id || path.basename(tool.path, '.js');
-    const cacheKey = crypto
-      .createHash('md5')
-      .update(toolId + tool.loadedAt)
-      .digest('hex');
-
-    // Check cache first
-    if (this.validationCache.has(cacheKey)) {
-      return this.validationCache.get(cacheKey);
-    }
-
-    const result = {
-      valid: true,
-      checks: [],
-      warnings: [],
-      errors: [],
-      score: 100,
-    };
-
-    try {
-      // Load allowlist if not loaded
-      await this.loadAllowlist();
-
-      // Run all validation checks
-      const checks = await Promise.allSettled([
-        this.checkFileSecurity(tool),
-        this.checkCodeSecurity(tool),
-        this.checkInterfaceCompliance(tool),
-        this.checkMetadataValidity(tool),
-        this.checkDependencySafety(tool),
-      ]);
-
-      // Process check results
-      checks.forEach((check, index) => {
-        const checkName = [
-          'fileSecurity',
-          'codeSecurity',
-          'interfaceCompliance',
-          'metadataValidity',
-          'dependencySafety',
-        ][index];
-
-        if (check.status === 'fulfilled') {
-          const checkResult = check.value;
-          result.checks.push({
-            name: checkName,
-            passed: checkResult.passed,
-            message: checkResult.message,
-            severity: checkResult.severity || 'info',
-          });
-
-          if (!checkResult.passed) {
-            result.valid = false;
-            if (checkResult.severity === 'error') {
-              result.errors.push(checkResult.message);
-              result.score -= 20;
-            } else {
-              result.warnings.push(checkResult.message);
-              result.score -= 5;
-            }
-          }
-        } else {
-          result.checks.push({
-            name: checkName,
-            passed: false,
-            message: `Check failed: ${check.reason.message}`,
-            severity: 'error',
-          });
-          result.valid = false;
-          result.errors.push(check.reason.message);
-          result.score -= 20;
-        }
-      });
-
-      // Cache result
-      this.validationCache.set(cacheKey, result);
-    } catch (error) {
-      result.valid = false;
-      result.errors.push(`Validation failed: ${error.message}`);
-      result.score = 0;
-    }
-
-    return result;
-  }
-
-  /**
-   * Check file-level security
-   * @private
-   * @param {Object} tool - Tool object
-   */
-  async checkFileSecurity(tool) {
-    const issues = [];
-
-    try {
-      const stats = await fs.promises.stat(tool.path);
-
-      // Check file size
-      if (stats.size > this.options.maxFileSize) {
-        issues.push(`File too large: ${stats.size} bytes > ${this.options.maxFileSize} bytes`);
-      }
-
-      // Check file permissions (should be readable)
-      const mode = stats.mode;
-      if (!(mode & parseInt('0444', 8))) {
-        // Owner, group, others can read
-        issues.push('File permissions too restrictive');
-      }
-
-      // Check if file is executable (should not be)
-      if (mode & parseInt('0111', 8)) {
-        // Execute permissions
-        issues.push('Tool file should not have execute permissions');
-      }
-    } catch (error) {
-      issues.push(`File access error: ${error.message}`);
-    }
-
-    return {
-      passed: issues.length === 0,
-      message: issues.length > 0 ? issues.join('; ') : 'File security check passed',
-      severity: issues.length > 0 ? 'error' : 'info',
-    };
-  }
-
-  /**
-   * Check code-level security
-   * @private
-   * @param {Object} tool - Tool object
-   */
-  async checkCodeSecurity(tool) {
-    const issues = [];
-
-    try {
-      const content = await fs.promises.readFile(tool.path, 'utf8');
-
-      // Check for dangerous patterns
-      const dangerousPatterns = [
-        { pattern: /require\(['"`]child_process['"`]\)/g, message: 'Direct child_process usage' },
-        { pattern: /require\(['"`]fs['"`]\)\.writeFileSync/g, message: 'Synchronous file writing' },
-        { pattern: /process\.exit\(/g, message: 'Process termination' },
-        { pattern: /eval\(/g, message: 'Code evaluation' },
-        { pattern: /Function\(['"`]/g, message: 'Dynamic function creation' },
-        { pattern: /require\(['"`]\.\./g, message: 'Directory traversal in require' },
-      ];
-
-      dangerousPatterns.forEach(({ pattern, message }) => {
-        const matches = content.match(pattern);
-        if (matches) {
-          issues.push(`${message} (${matches.length} occurrences)`);
-        }
-      });
-
-      // Check for secrets (basic pattern matching)
-      const secretPatterns = [
-        /password\s*[=:]\s*['"`][^'"]{8,}['"`]/gi,
-        /token\s*[=:]\s*['"`][^'"]{20,}['"`]/gi,
-        /key\s*[=:]\s*['"`][^'"]{16,}['"`]/gi,
-        /secret\s*[=:]\s*['"`][^'"]{16,}['"`]/gi,
-      ];
-
-      secretPatterns.forEach((pattern) => {
-        if (content.match(pattern)) {
-          issues.push('Potential hardcoded secrets detected');
-        }
-      });
-    } catch (error) {
-      issues.push(`Code analysis error: ${error.message}`);
-    }
-
-    return {
-      passed: issues.length === 0,
-      message:
-        issues.length > 0 ? `Security issues: ${issues.join('; ')}` : 'Code security check passed',
-      severity: issues.length > 0 ? 'error' : 'info',
-    };
-  }
-
-  /**
-   * Check interface compliance
-   * @private
-   * @param {Object} tool - Tool object
-   */
-  async checkInterfaceCompliance(tool) {
-    const requiredMethods = ['execute', 'getMetadata'];
-    const missingMethods = [];
-
-    requiredMethods.forEach((method) => {
-      if (typeof tool.module[method] !== 'function') {
-        missingMethods.push(method);
-      }
-    });
-
-    return {
-      passed: missingMethods.length === 0,
-      message:
-        missingMethods.length > 0
-          ? `Missing required methods: ${missingMethods.join(', ')}`
-          : 'Interface compliance check passed',
-      severity: missingMethods.length > 0 ? 'error' : 'info',
-    };
-  }
-
-  /**
-   * Check metadata validity
-   * @private
-   * @param {Object} tool - Tool object
-   */
-  async checkMetadataValidity(tool) {
-    const metadata = tool.metadata || {};
-    const requiredFields = ['id', 'name', 'version'];
-    const missingFields = [];
-    const invalidFields = [];
-
-    // Check required fields
-    requiredFields.forEach((field) => {
-      if (!metadata[field]) {
-        missingFields.push(field);
-      }
-    });
-
-    // Validate field types and formats
-    if (metadata.id && typeof metadata.id !== 'string') {
-      invalidFields.push('id must be string');
-    }
-    if (metadata.name && typeof metadata.name !== 'string') {
-      invalidFields.push('name must be string');
-    }
-    if (metadata.version && typeof metadata.version !== 'string') {
-      invalidFields.push('version must be string');
-    }
-    if (metadata.capabilities && !Array.isArray(metadata.capabilities)) {
-      invalidFields.push('capabilities must be array');
-    }
-
-    const issues = [...missingFields.map((f) => `missing ${f}`), ...invalidFields];
-
-    return {
-      passed: issues.length === 0,
-      message:
-        issues.length > 0
-          ? `Metadata issues: ${issues.join(', ')}`
-          : 'Metadata validity check passed',
-      severity: issues.length > 0 ? 'error' : 'info',
-    };
-  }
-
-  /**
-   * Check dependency safety
-   * @private
-   * @param {Object} tool - Tool object
-   */
-  async checkDependencySafety(tool) {
-    const metadata = tool.metadata || {};
-    const issues = [];
-
-    if (metadata.dependencies) {
-      if (!Array.isArray(metadata.dependencies)) {
-        issues.push('dependencies must be array');
-      } else {
-        // Check for potentially unsafe dependencies
-        const unsafeDeps = ['child_process', 'fs-extra', 'execa', 'shelljs'];
-        const foundUnsafe = metadata.dependencies.filter((dep) =>
-          unsafeDeps.some((unsafe) => dep.includes(unsafe))
-        );
-
-        if (foundUnsafe.length > 0) {
-          issues.push(`Potentially unsafe dependencies: ${foundUnsafe.join(', ')}`);
-        }
-      }
-    }
-
-    return {
-      passed: issues.length === 0,
-      message:
-        issues.length > 0
-          ? `Dependency issues: ${issues.join('; ')}`
-          : 'Dependency safety check passed',
-      severity: issues.length > 0 ? 'warning' : 'info',
-    };
-  }
-
-  /**
-   * Validate a command against the allowlist
-   * @param {string} command - Command to validate
-   * @returns {boolean} True if command is allowed
-   */
-  async validateCommand(command) {
-    const allowlist = await this.loadAllowlist();
-
-    // Check exact matches first
-    if (allowlist.includes(command)) {
-      return true;
-    }
-
-    // Check pattern matches
-    return allowlist.some((allowed) => {
-      if (allowed.includes('*')) {
-        // Simple wildcard matching
-        const regex = new RegExp(allowed.replace(/\*/g, '.*'));
-        return regex.test(command);
-      }
-      return false;
-    });
-  }
-
-  /**
-   * Clear validation cache
-   */
-  clearCache() {
-    this.validationCache.clear();
-  }
-
-  /**
-   * Get validator statistics
-   * @returns {Object} Statistics object
-   */
-  getStats() {
-    return {
-      allowlistLoaded: this.allowlist !== null,
-      allowlistSize: this.allowlist?.length || 0,
-      cacheSize: this.validationCache.size,
-      strictMode: this.options.strictMode,
-    };
-  }
-}
-
-module.exports = ToolValidator;

package/dist/utils/agent-session.js

@@ -1,202 +0,0 @@
-/**
- * Agent Session Identity
- *
- * Provides a unified way to identify the current agent session across
- * Claude Code, Cursor, and other IDE agent environments.
- *
- * Sources checked (first match wins):
- *   1. CLAUDE_SESSION_ID  — set by Claude Code automatically
- *   2. .caws/agents.json  — written by Cursor session-log hook (conversation_id)
- *   3. CURSOR_TRACE_ID    — set by Cursor (per-request, not stable, last resort)
- *
- * The agent registry (.caws/agents.json) also tracks active agents for
- * multi-agent coordination. Entries expire after a configurable TTL.
- *
- * @author @darianrosebrook
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const AGENTS_REGISTRY = '.caws/agents.json';
-const DEFAULT_TTL_MS = 30 * 60 * 1000; // 30 minutes
-
-/**
- * Get the current agent's session ID from the best available source.
- * @param {string} [projectRoot] - Project root (for reading agent registry)
- * @returns {string|null} Session ID or null if not in an agent context
- */
-function getAgentSessionId(projectRoot) {
-  // 1. Claude Code — most reliable, set automatically
-  if (process.env.CLAUDE_SESSION_ID) {
-    return process.env.CLAUDE_SESSION_ID;
-  }
-
-  // 2. Agent registry — written by Cursor session-log hook
-  if (projectRoot) {
-    const registry = loadAgentRegistry(projectRoot);
-    const active = findActiveAgent(registry);
-    if (active) {
-      return active.sessionId;
-    }
-  }
-
-  // 3. Cursor trace ID — per-request, not stable, but better than nothing
-  if (process.env.CURSOR_TRACE_ID) {
-    return `cursor:${process.env.CURSOR_TRACE_ID}`;
-  }
-
-  return null;
-}
-
-/**
- * Get the agent platform name.
- * @returns {string} 'claude-code' | 'cursor' | 'unknown'
- */
-function getAgentPlatform() {
-  if (process.env.CLAUDE_SESSION_ID) return 'claude-code';
-  if (process.env.CURSOR_TRACE_ID) return 'cursor';
-  return 'unknown';
-}
-
-/**
- * Load the agent registry, pruning stale entries.
- * @param {string} root - Project root
- * @returns {object} Registry with { agents: { [sessionId]: entry } }
- */
-function loadAgentRegistry(root) {
-  const registryPath = path.join(root, AGENTS_REGISTRY);
-  let registry = { version: 1, agents: {} };
-
-  if (fs.existsSync(registryPath)) {
-    try {
-      registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
-    } catch {
-      // Corrupt file — start fresh
-      registry = { version: 1, agents: {} };
-    }
-  }
-
-  // Prune stale entries on every read
-  const now = Date.now();
-  let pruned = false;
-  for (const [id, entry] of Object.entries(registry.agents || {})) {
-    const ttl = entry.ttl || DEFAULT_TTL_MS;
-    const lastSeenTime = entry.lastSeen ? new Date(entry.lastSeen).getTime() : 0;
-    const lastSeen = isNaN(lastSeenTime) ? 0 : lastSeenTime;
-    if (now - lastSeen > ttl) {
-      delete registry.agents[id];
-      pruned = true;
-    }
-  }
-
-  if (pruned) {
-    saveAgentRegistry(root, registry);
-  }
-
-  return registry;
-}
-
-/**
- * Save the agent registry atomically (write-then-rename).
- * @param {string} root - Project root
- * @param {object} registry - Registry object
- */
-function saveAgentRegistry(root, registry) {
-  const registryPath = path.join(root, AGENTS_REGISTRY);
-  const dir = path.dirname(registryPath);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-  const tmpPath = registryPath + '.tmp.' + process.pid;
-  fs.writeFileSync(tmpPath, JSON.stringify(registry, null, 2));
-  fs.renameSync(tmpPath, registryPath);
-}
-
-/**
- * Register or heartbeat an agent session.
- * Called by session-log hooks to keep entries fresh.
- * @param {string} root - Project root
- * @param {object} agent - Agent info
- * @param {string} agent.sessionId - Unique session/conversation ID
- * @param {string} agent.platform - 'claude-code' | 'cursor' | 'unknown'
- * @param {string} [agent.model] - Model name if known
- * @param {string} [agent.specId] - Active spec ID if known
- * @param {number} [agent.ttl] - Custom TTL in ms (default 30 min)
- */
-function heartbeatAgent(root, agent) {
-  const registry = loadAgentRegistry(root);
-  const existing = registry.agents[agent.sessionId] || {};
-
-  registry.agents[agent.sessionId] = {
-    ...existing,
-    sessionId: agent.sessionId,
-    platform: agent.platform || existing.platform || 'unknown',
-    model: agent.model || existing.model || null,
-    specId: agent.specId || existing.specId || null,
-    ttl: agent.ttl || existing.ttl || DEFAULT_TTL_MS,
-    firstSeen: existing.firstSeen || new Date().toISOString(),
-    lastSeen: new Date().toISOString(),
-  };
-
-  saveAgentRegistry(root, registry);
-}
-
-/**
- * Remove an agent session from the registry.
- * Called on session stop.
- * @param {string} root - Project root
- * @param {string} sessionId - Session to remove
- */
-function removeAgent(root, sessionId) {
-  const registry = loadAgentRegistry(root);
-  delete registry.agents[sessionId];
-  saveAgentRegistry(root, registry);
-}
-
-/**
- * Find the most recently active agent for this terminal/process.
- * Prefers agents that match the current environment.
- * @param {object} registry - Loaded registry
- * @returns {object|null} Agent entry or null
- */
-function findActiveAgent(registry) {
-  const agents = Object.values(registry.agents || {});
-  if (agents.length === 0) return null;
-
-  // If we're in Cursor, prefer cursor agents
-  const isCursor = !!process.env.CURSOR_TRACE_ID;
-  const preferred = agents.filter(a => {
-    if (isCursor) return a.platform === 'cursor';
-    return a.platform === 'claude-code';
-  });
-
-  const pool = preferred.length > 0 ? preferred : agents;
-
-  // Return most recently seen
-  pool.sort((a, b) => new Date(b.lastSeen) - new Date(a.lastSeen));
-  return pool[0];
-}
-
-/**
- * List all currently active (non-expired) agents.
- * @param {string} root - Project root
- * @returns {object[]} Array of agent entries
- */
-function listActiveAgents(root) {
-  const registry = loadAgentRegistry(root);
-  return Object.values(registry.agents || {});
-}
-
-module.exports = {
-  getAgentSessionId,
-  getAgentPlatform,
-  loadAgentRegistry,
-  saveAgentRegistry,
-  heartbeatAgent,
-  removeAgent,
-  findActiveAgent,
-  listActiveAgents,
-  AGENTS_REGISTRY,
-  DEFAULT_TTL_MS,
-};