agentsys 5.0.3 → 5.2.0

package/plugins/audit-project/lib/enhance/tool-patterns.js

@@ -1,373 +0,0 @@
-/**
- * MCP Tool Definition Patterns
- * Detection patterns for MCP tool definition issues
- * Based on FUNCTION-CALLING-TOOL-USE-REFERENCE.md best practices
- *
- * @author Avi Fenesh
- * @license MIT
- */
-
-/**
- * Tool definition patterns
- */
-const toolPatterns = {
-  /**
-   * Tool name should be verb + noun
-   * MEDIUM certainty - naming convention
-   */
-  poor_tool_naming: {
-    id: 'poor_tool_naming',
-    category: 'tool',
-    certainty: 'MEDIUM',
-    autoFix: false,
-    description: 'Tool name should follow verb_noun pattern',
-    check: (tool) => {
-      if (!tool || !tool.name) return null;
-
-      const name = tool.name;
-      // Check for common verb prefixes
-      const verbPrefixes = ['get', 'set', 'create', 'delete', 'update', 'list', 'find', 'search', 'add', 'remove', 'check', 'validate', 'run', 'execute', 'start', 'stop', 'read', 'write'];
-      const hasVerb = verbPrefixes.some(v => name.toLowerCase().startsWith(v));
-
-      if (!hasVerb && name.length > 3) {
-        return {
-          issue: `Tool name "${name}" doesn't start with a verb`,
-          fix: 'Rename to verb_noun pattern (e.g., get_user, create_file)'
-        };
-      }
-      return null;
-    }
-  },
-
-  /**
-   * Use enums for constrained values
-   * MEDIUM certainty - improves reliability
-   */
-  missing_enum: {
-    id: 'missing_enum',
-    category: 'tool',
-    certainty: 'MEDIUM',
-    autoFix: false,
-    description: 'Parameter with limited options should use enum',
-    check: (schema) => {
-      if (!schema || !schema.properties) return null;
-
-      const issues = [];
-      for (const [name, prop] of Object.entries(schema.properties)) {
-        // Check for string params that mention specific options in description
-        if (prop.type === 'string' && prop.description) {
-          const desc = prop.description.toLowerCase();
-          if ((desc.includes('one of') || desc.includes('must be') || desc.includes('can be')) &&
-              !prop.enum) {
-            issues.push({
-              param: name,
-              issue: `Parameter "${name}" describes options but doesn't use enum`,
-              fix: 'Add enum array with valid options'
-            });
-          }
-        }
-      }
-
-      return issues.length > 0 ? issues : null;
-    }
-  },
-
-  /**
-   * Flat structure preferred
-   * MEDIUM certainty - improves LLM reliability
-   */
-  nested_structure: {
-    id: 'nested_structure',
-    category: 'tool',
-    certainty: 'MEDIUM',
-    autoFix: false,
-    description: 'Prefer flat parameter structure over nested objects',
-    maxDepth: 2,
-    check: (schema, depth = 0) => {
-      if (!schema || typeof schema !== 'object') return null;
-
-      if (depth > 2) {
-        return {
-          issue: `Schema nested ${depth} levels (prefer flat structure)`,
-          fix: 'Flatten to max 2 levels for LLM reliability'
-        };
-      }
-
-      if (schema.properties) {
-        for (const [name, prop] of Object.entries(schema.properties)) {
-          if (prop.type === 'object' && prop.properties) {
-            const nested = toolPatterns.nested_structure.check(prop, depth + 1);
-            if (nested) return { ...nested, param: name };
-          }
-        }
-      }
-
-      return null;
-    }
-  },
-
-  /**
-   * Parameter format hints
-   * LOW certainty - improves clarity
-   */
-  missing_format_hints: {
-    id: 'missing_format_hints',
-    category: 'tool',
-    certainty: 'LOW',
-    autoFix: false,
-    description: 'Parameter description could include format hints',
-    check: (schema) => {
-      if (!schema || !schema.properties) return null;
-
-      const issues = [];
-      const formatKeywords = ['date', 'time', 'email', 'url', 'path', 'json', 'uuid', 'regex'];
-
-      for (const [name, prop] of Object.entries(schema.properties)) {
-        if (prop.type === 'string' && prop.description) {
-          const nameLower = name.toLowerCase();
-          const descLower = prop.description.toLowerCase();
-
-          // Check if name suggests a format but no format/pattern specified
-          for (const keyword of formatKeywords) {
-            if ((nameLower.includes(keyword) || descLower.includes(keyword)) &&
-                !prop.format && !prop.pattern) {
-              issues.push({
-                param: name,
-                issue: `Parameter "${name}" may need format hint`,
-                fix: `Consider adding format or pattern for ${keyword} validation`
-              });
-              break;
-            }
-          }
-        }
-      }
-
-      return issues.length > 0 ? issues : null;
-    }
-  },
-
-  /**
-   * Required parameters should be explicit
-   * HIGH certainty - prevents ambiguity
-   */
-  implicit_required: {
-    id: 'implicit_required',
-    category: 'tool',
-    certainty: 'HIGH',
-    autoFix: true,
-    description: 'Parameters should explicitly declare required status',
-    check: (schema) => {
-      if (!schema || !schema.properties) return null;
-
-      const propCount = Object.keys(schema.properties).length;
-      const requiredCount = schema.required?.length || 0;
-
-      // If properties exist but no required array
-      if (propCount > 0 && !schema.required) {
-        return {
-          issue: 'No required array defined',
-          fix: 'Add required array listing mandatory parameters',
-          autoFixFn: (s) => ({
-            ...s,
-            required: Object.keys(s.properties).filter(k => {
-              const prop = s.properties[k];
-              // Consider params required unless they have default or are marked optional
-              return !prop.default && !/optional/i.test(prop.description || '');
-            })
-          })
-        };
-      }
-
-      return null;
-    }
-  },
-
-  /**
-   * Strict mode recommended
-   * HIGH certainty - prevents undefined behavior
-   */
-  missing_strict_mode: {
-    id: 'missing_strict_mode',
-    category: 'tool',
-    certainty: 'HIGH',
-    autoFix: true,
-    description: 'Schema should use strict mode (additionalProperties: false)',
-    check: (schema) => {
-      if (!schema || schema.type !== 'object') return null;
-
-      if (schema.additionalProperties !== false) {
-        return {
-          issue: 'Schema not in strict mode',
-          fix: 'Add additionalProperties: false',
-          autoFixFn: (s) => ({ ...s, additionalProperties: false })
-        };
-      }
-
-      return null;
-    }
-  },
-
-  /**
-   * Description quality check
-   * LOW certainty - stylistic
-   */
-  poor_description: {
-    id: 'poor_description',
-    category: 'tool',
-    certainty: 'LOW',
-    autoFix: false,
-    description: 'Tool description could be more descriptive',
-    minLength: 20,
-    check: (tool) => {
-      if (!tool || !tool.description) return null;
-
-      const desc = tool.description.trim();
-
-      // Too short
-      if (desc.length < 20) {
-        return {
-          issue: `Description too short (${desc.length} chars)`,
-          fix: 'Add more detail about what the tool does'
-        };
-      }
-
-      // Just repeats the name
-      if (tool.name && desc.toLowerCase().replace(/[_-]/g, ' ') === tool.name.toLowerCase().replace(/[_-]/g, ' ')) {
-        return {
-          issue: 'Description just repeats tool name',
-          fix: 'Describe what the tool does, not its name'
-        };
-      }
-
-      return null;
-    }
-  },
-
-  /**
-   * Redundant tool detection
-   * LOW certainty - may be intentional
-   */
-  redundant_tools: {
-    id: 'redundant_tools',
-    category: 'tool',
-    certainty: 'LOW',
-    autoFix: false,
-    description: 'Potentially redundant tools with similar functionality',
-    check: (tools) => {
-      if (!tools || !Array.isArray(tools) || tools.length < 2) return null;
-
-      const issues = [];
-      const seen = new Map();
-
-      for (const tool of tools) {
-        if (!tool.name) continue;
-
-        // Normalize name for comparison
-        const normalized = tool.name.toLowerCase()
-          .replace(/[_-]/g, '')
-          .replace(/^(get|fetch|retrieve|find|search)/, 'get')
-          .replace(/^(set|update|modify|change)/, 'set')
-          .replace(/^(create|make|add|new)/, 'create')
-          .replace(/^(delete|remove|destroy)/, 'delete');
-
-        if (seen.has(normalized)) {
-          issues.push({
-            tool1: seen.get(normalized),
-            tool2: tool.name,
-            issue: `Tools "${seen.get(normalized)}" and "${tool.name}" may be redundant`,
-            fix: 'Consider consolidating into single tool'
-          });
-        }
-        seen.set(normalized, tool.name);
-      }
-
-      return issues.length > 0 ? issues : null;
-    }
-  }
-};
-
-/**
- * Get all tool patterns
- * @returns {Object} All tool patterns
- */
-function getAllPatterns() {
-  return toolPatterns;
-}
-
-/**
- * Get patterns by certainty level
- * @param {string} certainty - HIGH, MEDIUM, or LOW
- * @returns {Object} Filtered patterns
- */
-function getPatternsByCertainty(certainty) {
-  const result = {};
-  for (const [name, pattern] of Object.entries(toolPatterns)) {
-    if (pattern.certainty === certainty) {
-      result[name] = pattern;
-    }
-  }
-  return result;
-}
-
-/**
- * Analyze a tool definition
- * @param {Object} tool - Tool definition object
- * @returns {Array} Array of issues found
- */
-function analyzeTool(tool) {
-  const issues = [];
-
-  for (const [name, pattern] of Object.entries(toolPatterns)) {
-    if (pattern.check && name !== 'redundant_tools') {
-      const result = pattern.check(tool);
-      if (result) {
-        if (Array.isArray(result)) {
-          issues.push(...result.map(r => ({ ...r, patternId: pattern.id, certainty: pattern.certainty })));
-        } else {
-          issues.push({ ...result, patternId: pattern.id, certainty: pattern.certainty });
-        }
-      }
-    }
-  }
-
-  // Check schema separately
-  if (tool.inputSchema || tool.parameters) {
-    const schema = tool.inputSchema || tool.parameters;
-    for (const [name, pattern] of Object.entries(toolPatterns)) {
-      if (pattern.check && ['nested_structure', 'missing_enum', 'missing_format_hints', 'implicit_required', 'missing_strict_mode'].includes(name)) {
-        const result = pattern.check(schema);
-        if (result) {
-          if (Array.isArray(result)) {
-            issues.push(...result.map(r => ({ ...r, patternId: pattern.id, certainty: pattern.certainty, tool: tool.name })));
-          } else {
-            issues.push({ ...result, patternId: pattern.id, certainty: pattern.certainty, tool: tool.name });
-          }
-        }
-      }
-    }
-  }
-
-  return issues;
-}
-
-/**
- * Check for redundant tools across a set
- * @param {Array} tools - Array of tool definitions
- * @returns {Array} Array of redundancy issues
- */
-function checkRedundancy(tools) {
-  const pattern = toolPatterns.redundant_tools;
-  const result = pattern.check(tools);
-  if (result) {
-    return result.map(r => ({ ...r, patternId: pattern.id, certainty: pattern.certainty }));
-  }
-  return [];
-}
-
-module.exports = {
-  toolPatterns,
-  getAllPatterns,
-  getPatternsByCertainty,
-  analyzeTool,
-  checkRedundancy
-};

