@matimo/core 0.1.0-alpha.10

package/tools/calculator/definition.yaml

@@ -0,0 +1,70 @@
+name: calculator
+version: '1.0.0'
+description: 'Perform basic arithmetic operations'
+
+parameters:
+  operation:
+    type: string
+    description: 'The operation to perform. Accepts: add (addition, sum, plus), subtract (subtraction, minus), multiply (multiplication, times, product), divide (division)'
+    required: true
+  a:
+    type: number
+    description: 'First operand'
+    required: true
+  b:
+    type: number
+    description: 'Second operand'
+    required: true
+
+execution:
+  type: function
+  code: './calculator.ts'
+
+output_schema:
+  type: object
+  properties:
+    result:
+      type: number
+      description: 'Result of the operation'
+    operation:
+      type: string
+    operands:
+      type: object
+      properties:
+        a:
+          type: number
+        b:
+          type: number
+
+error_handling:
+  retry: 2
+  backoff_type: exponential
+  initial_delay_ms: 500
+
+examples:
+  - name: 'Simple addition'
+    description: 'Add 5 and 3'
+    params:
+      operation: 'add'
+      a: 5
+      b: 3
+  - name: 'Addition with variant'
+    description: "Add using 'addition' keyword"
+    params:
+      operation: 'addition'
+      a: 10
+      b: 20
+  - name: 'Subtraction'
+    description: 'Subtract 3 from 10'
+    params:
+      operation: 'subtract'
+      a: 10
+      b: 3
+  - name: 'Multiplication'
+    description: 'Multiply 4 and 7'
+    params:
+      operation: 'multiply'
+      a: 4
+      b: 7
+
+tags: [math, arithmetic, basic]

package/tools/edit/definition.yaml

@@ -0,0 +1,115 @@
+name: edit
+version: '1.0.0'
+description: Edit file contents with precise line-based insertion, replacement, and deletion. Supports undo/backup creation.
+requires_approval: true
+
+parameters:
+  filePath:
+    type: string
+    description: Absolute or relative path to file to edit (supports ~ for home directory)
+    required: true
+    example: './src/config.ts'
+
+  operation:
+    type: string
+    description: 'Edit operation: insert, replace, delete, append'
+    required: true
+    example: 'replace'
+
+  content:
+    type: string
+    description: Content to insert or use for replacement (required for insert/replace/append, forbidden for delete)
+    required: false
+    example: 'const value = 42;'
+
+  startLine:
+    type: number
+    description: Starting line number (1-based). For insert, line to insert before. For replace/delete, starting line.
+    required: true
+    example: 10
+
+  endLine:
+    type: number
+    description: Ending line number (1-based, inclusive) for replace/delete operations. Not used for insert/append.
+    required: false
+    example: 15
+
+  backup:
+    type: boolean
+    description: Create backup file before editing (default true). Backup saved as {filename}.backup
+    required: false
+    default: true
+
+execution:
+  type: function
+  code: './edit.ts'
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+      description: Whether edit operation succeeded
+    filePath:
+      type: string
+      description: Path to the edited file
+    operation:
+      type: string
+      description: Operation that was performed
+    linesAffected:
+      type: number
+      description: Number of lines modified
+    backupCreated:
+      type: boolean
+      description: Whether backup file was created
+    backupPath:
+      type: string
+      description: Path to backup file if created
+    previousContent:
+      type: string
+      description: Content before edit (for delete/replace operations)
+    newLineCount:
+      type: number
+      description: Total line count after edit
+    duration:
+      type: number
+      description: Edit operation duration in milliseconds
+  required: [success, filePath, operation, linesAffected]
+
+error_handling:
+  retry: 0
+  backoff_type: exponential
+  initial_delay_ms: 300
+
+examples:
+  - name: 'Replace lines'
+    description: 'Replace lines 10-12 with new content'
+    params:
+      filePath: './src/config.ts'
+      operation: 'replace'
+      startLine: 10
+      endLine: 12
+      content: 'const newValue = 99;'
+  - name: 'Insert content'
+    description: 'Insert new line before line 5'
+    params:
+      filePath: './src/app.ts'
+      operation: 'insert'
+      startLine: 5
+      content: '// New comment\nconst x = 10;'
+  - name: 'Delete lines'
+    description: 'Delete lines 20-25'
+    params:
+      filePath: './src/app.ts'
+      operation: 'delete'
+      startLine: 20
+      endLine: 25
+  - name: 'Append to file'
+    description: 'Add content at end of file'
+    params:
+      filePath: './data/log.txt'
+      operation: 'append'
+      startLine: 1
+      content: 'New log entry'
+
+tags: [file-io, edit, write, filesystem, text-manipulation]

