Contributing

Development Setup

Prerequisites

• Node.js v22+
• Bun v1.0+ (runtime for the web server and binary compilation)
• pnpm v9+ (package manager)
• A coding-agent CLI for running loops — rauf is optimized for and defaults to Claude Code

Getting Started

git clone https://github.com/your-org/rauf.git
cd rauf
pnpm install
pnpm build

Development Commands

pnpm install          # Install all dependencies
pnpm build            # Build all packages
pnpm test             # Run all tests (Vitest)
pnpm typecheck        # TypeScript type checking (pnpm -r typecheck)
pnpm lint             # ESLint across all packages
pnpm format:check     # Prettier format check
pnpm format           # Prettier auto-format
pnpm dev              # Start Vite dev server for the web frontend
pnpm compile          # Build + compile single binary (./rauf-bin)

Running Individual Packages

# Core tests only
cd packages/core && pnpm test

# CLI tests only
cd packages/cli && pnpm test

# Web tests only
cd packages/web && pnpm test

# Web dev server (frontend hot reload on :5174, API proxy to :5173)
cd packages/web && pnpm dev

Repository Layout

rauf/
├── packages/
│   ├── core/    — Shared business logic (discovery, installer, backlog, status, profile, template)
│   ├── loop/    — Loop runner engine (LoopRunner, events, claude process, signal parsing)
│   ├── cli/     — CLI tool (commands call core directly or HTTP when server is running)
│   └── web/     — Hono API server + React frontend (TanStack Router + Query)
├── artifacts/   — Canonical template files installed into target projects
│   └── variants/backlog-json/
├── docs/        — Specifications (ARCHITECTURE, SCHEMAS, SPEC-CORE, SPEC-CLI, SPEC-WEB)
├── scripts/     — Build scripts (embedded artifacts/assets generation, binary entry point)
└── .rauf/      — This project's own rauf loop state (self-hosting)

Architecture Rules

1. packages/core has zero imports from cli or web. All filesystem logic lives in core.
2. All file writes use atomic write (write .tmp then rename) with .bak backup for backlog.json.
3. Path sandboxing: Never write outside ROOT_DIRECTORY or ~/.rauf/. Validate with path.resolve() + startsWith().
4. The web server binds to 127.0.0.1 only. All mutation endpoints require X-Rauf-Request: true header.

Coding Conventions

• Strict TypeScript (strict: true, noUncheckedIndexedAccess: true)
• Named exports only (no default exports except where required by React)
• Prefer node: prefix for Node built-ins (node:fs, node:path)
• Error handling: return Result<T, E> types from core functions, never throw for expected errors
• File paths: always use path.resolve() before any operation
• JSON parsing: always wrap in try/catch, return structured errors
• Tests: colocate with source as *.test.ts

Testing

Tests use Vitest and are colocated with source files:

packages/core/src/backlog.ts
packages/core/src/backlog.test.ts

Run the full verification pipeline before submitting:

pnpm test && pnpm typecheck && pnpm lint && pnpm build && pnpm format:check

Specification Documents

Before implementing features, read the relevant spec in docs/:

Document	Covers
ARCHITECTURE.md	System architecture, data flow, package dependencies
SCHEMAS.md	All TypeScript types and JSON schemas
SPEC-CORE.md	Core package modules and logic
SPEC-CLI.md	CLI commands, flags, exit codes
SPEC-WEB.md	Web API endpoints and frontend components
SPEC-ARTIFACTS.md	Artifact templates (RAUF.md, CLAUDE_ADDON.md, etc.)

Self-Hosting

This repository is itself a rauf-managed project. The .rauf/ directory at the repo root is this project’s own rauf loop state. Run the loop with rauf loop run (direct mode) or rauf loop run --detached (server mode). The artifacts/variants/backlog-json/ directory contains the templates used when installing rauf into other projects. Do not confuse them.