matimo 0.1.0-alpha.1

package/docs/tool-development/YAML_TOOLS.md

@@ -0,0 +1,65 @@
+# YAML Tool Specification
+
+Complete guide to writing Matimo tools in YAML format.
+
+## Quick Reference
+
+See the [detailed specification](./TOOL_SPECIFICATION.md) for complete documentation.
+
+**Quick tool template:**
+
+```yaml
+name: my-tool
+description: Brief description
+version: '1.0.0'
+
+parameters:
+  param_name:
+    type: string
+    description: What this parameter does
+    required: true
+
+execution:
+  type: command
+  command: node script.js
+  args: ['--param', '{param_name}']
+
+output_schema:
+  type: object
+  properties:
+    result:
+      type: string
+```
+
+## Key Sections
+
+| Section | Purpose |
+|---------|---------|
+| `name` | Unique tool identifier (kebab-case) |
+| `description` | One-line description |
+| `version` | Semantic version (e.g., 1.0.0) |
+| `parameters` | Tool input parameters |
+| `execution` | How the tool runs (command or HTTP) |
+| `output_schema` | What the tool returns |
+| `authentication` | OAuth2/API key config (optional) |
+| `error_handling` | Retry policy (optional) |
+
+## Full Specification
+
+The complete YAML schema documentation is in [TOOL_SPECIFICATION.md](./TOOL_SPECIFICATION.md).
+
+Topics covered:
+- Metadata (name, description, version)
+- Parameter types and constraints
+- Execution modes (command, HTTP)
+- Authentication configuration
+- Output schema validation
+- Error handling and retry policies
+- Examples for each type
+
+## Next Steps
+
+- **Full Specification**: [TOOL_SPECIFICATION.md](./TOOL_SPECIFICATION.md)
+- **Test Your Tool**: [Testing Guide](./TESTING.md)
+- **Decorator Pattern**: [Decorator Guide](./DECORATOR_GUIDE.md)
+

package/docs/troubleshooting/FAQ.md

