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

• Node.js >= 18.0.0
• npm or yarn
• 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:

   npm install
   

4. Build the project:

   npm run build
   

5. Link for local testing:

   npm link
   

Development Workflow

# Start TypeScript watch mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

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:

   npm 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
├── commands/         # CLI command implementations
├── constants/        # Centralized constants
├── interfaces/       # Interface definitions
├── providers/        # LLM provider integrations
├── services/         # Business logic services
│   ├── hooks-service.ts    # Lifecycle hooks
│   ├── plugin-service.ts   # Plugin management
│   ├── plugin-loader.ts    # Plugin discovery
│   └── session-fork-service.ts  # Session forking
├── stores/           # Zustand state stores
│   └── vim-store.ts  # Vim mode state
├── tools/            # Agent tools (bash, read, write, edit)
├── tui/              # Terminal UI components
│   ├── components/   # Reusable UI components
│   └── hooks/        # React hooks (useVimMode, etc.)
└── types/            # Type definitions

Testing

• Write tests for non-UI logic
• Place tests in tests/ directory
• Name test files *.test.ts
• Use descriptive test names

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/agent.ts	Agent loop, tool orchestration
src/services/permissions.ts	Permission system
src/services/hooks-service.ts	Lifecycle hooks
src/services/plugin-service.ts	Plugin management
src/services/session-fork-service.ts	Session forking
src/commands/chat-tui.tsx	Main TUI command
src/tui/App.tsx	Root TUI component
src/tui/store.ts	Zustand state management
src/stores/vim-store.ts	Vim mode state
src/tui/hooks/useVimMode.ts	Vim keyboard handling

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_DEFAULT_BINDINGS in src/constants/vim.ts
2. Add action handler in src/tui/hooks/useVimMode.ts
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.