matimo 0.1.0-alpha.1

package/dist/auth/oauth2-provider-loader.js

@@ -0,0 +1,120 @@
+/**
+ * OAuth2ProviderLoader - Loads provider definitions from YAML files
+ *
+ * Pattern: Configuration-driven providers
+ * - Loads provider definitions from tools/[provider]/definition.yaml
+ * - Discovers providers with type: provider
+ * - Makes endpoints available to OAuth2Handler
+ * - Supports infinite providers without code changes
+ *
+ * Usage:
+ * ```typescript
+ * const loader = new OAuth2ProviderLoader('./tools');
+ * const providers = await loader.loadProviders();
+ * const googleEndpoints = providers.get('google');
+ * ```
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import YAML from 'yaml';
+import { MatimoError, ErrorCode } from '../errors/matimo-error';
+import { validateProviderDefinition } from '../core/schema';
+/**
+ * OAuth2ProviderLoader - Loads OAuth2 provider configurations from YAML
+ *
+ * Design Principle:
+ * - Configuration-driven: All provider config in YAML files
+ * - Discoverable: Automatically finds tools/[provider]/definition.yaml with type: provider
+ * - Extensible: Add new providers by adding YAML file, no code changes
+ * - Overridable: Users can override via env vars or runtime config
+ */
+export class OAuth2ProviderLoader {
+    constructor(toolsPath) {
+        this.providers = new Map();
+        this.definitions = new Map();
+        this.toolsPath = toolsPath;
+    }
+    /**
+     * Load all provider definitions from tools directory
+     *
+     * Discovers tools/[provider]/definition.yaml files with type: provider
+     * Validates and stores provider endpoint configurations
+     *
+     * @returns Map of provider name → OAuth2Endpoints
+     * @throws MatimoError if invalid provider definition found
+     */
+    async loadProviders() {
+        try {
+            const entries = await fs.readdir(this.toolsPath, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                const definitionPath = path.join(this.toolsPath, entry.name, 'definition.yaml');
+                try {
+                    const content = await fs.readFile(definitionPath, 'utf-8');
+                    const definition = YAML.parse(content);
+                    // Check if this is a provider definition
+                    if (definition.type === 'provider') {
+                        this.validateProviderDefinition(definition);
+                        this.registerProvider(definition);
+                    }
+                }
+                catch {
+                    // If file doesn't exist or isn't valid YAML, skip silently
+                    // Not all provider directories will have provider definitions
+                }
+            }
+            return this.providers;
+        }
+        catch (error) {
+            throw new MatimoError('Failed to load OAuth2 provider definitions', ErrorCode.TOOL_NOT_FOUND, {
+                toolsPath: this.toolsPath,
+                error: error.message,
+            });
+        }
+    }
+    /**
+     * Get endpoints for a specific provider
+     * @param providerName - Name of the provider (e.g., 'google', 'github')
+     * @returns OAuth2Endpoints or undefined if provider not found
+     */
+    getProvider(providerName) {
+        return this.providers.get(providerName);
+    }
+    /**
+     * Get full provider definition
+     * @param providerName - Name of the provider
+     * @returns ProviderDefinition or undefined if provider not found
+     */
+    getDefinition(providerName) {
+        return this.definitions.get(providerName);
+    }
+    /**
+     * List all loaded providers
+     */
+    listProviders() {
+        return Array.from(this.providers.keys());
+    }
+    /**
+     * Validate provider definition structure using Zod schema
+     */
+    validateProviderDefinition(definition) {
+        try {
+            // Use Zod schema validation for consistency with tool validation
+            validateProviderDefinition(definition);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new MatimoError(`Provider validation failed: ${message}`, ErrorCode.INVALID_SCHEMA);
+        }
+    }
+    /**
+     * Register a provider definition
+     */
+    registerProvider(definition) {
+        const providerName = definition.provider.name;
+        this.providers.set(providerName, definition.provider.endpoints);
+        this.definitions.set(providerName, definition);
+    }
+}
+//# sourceMappingURL=oauth2-provider-loader.js.map

package/dist/auth/oauth2-provider-loader.js.map

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

package/dist/core/schema.d.ts