@@ -0,0 +1,391 @@
+# Troubleshooting & FAQ
+
+Common issues and solutions for Matimo v0.1.0-alpha.1
+
+## Installation & Setup
+
+### Q: Node.js version error
+
+**Error**: `Node version must be 18.0.0 or higher`
+
+**Solution**:
+```bash
+node --version
+# If < v18, install from https://nodejs.org
+# Use nvm (Node Version Manager) for easy switching:
+nvm install 18
+nvm use 18
+```
+
+### Q: pnpm not found
+
+**Error**: `pnpm: command not found`
+
+**Solution**:
+```bash
+npm install -g pnpm@8.15.0
+pnpm --version
+```
+
+### Q: Build fails with TypeScript errors
+
+**Error**: `Found X errors in src/**`
+
+**Solution**:
+```bash
+# Clear and rebuild
+pnpm clean
+pnpm install
+pnpm build
+
+# If still failing, check TypeScript version
+pnpm list typescript
+# Should be 5.9.3 or higher
+```
+
+---
+
+## Tool Execution
+
+### Q: Tool not found error
+
+**Error**: `Tool not found: calculator`
+
+**Solutions**:
+1. Verify tool exists:
+```bash
+pnpm validate-tools
+# Lists all loaded tools
+```
+
+2. Check tools directory:
+```bash
+# Ensure tools/calculator/definition.yaml exists
+ls -la tools/calculator/definition.yaml
+```
+
+3. Verify tool definition:
+```bash
+pnpm validate-tools
+# Shows validation errors if YAML is invalid
+```
+
+### Q: Invalid parameters error
+
+**Error**: `Tool validation failed: Missing required parameter: operation`
+
+**Solutions**:
+1. Check tool parameters:
+```typescript
+const tool = matimoInstance.getTool('calculator');
+console.log(tool.parameters);  // See required fields
+```
+
+2. Verify your input matches schema:
+```typescript
+// ❌ Wrong
+await m.execute('calculator', { value: 5 });
+
+// ✅ Correct
+await m.execute('calculator', {
+  operation: 'add',
+  a: 5,
+  b: 3
+});
+```
+
+3. Check tool spec:
+```bash
+cat tools/calculator/definition.yaml | grep -A 20 "parameters:"
+```
+
+### Q: HTTP tool returns 401 Unauthorized
+
+**Error**: `HTTP 401: Unauthorized`
+
+**Common causes**:
+1. Missing OAuth token:
+```bash
+# Set required tokens
+export GMAIL_ACCESS_TOKEN=your_token
+export GITHUB_TOKEN=your_token
+```
+
+2. Expired token:
+```typescript
+// Token needs refresh
+const newToken = await oauth2Handler.refreshTokenIfNeeded(
+  userId,
+  currentToken
+);
+```
+
+3. Wrong token format:
+```typescript
+// Verify token is Bearer token, not full "Bearer token"
+const token = process.env.GMAIL_ACCESS_TOKEN;
+// Should be: "ya29.abc123..." not "Bearer ya29.abc123..."
+```
+
+### Q: Command executor fails
+
+**Error**: `Command not found: node` or shell command fails
+
+**Solutions**:
+1. Verify command exists:
+```bash
+which node
+which python
+```
+
+2. Check working directory:
+```yaml
+execution:
+  type: command
+  command: ./script.sh
+  cwd: /path/to/directory  # Ensure this exists
+```
+
+3. Test command manually:
+```bash
+# Test the exact command
+node calculator.js --op add 5 3
+```
+
+---
+
+## OAuth2 & Authentication
+
+### Q: OAuth token missing error
+
+**Error**: `Missing OAuth token for provider: google`
+
+**Solutions**:
+1. Set environment variables:
+```bash
+export GMAIL_ACCESS_TOKEN=ya29.your_token_here
+export GITHUB_TOKEN=ghp_your_token_here
+export SLACK_TOKEN=xoxb-your_token_here
+```
+
+2. Verify token is set:
+```typescript
+console.log(process.env.GMAIL_ACCESS_TOKEN);
+// Should print your token, not undefined
+```
+
+3. Check tool authentication config:
+```yaml
+authentication:
+  type: oauth2
+  provider: google  # Must match provider definition
+```
+
+### Q: OAuth provider configuration not found
+
+**Error**: `Provider definition not found: github`
+
+**Solutions**:
+1. Verify provider YAML exists:
+```bash
+ls tools/github/definition.yaml
+# Should exist and contain: type: provider
+```
+
+2. Check provider name:
+```bash
+pnpm validate-tools
+# Lists all loaded providers
+```
+
+3. Verify provider YAML format:
+```bash
+cat tools/github/definition.yaml | head -5
+# Should show: type: provider
+```
+
+### Q: Bearer token format issue
+
+**Error**: `Invalid authorization header`
+
+**Solutions**:
+1. Use correct token format:
+```bash
+# ✅ Correct: Just the token
+export GMAIL_ACCESS_TOKEN=ya29.abc123
+
+# ❌ Wrong: Don't include "Bearer"
+export GMAIL_ACCESS_TOKEN="Bearer ya29.abc123"
+```
+
+2. Verify token is actually a token:
+```bash
+echo $GMAIL_ACCESS_TOKEN | wc -c
+# Should be > 20 characters
+```
+
+---
+
+## Validation Errors
+
+### Q: Schema validation failed
+
+**Error**: `Tool schema validation failed: • execution: Required`
+
+**Solutions**:
+1. Check required fields in tool YAML:
+```yaml
+# ✅ All required fields
+name: my-tool
+version: 1.0.0
+description: Tool description
+parameters: {}
+execution:
+  type: http
+  method: GET
+  url: https://api.example.com
+```
+
+2. Run validation:
+```bash
+pnpm validate-tools
+# Shows exact field errors
+```
+
+### Q: Invalid execution type
+
+**Error**: `Invalid execution type: webhook`
+
+**Solutions**:
+Supported execution types are:
+- ✅ `command` - Shell commands
+- ✅ `http` - HTTP requests
+
+Unsupported (coming in future releases):
+- 🔜 `webhook` - v0.3.0
+- 🔜 `grpc` - Future
+- 🔜 `database` - Future
+
+---
+
+## Testing & Development
+
+### Q: Tests fail locally
+
+**Error**: Tests pass in CI but fail locally
+
+**Solutions**:
+1. Clear cache and reinstall:
+```bash
+pnpm clean
+rm -rf node_modules pnpm-lock.yaml
+pnpm install
+```
+
+2. Run specific test:
+```bash
+pnpm test -- --testNamePattern="oauth2"
+```
+
+3. Debug test:
+```bash
+node --inspect-brk ./node_modules/.bin/jest --runInBand
+# Then open chrome://inspect
+```
+
+### Q: Linting errors
+
+**Error**: `ESLint errors found`
+
+**Solution**:
+```bash
+# Fix automatically
+pnpm lint:fix
+
+# Then format
+pnpm format
+```
+
+---
+
+## Performance Issues
+
+### Q: Tool execution is slow
+
+**Possible causes**:
+1. Network latency (HTTP tools)
+2. OAuth token refresh overhead
+3. Tool parameter validation
+
+**Solutions**:
+```typescript
+// Time tool execution
+console.time('tool-execution');
+const result = await m.execute('gmail-send-email', params);
+console.timeEnd('tool-execution');
+
+// Optimize: Cache tools
+const tool = m.getTool('gmail-send-email');
+const result = await executor.execute(tool, params);
+```
+
+### Q: High memory usage
+
+**Solutions**:
+```typescript
+// Don't load all tools if not needed
+const tools = m.listTools();
+const filtered = tools.filter(t => t.tags.includes('gmail'));
+
+// Or use specific tool
+const tool = m.getTool('gmail-send-email');
+```
+
+---
+
+## v0.1.0-alpha.1 Specific
+
+### Features NOT in this version
+
+These are planned for future releases:
+
+- 🔜 **CLI** - `matimo` command (v0.2.0)
+- 🔜 **MCP Server** - Claude integration (v0.2.0)
+- 🔜 **REST API** - HTTP API (v0.3.0)
+- 🔜 **Python SDK** - Python support (v0.3.0)
+- 🔜 **Docker** - Containerization (v0.3.0)
+- 🔜 **Rate Limiting** - Token bucket (v0.2.0)
+- 🔜 **Health Monitoring** - Schema drift detection (v0.2.0)
+
+See [FUTURE_RELEASES.md](../FUTURE_RELEASES.md) for details.
+
+---
+
+## Getting Help
+
+Still stuck? Try:
+
+1. **GitHub Issues**: [Search issues](https://github.com/tallclub/matimo/issues)
+2. **GitHub Discussions**: [Ask questions](https://github.com/tallclub/matimo/discussions)
+3. **Documentation**: [Full docs](../)
+4. **Examples**: [See examples](../../examples/)
+
+---
+
+## Report a Bug
+
+Found a bug? Help us fix it:
+
+```bash
+# 1. Check if issue exists
+# Go to https://github.com/tallclub/matimo/issues
+
+# 2. If not, create new issue with:
+# - Matimo version: (run: npm list matimo)
+# - Node.js version: (run: node --version)
+# - Steps to reproduce
+# - Expected vs actual behavior
+# - Error message/stack trace
+```
+
+Thank you for helping improve Matimo! 🙏

package/docs/user-guide/AUTHENTICATION.md

@@ -0,0 +1,255 @@
+# Authentication Guide
+
+Setup OAuth2 for tools that require user authentication.
+
+## Overview
+
+Some tools require authentication (e.g., Gmail, GitHub, Slack). Matimo handles OAuth2 token injection automatically.
+
+**How it works:**
+1. Obtain OAuth2 token from provider (Google, GitHub, Slack)
+2. Set token in environment variable
+3. Matimo automatically injects token into tool execution
+4. Execute tool normally
+
+---
+
+## Quick Setup (Gmail Example)
+
+### 1. Get OAuth2 Token
+
+From Google Cloud Console:
+```bash
+# Set your Gmail access token
+export GMAIL_ACCESS_TOKEN="ya29.a0AfH6SMBx..."
+```
+
+For other providers, see [Full OAuth2 Guide](../architecture/OAUTH.md).
+
+### 2. Execute OAuth2 Tool
+
+```typescript
+import { matimo } from 'matimo';
+
+const m = await matimo.init('./tools');
+
+// Token automatically injected from GMAIL_ACCESS_TOKEN env var
+const result = await m.execute('gmail-send-email', {
+  to: 'user@example.com',
+  subject: 'Hello from Matimo',
+  body: 'This email was sent via Matimo!'
+});
+
+console.log('✅ Email sent:', result.messageId);
+```
+
+No additional code needed — Matimo handles token injection.
+
+---
+
+## Supported Providers
+
+| Provider | Token Env Var | Scope |
+|----------|---------------|-------|
+| **Google (Gmail)** | `GMAIL_ACCESS_TOKEN` | `https://www.googleapis.com/auth/gmail.send` |
+| **GitHub** | `GITHUB_ACCESS_TOKEN` | `repo, gist` |
+| **Slack** | `SLACK_ACCESS_TOKEN` | `chat:write, users:read` |
+
+---
+
+## Environment Variable Pattern
+
+Matimo uses a naming convention for OAuth2 tokens:
+
+```
+{PROVIDER}_{CREDENTIAL_TYPE}_TOKEN
+
+Examples:
+GMAIL_ACCESS_TOKEN
+GITHUB_ACCESS_TOKEN
+SLACK_ACCESS_TOKEN
+```
+
+Check tool documentation for exact variable name:
+
+```typescript
+const tool = m.getTool('gmail-send-email');
+console.log(tool.authentication);
+// { type: 'oauth2', provider: 'google', ... }
+```
+
+---
+
+## Getting OAuth2 Tokens
+
+### Google (Gmail)
+
+1. Visit [Google Cloud Console](https://console.cloud.google.com)
+2. Create OAuth2 credentials (type: Web application)
+3. Get access token:
+   ```bash
+   curl -X POST https://oauth2.googleapis.com/token \
+     -d "client_id=YOUR_CLIENT_ID&client_secret=YOUR_SECRET&grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN"
+   ```
+4. Set environment variable:
+   ```bash
+   export GMAIL_ACCESS_TOKEN="ya29.a0AfH6SMBx..."
+   ```
+
+### GitHub
+
+1. Visit [GitHub Settings → Developer Settings → Personal Tokens](https://github.com/settings/tokens)
+2. Create Personal Access Token with `repo` and `gist` scopes
+3. Set environment variable:
+   ```bash
+   export GITHUB_ACCESS_TOKEN="ghp_xxxxx..."
+   ```
+
+### Slack
+
+1. Visit [Slack App Configuration](https://api.slack.com/apps)
+2. Create new app or select existing
+3. Install app to workspace
+4. Copy Bot Token or OAuth token
+5. Set environment variable:
+   ```bash
+   export SLACK_ACCESS_TOKEN="xoxb-..."
+   ```
+
+---
+
+## Verify Authentication
+
+### Check Token
+
+```typescript
+// Verify token is set
+const token = process.env.GMAIL_ACCESS_TOKEN;
+if (!token) {
+  console.error('❌ GMAIL_ACCESS_TOKEN not set');
+  process.exit(1);
+}
+console.log('✅ Token found');
+```
+
+### Test Execution
+
+```typescript
+try {
+  const result = await m.execute('gmail-send-email', {
+    to: 'test@example.com',
+    subject: 'Test',
+    body: 'Test email'
+  });
+  console.log('✅ Authentication successful');
+} catch (error) {
+  if (error.code === 'EXECUTION_FAILED' && error.details?.statusCode === 401) {
+    console.error('❌ Token invalid or expired');
+  }
+}
+```
+
+---
+
+## Troubleshooting
+
+### Token Not Found
+
+**Error:**
+```
+Tool execution failed: Missing GMAIL_ACCESS_TOKEN environment variable
+```
+
+**Solution:**
+```bash
+# Verify token is set
+echo $GMAIL_ACCESS_TOKEN
+
+# If empty, set it
+export GMAIL_ACCESS_TOKEN="your_token_here"
+```
+
+### Token Expired
+
+**Error:**
+```
+401 Unauthorized: Invalid Credentials
+```
+
+**Solution:**
+1. Refresh your OAuth2 token from provider
+2. Update environment variable
+3. Retry execution
+
+### Invalid Scopes
+
+**Error:**
+```
+Access denied: Insufficient scopes
+```
+
+**Solution:**
+1. Check required scopes in tool documentation
+2. Generate new token with required scopes
+3. Update environment variable
+
+---
+
+## Security Best Practices
+
+⚠️ **Never commit tokens to git**
+
+```bash
+# ❌ DON'T do this
+export GITHUB_TOKEN="ghp_xxxxx"  # DO NOT COMMIT
+
+# ✅ DO this instead
+# Set in your .env file (add .env to .gitignore)
+# Or use your shell's secure storage
+```
+
+Store tokens securely:
+- Environment variables (recommended)
+- `.env` file (add to `.gitignore`)
+- System keychain (macOS Keychain, Windows Credential Manager)
+- CI/CD secrets (GitHub Actions, etc.)
+
+---
+
+## Advanced: Multiple Providers
+
+```typescript
+const m = await matimo.init('./tools');
+
+// Execute Gmail tool
+const email = await m.execute('gmail-send-email', {
+  to: 'user@example.com',
+  subject: 'From Matimo',
+  body: 'Test'
+});
+
+// Execute GitHub tool
+const issue = await m.execute('github-create-issue', {
+  owner: 'tallclub',
+  repo: 'matimo',
+  title: 'Feature request',
+  body: 'Please add more tools'
+});
+
+// Execute Slack tool
+const msg = await m.execute('slack-send-message', {
+  channel: '#general',
+  text: 'Hello from Matimo!'
+});
+```
+
+Each tool automatically uses the correct token based on its provider.
+
+---
+
+## Next Steps
+
+- **Full OAuth2 Details**: [OAuth2 Implementation Guide](../architecture/OAUTH.md)
+- **Tool Discovery**: [Find Tools](./TOOL_DISCOVERY.md)
+- **Error Handling**: [Error Codes Reference](../api-reference/ERRORS.md)
+