effect-cli-tui: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Prerequisites

bun is required to work with this codebase.

• Install: https://bun.sh
• Version: Node 20+ compatible
• Commands: Use bun instead of npm, pnpm, or yarn

All commands in this guide use bun (not pnpm/npm).

Quick Commands

Build & Development

bun run build              # Build with tsup
bun test                   # Run all tests once
bun test:watch            # Run tests in watch mode
bun test:ui               # Run tests with interactive UI
bun test:coverage         # Run tests with coverage report
bun run lint              # Run ESLint
bun run format            # Format code with Prettier
bun run type-check        # Run TypeScript type checking (non-emitting)

Full Validation Pipeline

bun run type-check && bun run lint && bun test && bun run build

Single Test File

bun test __tests__/colors.test.ts
bun test -- --watch __tests__/integration.test.ts

Code Style and Best Practices

Naming Conventions

• Use descriptive variable names with auxiliary verbs: isLoading, hasError, canExecute, shouldDisplay
• Use lowercase with dashes for directory names: src/core, src/interactive, __tests__/integration
• Use PascalCase for classes and components: TUIHandler, EffectCLI
• Use camelCase for functions and variables: displayJson, createPrompt, buildWorkflow

Code Organization

• Structure files with exported main exports first, then subcomponents/helpers
• Use modularization over code duplication — extract reusable logic into separate utility functions or modules
• Keep functions single-responsibility — each function should do one thing well
• Use JSDoc comments for all exported functions and methods to improve IDE intellisense

/**
 * Display a message with optional styling.
 *
 * @param message - The message to display
 * @param options - Display configuration options
 * @returns Effect that displays the message
 *
 * @example
 * ```ts
 * yield* _(display('Hello!', { type: 'success' }))
 * ```
 */
export const display = (message: string, options?: DisplayOptions): Effect<void> => {
  // implementation
}