Contributing to Ralph TUI

Thank you for your interest in contributing to Ralph TUI! This document provides guidelines and information for contributors.

Getting Started

Prerequisites

Bun >= 1.0.0 (runtime and package manager)
Git for version control

Development Setup

# Clone the repository
git clone https://github.com/subsy/ralph-tui.git
cd ralph-tui

# Install dependencies
bun install

# Run the TUI in development mode
bun run ./src/cli.tsx

# Or use the dev script
bun run dev

Running Quality Checks

# Type checking
bun run typecheck

# Linting
bun run lint

# Fix lint issues automatically
bun run lint:fix

# Build the project
bun run build

Code Style

General Principles

Simplicity over cleverness - Write clear, maintainable code
Minimal changes - Make the smallest reasonable change to achieve the goal
No unrelated changes - Don't refactor or "improve" code outside your scope
Preserve comments - Only remove comments if they're provably false

TypeScript Conventions

Strict mode is enabled - all code must be fully typed
Use ReactNode return type for component functions (not JSX.Element)
Use ES modules (import/export) - the package is "type": "module"

File Headers

Every source file must start with an ABOUTME comment explaining the file's purpose:

/**
 * ABOUTME: Brief description of what this file does.
 * Additional context if needed.
 */

Directory Structure

src/
├── cli.tsx           # CLI entry point
├── commands/         # CLI command implementations
├── config/           # Configuration system
├── engine/           # Execution engine
├── interruption/     # Signal handling
├── logs/             # Iteration logging
├── plugins/
│   ├── agents/       # Agent plugins (claude, opencode, gemini, codex, kiro)
│   └── trackers/     # Tracker plugins (beads, json)
├── session/          # Session management
├── setup/            # Interactive setup wizard
├── templates/        # Prompt templates
└── tui/
    └── components/   # OpenTUI React components

Plugin Architecture

Tracker plugins go in src/plugins/trackers/builtin/
Agent plugins go in src/plugins/agents/builtin/
Use the factory pattern with singleton registries
Extend BaseTrackerPlugin or BaseAgentPlugin for common functionality

TUI Components

Components go in src/tui/components/
Use OpenTUI's React bindings (@opentui/react)
Export components from src/tui/components/index.ts

Making Changes

Workflow

Create a branch from main
Make your changes following the code style guidelines
Run quality checks: bun run typecheck && bun run lint
Test your changes manually with bun run ./src/cli.tsx
Commit with a descriptive message
Open a pull request

Commit Messages

Use conventional commit format:

type: brief description

Longer explanation if needed.

Types:

feat: - New feature
fix: - Bug fix
docs: - Documentation changes
refactor: - Code refactoring
chore: - Maintenance tasks

Examples:

feat: add support for custom prompt templates
fix: handle empty task lists gracefully
docs: update README with configuration examples

Pull Request Guidelines

One feature per PR - Keep changes focused
Update documentation if adding features - any new or changed functionality must include documentation updates
Ensure CI passes - typecheck, lint, and tests must succeed
Meet test coverage requirements - PRs must have >50% test coverage on new and changed lines (enforced by Codecov)
Describe your changes in the PR description

Contribution Requirements Checklist

All contributions must meet these requirements before merging:

Code Quality

Test coverage >50% - New/changed code must have at least 50% unit test coverage (enforced by Codecov)
Typecheck passes - Run bun run typecheck with no errors
Lint passes - Run bun run lint with no errors
Build succeeds - Run bun run build with no errors

Documentation

Docs for user-facing changes - Any new or changed user-facing behavior must include documentation updates
ABOUTME header - All new source files must have an ABOUTME comment header

Adding New Features

Adding a New Tracker Plugin

Complete this checklist when adding a new tracker plugin:

Source Code

Registration

Import factory in src/plugins/trackers/builtin/index.ts
Add to builtinTrackers object
Add to registerBuiltinTrackers() function
Export the factory function

Tests

Documentation

Create docs page: website/content/docs/plugins/trackers/<tracker-name>.mdx
Include sections: Overview, Prerequisites, Basic Usage, Configuration, Options Reference, How It Works, Troubleshooting
Add to navigation: website/lib/navigation.ts (in Trackers section)

Adding a New Agent Plugin

Complete this checklist when adding a new agent plugin:

Source Code

Registration

Import factory in src/plugins/agents/builtin/index.ts
Add to registerBuiltinAgents() function
Export the factory function
Export the plugin class
Add to AGENT_ID_MAP in src/setup/skill-installer.ts

Tests

Documentation

Adding a New CLI Command

