matimo 0.1.0-alpha.1 → 0.1.0-alpha.3

package/docs/tool-development/YAML_TOOLS.md

@@ -1,65 +0,0 @@
-# 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

@@ -1,391 +0,0 @@
-# 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

@@ -1,255 +0,0 @@
-# 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)
-