@matimo/core 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matimo/core",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Core SDK for Matimo: Framework-agnostic YAML-driven tool ecosystem for AI agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -65,6 +65,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "axios": "^1.15.2",
     "dotenv": "^17.2.3",
+    "glob": "^10.5.0",
     "js-yaml": "^4.1.1",
     "winston": "^3.19.0",
     "yaml": "^2.8.2",
@@ -102,7 +103,7 @@
     "typescript": "^5.9.3"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.tools.json",
     "watch": "tsc --watch",
     "test": "jest",
     "test:watch": "jest --watch",

package/tools/calculator/calculator.js

@@ -0,0 +1,111 @@
+/**
+ * Calculator Tool - Perform basic arithmetic operations
+ * Pattern: Function-based tool (same as execute)
+ */
+import { MatimoError, ErrorCode, getGlobalMatimoLogger } from '@matimo/core/runtime';
+/**
+ * Normalize operation name to handle variations
+ */
+function normalizeOperation(op) {
+    const normalized = op.toLowerCase().trim();
+    // Map variations to canonical operation names
+    const operationMap = {
+        // Addition variants
+        add: 'add',
+        addition: 'add',
+        sum: 'add',
+        plus: 'add',
+        '+': 'add',
+        // Subtraction variants
+        subtract: 'subtract',
+        subtraction: 'subtract',
+        minus: 'subtract',
+        sub: 'subtract',
+        '-': 'subtract',
+        // Multiplication variants
+        multiply: 'multiply',
+        multiplication: 'multiply',
+        times: 'multiply',
+        product: 'multiply',
+        mul: 'multiply',
+        '*': 'multiply',
+        x: 'multiply',
+        // Division variants
+        divide: 'divide',
+        division: 'divide',
+        div: 'divide',
+        '/': 'divide',
+    };
+    return operationMap[normalized] || normalized;
+}
+/**
+ * Perform arithmetic calculation
+ */
+export default async function calculator(params) {
+    const logger = getGlobalMatimoLogger();
+    const { operation, a, b } = params;
+    logger.debug('Calculator tool invoked', {
+        operation,
+        a,
+        b,
+    });
+    if (typeof a !== 'number' || typeof b !== 'number') {
+        logger.error('Invalid calculator parameters', {
+            a,
+            b,
+            expectedTypes: 'numbers',
+        });
+        throw new MatimoError('Parameters a and b must be numbers', ErrorCode.INVALID_PARAMETER, {
+            a,
+            b,
+        });
+    }
+    const normalizedOp = normalizeOperation(operation);
+    let result;
+    switch (normalizedOp) {
+        case 'add':
+            result = a + b;
+            break;
+        case 'subtract':
+            result = a - b;
+            break;
+        case 'multiply':
+            result = a * b;
+            break;
+        case 'divide':
+            if (b === 0) {
+                logger.error('Division by zero attempted', {
+                    a,
+                    b,
+                });
+                throw new MatimoError('Division by zero', ErrorCode.EXECUTION_FAILED, {
+                    a,
+                    b,
+                });
+            }
+            result = a / b;
+            break;
+        default:
+            logger.error('Unsupported calculator operation', {
+                operation: normalizedOp,
+                requested: operation,
+            });
+            throw new MatimoError('Invalid operation', ErrorCode.INVALID_PARAMETER, {
+                operation,
+                normalizedOperation: normalizedOp,
+                validOperations: ['add', 'addition', 'sum', 'plus', 'subtract', 'subtraction', 'minus', 'multiply', 'multiplication', 'times', 'divide', 'division', 'div'],
+            });
+    }
+    const returnValue = {
+        result,
+        operation: normalizedOp,
+        original_operation: operation,
+        operands: { a, b },
+    };
+    logger.info('Calculator operation completed', {
+        operation: normalizedOp,
+        operands: { a, b },
+        result,
+    });
+    return returnValue;
+}

package/tools/calculator/definition.yaml

@@ -18,7 +18,7 @@ parameters:
 
 execution:
   type: function
-  code: './calculator.ts'
+  code: './calculator.js'
 
 output_schema:
   type: object

package/tools/edit/definition.yaml

@@ -42,7 +42,7 @@ parameters:
 
 execution:
   type: function
-  code: './edit.ts'
+  code: './edit.js'
 
 output_schema:
   type: object

package/tools/edit/edit.js

@@ -0,0 +1,144 @@
+#!/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';
+/**
+ * Edit file with insert/replace/delete/append operations
+ */
+export default async function editTool(params) {
+    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 = {
+        success: false,
+        filePath: resolvedPath,
+        operation,
+        linesAffected: 0,
+        backupCreated: false,
+        newLineCount: 0,
+        duration: 0,
+    };
+    const newLines = [...lines];
+    let backupPath;
+    let previousContent;
+    // 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

@@ -36,7 +36,7 @@ parameters:
 
 execution:
   type: function
-  code: './execute.ts'
+  code: './execute.js'
 
 output_schema:
   type: object

package/tools/execute/execute.js

@@ -0,0 +1,157 @@
+/**
+ * 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, getGlobalMatimoLogger, getGlobalApprovalHandler, } from '@matimo/core/runtime';
+const execAsync = promisify(exec);
+/**
+ * Basic injection detection - checks for common shell metacharacters
+ * that could be used for command injection attacks
+ */
+function detectCommandInjection(command) {
+    // 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;
+}
+/**
+ * Execute a shell command and return structured output
+ * Pattern based on LangChain.js exec/execSync approach
+ */
+export default async function executeCommand(params) {
+    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 ? String(stdout) : '');
+        const stderrStr = typeof stderr === 'string' ? stderr : (stderr ? 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) {
+        const duration = Date.now() - startTime;
+        // Type guard for error object
+        const errorObj = error;
+        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,
+        };
+    }
+}