Create a command file in src/commands/
Export from src/commands/index.ts
Add handling in src/cli.tsx
Update the help text in showHelp()
Create tests in tests/commands/ or src/commands/*.test.ts
Update documentation if user-facing

Testing

Ralph TUI uses Bun's built-in test runner for unit and integration tests.

Running Tests

# Run all tests
bun test

# Run tests in watch mode (re-runs on file changes)
bun test --watch

# Run tests with coverage report
bun test --coverage

# Run specific test file
bun test tests/plugins/claude-agent.test.ts

# Run tests matching a pattern
bun test --grep "ExecutionEngine"

Test File Naming Conventions

Test files are placed in the tests/ directory
Test files must end with .test.ts
Mirror the src/ structure: src/plugins/agents/ → tests/plugins/
Name test files after the module they test: claude.ts → claude-agent.test.ts

Test Directory Structure

tests/
├── commands/           # CLI command tests
├── engine/             # Execution engine tests
├── factories/          # Reusable test data factories
│   ├── agent-config.ts
│   ├── prd-data.ts
│   ├── session-state.ts
│   ├── tracker-config.ts
│   └── tracker-task.ts
├── fixtures/           # Static test data (JSON, configs)
├── mocks/              # Mock implementations
│   ├── agent-responses.ts
│   ├── child-process.ts
│   └── file-system.ts
├── plugins/            # Plugin tests (agents, trackers)
├── tui/                # TUI component tests
├── utils/              # Utility function tests
└── index.ts            # Test utilities exports

Writing New Tests

Every test file must start with an ABOUTME comment:

/**
 * ABOUTME: Tests for the ExecutionEngine.
 * Tests state machine transitions, iteration logic, and error handling.
 */

import { describe, test, expect, beforeEach, afterEach, mock } from 'bun:test';

Basic Test Structure

describe('ModuleName', () => {
  let instance: MyClass;

  beforeEach(() => {
    instance = new MyClass();
  });

  afterEach(async () => {
    await instance.dispose();
  });

  describe('methodName', () => {
    test('should do expected behavior', () => {
      const result = instance.methodName();
      expect(result).toBe(expectedValue);
    });

    test('should handle edge case', () => {
      expect(() => instance.methodName(null)).toThrow();
    });
  });
});

Using Factories

Factories provide consistent test data with sensible defaults. Import from tests/factories/:

import { createTrackerTask, createTrackerTasks } from '../factories/tracker-task.js';
import { createSessionState } from '../factories/session-state.js';

test('should process task', () => {
  // Create with defaults
  const task = createTrackerTask();

  // Create with overrides
  const customTask = createTrackerTask({
    id: 'custom-id',
    status: 'in_progress',
    priority: 1,
  });

  // Create multiple tasks
  const tasks = createTrackerTasks(5, { status: 'open' });
});

Using Mocks

Mocks simulate external dependencies. Import from tests/mocks/:

import { createMockAgentPlugin, createSuccessfulExecution } from '../mocks/agent-responses.js';
import { createMockChildProcess } from '../mocks/child-process.js';
import { createMockFileSystem } from '../mocks/file-system.js';

test('should execute agent', async () => {
  const mockAgent = createMockAgentPlugin();
  const mockExecution = createSuccessfulExecution('Task completed');
  
  // Use bun:test mock for module mocking
  mock.module('../../src/plugins/agents/registry.js', () => ({
    getAgentRegistry: () => ({
      getInstance: () => Promise.resolve(mockAgent),
    }),
  }));
});

Spying on Methods

import { spyOn } from 'bun:test';

test('should call dependency', () => {
  const spy = spyOn(dependency, 'method');
  
  instance.doSomething();
  
  expect(spy).toHaveBeenCalledTimes(1);
  expect(spy).toHaveBeenCalledWith('expected-arg');
});

Coverage Requirements

PRs must have >50% test coverage on new/changed lines (enforced by Codecov patch check)
Aim for 80%+ line coverage on new code when possible
Critical paths (engine, plugins) should have higher coverage
Run bun test --coverage to check coverage locally
Coverage reports are generated in CI and uploaded to Codecov

Note: If your PR adds new functionality, you must include tests that cover at least 50% of the new/changed lines. PRs that fail the Codecov patch check will not be merged.

Manual Testing

For integration testing with actual AI agents:

# Test the TUI
bun run ./src/cli.tsx

# Test specific commands
bun run ./src/cli.tsx run --help
bun run ./src/cli.tsx plugins agents
bun run ./src/cli.tsx config show

When testing changes manually:

Test with different trackers (beads, json)
Test with different agents (claude, opencode)
Test TUI keyboard navigation
Test headless mode
Test error conditions

Reporting Issues

When reporting issues, please include:

Ralph TUI version (ralph-tui --version or check package.json)
Bun version (bun --version)
Operating system
Steps to reproduce
Expected behavior
Actual behavior
Relevant logs (from .ralph-tui/iterations/)

Questions?

If you have questions about contributing, feel free to:

Open a GitHub issue with the question label
Check existing issues for similar questions

Thank you for contributing to Ralph TUI!

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to Ralph TUI

Getting Started

Prerequisites

Development Setup

Running Quality Checks

Code Style

General Principles

TypeScript Conventions

File Headers

Directory Structure

Plugin Architecture

TUI Components

Making Changes

Workflow

Commit Messages

Pull Request Guidelines

Contribution Requirements Checklist

Code Quality

Documentation

Adding New Features

Adding a New Tracker Plugin

Source Code

Registration

Tests

Documentation

Adding a New Agent Plugin

Source Code

Registration

Tests

Documentation

Adding a New CLI Command

Testing

Running Tests

Test File Naming Conventions

Test Directory Structure

Writing New Tests

Basic Test Structure

Using Factories

Using Mocks

Spying on Methods

Coverage Requirements

Manual Testing

Reporting Issues

Questions?