@paths.design/caws-cli 10.2.0 → 11.1.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-display.js

@@ -1,210 +0,0 @@
-/**
- * @fileoverview CAWSFIX-31 — agent claim display formatters.
- *
- * Single-purpose helpers for rendering agent / claim information so the
- * format ("<sessionId>:<platform>", claim panels, soft-block warnings)
- * is consistent across `caws status`, `caws agents`, and the
- * worktree-manager soft-block surface.
- *
- * Display only — no I/O of its own beyond the small loaders it needs.
- *
- * @author @darianrosebrook
- */
-
-const path = require('path');
-const fs = require('fs');
-
-const {
-  loadAgentRegistry,
-  findSessionLogs,
-} = require('./agent-session');
-
-/**
- * Composite identifier used in every visible reference to an agent.
- * Format: `<sessionId>:<platform>`. Lets readers trace provenance to
- * platform-specific transcript directories.
- *
- * @param {string} sessionId
- * @param {string} platform - 'claude-code' | 'cursor' | 'unknown'
- * @returns {string}
- */
-function formatAgentRef(sessionId, platform) {
-  const sid = sessionId || 'unknown';
-  const plat = platform || 'unknown';
-  return `${sid}:${plat}`;
-}
-
-/**
- * Compute a short human-readable age for a heartbeat timestamp.
- * @param {string|null} iso
- * @returns {string}
- */
-function formatHeartbeatAge(iso) {
-  if (!iso) return 'unknown';
-  const t = Date.parse(iso);
-  if (isNaN(t)) return 'unknown';
-  const ms = Date.now() - t;
-  if (ms < 0) return 'in the future';
-  const sec = Math.round(ms / 1000);
-  if (sec < 60) return `${sec}s ago`;
-  const min = Math.round(sec / 60);
-  if (min < 60) return `${min} min ago`;
-  const hr = Math.round(min / 60);
-  if (hr < 24) return `${hr}h ago`;
-  const days = Math.round(hr / 24);
-  return `${days}d ago`;
-}
-
-/**
- * Format a single session-log pointer for inclusion in a warning.
- * Path is project-relative when possible.
- *
- * @param {object} log - Result from findSessionLogs
- * @param {string} root - Project root (for relative path)
- * @returns {string}
- */
-function formatSessionLogPointer(log, root) {
-  const rel = path.relative(root, log.path) || log.path;
-  const parts = [`tmp/${path.basename(log.path)}`, `${log.turnCount} turns`];
-  if (log.lastTurn) parts.push(`last turn ${log.lastTurn}`);
-  return `   Session log: ${rel}\n                ${parts.join(', ')}`;
-}
-
-/**
- * Build the structured warning printed when a foreign claim is
- * detected on a worktree (for `assertWorktreeOwnership` soft-block,
- * `caws worktree claim` read-only mode, etc.).
- *
- * @param {object} args
- * @param {string} args.worktree - Worktree name
- * @param {object|null} args.priorOwnerEntry - The agents.json entry for the
- *   prior owner, or null when TTL-pruned.
- * @param {string} args.priorOwnerSessionId - Sid from worktrees.json:owner
- * @param {Array} args.sessionLogs - findSessionLogs() result
- * @param {string} args.root - Project root for relative paths
- * @param {string} args.takeoverCommand - Exact command to suggest
- * @returns {string}
- */
-function formatClaimNotice(args) {
-  const {
-    worktree,
-    priorOwnerEntry,
-    priorOwnerSessionId,
-    sessionLogs = [],
-    root,
-    takeoverCommand,
-  } = args;
-
-  const platform = priorOwnerEntry ? priorOwnerEntry.platform : 'unknown';
-  const ref = formatAgentRef(priorOwnerSessionId, platform);
-
-  const lines = [
-    `Worktree '${worktree}' is claimed by ${ref}`,
-  ];
-
-  if (priorOwnerEntry) {
-    const age = formatHeartbeatAge(priorOwnerEntry.lastSeen);
-    lines.push(`   Last heartbeat: ${priorOwnerEntry.lastSeen} (${age})`);
-  } else {
-    lines.push(`   Last heartbeat: no live agent registry entry (pruned or stale)`);
-  }
-
-  for (const log of sessionLogs) {
-    lines.push(formatSessionLogPointer(log, root));
-  }
-
-  if (takeoverCommand) {
-    lines.push(`   To proceed:    ${takeoverCommand}`);
-  }
-
-  return lines.join('\n');
-}
-
-/**
- * Build a softer hint when a worktree has no CAWS-tracked owner but a
- * matching session-log directory exists (the "may still be active"
- * scenario from AC A8).
- *
- * @param {object} args
- * @param {string} args.worktree
- * @param {Array} args.sessionLogs
- * @param {string} args.root
- * @returns {string}
- */
-function formatOrphanLogHint(args) {
-  const { worktree, sessionLogs = [], root } = args;
-  const lines = [
-    `No active CAWS claim on worktree '${worktree}', but a session log exists.`,
-    `   The previous session may still be active — read for context before continuing:`,
-  ];
-  for (const log of sessionLogs) {
-    lines.push(formatSessionLogPointer(log, root));
-  }
-  return lines.join('\n');
-}
-
-/**
- * Render the Claim panel that `caws status` includes when cwd is
- * inside a worktree. Returns a multi-line string (caller prints it).
- *
- * @param {string} root - Project root
- * @param {string} worktreeName - Worktree to inspect
- * @returns {string}
- */
-function renderClaimPanel(root, worktreeName) {
-  let entry = null;
-  try {
-    const wtRegistryPath = path.join(root, '.caws', 'worktrees.json');
-    if (fs.existsSync(wtRegistryPath)) {
-      const reg = JSON.parse(fs.readFileSync(wtRegistryPath, 'utf8'));
-      entry = reg.worktrees && reg.worktrees[worktreeName];
-    }
-  } catch {
-    // Best-effort.
-  }
-
-  if (!entry || !entry.owner) {
-    return `Claim: no active claim on worktree '${worktreeName}'`;
-  }
-
-  const agentRegistry = loadAgentRegistry(root);
-  const ownerEntry = agentRegistry.agents[entry.owner] || null;
-  const platform = ownerEntry ? ownerEntry.platform : 'unknown';
-  const ref = formatAgentRef(entry.owner, platform);
-
-  const lines = [`Claim: worktree '${worktreeName}' owned by ${ref}`];
-  if (ownerEntry) {
-    lines.push(
-      `   Last heartbeat: ${ownerEntry.lastSeen} (${formatHeartbeatAge(ownerEntry.lastSeen)})`
-    );
-    if (ownerEntry.specId) {
-      lines.push(`   Spec:           ${ownerEntry.specId}`);
-    }
-  } else {
-    lines.push(`   Last heartbeat: no live agent registry entry (pruned)`);
-  }
-
-  // Surface session-log pointers if present (filter by branch when known).
-  const branch = entry.branch || null;
-  const logs = findSessionLogs(root, { sessionId: entry.owner }).concat(
-    branch ? findSessionLogs(root, { branch }) : []
-  );
-  // Dedupe by path
-  const seen = new Set();
-  for (const log of logs) {
-    if (seen.has(log.path)) continue;
-    seen.add(log.path);
-    lines.push(formatSessionLogPointer(log, root));
-  }
-
-  return lines.join('\n');
-}
-
-module.exports = {
-  formatAgentRef,
-  formatHeartbeatAge,
-  formatSessionLogPointer,
-  formatClaimNotice,
-  formatOrphanLogHint,
-  renderClaimPanel,
-};