Contributing

Help improve Go Bananas! for everyone.

Welcome Contributors!

Go Bananas! is an open-source project and we welcome contributions of all kinds:

• 🐛 Bug reports and fixes
• ✨ New features
• 📖 Documentation improvements
• 🧪 Test coverage
• 💡 Ideas and feedback

Getting Started

Prerequisites

• Node.js 24
• npm or pnpm
• Cloudflare account (for testing deployments)
• Git

Development Setup

# Clone the repository
git clone https://github.com/davendra/go-bananas-app.git
cd go-bananas-app

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Start development server
npm run dev

Running Tests

# Type checking
npm run typecheck

# Unit tests
npm test

# All tests
npm run test:all

Contribution Workflow

1. Find or Create an Issue

• Check existing issues
• For new features, open a discussion first
• For bugs, include steps to reproduce

2. Fork and Branch

# Fork on GitHub, then clone
git clone https://github.com/your-username/go-bananas.git

# Create feature branch
git checkout -b feature/your-feature-name

3. Make Changes

• Follow the code style guide
• Add tests for new functionality
• Update documentation as needed

4. Test Locally

npm run typecheck
npm test
npm run dev  # Manual testing

5. Commit and Push

# Commit with conventional commit format
git commit -m "feat: add new feature description"

# Push to your fork
git push origin feature/your-feature-name

6. Open Pull Request

• Use the PR template
• Link related issues
• Wait for review

Code Style

TypeScript

• Use TypeScript strict mode
• Prefer interface over type for objects
• Use explicit return types for functions
• Avoid any - use unknown if type is uncertain

// Good
interface ImageMetadata {
  id: number;
  width: number;
  height: number;
}

async function processImage(data: unknown): Promise<ImageMetadata> {
  // Implementation
}

// Avoid
async function processImage(data: any) {
  // Implementation
}

Formatting

We use Prettier with default settings:

# Format all files
npx prettier --write .

# Check formatting
npx prettier --check .

Naming Conventions

Type	Convention	Example
Files	kebab-case	image-storage.ts
Classes	PascalCase	ImageStorageService
Functions	camelCase	processImage
Constants	UPPER_SNAKE	MAX_IMAGE_SIZE
Interfaces	PascalCase	ImageMetadata

Project Structure

go-bananas/
├── src/
│   ├── index.ts           # Worker entry point
│   ├── mcp/
│   │   └── agent.ts       # MCP Durable Object
│   ├── tools/             # MCP tool implementations
│   ├── api/               # REST API endpoints
│   ├── auth/              # Authentication
│   ├── services/          # Business logic
│   └── types/             # TypeScript definitions
├── frontend/              # React console
├── migrations/            # Database migrations
├── tests/                 # Test files
├── doc-site/              # This documentation
└── scripts/               # Utility scripts

Adding a New MCP Tool

1. Create Tool File

// src/tools/my-new-tool.ts
import { z } from 'zod';
import { trackUsage } from '../services/usage';
import { Env } from '../types';

// 1. Define input schema
export const MyNewToolInputSchema = z.object({
  param1: z.string().min(1).describe('First parameter'),
  param2: z.number().optional().describe('Optional parameter'),
});

export type MyNewToolInput = z.infer<typeof MyNewToolInputSchema>;

// 2. Define result type
export interface MyNewToolResult {
  success: boolean;
  data: any;
}

// 3. Implement handler
export async function myNewTool(
  env: Env,
  tenantId: string,
  sessionId: string,
  geminiApiKey: string,
  params: MyNewToolInput
): Promise<MyNewToolResult> {
  const startTime = Date.now();

  try {
    // Validate input
    const input = MyNewToolInputSchema.parse(params);

    // Implement logic
    const result = await doSomething(input);

    // Track usage
    await trackUsage(env.DB, {
      tenantId,
      sessionId,
      operation: 'my_new_tool',
      imagesGenerated: 0,
      durationMs: Date.now() - startTime,
    });

    return { success: true, data: result };
  } catch (error) {
    await trackUsage(env.DB, {
      tenantId,
      sessionId,
      operation: 'my_new_tool_failed',
      durationMs: Date.now() - startTime,
    });
    throw error;
  }
}