package/tools/edit/edit.ts

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * Edit Tool - Edit files with insert/replace/delete/append operations
+ * Function-type tool: Exports default async function
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { MatimoError, ErrorCode } from '@matimo/core';
+
+interface EditParams {
+  filePath: string;
+  operation: string;
+  content?: string;
+  startLine: number;
+  endLine?: number;
+  backup?: boolean;
+}
+
+interface EditResult {
+  success: boolean;
+  filePath: string;
+  operation: string;
+  linesAffected: number;
+  backupCreated: boolean;
+  backupPath?: string;
+  previousContent?: string;
+  newLineCount: number;
+  duration: number;
+}
+
+/**
+ * Edit file with insert/replace/delete/append operations
+ */
+export default async function editTool(params: EditParams): Promise<EditResult> {
+  const { filePath, operation, content = '', startLine, endLine, backup = true } = params;
+  const startTime = Date.now();
+
+  // Validate required parameters
+  if (!filePath) {
+    throw new MatimoError('Missing required parameter', ErrorCode.INVALID_PARAMETER, {
+      reason: 'filePath is required',
+    });
+  }
+
+  if (!operation) {
+    throw new MatimoError('Missing required parameter', ErrorCode.INVALID_PARAMETER, {
+      reason: 'operation is required',
+    });
+  }
+
+  if (startLine === undefined) {
+    throw new MatimoError('Missing required parameter', ErrorCode.INVALID_PARAMETER, {
+      reason: 'startLine is required',
+    });
+  }
+
+  // Resolve path
+  const resolvedPath = filePath.startsWith('~')
+    ? path.join(process.env.HOME || '/', filePath.slice(1))
+    : path.isAbsolute(filePath)
+    ? filePath
+    : path.resolve(process.cwd(), filePath);
+
+  // Validate file exists
+  if (!fs.existsSync(resolvedPath)) {
+    throw new MatimoError('File not found', ErrorCode.FILE_NOT_FOUND, {
+      filePath: resolvedPath,
+    });
+  }
+
+  // Approval is handled by MatimoInstance based on 'requires_approval' in YAML
+
+  // Read original content
+  const originalContent = fs.readFileSync(resolvedPath, 'utf8');
+  const lines = originalContent.split('\n');
+
+  const result: EditResult = {
+    success: false,
+    filePath: resolvedPath,
+    operation,
+    linesAffected: 0,
+    backupCreated: false,
+    newLineCount: 0,
+    duration: 0,
+  };
+
+  const newLines: string[] = [...lines];
+  let backupPath: string | undefined;
+  let previousContent: string | undefined;
+
+  // Create backup if requested
+  if (backup) {
+    backupPath = `${resolvedPath}.backup`;
+    fs.writeFileSync(backupPath, originalContent, 'utf8');
+    result.backupCreated = true;
+    result.backupPath = backupPath;
+  }
+
+  // Validate line numbers (1-based)
+  if (startLine < 1) {
+    throw new MatimoError('Invalid line number', ErrorCode.INVALID_PARAMETER, {
+      startLine,
+      reason: 'startLine must be >= 1',
+    });
+  }
+
+  // Convert to 0-based indexing
+  const startIdx = startLine - 1;
+  const endIdx = endLine ? endLine - 1 : startIdx;
+
+  switch (operation) {
+    case 'insert': {
+      // Insert before startLine
+      if (startIdx > newLines.length) {
+        throw new MatimoError('Invalid line range', ErrorCode.INVALID_PARAMETER, {
+          startLine,
+          reason: `startLine ${startLine} is beyond file length ${newLines.length}`,
+        });
+      }
+      const contentLines = content.split('\n');
+      newLines.splice(startIdx, 0, ...contentLines);
+      result.linesAffected = contentLines.length;
+      break;
+    }
+
+    case 'replace': {
+      // Replace lines from startLine to endLine
+      if (startIdx >= newLines.length || endIdx >= newLines.length) {
+        throw new MatimoError('Invalid line range', ErrorCode.INVALID_PARAMETER, {
+          startLine,
+          endLine,
+          fileLineCount: newLines.length,
+          reason: `Line range ${startLine}-${endLine} out of bounds`,
+        });
+      }
+      previousContent = newLines.slice(startIdx, endIdx + 1).join('\n');
+      const contentLines = content.split('\n');
+      newLines.splice(startIdx, endIdx - startIdx + 1, ...contentLines);
+      result.linesAffected = endIdx - startIdx + 1;
+      result.previousContent = previousContent;
+      break;
+    }
+
+    case 'delete': {
+      // Delete lines from startLine to endLine
+      if (startIdx >= newLines.length || endIdx >= newLines.length) {
+        throw new MatimoError('Invalid line range', ErrorCode.INVALID_PARAMETER, {
+          startLine,
+          endLine,
+          fileLineCount: newLines.length,
+          reason: `Line range ${startLine}-${endLine} out of bounds`,
+        });
+      }
+      previousContent = newLines.slice(startIdx, endIdx + 1).join('\n');
+      newLines.splice(startIdx, endIdx - startIdx + 1);
+      result.linesAffected = endIdx - startIdx + 1;
+      result.previousContent = previousContent;
+      break;
+    }
+
+    case 'append': {
+      // Append to end of file
+      const contentLines = content.split('\n');
+      newLines.push(...contentLines);
+      result.linesAffected = contentLines.length;
+      break;
+    }
+
+    default: {
+      throw new MatimoError('Unknown operation', ErrorCode.INVALID_PARAMETER, {
+        operation,
+        supportedOperations: ['insert', 'replace', 'delete', 'append'],
+      });
+    }
+  }
+
+  // Write new content
+  const newContent = newLines.join('\n');
+  fs.writeFileSync(resolvedPath, newContent, 'utf8');
+
+  result.success = true;
+  result.newLineCount = newLines.length;
+  result.duration = Date.now() - startTime;
+
+  return result;
+}

