Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
218 lines (159 loc) · 5.79 KB

CONTRIBUTING.md

File metadata and controls

218 lines (159 loc) · 5.79 KB
Raw

Contributing to Repatch

Thank you for your interest in contributing! This guide covers the development workflow, coding standards, and how to submit changes.

Quick Start

# Clone and install
git clone https://github.com/Sagar-024/Repatch
cd Repatch
npm install

# Run tests
npm test

# Build
npm run build

# Run CLI locally
node dist/index.js --help

Development Workflow

  1. Pick an issue — Check Issues or propose new work
  2. Create a branch — git checkout -b feature/my-feature
  3. Make changes — Follow coding standards below
  4. Test — npm test and npm run build must pass
  5. Commit — Use conventional commits (see below)
  6. Push & PR — Open a PR against main

Coding Standards

TypeScript

  • Strict mode — All code must pass tsc --noEmit
  • No any — Use proper types, unknown for truly dynamic values
  • Zod for validation — All config/input validation uses Zod schemas
  • Interfaces over types — Prefer interface for object shapes

Code Style

  • ESLint + Prettier — Run npm run lint before committing
  • Logger — Use logger from ../utils/logger.ts (not console.log)
    • logger.info() — user-facing info
    • logger.debug() — verbose (requires DEBUG=1)
    • logger.warn() — warnings
    • logger.error() — errors
    • logger.succeed() / logger.fail() — step completion
  • Error handling — Always try/catch async operations, use safeLogError() for LLM errors
  • No dead code — Remove unused imports, functions, files

Architecture Conventions

  • Steps — Each step in src/orchestrator/steps/ implements Step interface
  • Tools — Register in src/tools/registry.ts with Zod schema + availableInSteps
  • Providers — Implement LLMProvider in src/inference/provider.ts
  • Sandbox — Implement SandboxExecutor in src/sandbox/

Testing

# All tests
npm test

# Watch mode
npm run test:watch

# Single test file
npx vitest run tests/orchestrator/machine.test.ts

Test Guidelines

  • Unit tests for pure functions (sanitize, redact, cost, Nixpacks detection)
  • Integration tests for orchestrator steps (use mocked providers)
  • No live LLM calls in tests — use createMockProvider()
  • Coverage — Aim for >80% on new code

Commit Convention

Use Conventional Commits:

type(scope): short description

[optional body]

[optional footer]

Types

Type Use Case
feat New feature
fix Bug fix
refactor Code restructuring
docs Documentation only
test Adding/updating tests
chore Maintenance (deps, scripts, CI)
perf Performance improvement
security Security fix

Examples

feat(orchestrator): add checkpoint resume via --resume flag
fix(inference): redact API keys in Gemini provider errors
refactor(tools): unify run_command and run_local_command interface
docs: add ARCHITECTURE.md with mermaid diagrams
test(sanitize): add 28 prompt injection test cases

PR Checklist

  • npm run build passes (no TypeScript errors)
  • npm test passes (98+ tests)
  • npm run lint passes
  • Conventional commit messages
  • No console.log — use logger
  • New features have tests
  • Documentation updated if user-facing

Project Structure

src/
├── index.ts                      # CLI entry
├── orchestrator/
│   ├── machine.ts                # State machine
│   └── steps/                    # 7 step implementations
├── inference/
│   ├── provider.ts               # LLMProvider interface
│   └── *-provider.ts             # 4 provider implementations
├── sandbox/
│   ├── docker.ts                 # Docker execution
│   └── local.ts                  # Local execution (Nixpacks)
├── tools/
│   ├── registry.ts               # Tool definitions
│   └── index.ts                  # Tool implementations
├── adapters/
│   └── github.ts                 # GitHub API
├── utils/
│   ├── sanitize.ts               # Prompt injection defense
│   ├── redact.ts                 # Secret redaction
│   ├── cost.ts                   # Token cost tracking
│   └── logger.ts                 # Unified logging
└── config.ts                     # Config schema

Adding a New Step

  1. Create src/orchestrator/steps/my-step.ts implementing Step interface
  2. Define prompt in getPrompt() method
  3. Declare available tools via getAvailableTools()
  4. Register in src/orchestrator/machine.ts step order
  5. Add tests in tests/orchestrator/steps/

Adding a New Tool

  1. Define schema + handler in src/tools/registry.ts
  2. Add to toolRegistry with availableInSteps array
  3. Implement in src/tools/index.ts if complex logic
  4. Add tests

Adding a New LLM Provider

  1. Create src/inference/my-provider.ts implementing LLMProvider
  2. Implement complete() and streamComplete()
  3. Transform tools to provider's format in transformTools()
  4. Use safeLogError() for all error logging
  5. Register in src/inference/provider.ts factory

Security

  • Never commit secrets — .repatch.yaml is gitignored
  • Redact secrets — Use safeLogError() for all LLM error paths
  • Sanitize input — User data wrapped via wrapUserData() before prompts
  • Path traversal — All file writes validated in machine.ts

Release Process

Maintainers only:

# Bump version in package.json
npm version patch|minor|major

# Push tags
git push origin main --tags

# GitHub Actions builds binaries, creates release, updates Homebrew