Development Guide

Detailed guide for setting up your development environment and working with the ai.matey codebase.

Prerequisites

Before you begin, ensure you have:

Node.js 18+ installed
npm 9+ (comes with Node.js)
Git for version control
A code editor (we recommend VS Code)

Initial Setup

1. Clone the Repository

# Fork the repository on GitHub first, then:
git clone https://github.com/YOUR_USERNAME/ai.matey.git
cd ai.matey

2. Install Dependencies

npm install

This installs dependencies for all packages in the monorepo.

3. Set Up Environment

Create a .env file for API keys (optional, needed for testing):

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=...
GROQ_API_KEY=...

Note: Never commit API keys! The .env file is gitignored.

4. Build All Packages

npm run build

This builds all packages in dependency order using Turbo.

Monorepo Structure

ai.matey uses npm workspaces for package management and Turbo for build orchestration.

Workspaces

{
  "workspaces": [
    "packages/*"
  ]
}

All packages are in packages/. Dependencies between packages are managed automatically.

Package Dependencies

Packages have internal dependencies:

ai.matey.core → ai.matey.types
ai.matey.frontend → ai.matey.types
ai.matey.backend → ai.matey.types
ai.matey.middleware → ai.matey.core, ai.matey.types

Development Commands

Build

# Build all packages
npm run build

# Build specific package
npm run build --workspace=ai.matey.core

# Build in watch mode
npm run dev

Test

# Run all tests
npm test

# Run tests for specific package
npm test --workspace=ai.matey.core

# Run tests in watch mode
npm test -- --watch

# Run tests with coverage
npm test -- --coverage

Lint

# Check all packages
npm run lint

# Auto-fix issues
npm run lint:fix

# Lint specific package
npm run lint --workspace=ai.matey.core

Format

# Format all code
npm run format

# Check formatting
npm run format:check

Clean

# Clean build artifacts
npm run clean

# Clean and rebuild
npm run clean && npm run build

Working with Packages

Creating a New Package

Create package directory:

mkdir packages/ai.matey.newpackage
cd packages/ai.matey.newpackage

Initialize package.json:

{
  "name": "ai.matey.newpackage",
  "version": "0.1.0",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "scripts": {
    "build": "tsc",
    "test": "jest"
  },
  "dependencies": {
    "ai.matey.types": "*"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "jest": "^29.0.0"
  }
}

Add tsconfig.json:

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"]
}

Create source files:
Terminal window
```
mkdir src
touch src/index.ts
```

Adding Dependencies

# Add to specific package
npm install package-name --workspace=ai.matey.core

# Add to root (dev dependencies)
npm install -D package-name

Linking Between Packages

Packages automatically link in the monorepo:

{
  "dependencies": {
    "ai.matey.core": "*"  // Uses local version
  }
}

TypeScript Configuration

Root tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

Package-Specific Config

Packages extend the root config:

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "references": [
    { "path": "../ai.matey.types" }
  ]
}

Testing

Test Structure

Tests live alongside source code:

src/
├── bridge.ts
├── bridge.test.ts
├── router.ts
└── router.test.ts

Writing Tests

import { Bridge } from './bridge';
import { MockFrontendAdapter, MockBackendAdapter } from '../test-utils';

describe('Bridge', () => {
  let bridge: Bridge;
  let mockBackend: MockBackendAdapter;

  beforeEach(() => {
    mockBackend = new MockBackendAdapter();
    bridge = new Bridge(
      new MockFrontendAdapter(),
      mockBackend
    );
  });

  describe('chat()', () => {
    it('should process requests correctly', async () => {
      mockBackend.setResponse({
        choices: [{ message: { content: 'Test response' } }]
      });

      const response = await bridge.chat({
        model: 'test',
        messages: [{ role: 'user', content: 'Test' }]
      });

      expect(response.choices[0].message.content).toBe('Test response');
    });

    it('should handle errors', async () => {
      mockBackend.setError(new Error('API Error'));

      await expect(
        bridge.chat({
          model: 'test',
          messages: [{ role: 'user', content: 'Test' }]
        })
      ).rejects.toThrow('API Error');
    });
  });

  describe('chatStream()', () => {
    it('should stream responses', async () => {
      const stream = await bridge.chatStream({
        model: 'test',
        messages: [{ role: 'user', content: 'Test' }],
        stream: true
      });

      const chunks = [];
      for await (const chunk of stream) {
        chunks.push(chunk);
      }

      expect(chunks.length).toBeGreaterThan(0);
    });
  });
});

Test Utilities

Create mock adapters for testing:

export class MockBackendAdapter implements BackendAdapter {
  name = 'mock';
  private response: any;
  private error: Error | null = null;

  setResponse(response: any) {
    this.response = response;
  }

  setError(error: Error) {
    this.error = error;
  }

  async chat(request: IRChatCompletionRequest) {
    if (this.error) throw this.error;
    return this.response || { choices: [{ message: { content: 'Mock' } }] };
  }

  async *chatStream(request: IRChatCompletionRequest) {
    if (this.error) throw this.error;
    yield { choices: [{ delta: { content: 'Mock' } }] };
  }
}

Debugging

VS Code Configuration

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Tests",
      "program": "${workspaceFolder}/node_modules/jest/bin/jest",
      "args": ["--runInBand", "--no-coverage"],
      "cwd": "${workspaceFolder}",
      "console": "integratedTerminal"
    },
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Current File",
      "program": "${file}",
      "cwd": "${workspaceFolder}",
      "console": "integratedTerminal"
    }
  ]
}

Debugging Tips

Use breakpoints in VS Code
Add debugger statements in code
Use console.log strategically
Run tests in watch mode for quick feedback

Build System (Turbo)

Turbo Configuration

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": []
    },
    "lint": {
      "outputs": []
    }
  }
}

Caching

Turbo caches build outputs. To clear cache:

npx turbo run build --force

Common Tasks

Adding a New Backend Adapter

Create adapter file:

cd packages/ai.matey.backend
touch src/adapters/newprovider.ts

Implement adapter:

export class NewProviderBackendAdapter implements BackendAdapter {
  name = 'newprovider';
  // ... implementation
}

Add tests:
Terminal window
```
touch src/adapters/newprovider.test.ts
```

Export:

export { NewProviderBackendAdapter } from './adapters/newprovider';

Test:
Terminal window
```
npm test --workspace=ai.matey.backend
```

Adding New Middleware

Create middleware file:

cd packages/ai.matey.middleware
touch src/newmiddleware.ts

Implement:

export function createNewMiddleware(options) {
  return {
    name: 'new-middleware',
    async execute(request, next) {
      // Implementation
      return await next(request);
    }
  };
}

Test and export

Troubleshooting

Build Failures

# Clean and rebuild
npm run clean
npm install
npm run build

Test Failures

# Run specific test
npm test -- bridge.test.ts

# Update snapshots
npm test -- -u

Type Errors

# Check types
npx tsc --noEmit

# Rebuild types
npm run build --workspace=ai.matey.types

Dependency Issues

# Clear npm cache
npm cache clean --force

# Reinstall
rm -rf node_modules
npm install

Best Practices

Write tests first (TDD)
Keep PRs focused - one feature/fix per PR
Update docs with code changes
Add examples for new features
Run linter before committing
Test edge cases
Handle errors gracefully

Next Steps

Architecture Guide - Understanding the codebase
Contributing Guide - General contribution guidelines

Happy coding! 🚀