package/tools/execute/definition.yaml

@@ -0,0 +1,90 @@
+name: execute
+version: '1.0.0'
+description: Execute shell commands and capture output. Supports command execution with arguments and streaming output capture.
+requires_approval: true
+
+parameters:
+  command:
+    type: string
+    description: Shell command to execute (e.g., 'npm test', 'git status', 'ls -la')
+    required: true
+    example: 'npm test'
+
+  args:
+    type: array
+    description: Command arguments as array of strings (optional, can also embed in command)
+    required: false
+    example: ['--verbose', '--color']
+
+  cwd:
+    type: string
+    description: Working directory context for command execution (relative or absolute path)
+    required: false
+    example: '/project/src'
+
+  timeout:
+    type: number
+    description: Maximum execution time in milliseconds (default 30000)
+    required: false
+    example: 60000
+
+  shell:
+    type: string
+    description: Shell to use (e.g. '/bin/bash', '/bin/zsh'). Defaults to system shell.
+    required: false
+    example: '/bin/bash'
+
+execution:
+  type: function
+  code: './execute.ts'
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+      description: Whether command executed successfully (exit code 0)
+    exitCode:
+      type: number
+      description: Command exit code
+    stdout:
+      type: string
+      description: Standard output from command execution
+    stderr:
+      type: string
+      description: Standard error from command execution
+    command:
+      type: string
+      description: Command that was executed
+    duration:
+      type: number
+      description: Execution duration in milliseconds
+  required: [success, exitCode, stdout, stderr, duration]
+
+error_handling:
+  retry: 1
+  backoff_type: exponential
+  initial_delay_ms: 500
+
+examples:
+  - name: 'Run npm test'
+    description: 'Execute npm test in current directory'
+    params:
+      command: 'npm test'
+  - name: 'List files with details'
+    description: 'List directory contents'
+    params:
+      command: 'ls'
+      args: ['-la', '/Users']
+  - name: 'Git status'
+    description: 'Check git repository status'
+    params:
+      command: 'git status'
+      cwd: '/project'
+  - name: 'Long running command with timeout'
+    description: 'Execute with custom timeout'
+    params:
+      command: 'sleep 5'
+      timeout: 10000
+
+tags: [shell, command, system, execution, process]

