{"owner":"hey-api","repo":"openapi-ts","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md",".github/copilot-instructions.md"],"files":{"CLAUDE.md":"# CLAUDE.md\n\nOpenAPI 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.\n\n## Quick Reference\n\n```bash\npnpm install                          # Install dependencies\npnpm build --filter=\"@hey-api/**\"     # Build packages only\npnpm build                            # Build everything (packages + examples + docs)\npnpm test                             # Run all tests\npnpm typecheck                        # Type check all packages\npnpm lint                             # Check formatting (oxfmt) + linting (oxlint)\npnpm lint:fix                         # Auto-fix formatting and linting\npnpm format                           # Format with oxfmt\n```\n\n### Shortcuts\n\n```bash\npnpm tt -- @hey-api/openapi-ts        # Test specific package\npnpm tw -- @hey-api/openapi-ts        # Test watch specific package\npnpm tu -- @hey-api/openapi-ts        # Update test snapshots\npnpm tb -- @hey-api/openapi-ts        # Build specific package\npnpm ty -- @hey-api/openapi-ts        # Typecheck specific package\n```\n\n### Development\n\n```bash\npnpm dev:ts                           # Watch mode for openapi-ts (runs from dev/)\npnpm dev:py                           # Watch mode for openapi-python (runs from dev/)\n```\n\n## Build Timing\n\n**Do not cancel build commands** - they take significant time:\n\n- `pnpm install`: ~1m 20s\n- `pnpm build --filter=\"@hey-api/**\"`: ~2m 15s\n- `pnpm build` (full): ~5+ minutes\n- `pnpm test`: ~1m 5s\n- `pnpm typecheck`: ~1m 20s\n- `pnpm lint`: ~35s\n\nSet timeouts accordingly (180s+ for builds, 120s+ for tests/typecheck).\n\n## Repository Structure\n\n```\npackages/\n  openapi-ts/          # Main CLI tool and library\n  openapi-python/      # Python DSL generation\n  codegen-core/        # Core code generation utilities\n  shared/              # Cross-package utilities (migrating out)\n  types/               # Shared type definitions\n  custom-client/       # Custom HTTP client implementations\n  nuxt/                # Nuxt.js integration\n  vite-plugin/         # Vite plugin\n  config-vite-base/    # Shared Vite base configuration\n  openapi-ts-tests/    # Test utilities and snapshots\nexamples/              # 16+ framework-specific examples\ndev/                   # Development environment (CLI testing configs)\nspecs/                 # OpenAPI test specifications\nscripts/               # Build and test scripts\nweb/                   # Astro website\n```\n\n## Tooling\n\n- **Package manager**: pnpm 10.28.2 (strict engine, exact versions)\n- **Node**: >=22.18.0 (see .nvmrc for exact version)\n- **Build**: Turbo 2.8.0 + tsdown + Rollup\n- **Language**: TypeScript 5.9.3, ESM only\n- **Formatter**: oxfmt 0.27.0 (single quotes via .oxfmtrc.json)\n- **Linter**: Oxlint with eslint, typescript, and oxc plugins; simple-import-sort, sort-destructure-keys, and typescript-sort-keys loaded as JS plugins\n- **Tests**: Vitest 3.2.4\n- **Pre-commit**: Husky + lint-staged (runs `pnpm format` + `pnpm lint:fix`)\n- **Python** (for openapi-python): Python >=3.10, mypy, ruff, line length 120\n- **Releases**: Changesets\n\n## Code Conventions\n\n- ESM modules only (`.mts`/`.mjs` extensions in builds)\n- UTF-8, LF line endings, 2-space indentation\n- Single quotes (enforced by oxfmt)\n- Imports sorted by eslint-plugin-simple-import-sort (via Oxlint `jsPlugins`)\n- Object/interface keys sorted alphabetically\n- Destructured keys sorted alphabetically\n\n## Refactoring Guidelines\n\nWhen refactoring existing code:\n\n- **Preserve all JSDoc comments** - Read the original file first and keep all existing documentation\n- **Match existing code patterns** - Look at similar files in the codebase for conventions\n- **Prefer `edit` over `write`** - Making targeted edits preserves comments better than rewriting files\n- **Check reference implementations** - For plugin work, use Valibot as a reference for proper patterns\n\n## Pre-commit Checklist\n\nRun before committing (Husky runs format + lint automatically, but also verify):\n\n```bash\npnpm lint:fix       # Auto-fix formatting and linting\npnpm typecheck      # Type check\npnpm test           # Run tests\n```\n\nSome linting warnings in `.gen/snapshots/` directories are expected for generated code.\n\n## Git Conventions\n\n- **Branch naming**: `feat/`, `fix/`, `chore/`, `refactor/`, `docs/` prefixes\n- **Commit messages**: Conventional Commits (`feat:`, `fix:`, `chore:`, `refactor:`, `ci:`, `docs:`)\n- **Releases**: Changesets-based, auto-publish on merge to main\n\n## Known Issues\n\n- Some tests may fail in sandboxed environments due to network restrictions (OpenAPI spec downloads)\n- Generated test files in `packages/openapi-ts-tests/` may have expected linting warnings\n",".github/copilot-instructions.md":"# Hey API OpenAPI TypeScript Codegen\n\nOpenAPI 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.\n\n**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.**\n\n## Working Effectively\n\n### Prerequisites and Setup\n\n- Install Node.js (see `.nvmrc` for recommended version)\n- Install pnpm globally: `npm install -g pnpm@10.15.1`\n- Clone the repository and run setup commands\n\n### Bootstrap, Build, and Test\n\n```bash\n# Install dependencies (takes ~1m 20s)\npnpm install\n\n# Build packages only (NEVER CANCEL - takes ~2m 15s - set timeout to 180+ seconds)\npnpm build --filter=\"@hey-api/**\"\n\n# Build all including examples (NEVER CANCEL - takes ~5+ minutes - set timeout to 360+ seconds)\npnpm build\n\n# Run tests (takes ~1m 5s - set timeout to 120+ seconds)\n# NOTE: Some network-dependent tests may fail in sandboxed environments\npnpm test\n\n# Run linting (takes ~35s)\npnpm lint\n\n# Run type checking (NEVER CANCEL - takes ~1m 20s - set timeout to 120+ seconds)\npnpm typecheck\n\n# Format code (takes ~35s)\npnpm format\n```\n\n### Development Workflow\n\n```bash\n# Start development mode for main package (watches for changes)\npnpm --filter @hey-api/openapi-ts dev\n\n# Start development server for examples (e.g., fetch example)\npnpm --filter @example/openapi-ts-fetch dev\n# Server starts on http://localhost:5173/\n\n# Run CLI tool directly\nnode packages/openapi-ts/dist/run.js --help\n# or after building\nnpx @hey-api/openapi-ts --help\n```\n\n## Build and Test Details\n\n### **CRITICAL BUILD TIMING**\n\n- **NEVER CANCEL BUILD COMMANDS** - They may take 2-5+ minutes\n- `pnpm build --filter=\"@hey-api/**\"`: ~2m 15s (packages only)\n- `pnpm build`: ~5+ minutes (includes docs and examples)\n- `pnpm install`: ~1m 20s\n- `pnpm test`: ~1m 5s\n- `pnpm typecheck`: ~1m 20s\n- `pnpm lint`: ~35s\n- `pnpm format`: ~35s\n\n### Build Issues and Workarounds\n\n- Use `pnpm build --filter=\"@hey-api/**\"` to build packages without docs\n- **Some tests may fail** in sandboxed environments due to network restrictions (OpenAPI spec downloads)\n- **Generated test files** in `packages/openapi-ts-tests/` contain auto-generated snapshots that may have linting warnings - this is expected\n- **Linting issues** in `.gen/snapshots/` directories are expected for generated code\n\n## Validation\n\n### Manual Testing Scenarios\n\nAfter making changes, ALWAYS validate with these scenarios:\n\n1. **CLI Functionality Test**:\n\n   ```bash\n   # Test CLI help\n   node packages/openapi-ts/dist/run.js --help\n\n   # Test CLI version\n   node packages/openapi-ts/dist/run.js --version\n\n   # Test basic code generation with a simple OpenAPI spec\n   # Create a minimal test spec and generate client code\n   node packages/openapi-ts/dist/run.js -i path/to/spec.json -o ./test-output --plugins \"@hey-api/client-fetch\" \"@hey-api/typescript\"\n   ```\n\n2. **Example Application Test**:\n\n   ```bash\n   # Start fetch example and verify it loads\n   pnpm --filter @example/openapi-ts-fetch dev\n   # Should start on http://localhost:5173/\n   ```\n\n3. **Development Mode Test**:\n   ```bash\n   # Start dev mode and make a small change to verify rebuilding\n   pnpm --filter @hey-api/openapi-ts dev\n   ```\n\n### Pre-commit Validation\n\nALWAYS run these commands before committing or the CI will fail:\n\n```bash\n# Use lint:fix to auto-fix issues (some warnings in generated test files are expected)\npnpm lint:fix\n\n# Run typecheck (can target specific packages with --filter)\npnpm typecheck\n\n# Run tests (some network tests may fail in sandboxed environments)\npnpm test\n```\n\n**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.\n\n## Repository Structure\n\n### Key Packages\n\n- `packages/openapi-ts/` - Main CLI tool and library\n- `packages/codegen-core/` - Core code generation utilities\n- `packages/custom-client/` - Custom HTTP client implementations\n- `packages/nuxt/` - Nuxt.js integration\n- `packages/vite-plugin/` - Vite plugin\n\n### Examples\n\n- `examples/openapi-ts-fetch/` - Fetch client example (React + Vite)\n- `examples/openapi-ts-angular/` - Angular client example\n- `examples/openapi-ts-tanstack-react-query/` - TanStack React Query integration\n- `examples/openapi-ts-vue/` - Vue.js integration\n- Plus many more framework-specific examples\n\n### Configuration Files\n\n- `pnpm-workspace.yaml` - Workspace configuration\n- `turbo.json` - Turbo build configuration\n- `package.json` - Root package with workspace scripts\n- `.nvmrc` - Node.js version specification\n\n## Common Tasks\n\n### Working with the Main Package\n\n```bash\n# Install deps for main package\npnpm --filter @hey-api/openapi-ts install\n\n# Build main package only\npnpm --filter @hey-api/openapi-ts build\n\n# Test main package only\npnpm --filter @hey-api/openapi-ts test\n\n# Start dev mode for main package\npnpm --filter @hey-api/openapi-ts dev\n```\n\n### Working with Examples\n\n```bash\n# List all example packages\nls examples/\n\n# Run specific example\npnpm --filter @example/openapi-ts-fetch dev\n\n# Build all examples\npnpm build --filter=\"@example/**\"\n```\n\n### Debugging and Troubleshooting\n\n- Check `turbo.json` for task dependencies and configuration\n- Use `pnpm list` to see installed packages\n- Use `pnpm why <package>` to understand dependency chains\n- Check individual package `package.json` files for available scripts\n\n## CI/CD Pipeline\n\nThe repository uses GitHub Actions (`.github/workflows/ci.yml`):\n\n- Tests on multiple Node.js versions\n- Tests on multiple OS (macOS, Ubuntu, Windows)\n- Runs build, lint, typecheck, and test commands\n- Publishes preview packages on PRs\n\n## Performance Expectations\n\n- **Cold install**: ~1m 20s\n- **Cold build**: ~2-5m depending on scope\n- **Incremental builds**: ~30s in dev mode\n- **Test suite**: ~1m 5s\n- **Linting**: ~35s\n- **Type checking**: ~1m 20s\n\nRemember: This is a complex monorepo with many dependencies. Be patient with build times and always use appropriate timeouts for long-running commands.\n"}}