// 4. Export tool definition
export function getMyNewToolDefinition() {
  return {
    name: 'my_new_tool',
    description: 'What this tool does',
    inputSchema: MyNewToolInputSchema,
  };
}

2. Register in Agent

// src/mcp/agent.ts
import { myNewTool, MyNewToolInputSchema } from '../tools/my-new-tool';

// In constructor
this.registerMyNewTool();

// Add registration method
private registerMyNewTool() {
  this.server.tool(
    'my_new_tool',
    'What this tool does',
    MyNewToolInputSchema.shape,
    async (params) => this.handleMyNewTool(params)
  );
}

// Add handler
private async handleMyNewTool(params: unknown) {
  const result = await myNewTool(
    this.env,
    this.tenant.tenantId,
    this.sessionId,
    this.tenant.geminiApiKey,
    params as MyNewToolInput
  );
  return {
    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
  };
}

3. Add Tests

// tests/my-new-tool.test.ts
import { describe, it, expect } from 'vitest';
import { MyNewToolInputSchema, myNewTool } from '../src/tools/my-new-tool';

describe('myNewTool', () => {
  it('validates input correctly', () => {
    const valid = MyNewToolInputSchema.parse({ param1: 'test' });
    expect(valid.param1).toBe('test');
  });

  it('rejects invalid input', () => {
    expect(() => MyNewToolInputSchema.parse({})).toThrow();
  });
});

4. Update Documentation

• Add to MCP tools documentation
• Update tool count in CLAUDE.md
• Add examples in README

Testing Guidelines

Unit Tests

Test individual functions in isolation:

import { describe, it, expect, vi } from 'vitest';

describe('functionName', () => {
  it('should handle normal case', () => {
    const result = functionName(input);
    expect(result).toBe(expected);
  });

  it('should handle edge case', () => {
    // Test edge cases
  });

  it('should throw on invalid input', () => {
    expect(() => functionName(invalid)).toThrow();
  });
});

Integration Tests

Test API endpoints and database interactions:

import { unstable_dev } from 'wrangler';

describe('API Integration', () => {
  let worker: UnstableDevWorker;

  beforeAll(async () => {
    worker = await unstable_dev('src/index.ts', {
      experimental: { disableExperimentalWarning: true },
    });
  });

  afterAll(async () => {
    await worker.stop();
  });

  it('returns images list', async () => {
    const resp = await worker.fetch('/api/images', {
      headers: { 'X-API-Key': 'sk_test_xxx' },
    });
    expect(resp.status).toBe(200);
  });
});

Documentation

Writing Documentation

• Use VitePress markdown
• Include code examples
• Add Mermaid diagrams for complex flows
• Use admonitions for important notes

::: tip
This is a helpful tip.
:::

::: warning
This is a warning message.
:::

::: danger
This is a dangerous operation.
:::

Testing Documentation

cd doc-site
npm install
npm run dev

Pull Request Guidelines

PR Title Format

Use conventional commits:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation only
• test: - Adding tests
• refactor: - Code refactoring
• chore: - Maintenance tasks

PR Checklist

• [ ] Tests added/updated
• [ ] Documentation updated
• [ ] TypeScript types checked
• [ ] No console.log statements
• [ ] Follows code style

Review Process

1. Automated checks must pass
2. At least one maintainer review
3. All comments addressed
4. Squash and merge

Community

Communication

• GitHub Issues - Bug reports and features
• Discussions - Questions and ideas
• Pull Requests - Code contributions

Code of Conduct

Be respectful and inclusive. We follow the Contributor Covenant.

Next Steps

• Development Guide →
• Code Style →
• Testing →