package/tools/execute/execute.ts

@@ -0,0 +1,207 @@
+/**
+ * Execute Tool - Execute shell commands with full output capture
+ * LangChain-style: uses exec() directly from same process
+ * Cross-platform: Windows (cmd.exe), Unix/Linux/Mac (sh/bash)
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { MatimoError, ErrorCode } from '../../src/errors/matimo-error';
+import { getGlobalMatimoLogger } from '../../src/logging/logger';
+import { getGlobalApprovalHandler } from '../../src/approval/approval-handler';
+
+const execAsync = promisify(exec);
+
+/**
+ * Basic injection detection - checks for common shell metacharacters
+ * that could be used for command injection attacks
+ */
+function detectCommandInjection(command: string): boolean {
+  // Common injection patterns: command chaining, redirection, substitution
+  // Note: $\w+ pattern is handled separately below
+  const dangerousPatterns = [
+    /;/,      // Command separator
+    /\|/,     // Pipe
+    /&/,      // Background/AND
+    /`/,      // Command substitution (backticks)
+    /\$\(/,   // Command substitution ($(command))
+    /</,      // Input redirection
+    />/,      // Output redirection
+    /\$\{/,   // Variable expansion ${VAR}
+  ];
+
+  // Allow some safe variable expansions like $HOME, $PATH, but flag suspicious ones
+  const safeVars = /^\$(HOME|PATH|USER|PWD|SHELL|LANG|TERM)$/i;
+
+  // Check for dangerous patterns first
+  for (const pattern of dangerousPatterns) {
+    if (pattern.test(command)) {
+      return true;
+    }
+  }
+
+  // Special handling for environment variables: allow safe ones, flag suspicious ones
+  const variablePattern = /\$\w+/g;
+  const variables = command.match(variablePattern);
+  if (variables) {
+    for (const variable of variables) {
+      if (!safeVars.test(variable)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+interface ExecuteParams {
+  command: string;
+  cwd?: string;
+  timeout?: number;
+}
+
+interface ExecuteResult {
+  success: boolean;
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  command: string;
+  duration: number;
+}
+
+/**
+ * Execute a shell command and return structured output
+ * Pattern based on LangChain.js exec/execSync approach
+ */
+export default async function executeCommand(
+  params: ExecuteParams
+): Promise<ExecuteResult> {
+  const logger = getGlobalMatimoLogger();
+  const { command, cwd, timeout = 30000 } = params;
+  const startTime = Date.now();
+
+  logger.debug('Execute tool: Command received', {
+    command: command.substring(0, 100),
+    cwd,
+    timeout,
+  });
+
+  if (!command || command.trim().length === 0) {
+    logger.error('Execute tool: Empty command provided', {
+      reason: 'No command provided',
+    });
+    throw new MatimoError('Command required', ErrorCode.INVALID_PARAMETER, {
+      reason: 'No command provided',
+    });
+  }
+
+  // Check for potential command injection
+  if (detectCommandInjection(command)) {
+    logger.warn('Execute tool: Command injection detected', {
+      command: command.substring(0, 100),
+      reason: 'Contains potentially dangerous shell metacharacters',
+    });
+    throw new MatimoError('Command injection detected', ErrorCode.INVALID_PARAMETER, {
+      reason: 'Command contains potentially dangerous shell metacharacters',
+      command: command,
+    });
+  }
+
+  // Check if command appears to be destructive and request approval if needed
+  // ApprovalHandler checks against centralized destructive keywords from YAML
+  const approvalHandler = getGlobalApprovalHandler();
+  
+  if (approvalHandler.requiresApproval(false, command)) {
+    logger.info('Execute tool: Destructive command detected - requesting approval', {
+      command: command.substring(0, 100),
+    });
+
+    // Request user approval before executing destructive command
+    if (!approvalHandler.isPreApproved('execute')) {
+      await approvalHandler.requestApproval({
+        toolName: 'execute',
+        description: `Execute shell command: ${command.substring(0, 100)}${command.length > 100 ? '...' : ''}`,
+        params: { command, cwd },
+      });
+    }
+  }
+
+  try {
+    // SECURITY WARNING: This tool executes arbitrary shell commands directly.
+    // The 'command' parameter is passed to exec() without sanitization, creating
+    // a command injection vulnerability if user input is not properly validated.
+    // Basic injection detection is performed above, but this is NOT foolproof.
+    // Only use with trusted input or implement additional validation layers.
+    // exec() auto-selects shell: cmd.exe on Windows, /bin/sh on Unix
+    const { stdout, stderr } = await execAsync(command, {
+      cwd,
+      timeout,
+      maxBuffer: 10 * 1024 * 1024, // 10MB buffer for large outputs
+    });
+
+    const duration = Date.now() - startTime;
+
+    // Convert Buffer to string if needed
+    const stdoutStr = typeof stdout === 'string' ? stdout : (stdout as unknown ? String(stdout) : '');
+    const stderrStr = typeof stderr === 'string' ? stderr : (stderr as unknown ? String(stderr) : '');
+
+    logger.info('Execute tool: Command completed successfully', {
+      command: command.substring(0, 100),
+      duration,
+      stdoutLength: stdoutStr.length,
+      stderrLength: stderrStr.length,
+    });
+
+    return {
+      success: true,
+      exitCode: 0,
+      stdout: stdoutStr.trim(),
+      stderr: stderrStr.trim(),
+      command,
+      duration,
+    };
+  } catch (error: unknown) {
+    const duration = Date.now() - startTime;
+    
+    // Type guard for error object
+    const errorObj = error as Record<string, unknown> & { 
+      killed?: boolean;
+      signal?: string;
+      code?: number;
+      stdout?: string;
+      stderr?: string;
+      message?: string;
+    };
+    
+    const isTimeout = errorObj.killed || errorObj.signal === 'SIGTERM';
+
+    // If it's already a MatimoError, re-throw it
+    if (error instanceof MatimoError) {
+      throw error;
+    }
+
+    // Convert Buffer to string if needed
+    const stdoutStr = typeof errorObj.stdout === 'string' ? errorObj.stdout : (errorObj.stdout ? String(errorObj.stdout) : '');
+    const stderrStr = typeof errorObj.stderr === 'string' ? errorObj.stderr : (errorObj.stderr ? String(errorObj.stderr) : '');
+
+    logger.warn('Execute tool: Command execution failed', {
+      command: command.substring(0, 100),
+      duration,
+      exitCode: isTimeout ? -1 : (errorObj.code || 1),
+      isTimeout,
+      errorMessage: errorObj.message ? errorObj.message.substring(0, 100) : 'Unknown error',
+      stderrLength: stderrStr.length,
+    });
+
+    // For command execution failures, return structured result (not throw)
+    // This allows the agent to see what went wrong
+    return {
+      success: false,
+      exitCode: isTimeout ? -1 : (errorObj.code || 1),
+      stdout: stdoutStr.trim(),
+      stderr: stderrStr.trim(),
+      command,
+      duration,
+    };
+  }
+}