@matimo/core 0.1.0-alpha.10

package/dist/matimo-instance.js

@@ -0,0 +1,412 @@
+import path from 'path';
+import { ToolLoader } from './core/tool-loader';
+import { ToolRegistry } from './core/tool-registry';
+import { CommandExecutor } from './executors/command-executor';
+import { HttpExecutor } from './executors/http-executor';
+import { FunctionExecutor } from './executors/function-executor';
+import { MatimoError, ErrorCode } from './errors/matimo-error';
+import { getLoggerConfig, createLogger, setGlobalMatimoLogger, } from './logging';
+import { getGlobalApprovalHandler } from './approval/approval-handler';
+/**
+ * Matimo Instance - Single initialization point for tool execution
+ * Combines loader, registry, and executors into one interface
+ */
+export class MatimoInstance {
+    constructor(toolPaths, logger) {
+        this.toolPaths = toolPaths;
+        this.logger = logger;
+        this.loader = new ToolLoader();
+        this.registry = new ToolRegistry();
+        // Use the first path (primary) as working directory for command executor
+        const workingDir = toolPaths.length > 0 ? path.dirname(toolPaths[0]) : process.cwd();
+        this.commandExecutor = new CommandExecutor(workingDir);
+        this.httpExecutor = new HttpExecutor();
+        this.functionExecutor = new FunctionExecutor(toolPaths[0] || '');
+        this.approvalHandler = getGlobalApprovalHandler();
+    }
+    /**
+     * Initialize Matimo with tools from directory or auto-discovery
+     * @param options - Initialization options (string for backward compatibility)
+     * @returns MatimoInstance ready to execute tools
+     *
+     * @example
+     * // Backward compatible - single path
+     * const matimo = await MatimoInstance.init('./tools');
+     *
+     * // New - auto-discovery
+     * const matimo = await MatimoInstance.init({ autoDiscover: true });
+     *
+     * // Explicit paths with logging config
+     * const matimo = await MatimoInstance.init({
+     *   toolPaths: ['./tools'],
+     *   logLevel: 'debug',
+     *   logFormat: 'json'
+     * });
+     *
+     * // Custom logger
+     * const matimo = await MatimoInstance.init({
+     *   toolPaths: ['./tools'],
+     *   logger: myCustomLogger
+     * });
+     */
+    static async init(options) {
+        let finalOptions;
+        // Backward compatibility: if string is passed, treat as toolPath
+        if (typeof options === 'string') {
+            finalOptions = {
+                toolPaths: [options],
+                autoDiscover: false,
+                includeCore: false,
+            };
+        }
+        else {
+            finalOptions = {
+                autoDiscover: false,
+                includeCore: true,
+                ...options,
+            };
+        }
+        // Initialize logger from config and environment variables
+        const loggerConfig = getLoggerConfig({
+            logLevel: finalOptions.logLevel,
+            logFormat: finalOptions.logFormat,
+            logger: finalOptions.logger,
+        });
+        const logger = createLogger(loggerConfig);
+        // Set global logger for use by modules
+        setGlobalMatimoLogger(logger);
+        logger.debug('Matimo SDK initializing', {
+            logLevel: loggerConfig.logLevel,
+            logFormat: loggerConfig.logFormat,
+            hasPaths: !!finalOptions.toolPaths?.length,
+            autoDiscover: finalOptions.autoDiscover,
+        });
+        const toolPaths = [];
+        // Include core tools (calculator, etc.) - currently not used in monorepo
+        // Use explicit toolPaths or autoDiscover instead
+        // if (finalOptions.includeCore) { ... }
+        // Add explicit paths
+        if (finalOptions.toolPaths) {
+            toolPaths.push(...finalOptions.toolPaths);
+            logger.debug(`Adding explicit tool paths`, { count: finalOptions.toolPaths.length });
+        }
+        // Auto-discover @matimo/* packages
+        if (finalOptions.autoDiscover) {
+            const discoveredPaths = new ToolLoader().autoDiscoverPackages();
+            toolPaths.push(...discoveredPaths);
+            logger.debug(`Auto-discovered tool paths`, { count: discoveredPaths.length });
+        }
+        const instance = new MatimoInstance(toolPaths, logger);
+        // Load tools from all paths
+        const allTools = instance.loader.loadToolsFromMultiplePaths(toolPaths);
+        instance.registry.registerAll(Array.from(allTools.values()));
+        logger.info(`Matimo SDK initialized successfully`, {
+            toolCount: allTools.size,
+            paths: toolPaths.length,
+        });
+        return instance;
+    }
+    /**
+     * Get tool paths
+     * @returns Array of tool paths
+     */
+    getToolPaths() {
+        return [...this.toolPaths];
+    }
+    /**
+     * Get the logger instance
+     * @returns MatimoLogger instance
+     */
+    getLogger() {
+        return this.logger;
+    }
+    /**
+     * Execute a tool by name with parameters
+     * @param toolName - Name of the tool to execute
+     * @param params - Tool parameters
+     * @returns Tool execution result
+     */
+    async execute(toolName, params) {
+        const tool = this.registry.get(toolName);
+        if (!tool) {
+            const availableTools = this.registry.getAll().map((t) => t.name);
+            this.logger.error(`Tool not found: ${toolName}`, {
+                toolName,
+                availableTools,
+            });
+            throw new MatimoError(`Tool '${toolName}' not found in registry`, ErrorCode.TOOL_NOT_FOUND, {
+                toolName,
+                availableTools,
+            });
+        }
+        this.logger.debug(`Executing tool: ${toolName}`, {
+            toolName,
+            paramCount: Object.keys(params).length,
+        });
+        try {
+            // Simple approval flow:
+            // 1. Check if tool requires approval (from YAML or keyword detection)
+            // 2. Check if pre-approved via env vars
+            // 3. Call approval callback if not pre-approved
+            // Prefer execution-type-specific checks to reduce false positives.
+            // - `command` tools: scan `params.command`
+            // - SQL tools (convention): scan `params.sql`
+            // If configured via `MATIMO_APPROVAL_SCAN_ALL_PARAMS=true`, fall back
+            // to scanning all string-valued params.
+            const executionType = (tool.execution.type || '');
+            let scanContent;
+            if (executionType === 'command' && typeof params.command === 'string') {
+                scanContent = params.command;
+            }
+            else if (typeof params.sql === 'string') {
+                scanContent = params.sql;
+            }
+            else if (process.env.MATIMO_APPROVAL_SCAN_ALL_PARAMS === 'true') {
+                const parts = [];
+                for (const val of Object.values(params)) {
+                    if (typeof val === 'string')
+                        parts.push(val);
+                }
+                if (parts.length > 0)
+                    scanContent = parts.join(' ');
+            }
+            const requiresApproval = this.approvalHandler.requiresApproval(tool.requires_approval, scanContent);
+            if (requiresApproval && !this.approvalHandler.isPreApproved(toolName)) {
+                this.logger.debug(`Approval required for: ${toolName}`, { toolName });
+                await this.approvalHandler.requestApproval({
+                    toolName,
+                    description: tool.description,
+                    params,
+                });
+                this.logger.info(`Destructive operation approved: ${toolName}`, { toolName });
+            }
+            // Auto-inject authentication parameters from environment variables
+            const finalParams = this.injectAuthParameters(tool, params);
+            const executor = this.getExecutor(tool);
+            const result = await executor.execute(tool, finalParams);
+            this.logger.debug(`Tool executed successfully: ${toolName}`, {
+                toolName,
+                hasResult: !!result,
+            });
+            return result;
+        }
+        catch (error) {
+            this.logger.error(`Tool execution failed: ${toolName}`, {
+                toolName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    }
+    /**
+     * Get a tool definition by name
+     * @param toolName - Name of the tool
+     * @returns Tool definition or undefined
+     */
+    getTool(toolName) {
+        return this.registry.get(toolName);
+    }
+    /**
+     * List all available tools
+     * @returns Array of tool definitions
+     */
+    listTools() {
+        return this.registry.getAll();
+    }
+    /**
+     * Get all available tools (alias for listTools)
+     * @returns Array of tool definitions
+     */
+    getAllTools() {
+        return this.registry.getAll();
+    }
+    /**
+     * Search tools by name or description
+     * @param query - Search query
+     * @returns Matching tools
+     */
+    searchTools(query) {
+        return this.registry.search(query);
+    }
+    /**
+     * Get tools by tag
+     * @param tag - Tag to search for
+     * @returns Tools with the given tag
+     */
+    getToolsByTag(tag) {
+        return this.registry.getByTag(tag);
+    }
+    /**
+     * Automatically inject parameters from environment variables
+     * Uses a YAML-native, scale-friendly approach:
+     *
+     * 1. Scans the execution config for all parameter placeholders
+     * 2. For each parameter not provided by user, checks if it looks like auth (TOKEN, KEY, SECRET, etc.)
+     * 3. If yes, attempts to load from environment: MATIMO_<PARAM_NAME> or <PARAM_NAME>
+     *
+     * This works for ANY tool with ANY auth parameter name - no hardcoding needed.
+     * Scales to unlimited tools - contributors just submit YAML.
+     *
+     * Examples:
+     * - GMAIL_ACCESS_TOKEN → looks in env vars
+     * - GITHUB_TOKEN → looks in env vars
+     * - SLACK_BOT_TOKEN → looks in env vars
+     * - MY_CUSTOM_API_KEY → looks in env vars
+     * - ANY_SECRET → looks in env vars
+     */
+    injectAuthParameters(tool, params) {
+        const result = { ...params };
+        // Collect all parameter names referenced in the execution config
+        const referencedParams = this.extractParameterPlaceholders(tool);
+        // Auth-related parameter name patterns (case-insensitive)
+        const authPatterns = [
+            'token',
+            'key',
+            'secret',
+            'password',
+            'credential',
+            'auth',
+            'bearer',
+            'api_key',
+        ];
+        // Check each referenced parameter
+        for (const paramName of referencedParams) {
+            // Skip if user already provided it
+            if (paramName in result) {
+                continue;
+            }
+            // Check if parameter name looks like auth
+            const lowerName = paramName.toLowerCase();
+            const isAuthParam = authPatterns.some((pattern) => lowerName.includes(pattern));
+            if (isAuthParam) {
+                // Try to load from environment
+                // First try MATIMO_ prefixed version for organization
+                let envValue = process.env[`MATIMO_${paramName}`];
+                // If not found, try the parameter name directly
+                if (!envValue) {
+                    envValue = process.env[paramName];
+                }
+                // If found, inject it
+                if (envValue) {
+                    result[paramName] = envValue;
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Extract all parameter placeholders from execution config
+     * Scans headers, body, URL, and query_params for {paramName} patterns
+     */
+    extractParameterPlaceholders(tool) {
+        const params = new Set();
+        const placeholderRegex = /\{([^}]+)\}/g;
+        const execution = tool.execution;
+        // Scan URL
+        if ('url' in execution && execution.url) {
+            let match;
+            while ((match = placeholderRegex.exec(execution.url)) !== null) {
+                params.add(match[1]);
+            }
+        }
+        // Scan headers
+        if ('headers' in execution && execution.headers && typeof execution.headers === 'object') {
+            for (const value of Object.values(execution.headers)) {
+                if (typeof value === 'string') {
+                    let match;
+                    while ((match = placeholderRegex.exec(value)) !== null) {
+                        params.add(match[1]);
+                    }
+                }
+            }
+        }
+        // Scan body (recursively for nested objects)
+        if ('body' in execution && execution.body) {
+            this.scanObjectForParams(execution.body, params);
+        }
+        // Scan query_params
+        if ('query_params' in execution &&
+            execution.query_params &&
+            typeof execution.query_params === 'object') {
+            for (const value of Object.values(execution.query_params)) {
+                if (typeof value === 'string') {
+                    let match;
+                    while ((match = placeholderRegex.exec(value)) !== null) {
+                        params.add(match[1]);
+                    }
+                }
+            }
+        }
+        return params;
+    }
+    /**
+     * Recursively scan object for parameter placeholders
+     */
+    scanObjectForParams(obj, params, visited = new WeakSet()) {
+        if (!obj || typeof obj !== 'object') {
+            return;
+        }
+        // Prevent infinite loops
+        if (visited.has(obj)) {
+            return;
+        }
+        visited.add(obj);
+        const placeholderRegex = /\{([^}]+)\}/g;
+        if (Array.isArray(obj)) {
+            for (const item of obj) {
+                if (typeof item === 'string') {
+                    let match;
+                    while ((match = placeholderRegex.exec(item)) !== null) {
+                        params.add(match[1]);
+                    }
+                }
+                else if (item && typeof item === 'object') {
+                    this.scanObjectForParams(item, params, visited);
+                }
+            }
+        }
+        else {
+            for (const value of Object.values(obj)) {
+                if (typeof value === 'string') {
+                    let match;
+                    while ((match = placeholderRegex.exec(value)) !== null) {
+                        params.add(match[1]);
+                    }
+                }
+                else if (value && typeof value === 'object') {
+                    this.scanObjectForParams(value, params, visited);
+                }
+            }
+        }
+    }
+    /**
+     * Get the appropriate executor for a tool
+     */
+    getExecutor(tool) {
+        const executionType = tool.execution.type;
+        switch (executionType) {
+            case 'command':
+                return this.commandExecutor;
+            case 'http':
+                return this.httpExecutor;
+            case 'function':
+                return this.functionExecutor;
+            default:
+                throw new MatimoError(`Unsupported execution type: ${executionType}`, ErrorCode.EXECUTION_FAILED, { executionType });
+        }
+    }
+}
+/**
+ * Matimo namespace - Entry point for the SDK
+ */
+export const matimo = {
+    /**
+     * Initialize Matimo with a tools directory
+     * @param toolsPath - Path to tools directory
+     * @returns MatimoInstance ready to use
+     */
+    async init(toolsPath) {
+        return MatimoInstance.init(toolsPath);
+    },
+};
+//# sourceMappingURL=matimo-instance.js.map

package/dist/matimo-instance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"matimo-instance.js","sourceRoot":"","sources":["../src/matimo-instance.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@matimo/core",
+  "version": "0.1.0-alpha.10",
+  "description": "Core SDK for Matimo: Framework-agnostic YAML-driven tool ecosystem for AI agents.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "packageManager": "pnpm@8.15.0",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "pnpm": ">=8.0.0"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "tools",
+    "mcp",
+    "llm",
+    "claude",
+    "langchain",
+    "crewai",
+    "ai-agent",
+    "langchain-tools",
+    "claude-tools",
+    "framework-agnostic",
+    "yaml-tools",
+    "agent-toolkit",
+    "typescript-ai"
+  ],
+  "author": "Sajesh Nair <vsajeshnair@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tallclub/matimo.git"
+  },
+  "homepage": "https://github.com/tallclub/matimo#readme",
+  "bugs": {
+    "url": "https://github.com/tallclub/matimo/issues"
+  },
+  "files": [
+    "dist",
+    "tools",
+    "destructive-keywords.yaml",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "axios": "^1.13.4",
+    "dotenv": "^17.2.3",
+    "js-yaml": "^4.1.1",
+    "winston": "^3.19.0",
+    "yaml": "^2.8.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.3.1",
+    "@commitlint/config-conventional": "^20.3.1",
+    "@langchain/core": "^1.1.19",
+    "@types/jest": "^30.0.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.1.0",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "eslint": "^9.39.2",
+    "husky": "^9.1.7",
+    "jest": "^30.2.0",
+    "langchain": "^1.2.18",
+    "prettier": "^3.8.1",
+    "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src test --ext .ts",
+    "lint:fix": "eslint src test --ext .ts --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\" \"*.json\" \"*.md\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\"",
+    "dev": "tsx src/index.ts"
+  }
+}

package/tools/calculator/calculator.ts

@@ -0,0 +1,145 @@
+/**
+ * Calculator Tool - Perform basic arithmetic operations
+ * Pattern: Function-based tool (same as execute)
+ */
+
+import { MatimoError, ErrorCode } from '../../src/errors/matimo-error';
+import { getGlobalMatimoLogger } from '../../src/logging/logger';
+
+interface CalculatorParams {
+  operation: string;
+  a: number;
+  b: number;
+}
+
+interface CalculatorResult {
+  result: number;
+  operation: string;
+  original_operation: string;
+  operands: {
+    a: number;
+    b: number;
+  };
+}
+
+/**
+ * Normalize operation name to handle variations
+ */
+function normalizeOperation(op: string): string {
+  const normalized = op.toLowerCase().trim();
+
+  // Map variations to canonical operation names
+  const operationMap: Record<string, string> = {
+    // 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: CalculatorParams
+): Promise<CalculatorResult> {
+  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: number;
+
+  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;
+}