package/plugins/audit-project/lib/index.js

@@ -1,270 +0,0 @@
-/**
- * AgentSys Core Library
- *
- * Unified entry point for all core library modules.
- * Provides platform detection, pattern matching, workflow state management,
- * configuration management, and context optimization utilities.
- *
- * @module agentsys/lib
- * @author Avi Fenesh
- * @license MIT
- */
-
-const detectPlatform = require('./platform/detect-platform');
-const verifyTools = require('./platform/verify-tools');
-const reviewPatterns = require('./patterns/review-patterns');
-const slopPatterns = require('./patterns/slop-patterns');
-const pipeline = require('./patterns/pipeline');
-const cliEnhancers = require('./patterns/cli-enhancers');
-const workflowState = require('./state/workflow-state');
-const contextOptimizer = require('./utils/context-optimizer');
-const shellEscape = require('./utils/shell-escape');
-const config = require('./config');
-const sourceCache = require('./sources/source-cache');
-const customHandler = require('./sources/custom-handler');
-const policyQuestions = require('./sources/policy-questions');
-const crossPlatform = require('./cross-platform');
-const enhance = require('./enhance');
-const repoMap = require('./repo-map');
-const perf = require('./perf');
-const collectors = require('./collectors');
-const discoveryModule = require('./discovery');
-
-/**
- * Platform detection and verification utilities
- */
-const platform = {
-  /**
-   * Detect project platform configuration
-   * @see module:platform/detect-platform
-   */
-  detect: detectPlatform.detect,
-  detectAsync: detectPlatform.detectAsync,
-  detectCI: detectPlatform.detectCI,
-  detectDeployment: detectPlatform.detectDeployment,
-  detectProjectType: detectPlatform.detectProjectType,
-  detectPackageManager: detectPlatform.detectPackageManager,
-  detectBranchStrategy: detectPlatform.detectBranchStrategy,
-  detectMainBranch: detectPlatform.detectMainBranch,
-  invalidateCache: detectPlatform.invalidateCache,
-
-  /**
-   * Verify tool availability
-   * @see module:platform/verify-tools
-   */
-  verifyTools: verifyTools.verify,
-  verifyToolsAsync: verifyTools.verifyAsync,
-  checkTool: verifyTools.checkTool,
-  checkToolAsync: verifyTools.checkToolAsync,
-  TOOL_DEFINITIONS: verifyTools.TOOL_DEFINITIONS
-};
-
-/**
- * Code pattern matching utilities
- */
-const patterns = {
-  /**
-   * Review patterns for code quality analysis
-   * @see module:patterns/review-patterns
-   */
-  review: reviewPatterns,
-
-  /**
-   * Slop patterns for AI-generated code detection
-   * @see module:patterns/slop-patterns
-   */
-  slop: slopPatterns,
-
-  /**
-   * Slop detection pipeline orchestrator
-   * @see module:patterns/pipeline
-   */
-  pipeline: {
-    runPipeline: pipeline.runPipeline,
-    CERTAINTY: pipeline.CERTAINTY,
-    THOROUGHNESS: pipeline.THOROUGHNESS,
-    formatHandoffPrompt: pipeline.formatHandoffPrompt,
-    buildSummary: pipeline.buildSummary
-  },
-
-  /**
-   * Optional CLI tool enhancers for deep analysis
-   * @see module:patterns/cli-enhancers
-   */
-  cliEnhancers: {
-    detectAvailableTools: cliEnhancers.detectAvailableTools,
-    runDuplicateDetection: cliEnhancers.runDuplicateDetection,
-    runDependencyAnalysis: cliEnhancers.runDependencyAnalysis,
-    runComplexityAnalysis: cliEnhancers.runComplexityAnalysis,
-    getMissingToolsMessage: cliEnhancers.getMissingToolsMessage,
-    CLI_TOOLS: cliEnhancers.CLI_TOOLS
-  }
-};
-
-/**
- * Workflow state management
- * @see module:state/workflow-state
- */
-const state = {
-  // Constants
-  SCHEMA_VERSION: workflowState.SCHEMA_VERSION,
-  PHASES: workflowState.PHASES,
-  DEFAULT_POLICY: workflowState.DEFAULT_POLICY,
-
-  // Core functions
-  generateWorkflowId: workflowState.generateWorkflowId,
-  getStatePath: workflowState.getStatePath,
-  ensureStateDir: workflowState.ensureStateDir,
-  validateStateSchema: workflowState.validateStateSchema,
-
-  // CRUD operations
-  createState: workflowState.createState,
-  readState: workflowState.readState,
-  writeState: workflowState.writeState,
-  updateState: workflowState.updateState,
-  deleteState: workflowState.deleteState,
-
-  // Phase management
-  startPhase: workflowState.startPhase,
-  completePhase: workflowState.completePhase,
-  failPhase: workflowState.failPhase,
-  skipToPhase: workflowState.skipToPhase,
-
-  // Workflow lifecycle
-  completeWorkflow: workflowState.completeWorkflow,
-  abortWorkflow: workflowState.abortWorkflow,
-  hasActiveWorkflow: workflowState.hasActiveWorkflow,
-  getWorkflowSummary: workflowState.getWorkflowSummary,
-
-  // Agent management
-  updateAgentResult: workflowState.updateAgentResult,
-  incrementIteration: workflowState.incrementIteration
-};
-
-/**
- * Git command optimization and string escaping utilities
- * @see module:utils/context-optimizer
- * @see module:utils/shell-escape
- */
-const utils = {
-  contextOptimizer,
-  shellEscape
-};
-
-/**
- * Task source management
- * @see module:sources/source-cache
- * @see module:sources/custom-handler
- * @see module:sources/policy-questions
- */
-const sources = {
-  // Main entry point - returns ready-to-use question structure
-  getPolicyQuestions: policyQuestions.getPolicyQuestions,
-  getCustomTypeQuestions: policyQuestions.getCustomTypeQuestions,
-  getCustomNameQuestion: policyQuestions.getCustomNameQuestion,
-  parseAndCachePolicy: policyQuestions.parseAndCachePolicy,
-  isUsingCached: policyQuestions.isUsingCached,
-  needsCustomFollowUp: policyQuestions.needsCustomFollowUp,
-  needsOtherDescription: policyQuestions.needsOtherDescription,
-
-  // Cache operations (direct access if needed)
-  getPreference: sourceCache.getPreference,
-  savePreference: sourceCache.savePreference,
-  getToolCapabilities: sourceCache.getToolCapabilities,
-  saveToolCapabilities: sourceCache.saveToolCapabilities,
-  clearCache: sourceCache.clearCache,
-
-  // Custom source handling (direct access if needed)
-  SOURCE_TYPES: customHandler.SOURCE_TYPES,
-  probeCLI: customHandler.probeCLI,
-  buildCustomConfig: customHandler.buildCustomConfig
-};
-
-/**
- * Cross-platform utilities for Claude Code, OpenCode, and Codex CLI
- * @see module:cross-platform
- */
-const xplat = {
-  // Platform detection
-  PLATFORMS: crossPlatform.PLATFORMS,
-  STATE_DIRS: crossPlatform.STATE_DIRS,
-  getStateDir: crossPlatform.getStateDir,
-  detectPlatform: crossPlatform.detectPlatform,
-
-  // Tool schema helpers
-  TOOL_SCHEMA_GUIDELINES: crossPlatform.TOOL_SCHEMA_GUIDELINES,
-  createToolDefinition: crossPlatform.createToolDefinition,
-
-  // Response helpers (MCP-compatible)
-  successResponse: crossPlatform.successResponse,
-  errorResponse: crossPlatform.errorResponse,
-  unknownToolResponse: crossPlatform.unknownToolResponse,
-
-  // Prompt formatting
-  formatBlock: crossPlatform.formatBlock,
-  formatList: crossPlatform.formatList,
-  formatSection: crossPlatform.formatSection,
-
-  // Token efficiency
-  truncate: crossPlatform.truncate,
-  compactSummary: crossPlatform.compactSummary,
-
-  // Agent prompts
-  AGENT_TEMPLATE: crossPlatform.AGENT_TEMPLATE,
-  createAgentPrompt: crossPlatform.createAgentPrompt,
-
-  // Platform configs
-  getOpenCodeConfig: crossPlatform.getOpenCodeConfig,
-  getCodexConfig: crossPlatform.getCodexConfig,
-  getInstructionFiles: crossPlatform.getInstructionFiles,
-  INSTRUCTION_FILES: crossPlatform.INSTRUCTION_FILES
-};
-
-/**
- * Plugin discovery via filesystem convention
- * @see module:discovery
- */
-const discovery = {
-  parseFrontmatter: discoveryModule.parseFrontmatter,
-  discoverPlugins: discoveryModule.discoverPlugins,
-  discoverCommands: discoveryModule.discoverCommands,
-  discoverAgents: discoveryModule.discoverAgents,
-  discoverSkills: discoveryModule.discoverSkills,
-  discoverAll: discoveryModule.discoverAll,
-  getCommandMappings: discoveryModule.getCommandMappings,
-  getCodexSkillMappings: discoveryModule.getCodexSkillMappings,
-  getPluginPrefixRegex: discoveryModule.getPluginPrefixRegex,
-  invalidateCache: discoveryModule.invalidateCache
-};
-
-// Main exports
-module.exports = {
-  platform,
-  patterns,
-  state,
-  utils,
-  config,
-  sources,
-  xplat,
-  enhance,
-  repoMap,
-  perf,
-  collectors,
-  discovery,
-
-  // Direct module access for backward compatibility
-  detectPlatform,
-  verifyTools,
-  reviewPatterns,
-  slopPatterns,
-  pipeline,
-  cliEnhancers,
-  workflowState,
-  contextOptimizer,
-  shellEscape,
-  sourceCache,
-  customHandler,
-  policyQuestions,
-  crossPlatform,
-  discoveryModule
-};