package/tools/matimo_approve_tool/definition.yaml

@@ -19,7 +19,7 @@ parameters:
 
 execution:
   type: function
-  code: './matimo_approve_tool.ts'
+  code: './matimo_approve_tool.js'
 
 output_schema:
   type: object

package/tools/matimo_approve_tool/matimo_approve_tool.js

@@ -0,0 +1,54 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import { validateToolDefinition, validateToolContent, ApprovalManifest, getGlobalMatimoLogger, } from '@matimo/core';
+export default async function matimoApproveTool(params, context) {
+    const logger = getGlobalMatimoLogger();
+    const toolDir = params.tool_dir || './matimo-tools';
+    // Step 1: Read tool definition
+    const defPath = path.join(toolDir, params.name, 'definition.yaml');
+    if (!fs.existsSync(defPath)) {
+        return { success: false, message: `Tool not found: ${defPath}` };
+    }
+    const yamlContent = fs.readFileSync(defPath, 'utf-8');
+    // Step 2: Parse and validate
+    let tool;
+    try {
+        const parsed = yaml.load(yamlContent);
+        tool = validateToolDefinition(parsed);
+    }
+    catch (err) {
+        return { success: false, message: `Validation failed: ${err.message}` };
+    }
+    // Step 3: Re-run content validator
+    const validation = validateToolContent(tool, { source: 'untrusted' });
+    const criticalOrHigh = validation.violations.filter((v) => v.severity === 'critical' || v.severity === 'high');
+    if (criticalOrHigh.length > 0) {
+        return {
+            success: false,
+            message: 'Tool has policy violations that must be resolved before approval',
+        };
+    }
+    // Step 4: Approve via manifest
+    const approvalDir = path.resolve(toolDir);
+    const manifest = new ApprovalManifest(approvalDir, context?.credentials?.MATIMO_APPROVAL_SECRET);
+    const hash = manifest.computeHash(yamlContent);
+    manifest.approve(params.name, hash);
+    const approval = manifest.getApproval(params.name);
+    // Step 5: Update status in YAML
+    const parsed = yaml.load(yamlContent);
+    parsed.status = 'approved';
+    const updatedYaml = yaml.dump(parsed);
+    fs.writeFileSync(defPath, updatedYaml, 'utf-8');
+    logger.info('matimo_approve_tool: tool approved', {
+        name: params.name,
+        hash,
+    });
+    return {
+        success: true,
+        name: params.name,
+        hash,
+        approvedAt: approval?.approvedAt,
+        message: 'Tool approved. Effective after reload or immediately if auto-reload is active.',
+    };
+}

package/tools/matimo_create_skill/definition.yaml

@@ -33,7 +33,7 @@ parameters:
 
 execution:
   type: function
-  code: './matimo_create_skill.ts'
+  code: './matimo_create_skill.js'
 
 output_schema:
   type: object

package/tools/matimo_create_skill/matimo_create_skill.js

@@ -0,0 +1,48 @@
+import fs from 'fs';
+import path from 'path';
+import { getGlobalMatimoLogger } from '@matimo/core';
+import { validateSkillName, parseSkillContent, validateFrontmatter, } from '../shared/skill-validation.js';
+/**
+ * Create a new skill following the Agent Skills specification.
+ *
+ * Validates the name (lowercase, hyphens, max 64 chars), ensures frontmatter
+ * has required fields (name, description), and enforces that the frontmatter
+ * name matches the directory name.
+ *
+ * @see https://agentskills.io/specification
+ */
+export default async function matimoCreateSkill(params) {
+    const logger = getGlobalMatimoLogger();
+    const targetDir = params.target_dir || './matimo-tools/skills';
+    // Step 1: Validate the skill name against Agent Skills spec
+    const nameResult = validateSkillName(params.name);
+    if (!nameResult.valid) {
+        return { success: false, message: nameResult.error };
+    }
+    // Step 2: Parse and validate frontmatter
+    const parseResult = parseSkillContent(params.content);
+    if (!parseResult.success) {
+        return { success: false, message: parseResult.error };
+    }
+    const { frontmatter } = parseResult.parsed;
+    // Step 3: Validate frontmatter fields + name must match directory
+    const fmResult = validateFrontmatter(frontmatter, params.name);
+    if (!fmResult.valid) {
+        const firstError = fmResult.issues.find(i => i.severity === 'error');
+        return { success: false, message: firstError.message };
+    }
+    // Step 4: Write to disk
+    const skillDirPath = path.resolve(targetDir, params.name);
+    fs.mkdirSync(skillDirPath, { recursive: true });
+    const filePath = path.join(skillDirPath, 'SKILL.md');
+    fs.writeFileSync(filePath, params.content, 'utf-8');
+    logger.info('matimo_create_skill: skill created', {
+        name: params.name,
+        path: filePath,
+    });
+    return {
+        success: true,
+        path: filePath,
+        message: `Skill "${params.name}" created successfully.`,
+    };
+}

package/tools/matimo_create_tool/definition.yaml

@@ -31,7 +31,7 @@ parameters:
 
 execution:
   type: function
-  code: './matimo_create_tool.ts'
+  code: './matimo_create_tool.js'
 
 output_schema:
   type: object