@@ -0,0 +1,238 @@
+import { z } from 'zod';
+/**
+ * Core Zod validation schemas for all Matimo tool properties.
+ * These schemas ensure YAML tools conform to the spec on load.
+ */
+export declare const ParameterSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        object: "object";
+        array: "array";
+    }>;
+    description: z.ZodString;
+    required: z.ZodOptional<z.ZodBoolean>;
+    enum: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+    default: z.ZodOptional<z.ZodAny>;
+    examples: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+}, z.core.$strip>;
+export type Parameter = z.infer<typeof ParameterSchema>;
+export declare const AuthConfigSchema: z.ZodObject<{
+    type: z.ZodOptional<z.ZodEnum<{
+        api_key: "api_key";
+        oauth2: "oauth2";
+        basic: "basic";
+        bearer: "bearer";
+        custom: "custom";
+    }>>;
+    location: z.ZodOptional<z.ZodEnum<{
+        body: "body";
+        header: "header";
+        query: "query";
+    }>>;
+    name: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodString>;
+    required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type AuthConfig = z.infer<typeof AuthConfigSchema>;
+export declare const ExecutionConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"command">;
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    shell: z.ZodOptional<z.ZodBoolean>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"http">;
+    method: z.ZodEnum<{
+        GET: "GET";
+        POST: "POST";
+        PUT: "PUT";
+        DELETE: "DELETE";
+        PATCH: "PATCH";
+    }>;
+    url: z.ZodString;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    body: z.ZodOptional<z.ZodUnknown>;
+    query_params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    parameter_encoding: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        source: z.ZodArray<z.ZodString>;
+        target: z.ZodString;
+        encoding: z.ZodString;
+        options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>], "type">;
+export type ExecutionConfig = z.infer<typeof ExecutionConfigSchema>;
+export declare const OutputSchemaSchema: z.ZodObject<{
+    type: z.ZodOptional<z.ZodString>;
+    properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    required: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type OutputSchema = z.infer<typeof OutputSchemaSchema>;
+export declare const ErrorHandlingSchema: z.ZodObject<{
+    retry: z.ZodOptional<z.ZodNumber>;
+    backoff_type: z.ZodOptional<z.ZodEnum<{
+        exponential: "exponential";
+        linear: "linear";
+    }>>;
+    initial_delay_ms: z.ZodOptional<z.ZodNumber>;
+    max_delay_ms: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ErrorHandling = z.infer<typeof ErrorHandlingSchema>;
+export declare const RateLimitingSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    requests_per_minute: z.ZodOptional<z.ZodNumber>;
+    burst_size: z.ZodOptional<z.ZodNumber>;
+    quota_per_hour: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type RateLimiting = z.infer<typeof RateLimitingSchema>;
+export declare const ToolDefinitionSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    version: z.ZodString;
+    parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            object: "object";
+            array: "array";
+        }>;
+        description: z.ZodString;
+        required: z.ZodOptional<z.ZodBoolean>;
+        enum: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+        default: z.ZodOptional<z.ZodAny>;
+        examples: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+    }, z.core.$strip>>>;
+    execution: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"command">;
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        cwd: z.ZodOptional<z.ZodString>;
+        shell: z.ZodOptional<z.ZodBoolean>;
+        timeout: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"http">;
+        method: z.ZodEnum<{
+            GET: "GET";
+            POST: "POST";
+            PUT: "PUT";
+            DELETE: "DELETE";
+            PATCH: "PATCH";
+        }>;
+        url: z.ZodString;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        body: z.ZodOptional<z.ZodUnknown>;
+        query_params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        parameter_encoding: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            source: z.ZodArray<z.ZodString>;
+            target: z.ZodString;
+            encoding: z.ZodString;
+            options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>>>;
+        timeout: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>], "type">;
+    authentication: z.ZodOptional<z.ZodObject<{
+        type: z.ZodOptional<z.ZodEnum<{
+            api_key: "api_key";
+            oauth2: "oauth2";
+            basic: "basic";
+            bearer: "bearer";
+            custom: "custom";
+        }>>;
+        location: z.ZodOptional<z.ZodEnum<{
+            body: "body";
+            header: "header";
+            query: "query";
+        }>>;
+        name: z.ZodOptional<z.ZodString>;
+        provider: z.ZodOptional<z.ZodString>;
+        required: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    output_schema: z.ZodOptional<z.ZodObject<{
+        type: z.ZodOptional<z.ZodString>;
+        properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        required: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    error_handling: z.ZodOptional<z.ZodObject<{
+        retry: z.ZodOptional<z.ZodNumber>;
+        backoff_type: z.ZodOptional<z.ZodEnum<{
+            exponential: "exponential";
+            linear: "linear";
+        }>>;
+        initial_delay_ms: z.ZodOptional<z.ZodNumber>;
+        max_delay_ms: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    rate_limiting: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        requests_per_minute: z.ZodOptional<z.ZodNumber>;
+        burst_size: z.ZodOptional<z.ZodNumber>;
+        quota_per_hour: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    examples: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        params: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    deprecated: z.ZodOptional<z.ZodBoolean>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type ToolDefinition = z.infer<typeof ToolDefinitionSchema>;
+export declare const OAuth2EndpointsSchema: z.ZodObject<{
+    authorizationUrl: z.ZodString;
+    tokenUrl: z.ZodString;
+    revokeUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type OAuth2Endpoints = z.infer<typeof OAuth2EndpointsSchema>;
+export declare const ProviderDefinitionSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodLiteral<"provider">;
+    version: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    provider: z.ZodObject<{
+        name: z.ZodString;
+        displayName: z.ZodOptional<z.ZodString>;
+        endpoints: z.ZodObject<{
+            authorizationUrl: z.ZodString;
+            tokenUrl: z.ZodString;
+            revokeUrl: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        defaultScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        documentation: z.ZodOptional<z.ZodString>;
+        learnMore: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ProviderDefinition = z.infer<typeof ProviderDefinitionSchema>;
+/**
+ * Validate a tool definition against the schema
+ * Provides detailed error messages for validation failures
+ *
+ * @param tool - Tool definition to validate
+ * @returns Validated tool definition
+ * @throws {Error} If validation fails with detailed error information
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const tool = validateToolDefinition(parsedYAML);
+ * } catch (error) {
+ *   console.error('Invalid tool:', error.message);
+ *   // Error message includes specific field and validation issue
+ * }
+ * ```
+ */
+export declare function validateToolDefinition(tool: unknown): ToolDefinition;
+/**
+ * Validate a provider definition against the schema
+ * Provides detailed error messages for validation failures
+ *
+ * @param provider - Provider definition to validate
+ * @returns Validated provider definition
+ * @throws {Error} If validation fails with detailed error information
+ */
+export declare function validateProviderDefinition(provider: unknown): ProviderDefinition;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/core/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AAGH,eAAO,MAAM,eAAe;;;;;;;;;;;;;iBAO1B,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAGxD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;iBAM3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAG1D,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;2BA4BhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAGpE,eAAO,MAAM,kBAAkB;;;;;iBAK7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAG9D,eAAO,MAAM,mBAAmB;;;;;;;;iBAK9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAGhE,eAAO,MAAM,kBAAkB;;;;;iBAK7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAG9D,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqB/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAGlE,eAAO,MAAM,qBAAqB;;;;iBAIhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAGpE,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;iBAanC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAgBpE;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,OAAO,GAAG,kBAAkB,CAgBhF"}

package/dist/core/schema.js

@@ -0,0 +1,168 @@
+import { z } from 'zod';
+/**
+ * Core Zod validation schemas for all Matimo tool properties.
+ * These schemas ensure YAML tools conform to the spec on load.
+ */
+// Parameter types that tools can define
+export const ParameterSchema = z.object({
+    type: z.enum(['string', 'number', 'boolean', 'array', 'object']),
+    description: z.string(),
+    required: z.boolean().optional(),
+    enum: z.array(z.any()).optional(),
+    default: z.any().optional(),
+    examples: z.array(z.any()).optional(),
+});
+// Authentication configuration
+export const AuthConfigSchema = z.object({
+    type: z.enum(['api_key', 'basic', 'bearer', 'oauth2', 'custom']).optional(),
+    location: z.enum(['header', 'query', 'body']).optional(),
+    name: z.string().optional(),
+    provider: z.string().optional(),
+    required: z.boolean().optional(),
+});
+// Execution configuration (command or HTTP)
+export const ExecutionConfigSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('command'),
+        command: z.string(),
+        args: z.array(z.string()).optional(),
+        cwd: z.string().optional(),
+        shell: z.boolean().optional(),
+        timeout: z.number().optional(),
+    }),
+    z.object({
+        type: z.literal('http'),
+        method: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']),
+        url: z.string(),
+        headers: z.record(z.string(), z.string()).optional(),
+        body: z.unknown().optional(),
+        query_params: z.record(z.string(), z.string()).optional(),
+        parameter_encoding: z
+            .array(z.object({
+            source: z.array(z.string()),
+            target: z.string(),
+            encoding: z.string(),
+            options: z.record(z.string(), z.unknown()).optional(),
+        }))
+            .optional(),
+        timeout: z.number().optional(),
+    }),
+]);
+// Output schema for validation
+export const OutputSchemaSchema = z.object({
+    type: z.string().optional(),
+    properties: z.record(z.string(), z.unknown()).optional(),
+    required: z.array(z.string()).optional(),
+    description: z.string().optional(),
+});
+// Error handling configuration
+export const ErrorHandlingSchema = z.object({
+    retry: z.number().optional(),
+    backoff_type: z.enum(['linear', 'exponential']).optional(),
+    initial_delay_ms: z.number().optional(),
+    max_delay_ms: z.number().optional(),
+});
+// Rate limiting configuration
+export const RateLimitingSchema = z.object({
+    enabled: z.boolean().optional(),
+    requests_per_minute: z.number().optional(),
+    burst_size: z.number().optional(),
+    quota_per_hour: z.number().optional(),
+});
+// Complete tool definition
+export const ToolDefinitionSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    version: z.string(),
+    parameters: z.record(z.string(), ParameterSchema).optional(),
+    execution: ExecutionConfigSchema,
+    authentication: AuthConfigSchema.optional(),
+    output_schema: OutputSchemaSchema.optional(),
+    error_handling: ErrorHandlingSchema.optional(),
+    rate_limiting: RateLimitingSchema.optional(),
+    examples: z
+        .array(z.object({
+        name: z.string(),
+        params: z.record(z.string(), z.unknown()),
+        description: z.string().optional(),
+    }))
+        .optional(),
+    deprecated: z.boolean().optional(),
+    tags: z.array(z.string()).optional(),
+});
+// OAuth2 provider endpoints schema
+export const OAuth2EndpointsSchema = z.object({
+    authorizationUrl: z.string().url(),
+    tokenUrl: z.string().url(),
+    revokeUrl: z.string().url().optional(),
+});
+// Provider definition schema
+export const ProviderDefinitionSchema = z.object({
+    name: z.string(),
+    type: z.literal('provider'),
+    version: z.string(),
+    description: z.string().optional(),
+    provider: z.object({
+        name: z.string(),
+        displayName: z.string().optional(),
+        endpoints: OAuth2EndpointsSchema,
+        defaultScopes: z.array(z.string()).optional(),
+        documentation: z.string().url().optional(),
+        learnMore: z.string().url().optional(),
+    }),
+});
+/**
+ * Validate a tool definition against the schema
+ * Provides detailed error messages for validation failures
+ *
+ * @param tool - Tool definition to validate
+ * @returns Validated tool definition
+ * @throws {Error} If validation fails with detailed error information
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const tool = validateToolDefinition(parsedYAML);
+ * } catch (error) {
+ *   console.error('Invalid tool:', error.message);
+ *   // Error message includes specific field and validation issue
+ * }
+ * ```
+ */
+export function validateToolDefinition(tool) {
+    const result = ToolDefinitionSchema.safeParse(tool);
+    if (!result.success) {
+        // Format detailed error messages from Zod v4
+        const errors = result.error.issues
+            .map((issue) => {
+            const path = issue.path.length > 0 ? issue.path.join('.') : 'root';
+            return `  • ${path}: ${issue.message} (${issue.code})`;
+        })
+            .join('\n');
+        throw new Error(`Tool schema validation failed:\n${errors}`);
+    }
+    return result.data;
+}
+/**
+ * Validate a provider definition against the schema
+ * Provides detailed error messages for validation failures
+ *
+ * @param provider - Provider definition to validate
+ * @returns Validated provider definition
+ * @throws {Error} If validation fails with detailed error information
+ */
+export function validateProviderDefinition(provider) {
+    const result = ProviderDefinitionSchema.safeParse(provider);
+    if (!result.success) {
+        // Format detailed error messages from Zod v4
+        const errors = result.error.issues
+            .map((issue) => {
+            const path = issue.path.length > 0 ? issue.path.join('.') : 'root';
+            return `  • ${path}: ${issue.message} (${issue.code})`;
+        })
+            .join('\n');
+        throw new Error(`Provider schema validation failed:\n${errors}`);
+    }
+    return result.data;
+}
+//# sourceMappingURL=schema.js.map

package/dist/core/schema.js.map

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

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

@@ -0,0 +1,29 @@
+import { ToolDefinition } from './schema';
+/**
+ * Tool Loader - Loads and validates YAML/JSON tool definitions
+ * Implements TDD pattern: test failures guide implementation
+ */
+export declare class ToolLoader {
+    /**
+     * 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: string): ToolDefinition;
+    /**
+     * 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: string): Map<string, ToolDefinition>;
+    /**
+     * Load a tool from a JSON object
+     * @param data - Tool definition as object
+     * @returns Validated tool definition
+     */
+    loadToolFromObject(data: unknown): ToolDefinition;
+}
+export default ToolLoader;
+//# sourceMappingURL=tool-loader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-loader.d.ts","sourceRoot":"","sources":["../../src/core/tool-loader.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAA0B,MAAM,UAAU,CAAC;AAElE;;;GAGG;AAEH,qBAAa,UAAU;IACrB;;;;;OAKG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc;IA6BlD;;;;;OAKG;IACH,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC;IAgDpE;;;;OAIG;IACH,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc;CAGlD;AAED,eAAe,UAAU,CAAC"}