matimo 0.1.0-alpha.1

package/docs/ROADMAP.md

@@ -0,0 +1,138 @@
+# Matimo Roadmap
+
+## v0.1.0-alpha.1 (Current Release)
+
+### ✅ Core Features Implemented
+
+**OAuth2 Authentication**
+- OAuth2 handler with token management
+- Provider-agnostic configuration via YAML
+- Multi-provider support (Google, GitHub, Slack)
+- Token injection system for tools
+
+**Tool System**
+- YAML-based tool definitions with Zod validation
+- Tool loader and registry
+- Command executor (shell commands + templating)
+- HTTP executor (REST APIs with OAuth2 support)
+- Parameter encoding utilities
+
+**SDK Patterns**
+- Factory pattern (recommended for simple use cases)
+- Decorator pattern (@tool decorators for class-based code)
+- Tool discovery and filtering
+- Full TypeScript type safety (zero `any` types)
+
+**Tool Examples**
+- Gmail tools (list, get, send, create-draft, delete)
+- GitHub provider configuration
+- Slack provider configuration
+- Calculator and echo tools (reference implementations)
+
+**Quality Assurance**
+- 100% test passing
+- Full TypeScript strict mode enforcement
+- ESLint clean with zero warnings
+- Prettier formatting
+- Zod schema validation for all definitions
+
+**Documentation**
+- Quick start guide
+- API reference
+- Tool specification
+- OAuth2 implementation guide
+- Decorator pattern guide
+- Contributing guide
+- Security guidelines
+
+---
+
+## Future Release (not in specific order)
+
+### 🔜 Planned Features
+
+**CLI Tool**
+- `matimo list` - List all tools
+- `matimo execute` - Execute tools from command line
+- `matimo validate` - Validate tool YAML files
+- `matimo test` - Test tool execution locally
+
+**MCP (Model Context Protocol) Server**
+- Native MCP server 
+- Tool discovery via MCP
+- Automatic tool calling
+- Session management
+
+**Framework Integrations**
+- CrewAI integration examples
+- Vercel AI SDK integration
+- Custom framework patterns
+- Framework-specific documentation
+
+**Advanced Features**
+- Rate limiting (token bucket algorithm)
+- Health monitoring (API schema drift detection)
+- Token refresh automation
+- Error recovery strategies
+
+**REST API Server**
+- HTTP endpoints for tool execution
+- Async job execution
+- Webhook support
+- OpenAPI documentation
+
+**Python SDK**
+- Python implementation with same YAML definitions
+- LangChain Python integration
+- CrewAI Python support
+- Feature parity with Node.js SDK
+
+**Tool Marketplace**
+- Distributed tool registry
+- Tool publishing and versioning
+- Community tool submissions
+- Tool ratings and reviews
+
+**Deployment**
+- Docker images and Dockerfile examples
+- Kubernetes deployment guides
+- CI/CD integration examples
+- Production deployment patterns
+
+**Ecosystem Maturity**
+- Automated schema translation (OpenAPI → Matimo YAML)
+- Performance optimizations
+- Enterprise features (audit logs, rate limiting)
+
+**Skills/Workflows**
+- Tool composition/chaining
+- Conditional execution
+- Error handling workflows
+- Advanced orchestration
+
+
+## How to Use This Roadmap
+
+- **v0.1.0-alpha.1**: Use current implementation for OAuth2, tool execution, and SDK patterns
+- **Future Releases**: These are planned but not yet implemented. Contributions welcome!
+- **Contributing**: See [CONTRIBUTING.md](../CONTRIBUTING.md) for how to help
+
+---
+
+## Release Thoughts
+
+```
+v0.1.0-alpha.1  Feb 2026 (Current)
+    ↓
+v0.1.0-alpha.2  3rd week Feb 2026.     
+    ↓
+v0.1.0-alpha.3  1st week Mar 2026.    
+    ↓
+v0.1.0     End of March 2026. 
+```
+
+---
+
+## Contributing to the Roadmap
+
+Have ideas? [Open a GitHub Discussion](https://github.com/tallclub/matimo/discussions) to propose features for future releases.

package/docs/_config.yml

@@ -0,0 +1,27 @@
+theme: jekyll-theme-slate
+title: Matimo - AI Tools Ecosystem
+description: Define tools once in YAML, use them everywhere
+show_downloads: true
+google_analytics: false
+
+# Matimo Documentation
+url: "https://tallclub.github.io"
+baseurl: "/matimo"
+repository: "tallclub/matimo"
+
+# Build settings
+markdown: kramdown
+highlighter: rouge
+
+# Navigation
+nav:
+  - text: "Home"
+    url: "/"
+  - text: "Getting Started"
+    url: "/getting-started/"
+  - text: "Documentation"
+    url: "/"
+  - text: "GitHub"
+    url: "https://github.com/tallclub/matimo"
+  - text: "npm"
+    url: "https://www.npmjs.com/package/matimo"

package/docs/api-reference/ERRORS.md

@@ -0,0 +1,445 @@
+# API Error Codes Reference
+
+Complete reference of error codes returned by Matimo SDK.
+
+## Central Error Management
+
+Matimo uses a centralized error handling system via the `MatimoError` class defined in `src/errors/matimo-error.ts`. This ensures consistent error handling across all SDK operations.
+
+### MatimoError Class
+
+All Matimo errors extend the native `Error` class and include:
+
+```typescript
+import { MatimoError, ErrorCode } from 'matimo';
+
+class MatimoError extends Error {
+  code: ErrorCode;              // Machine-readable error code
+  details?: Record<string, unknown>;  // Additional context
+  
+  toJSON(): Record<string, unknown>;  // Serialize to JSON
+}
+```
+
+**Key Benefits:**
+- **Centralized Definition**: All error codes defined in one place (`ErrorCode` enum)
+- **Type-Safe**: TypeScript enum ensures only valid error codes can be thrown
+- **Serializable**: `toJSON()` method for logging and API responses
+- **Extensible**: Details object captures context-specific information
+- **Consistent**: Same error structure across all SDK methods
+
+### Error Codes Enum
+
+All 11 error codes are defined in the `ErrorCode` enum:
+
+```typescript
+export enum ErrorCode {
+  INVALID_SCHEMA = 'INVALID_SCHEMA',        // Tool definition validation failed
+  EXECUTION_FAILED = 'EXECUTION_FAILED',    // Tool execution error
+  AUTH_FAILED = 'AUTH_FAILED',              // Authentication/token error
+  TOOL_NOT_FOUND = 'TOOL_NOT_FOUND',        // Tool not in registry
+  FILE_NOT_FOUND = 'FILE_NOT_FOUND',        // File/directory missing
+  VALIDATION_FAILED = 'VALIDATION_FAILED',  // Parameter validation error
+  RATE_LIMIT_EXCEEDED = 'RATE_LIMIT_EXCEEDED', // API rate limit hit
+  TIMEOUT = 'TIMEOUT',                      // Operation timeout
+  NETWORK_ERROR = 'NETWORK_ERROR',          // Network/connection error
+  INVALID_PARAMETER = 'INVALID_PARAMETER',  // Invalid parameter value
+  UNKNOWN_ERROR = 'UNKNOWN_ERROR',          // Unknown error
+}
+```
+
+### Creating Errors
+
+Matimo provides helper functions for common error types:
+
+```typescript
+import { 
+  createValidationError, 
+  createExecutionError,
+  MatimoError,
+  ErrorCode 
+} from 'matimo';
+
+// Using helpers
+const validationErr = createValidationError(
+  'Missing required parameter',
+  { param: 'email' }
+);
+
+const executionErr = createExecutionError(
+  'Tool returned error 500',
+  { statusCode: 500, tool: 'gmail-send' }
+);
+
+// Direct instantiation
+const authErr = new MatimoError(
+  'Missing API token',
+  ErrorCode.AUTH_FAILED,
+  { env: 'GMAIL_ACCESS_TOKEN' }
+);
+```
+
+---
+
+## Error Structure
+
+All Matimo errors follow this structure (via `MatimoError`):
+
+```typescript
+{
+  name: 'MatimoError';      // Error class name
+  message: string;           // Human-readable message
+  code: ErrorCode;           // Error code enum value
+  details?: object;          // Additional context
+}
+```
+
+**Example:**
+```typescript
+import { MatimoError, ErrorCode } from 'matimo';
+
+try {
+  await m.execute('unknown-tool', {});
+} catch (error) {
+  if (error instanceof MatimoError) {
+    console.log(error.code);        // ErrorCode.TOOL_NOT_FOUND
+    console.log(error.message);     // 'Tool "unknown-tool" not found'
+    console.log(error.details);     // { toolName: 'unknown-tool' }
+    console.log(error.toJSON());    // Full error object for logging
+  }
+}
+```
+
+---
+
+## Error Codes
+
+### TOOL_NOT_FOUND
+
+Tool name doesn't exist in registry.
+
+```typescript
+if (error.code === 'TOOL_NOT_FOUND') {
+  // Tool doesn't exist
+  // Check tool name spelling
+  // Use m.listTools() to see available tools
+}
+```
+
+**Common causes:**
+- Typo in tool name
+- Tool file not loaded
+- Tool definition invalid
+
+**Resolution:**
+```typescript
+// List available tools
+const tools = m.listTools();
+console.log(tools.map(t => t.name));
+
+// Use correct tool name
+const result = await m.execute('calculator', params);
+```
+
+---
+
+### INVALID_PARAMETERS
+
+Required parameters missing or wrong type.
+
+```typescript
+if (error.code === 'INVALID_PARAMETERS') {
+  console.log('Missing or invalid:', error.details.invalidFields);
+  // e.g., { invalidFields: ['operation', 'a'] }
+}
+```
+
+**Common causes:**
+- Missing required parameter
+- Wrong parameter type (string vs number)
+- Parameter value outside allowed range
+
+**Resolution:**
+```typescript
+// Get tool definition
+const tool = m.getTool('calculator');
+
+// Check required parameters
+Object.entries(tool.parameters).forEach(([name, param]) => {
+  if (param.required) {
+    console.log(`Required: ${name}`);
+  }
+});
+
+// Execute with all required params
+const result = await m.execute('calculator', {
+  operation: 'add',  // required
+  a: 5,              // required
+  b: 3               // required
+});
+```
+
+---
+
+### EXECUTION_FAILED
+
+Tool execution encountered an error.
+
+```typescript
+if (error.code === 'EXECUTION_FAILED') {
+  console.log('Tool error:', error.details);
+  // Details vary by tool type
+}
+```
+
+**Common causes:**
+- Tool returned error (e.g., API returned 500)
+- Command execution failed
+- Network error
+- Authentication failed
+
+**Resolution:**
+```typescript
+try {
+  const result = await m.execute('gmail-send-email', {
+    to: 'user@example.com',
+    subject: 'Test',
+    body: 'Test'
+  });
+} catch (error) {
+  if (error.code === 'EXECUTION_FAILED') {
+    if (error.details.statusCode === 401) {
+      console.error('❌ Authentication failed - check token');
+    } else if (error.details.statusCode === 429) {
+      console.error('⏱️ Rate limited - retry later');
+    } else {
+      console.error('Tool error:', error.message);
+    }
+  }
+}
+```
+
+---
+
+### INVALID_SCHEMA
+
+Tool definition doesn't match schema.
+
+```typescript
+if (error.code === 'INVALID_SCHEMA') {
+  console.log('Tool definition invalid:', error.details.errors);
+}
+```
+
+**Common causes:**
+- Required field missing in tool YAML
+- Wrong parameter type in YAML
+- Invalid execution configuration
+
+**Resolution:**
+```bash
+# Validate all tools
+pnpm validate-tools
+
+# This will show which tools have schema errors
+```
+
+See [Tool Specification](../tool-development/YAML_TOOLS.md) for correct YAML format.
+
+---
+
+### VALIDATION_FAILED
+
+Parameter validation failed (e.g., not in enum, wrong regex pattern).
+
+```typescript
+if (error.code === 'VALIDATION_FAILED') {
+  console.log('Validation errors:', error.details.errors);
+}
+```
+
+**Common causes:**
+- Parameter value not in enum list
+- String doesn't match regex pattern
+- Number outside min/max range
+
+**Resolution:**
+```typescript
+// Get tool definition
+const tool = m.getTool('calculator');
+
+// Check parameter constraints
+const operation = tool.parameters.operation;
+console.log('Allowed operations:', operation.enum);
+// ['add', 'subtract', 'multiply', 'divide']
+
+// Use allowed value
+const result = await m.execute('calculator', {
+  operation: 'add',  // Must be in enum
+  a: 5,
+  b: 3
+});
+```
+
+---
+
+### AUTH_FAILED
+
+Authentication error (missing or invalid token).
+
+```typescript
+if (error.code === 'AUTH_FAILED') {
+  console.log('Auth error:', error.message);
+  // e.g., "Missing GMAIL_ACCESS_TOKEN environment variable"
+}
+```
+
+**Common causes:**
+- OAuth2 token not set in environment variable
+- Token expired
+- Token invalid or revoked
+
+**Resolution:**
+```bash
+# Check token is set
+echo $GMAIL_ACCESS_TOKEN
+
+# If empty, set it
+export GMAIL_ACCESS_TOKEN="ya29.a0AfH6SMBx..."
+
+# Test execution
+npx tsx -e "import {matimo} from 'matimo'; const m = await matimo.init('./tools'); console.log(await m.execute('gmail-send-email', {to: 'test@example.com', subject: 'Test', body: 'Test'}));"
+```
+
+See [Authentication Guide](../user-guide/AUTHENTICATION.md) for token setup.
+
+---
+
+### FILE_NOT_FOUND
+
+Tool file or directory doesn't exist.
+
+```typescript
+if (error.code === 'FILE_NOT_FOUND') {
+  console.log('Missing file:', error.details.path);
+}
+```
+
+**Common causes:**
+- Tools directory path is wrong
+- Tool YAML file deleted
+- Incorrect file path in code
+
+**Resolution:**
+```bash
+# Verify tools directory exists
+ls -la ./tools
+
+# Verify tool file exists
+ls -la ./tools/calculator/definition.yaml
+
+# Use correct path when initializing
+const m = await matimo.init('./tools');
+```
+
+---
+
+## Handling Errors
+
+### Pattern 1: Type Check and Handle Specific Codes
+
+```typescript
+import { MatimoError, ErrorCode } from 'matimo';
+
+try {
+  const result = await m.execute('calculator', params);
+} catch (error) {
+  if (error instanceof MatimoError) {
+    switch (error.code) {
+      case ErrorCode.TOOL_NOT_FOUND:
+        console.error('Tool not available');
+        break;
+      case ErrorCode.VALIDATION_FAILED:
+        console.error('Bad parameters:', error.details);
+        break;
+      case ErrorCode.EXECUTION_FAILED:
+        console.error('Tool execution failed:', error.details);
+        break;
+      default:
+        console.error('Unknown error:', error.message);
+    }
+  } else {
+    // Handle non-Matimo errors
+    throw error;
+  }
+}
+```
+
+### Pattern 2: Check Specific Error Code
+
+```typescript
+import { MatimoError, ErrorCode } from 'matimo';
+
+try {
+  await m.execute('gmail-send-email', params);
+} catch (error) {
+  if (error instanceof MatimoError) {
+    if (error.code === ErrorCode.AUTH_FAILED) {
+      // Handle auth separately
+      return redirectToLogin();
+    }
+    
+    if (error.code === ErrorCode.EXECUTION_FAILED) {
+      // Handle tool error
+      return retryWithBackoff();
+    }
+  }
+  
+  // Handle others
+  throw error;
+}
+```
+
+### Pattern 3: Serialize for Logging
+
+```typescript
+import { MatimoError } from 'matimo';
+
+try {
+  await m.execute(toolName, params);
+} catch (error) {
+  if (error instanceof MatimoError) {
+    // Use toJSON() for structured logging
+    logger.error('tool_execution_failed', error.toJSON());
+  } else {
+    throw error;
+  }
+}
+```
+
+---
+
+## Error Codes Reference
+
+| Code | ErrorCode Enum | Cause | Resolution |
+|------|---|-------|-----------|
+| `TOOL_NOT_FOUND` | `ErrorCode.TOOL_NOT_FOUND` | Tool doesn't exist | Check tool name, use `listTools()` |
+| `INVALID_PARAMETERS` | `ErrorCode.INVALID_PARAMETER` | Missing/wrong params | Check tool definition |
+| `EXECUTION_FAILED` | `ErrorCode.EXECUTION_FAILED` | Tool execution error | Check tool error details |
+| `INVALID_SCHEMA` | `ErrorCode.INVALID_SCHEMA` | Bad tool definition | Fix tool YAML, run `validate-tools` |
+| `VALIDATION_FAILED` | `ErrorCode.VALIDATION_FAILED` | Param validation failed | Check constraints (enum, regex, range) |
+| `AUTH_FAILED` | `ErrorCode.AUTH_FAILED` | Missing/invalid token | Set OAuth2 env var |
+| `FILE_NOT_FOUND` | `ErrorCode.FILE_NOT_FOUND` | File/dir missing | Verify paths exist |
+| `RATE_LIMIT_EXCEEDED` | `ErrorCode.RATE_LIMIT_EXCEEDED` | API rate limit hit | Wait and retry |
+| `TIMEOUT` | `ErrorCode.TIMEOUT` | Operation timeout | Increase timeout or check network |
+| `NETWORK_ERROR` | `ErrorCode.NETWORK_ERROR` | Network/connection error | Check connectivity |
+| `UNKNOWN_ERROR` | `ErrorCode.UNKNOWN_ERROR` | Unknown error | Check error details |
+
+---
+
+## Next Steps
+
+- **Handle Errors**: [Error Handling Patterns](#handling-errors)
+- **Setup Auth**: [Authentication Guide](../user-guide/AUTHENTICATION.md)
+- **Type Definitions**: [Type Reference](./TYPES.md)
+