codetyper.cli/docs/CONTRIBUTING.md

Contributing to CodeTyper CLI

Thank you for your interest in contributing to CodeTyper CLI! This document provides guidelines and instructions for contributing.

Code of Conduct

Please be respectful and constructive in all interactions. We welcome contributors of all experience levels.

Getting Started

Prerequisites

• Bun >= 1.0.0
• Git

Setup

1. Fork the repository
2. Clone your fork:

   git clone https://github.com/YOUR_USERNAME/codetyper.cli.git
   cd codetyper.cli
   

3. Install dependencies:

   bun install
   

4. Build the project:

   bun run build
   

5. Link for local testing:

   bun link
   

Development Workflow

# Start development mode
bun run dev

# Watch mode with auto-rebuild
bun run dev:watch

# Run tests
bun test

# Type check
bun run typecheck

# Lint code
bun run lint

# Format code
bun run prettier

How to Contribute

Reporting Bugs

1. Check existing issues to avoid duplicates
2. Create a new issue with:
   • Clear, descriptive title
   • Steps to reproduce
   • Expected vs actual behavior
   • Environment details (OS, Node version, provider)
   • Relevant logs or screenshots

Suggesting Features

1. Check existing issues for similar requests
2. Create a feature request with:
   • Clear description of the feature
   • Use cases and motivation
   • Proposed implementation (optional)

Submitting Pull Requests

1. Create a branch from main:

   git checkout -b feature/your-feature-name
   

2. Make your changes following our coding standards

3. Write/update tests if applicable

4. Ensure all tests pass:

   bun test
   

5. Commit with clear messages:

   git commit -m "feat: add new feature description"
   

6. Push and create a Pull Request

Commit Message Format

We follow Conventional Commits:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• style: - Code style changes (formatting, etc.)
• refactor: - Code refactoring
• test: - Adding or updating tests
• chore: - Maintenance tasks

Examples:

feat: add permission caching for faster lookups
fix: resolve race condition in agent loop
docs: update README with new CLI options

Coding Standards

TypeScript

• Use TypeScript strict mode
• Define explicit types (avoid any when possible)
• Use interfaces for object shapes
• Export types that are part of the public API

Code Style

• Use 2 spaces for indentation
• Use single quotes for strings
• Add trailing commas in multi-line structures
• Keep lines under 100 characters when reasonable

File Organization

src/
├── index.ts          # Entry point only
├── api/              # API clients (Copilot, Ollama, Brain)
├── commands/         # CLI command implementations
├── constants/        # Centralized constants
├── interfaces/       # Interface definitions
├── prompts/          # System prompts and prompt templates
├── providers/        # LLM provider integrations
├── services/         # Business logic services
│   ├── core/         # Core agent and orchestration
│   ├── hooks/        # Lifecycle hooks
│   ├── plugin/       # Plugin management
│   └── session/      # Session management and forking
├── skills/           # Agent skill definitions
├── stores/           # Zustand state stores
├── tools/            # Agent tools (bash, read, write, edit, etc.)
├── tui-solid/        # Terminal UI (Solid.js + OpenTUI)
│   ├── components/   # Reusable UI components
│   ├── context/      # Solid.js context providers
│   ├── routes/       # TUI route components
│   └── ui/           # Base UI primitives
├── types/            # Type definitions
├── ui/               # Print-mode UI components
└── utils/            # Utility functions

Testing

• Write tests for non-UI logic
• Place tests in tests/ directory or colocate with source files
• Name test files *.test.ts
• Use descriptive test names
• Tests run with Vitest via bun test

describe('PermissionManager', () => {
  it('should match wildcard patterns correctly', () => {
    // ...
  });
});

Documentation

• Add JSDoc comments for public APIs
• Update README for user-facing changes
• Update CHANGELOG for notable changes

Project Structure

Key Files

File	Purpose
src/index.ts	CLI entry point, command registration
src/services/core/agent.ts	Agent loop, tool orchestration
src/services/permissions/	Permission system
src/services/hooks/	Lifecycle hooks
src/services/plugin/	Plugin management
src/services/session/	Session forking
src/tui-solid/app.tsx	Root TUI component (Solid.js)
src/tui-solid/components/	UI components
src/stores/	Zustand state management
src/prompts/	System prompt templates
src/tools/	Tool implementations

Adding a New Provider

1. Create src/providers/yourprovider.ts
2. Implement the Provider interface
3. Register in src/providers/index.ts
4. Add authentication in src/commands/login.ts
5. Update documentation

Adding a New Tool

1. Create src/tools/yourtool.ts
2. Define parameters with Zod schema
3. Implement execute function
4. Register in src/tools/index.ts
5. Add permission handling if needed

Adding a Hook Event

1. Add event type to src/types/hooks.ts
2. Add constants to src/constants/hooks.ts
3. Add input type for the event
4. Implement execution in src/services/hooks-service.ts
5. Call hook from appropriate location

Creating a Plugin

1. Create directory in .codetyper/plugins/{name}/
2. Add plugin.json manifest
3. Add tools in tools/*.ts
4. Add commands in commands/*.md
5. Add hooks in hooks/*.sh

Adding Vim Bindings

1. Add binding to vim constants in src/constants/
2. Add action handler in the vim store (src/stores/)
3. Update documentation

Questions?

• Open a GitHub issue for questions
• Tag with question label

License

By contributing, you agree that your contributions will be licensed under the MIT License.