Add comprehensive GitHub Copilot instructions for hey-api/openapi-ts repository

Co-authored-by: mrlubos <[email protected]>

Author: Copilot

.github/copilot-instructions.md

@@ -0,0 +1,210 @@
+# Hey API OpenAPI TypeScript Codegen
+
+OpenAPI TypeScript is a CLI tool and library for generating TypeScript clients, SDKs, validators, and schemas from OpenAPI specifications. This is a monorepo built with pnpm workspaces, Turbo build orchestration, and TypeScript.
+
+**ALWAYS reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**
+
+## Working Effectively
+
+### Prerequisites and Setup
+
+- Install Node.js 20.19.0+ or 24.7.0+ (see `.nvmrc` for current version: 24.7.0)
+- Install pnpm globally: `npm install -g [email protected]`
+- Clone the repository and run setup commands
+
+### Bootstrap, Build, and Test
+
+```bash
+# Install dependencies (takes ~1m 20s)
+pnpm install
+
+# Build packages only (NEVER CANCEL - takes ~2m 15s - set timeout to 180+ seconds)
+pnpm build --filter="@hey-api/**"
+
+# Build all including examples (NEVER CANCEL - takes ~5+ minutes - set timeout to 360+ seconds)
+pnpm build
+
+# Run tests (takes ~1m 5s - set timeout to 120+ seconds)
+# NOTE: Some network-dependent tests may fail in sandboxed environments
+pnpm test
+
+# Run linting (takes ~35s)
+pnpm lint
+
+# Run type checking (NEVER CANCEL - takes ~1m 20s - set timeout to 120+ seconds)
+pnpm typecheck
+
+# Format code (takes ~35s)
+pnpm format
+```
+
+### Development Workflow
+
+```bash
+# Start development mode for main package (watches for changes)
+pnpm --filter @hey-api/openapi-ts dev
+
+# Start development server for examples (e.g., fetch example)
+pnpm --filter @example/openapi-ts-fetch dev
+# Server starts on http://localhost:5173/
+
+# Run CLI tool directly
+node packages/openapi-ts/bin/index.cjs --help
+# or after building
+npx @hey-api/openapi-ts --help
+```
+
+## Build and Test Details
+
+### **CRITICAL BUILD TIMING**
+
+- **NEVER CANCEL BUILD COMMANDS** - They may take 2-5+ minutes
+- `pnpm build --filter="@hey-api/**"`: ~2m 15s (packages only)
+- `pnpm build`: ~5+ minutes (includes docs and examples)
+- `pnpm install`: ~1m 20s
+- `pnpm test`: ~1m 5s
+- `pnpm typecheck`: ~1m 20s
+- `pnpm lint`: ~35s
+- `pnpm format`: ~35s
+
+### Build Issues and Workarounds
+
+- **Docs build may fail** due to pnpm version mismatch in VitePress - this is expected in some environments
+- Use `pnpm build --filter="@hey-api/**"` to build packages without docs
+- **Some tests may fail** in sandboxed environments due to network restrictions (OpenAPI spec downloads)
+- **Generated test files** in `packages/openapi-ts-tests/` contain auto-generated snapshots that may have linting warnings - this is expected
+- **Linting issues** in `.gen/snapshots/` directories are expected for generated code
+
+## Validation
+
+### Manual Testing Scenarios
+
+After making changes, ALWAYS validate with these scenarios:
+
+1. **CLI Functionality Test**:
+
+   ```bash
+   # Test CLI help
+   node packages/openapi-ts/bin/index.cjs --help
+
+   # Test CLI version
+   node packages/openapi-ts/bin/index.cjs --version
+
+   # Test basic code generation with a simple OpenAPI spec
+   # Create a minimal test spec and generate client code
+   node packages/openapi-ts/bin/index.cjs -i path/to/spec.json -o ./test-output --plugins "@hey-api/client-fetch" "@hey-api/typescript"
+   ```
+
+2. **Example Application Test**:
+
+   ```bash
+   # Start fetch example and verify it loads
+   pnpm --filter @example/openapi-ts-fetch dev
+   # Should start on http://localhost:5173/
+   ```
+
+3. **Development Mode Test**:
+   ```bash
+   # Start dev mode and make a small change to verify rebuilding
+   pnpm --filter @hey-api/openapi-ts dev
+   ```
+
+### Pre-commit Validation
+
+ALWAYS run these commands before committing or the CI will fail:
+
+```bash
+# Use lint:fix to auto-fix issues (some warnings in generated test files are expected)
+pnpm lint:fix
+
+# Run typecheck (can target specific packages with --filter)
+pnpm typecheck
+
+# Run tests (some network tests may fail in sandboxed environments)
+pnpm test
+```
+
+**NOTE**: Some linting warnings in generated test snapshot files (`.gen/snapshots/`) are expected and should be ignored. The `lint:fix` command will resolve actual source code issues.
+
+## Repository Structure
+
+### Key Packages
+
+- `packages/openapi-ts/` - Main CLI tool and library
+- `packages/codegen-core/` - Core code generation utilities
+- `packages/custom-client/` - Custom HTTP client implementations
+- `packages/nuxt/` - Nuxt.js integration
+- `packages/vite-plugin/` - Vite plugin
+
+### Examples
+
+- `examples/openapi-ts-fetch/` - Fetch client example (React + Vite)
+- `examples/openapi-ts-angular/` - Angular client example
+- `examples/openapi-ts-tanstack-react-query/` - TanStack React Query integration
+- `examples/openapi-ts-vue/` - Vue.js integration
+- Plus many more framework-specific examples
+
+### Configuration Files
+
+- `pnpm-workspace.yaml` - Workspace configuration
+- `turbo.json` - Turbo build configuration
+- `package.json` - Root package with workspace scripts
+- `.nvmrc` - Node.js version specification
+
+## Common Tasks
+
+### Working with the Main Package
+
+```bash
+# Install deps for main package
+pnpm --filter @hey-api/openapi-ts install
+
+# Build main package only
+pnpm --filter @hey-api/openapi-ts build
+
+# Test main package only
+pnpm --filter @hey-api/openapi-ts test
+
+# Start dev mode for main package
+pnpm --filter @hey-api/openapi-ts dev
+```
+
+### Working with Examples
+
+```bash
+# List all example packages
+ls examples/
+
+# Run specific example
+pnpm --filter @example/openapi-ts-fetch dev
+
+# Build all examples
+pnpm build --filter="@example/**"
+```
+
+### Debugging and Troubleshooting
+
+- Check `turbo.json` for task dependencies and configuration
+- Use `pnpm list` to see installed packages
+- Use `pnpm why <package>` to understand dependency chains
+- Check individual package `package.json` files for available scripts
+
+## CI/CD Pipeline
+
+The repository uses GitHub Actions (`.github/workflows/ci.yml`):
+
+- Tests on multiple Node.js versions (20.19.0, 22.12.0, 24.7.0)
+- Tests on multiple OS (macOS, Ubuntu, Windows)
+- Runs build, lint, typecheck, and test commands
+- Publishes preview packages on PRs
+
+## Performance Expectations
+
+- **Cold install**: ~1m 20s
+- **Cold build**: ~2-5m depending on scope
+- **Incremental builds**: ~30s in dev mode
+- **Test suite**: ~1m 5s
+- **Linting**: ~35s
+- **Type checking**: ~1m 20s
+
+Remember: This is a complex monorepo with many dependencies. Be patient with build times and always use appropriate timeouts for long-running commands.