@matimo/core 0.1.0-alpha.10

package/dist/core/tool-loader.js

@@ -0,0 +1,250 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as YAML from 'js-yaml';
+import { validateToolDefinition } from './schema';
+import { MatimoError, ErrorCode } from '../errors/matimo-error';
+/**
+ * Tool Loader - Loads and validates YAML/JSON tool definitions
+ * Implements TDD pattern: test failures guide implementation
+ * Features caching for efficient discovery with thousands of tools
+ */
+export class ToolLoader {
+    /**
+     * Discover packages using only fs and path (no createRequire needed)
+     * Searches for tools in node_modules/@matimo/* and workspace packages
+     */
+    getNodeModulesPath() {
+        try {
+            // Start from current working directory and search upwards
+            let currentPath = process.cwd();
+            for (let i = 0; i < 15; i++) {
+                const nodeModules = path.join(currentPath, 'node_modules');
+                if (fs.existsSync(nodeModules)) {
+                    // Verify @matimo scope exists
+                    const matimoScope = path.join(nodeModules, '@matimo');
+                    if (fs.existsSync(matimoScope)) {
+                        return nodeModules;
+                    }
+                }
+                currentPath = path.dirname(currentPath);
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Load a single tool from a YAML or JSON file
+     * @param filePath - Path to tool definition file
+     * @returns Validated tool definition
+     * @throws {Error} If file not found or invalid schema
+     */
+    loadToolFromFile(filePath) {
+        // Read file
+        if (!fs.existsSync(filePath)) {
+            throw new MatimoError(`Tool file not found: ${filePath}`, ErrorCode.FILE_NOT_FOUND, {
+                filePath,
+            });
+        }
+        const content = fs.readFileSync(filePath, 'utf-8');
+        // Parse based on file extension
+        let parsed;
+        const ext = path.extname(filePath).toLowerCase();
+        if (ext === '.yaml' || ext === '.yml') {
+            parsed = YAML.load(content);
+        }
+        else if (ext === '.json') {
+            parsed = JSON.parse(content);
+        }
+        else {
+            throw new MatimoError(`Unsupported file format: ${ext}. Use .yaml or .json`, ErrorCode.INVALID_SCHEMA, {
+                filePath,
+                fileExtension: ext,
+            });
+        }
+        // Validate against schema
+        try {
+            const tool = validateToolDefinition(parsed);
+            // Store the definition file path for relative path resolution in executors
+            tool._definitionPath = path.resolve(filePath);
+            return tool;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new MatimoError(`Invalid tool definition in ${filePath}:\n${message}`, ErrorCode.INVALID_SCHEMA, {
+                filePath,
+                originalError: message,
+            });
+        }
+    }
+    /**
+     * Load all tools from a directory
+     * @param dirPath - Path to directory containing tool files
+     * @returns Map of tool names to definitions
+     * @note Prefers definition.yaml/definition.json over tool.yaml/tool.json
+     */
+    loadToolsFromDirectory(dirPath) {
+        const tools = new Map();
+        if (!fs.existsSync(dirPath)) {
+            throw new MatimoError(`Tools directory not found: ${dirPath}`, ErrorCode.FILE_NOT_FOUND, {
+                directoryPath: dirPath,
+            });
+        }
+        // Recursively find all definition files (definition.yaml/definition.json preferred)
+        // Also finds tool.yaml/tool.json for backwards compatibility
+        const findToolFiles = (dir) => {
+            const files = [];
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    files.push(...findToolFiles(fullPath));
+                }
+                else if (entry.isFile() &&
+                    (/^definition\.(yaml|yml|json)$/.test(entry.name) ||
+                        /^tool\.(yaml|yml|json)$/.test(entry.name))) {
+                    files.push(fullPath);
+                }
+            }
+            return files;
+        };
+        const toolFiles = findToolFiles(dirPath);
+        for (const file of toolFiles) {
+            try {
+                const tool = this.loadToolFromFile(file);
+                // Don't add if we already have this tool (definition.yaml takes precedence)
+                if (!tools.has(tool.name)) {
+                    tools.set(tool.name, tool);
+                }
+            }
+            catch {
+                // Skip files that fail validation - they may not be tool definitions
+                // (e.g., provider definitions are in tools/ directory but are not tools)
+            }
+        }
+        return tools;
+    }
+    /**
+     * Load a tool from a JSON object
+     * @param data - Tool definition as object
+     * @returns Validated tool definition
+     */
+    loadToolFromObject(data) {
+        return validateToolDefinition(data);
+    }
+    /**
+     * Auto-discover tool packages in node_modules/@matimo/* and core tools
+     * Features efficient caching: first call discovers, subsequent calls return cached result
+     * @returns Array of paths to tool directories
+     */
+    autoDiscoverPackages() {
+        // Return cached paths if already discovered (O(1) lookup)
+        if (ToolLoader.discoveredPathsCache !== null) {
+            return ToolLoader.discoveredPathsCache;
+        }
+        const discoveredPaths = [];
+        // 1. Discover core tools from workspace (packages/core/tools) or @matimo/core in node_modules
+        try {
+            // Try node_modules first (@matimo/core)
+            const nodeModulesPath = this.getNodeModulesPath();
+            if (nodeModulesPath) {
+                const coreToolsPath = path.join(nodeModulesPath, '@matimo', 'core', 'tools');
+                if (fs.existsSync(coreToolsPath)) {
+                    discoveredPaths.push(coreToolsPath);
+                }
+            }
+            // If not found in node_modules, try workspace
+            if (discoveredPaths.length === 0) {
+                let currentPath = process.cwd();
+                for (let i = 0; i < 20; i++) {
+                    const coreToolsPath = path.join(currentPath, 'packages', 'core', 'tools');
+                    if (fs.existsSync(coreToolsPath)) {
+                        discoveredPaths.push(coreToolsPath);
+                        break;
+                    }
+                    currentPath = path.dirname(currentPath);
+                }
+            }
+        }
+        catch {
+            // Continue if core tools discovery fails
+        }
+        // 2. Discover @matimo/* packages from node_modules (installed providers like slack, gmail)
+        try {
+            const nodeModulesPath = this.getNodeModulesPath();
+            if (nodeModulesPath && fs.existsSync(nodeModulesPath)) {
+                const matimoScopePath = path.join(nodeModulesPath, '@matimo');
+                if (fs.existsSync(matimoScopePath)) {
+                    // Scan @matimo/* directories for tools/
+                    const entries = fs.readdirSync(matimoScopePath, { withFileTypes: true });
+                    for (const entry of entries) {
+                        // Skip core if already discovered
+                        if (entry.name === 'core') {
+                            continue;
+                        }
+                        // Handle both real directories and symlinks
+                        let isDir = entry.isDirectory();
+                        if (!isDir && !entry.name.startsWith('.')) {
+                            try {
+                                // Use statSync to follow symlinks
+                                isDir = fs.statSync(path.join(matimoScopePath, entry.name)).isDirectory();
+                            }
+                            catch {
+                                continue;
+                            }
+                        }
+                        if (isDir && !entry.name.startsWith('.')) {
+                            const toolsPath = path.join(matimoScopePath, entry.name, 'tools');
+                            if (fs.existsSync(toolsPath)) {
+                                discoveredPaths.push(toolsPath);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // Continue even if @matimo discovery fails
+        }
+        // Cache the results for future calls - this makes subsequent autoDiscoverPackages() calls O(1)
+        ToolLoader.discoveredPathsCache = discoveredPaths;
+        return discoveredPaths;
+    }
+    /**
+     * Clear the discovery cache (useful for testing or dynamic tool loading scenarios)
+     * @internal Used for testing only
+     */
+    static clearDiscoveryCache() {
+        ToolLoader.discoveredPathsCache = null;
+    }
+    /**
+     * Load tools from multiple directories
+     * @param dirPaths - Array of directory paths
+     * @returns Combined map of all tools
+     */
+    loadToolsFromMultiplePaths(dirPaths) {
+        const allTools = new Map();
+        for (const dirPath of dirPaths) {
+            try {
+                const tools = this.loadToolsFromDirectory(dirPath);
+                for (const [name, definition] of tools) {
+                    // Later paths can override earlier ones
+                    allTools.set(name, definition);
+                }
+            }
+            catch {
+                // Continue with other paths even if one fails
+                // This allows optional tool packages
+            }
+        }
+        return allTools;
+    }
+}
+/**
+ * Static cache for discovered paths - populated on first autoDiscover call
+ * Subsequent calls return cached result (O(1) instead of O(n))
+ */
+ToolLoader.discoveredPathsCache = null;
+export default ToolLoader;
+//# sourceMappingURL=tool-loader.js.map

package/dist/core/tool-loader.js.map

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

package/dist/core/tool-registry.d.ts

@@ -0,0 +1,48 @@
+import { ToolDefinition } from './schema';
+/**
+ * Tool Registry - In-memory store for loaded tools
+ * Enables tool discovery and management
+ */
+export declare class ToolRegistry {
+    private tools;
+    private toolsByTag;
+    /**
+     * Register a tool in the registry
+     * @param tool - Tool definition to register
+     */
+    register(tool: ToolDefinition): void;
+    /**
+     * Register multiple tools
+     */
+    registerAll(tools: ToolDefinition[]): void;
+    /**
+     * Get a tool by name
+     */
+    get(name: string): ToolDefinition | undefined;
+    /**
+     * Check if a tool exists
+     */
+    has(name: string): boolean;
+    /**
+     * Get all tools
+     */
+    getAll(): ToolDefinition[];
+    /**
+     * Get tools by tag
+     */
+    getByTag(tag: string): ToolDefinition[];
+    /**
+     * Search tools by name (partial match)
+     */
+    search(query: string): ToolDefinition[];
+    /**
+     * Get total count of registered tools
+     */
+    count(): number;
+    /**
+     * Clear all tools
+     */
+    clear(): void;
+}
+export default ToolRegistry;
+//# sourceMappingURL=tool-registry.d.ts.map

package/dist/core/tool-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../../src/core/tool-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAG1C;;;GAGG;AAEH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAA0C;IACvD,OAAO,CAAC,UAAU,CAAuC;IAEzD;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IAqBpC;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,IAAI;IAM1C;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI7C;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;OAEG;IACH,MAAM,IAAI,cAAc,EAAE;IAI1B;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,EAAE;IAQvC;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE;IASvC;;OAEG;IACH,KAAK,IAAI,MAAM;IAIf;;OAEG;IACH,KAAK,IAAI,IAAI;CAId;AAED,eAAe,YAAY,CAAC"}

package/dist/core/tool-registry.js

@@ -0,0 +1,93 @@
+import { MatimoError, ErrorCode } from '../errors/matimo-error';
+/**
+ * Tool Registry - In-memory store for loaded tools
+ * Enables tool discovery and management
+ */
+export class ToolRegistry {
+    constructor() {
+        this.tools = new Map();
+        this.toolsByTag = new Map();
+    }
+    /**
+     * Register a tool in the registry
+     * @param tool - Tool definition to register
+     */
+    register(tool) {
+        if (this.tools.has(tool.name)) {
+            throw new MatimoError(`Tool '${tool.name}' is already registered`, ErrorCode.TOOL_NOT_FOUND, {
+                toolName: tool.name,
+                reason: 'duplicate_registration',
+            });
+        }
+        this.tools.set(tool.name, tool);
+        // Index by tags for discovery
+        if (tool.tags && tool.tags.length > 0) {
+            for (const tag of tool.tags) {
+                if (!this.toolsByTag.has(tag)) {
+                    this.toolsByTag.set(tag, new Set());
+                }
+                this.toolsByTag.get(tag).add(tool.name);
+            }
+        }
+    }
+    /**
+     * Register multiple tools
+     */
+    registerAll(tools) {
+        for (const tool of tools) {
+            this.register(tool);
+        }
+    }
+    /**
+     * Get a tool by name
+     */
+    get(name) {
+        return this.tools.get(name);
+    }
+    /**
+     * Check if a tool exists
+     */
+    has(name) {
+        return this.tools.has(name);
+    }
+    /**
+     * Get all tools
+     */
+    getAll() {
+        return Array.from(this.tools.values());
+    }
+    /**
+     * Get tools by tag
+     */
+    getByTag(tag) {
+        const toolNames = this.toolsByTag.get(tag);
+        if (!toolNames)
+            return [];
+        return Array.from(toolNames)
+            .map((name) => this.tools.get(name))
+            .filter((tool) => tool !== undefined);
+    }
+    /**
+     * Search tools by name (partial match)
+     */
+    search(query) {
+        const lowerQuery = query.toLowerCase();
+        return this.getAll().filter((tool) => tool.name.toLowerCase().includes(lowerQuery) ||
+            tool.description.toLowerCase().includes(lowerQuery));
+    }
+    /**
+     * Get total count of registered tools
+     */
+    count() {
+        return this.tools.size;
+    }
+    /**
+     * Clear all tools
+     */
+    clear() {
+        this.tools.clear();
+        this.toolsByTag.clear();
+    }
+}
+export default ToolRegistry;
+//# sourceMappingURL=tool-registry.js.map

package/dist/core/tool-registry.js.map

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

package/dist/core/types.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Core type definitions for Matimo tool ecosystem
+ */
+import { ParameterEncodingConfig } from '../encodings/parameter-encoding';
+/**
+ * Parameter definition for a tool
+ */
+export interface Parameter {
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+    description: string;
+    required?: boolean;
+    enum?: (string | number | boolean)[];
+    default?: unknown;
+    items?: Parameter;
+    properties?: Record<string, Parameter>;
+}
+/**
+ * Authentication configuration for a tool
+ */
+export interface AuthConfig {
+    type: 'none' | 'api_key' | 'oauth2' | 'basic' | 'bearer';
+    location?: 'header' | 'query' | 'body';
+    name?: string;
+    scheme?: string;
+}
+/**
+ * HTTP execution configuration
+ */
+export interface HttpExecution {
+    type: 'http';
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    url: string;
+    headers?: Record<string, string>;
+    body?: Record<string, unknown>;
+    params?: Record<string, string>;
+    query_params?: Record<string, string>;
+    parameter_encoding?: ParameterEncodingConfig[];
+    timeout?: number;
+}
+/**
+ * Command execution configuration
+ */
+export interface CommandExecution {
+    type: 'command';
+    command: string;
+    args?: string[];
+    cwd?: string;
+    shell?: boolean;
+    timeout?: number;
+    env?: Record<string, string>;
+}
+/**
+ * Function execution configuration
+ * Supports embedded async functions for direct execution
+ */
+export interface FunctionExecution {
+    type: 'function';
+    code: string;
+    timeout?: number;
+}
+/**
+ * Output schema for tool response validation
+ */
+export interface OutputSchema {
+    type: 'object' | 'array' | 'string' | 'number' | 'boolean';
+    properties?: Record<string, OutputSchema>;
+    items?: OutputSchema;
+    description?: string;
+}
+/**
+ * Rate limiting configuration
+ */
+export interface RateLimitConfig {
+    enabled?: boolean;
+    requests_per_minute?: number;
+    requests_per_hour?: number;
+    burst_size?: number;
+}
+/**
+ * Error handling configuration
+ */
+export interface ErrorHandlingConfig {
+    retry?: number;
+    backoff_type?: 'exponential' | 'linear' | 'fixed';
+    initial_delay_ms?: number;
+    max_delay_ms?: number;
+}
+/**
+ * Tool example configuration
+ */
+export interface ToolExample {
+    name: string;
+    params: Record<string, unknown>;
+    description?: string;
+}
+/**
+ * Complete tool definition
+ */
+export interface ToolDefinition {
+    name: string;
+    version: string;
+    description: string;
+    parameters: Record<string, Parameter>;
+    execution: HttpExecution | CommandExecution | FunctionExecution;
+    authentication?: AuthConfig;
+    output_schema?: OutputSchema;
+    rate_limiting?: RateLimitConfig;
+    error_handling?: ErrorHandlingConfig;
+    examples?: ToolExample[];
+    deprecated?: boolean;
+    deprecation_message?: string;
+    tags?: string[];
+    /**
+     * Whether this tool requires approval before execution
+     * Set to true for destructive operations (CREATE, DELETE, DROP, etc.)
+     */
+    requires_approval?: boolean;
+    /**
+     * Internal: Path to the tool definition file (set by ToolLoader)
+     * Used to resolve relative paths for function executors
+     */
+    _definitionPath?: string;
+}
+/**
+ * Tool execution result
+ */
+export interface ExecutionResult {
+    success: boolean;
+    data?: unknown;
+    error?: string;
+    statusCode?: number;
+    duration: number;
+    traceId: string;
+}
+/**
+ * Execution context for a tool run
+ */
+export interface ExecutionContext {
+    traceId: string;
+    userId?: string;
+    toolName: string;
+    parameters: Record<string, unknown>;
+    timestamp: Date;
+    secrets: Record<string, string>;
+}
+/**
+ * Schema validation error
+ */
+export interface ValidationError {
+    field: string;
+    message: string;
+    expectedType?: string;
+    receivedValue?: unknown;
+}
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

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

package/dist/core/types.js

@@ -0,0 +1,5 @@
+/**
+ * Core type definitions for Matimo tool ecosystem
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/decorators/index.d.ts

@@ -0,0 +1,2 @@
+export { tool, setGlobalMatimoInstance, getGlobalMatimoInstance } from './tool-decorator';
+//# sourceMappingURL=index.d.ts.map

package/dist/decorators/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/decorators/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/decorators/index.js

@@ -0,0 +1,2 @@
+export { tool, setGlobalMatimoInstance, getGlobalMatimoInstance } from './tool-decorator';
+//# sourceMappingURL=index.js.map

package/dist/decorators/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/decorators/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC"}