klasik 1.0.41 → 2.0.1

package/README.md

@@ -1,1328 +1,824 @@
-# klasik
+# Klasik
 
-Download OpenAPI specifications from remote URLs and generate TypeScript clients with class-transformer support for Kubernetes and other APIs.
+Generate TypeScript clients from OpenAPI specifications, Kubernetes CRDs, and JSON Schema with full type safety and class-transformer support.
+
+Perfect for:
+- 🚀 Kubernetes operators and controllers
+- 🔧 REST API clients with type safety
+- 📦 NestJS backend services
+- 🎯 Type-safe microservice communication
 
 ## Features
 
-- 📥 **Download OpenAPI specs** from remote URLs or local files
-- ☸️ **Kubernetes CRD support** - Generate TypeScript models from CustomResourceDefinitions
-- 📋 **JSON Schema support** - Generate models from JSON Schema files (SchemaStore.org and more)
-- 📁 **Multiple input formats** - HTTP/HTTPS URLs, file:// URLs, absolute/relative paths
-- 📄 **JSON and YAML support** - Automatically parse and handle both formats (YAML specs are converted to JSON for code generation)
-- 🔐 **Authentication support** - Custom headers including Bearer tokens and API keys
-- 🔗 **External reference resolution** - Automatically download referenced schema files (`$ref`)
-- 📦 **ESM compatibility** - Automatic `.js` extension fixing for Node.js ESM projects
-- 🔄 **Automatic transformation** - Converts API responses to class instances using class-transformer
-- 🎯 **Type-safe** - Full TypeScript support with decorators
-- 🛠️ **Configurable** - Custom headers, timeouts, and templates
-- 🧪 **Well-tested** - Comprehensive test coverage
-- 📦 **Easy to use** - Simple CLI and programmatic API
+✨ **Easy to Use** - Single CLI command to generate types
+🎯 **Type-Safe** - Full TypeScript support with strict typing
+🔄 **class-transformer** - Automatic serialization/deserialization
+✅ **class-validator** - Built-in validation decorators
+🎨 **NestJS Ready** - @ApiProperty decorators out of the box
+📦 **Multiple Formats** - OpenAPI, Kubernetes CRDs, JSON Schema
+🌐 **ESM Support** - Modern JavaScript modules with .js extensions
+🔗 **External $refs** - Automatic resolution of external schemas
+🎭 **Custom Templates** - Mustache-based customization
+⚙️ **Flexible Output** - Multiple export styles (namespace, direct, both)
+🧪 **Well Tested** - Comprehensive test coverage (748 passing tests)
+🚀 **Production Ready** - Used in real-world projects
+📝 **Full CLI** - Rich command-line interface with 4 commands
+🔐 **Authentication** - Custom headers including Bearer tokens
 
 ## Installation
 
 ```bash
-npm install klasik
+npm install -g klasik
+
+# or use directly with npx
+npx klasik <command>
 ```
 
 ## Quick Start
 
 ### CLI Usage
 
-Generate a TypeScript client from a remote OpenAPI spec:
+Generate from OpenAPI spec:
 
 ```bash
-# JSON spec
-npx klasik generate \
-  --url https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json \
-  --output ./k8s-client
-
-# YAML spec
-npx klasik generate \
-  --url https://api.example.com/openapi.yaml \
-  --output ./client
+klasik generate --url https://api.example.com/openapi.json --output ./src/generated
 ```
 
-Generate from a local OpenAPI spec file (JSON or YAML):
+Generate from Kubernetes CRDs:
 
 ```bash
-# Absolute path
-npx klasik generate \
-  --url /path/to/openapi.yaml \
-  --output ./client
-
-# Relative path
-npx klasik generate \
-  --url ./specs/openapi.json \
-  --output ./client
-
-# file:// URL
-npx klasik generate \
-  --url file:///path/to/openapi.yaml \
-  --output ./client
+klasik generate-crd \
+  --url https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/crds/application-crd.yaml \
+  --output ./src/generated \
+  --class-validator \
+  --nestjs-swagger
 ```
 
-Download an OpenAPI spec without generating (supports JSON and YAML):
+Generate from JSON Schema:
 
 ```bash
-# Download JSON spec
-npx klasik download \
-  --url https://api.example.com/openapi.json \
-  --output ./specs/api-spec.json
-
-# Download YAML spec
-npx klasik download \
-  --url https://api.example.com/openapi.yaml \
-  --output ./specs/api-spec.yaml
+klasik generate-jsonschema \
+  --url ./schemas/user.json \
+  --output ./src/generated
 ```
 
 ### Programmatic Usage
 
 ```typescript
-import { OpenAPIClientGenerator } from 'klasik';
+import { Generator, OpenAPIParser, SpecLoader } from 'klasik';
 
-const generator = new OpenAPIClientGenerator();
-
-await generator.generate({
-  specUrl: 'https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json',
-  outputDir: './k8s-client',
-});
-```
+// Load and parse OpenAPI spec
+const loader = new SpecLoader();
+const spec = await loader.load({ url: 'https://api.example.com/openapi.json' });
 
-## Kubernetes CRD Support
+const parser = new OpenAPIParser();
+const ir = parser.parse(spec, { includeOperations: true });
 
-Klasik can generate TypeScript models directly from Kubernetes CustomResourceDefinitions (CRDs). This is perfect for working with custom Kubernetes resources like ArgoCD Applications, Cert-Manager Certificates, or your own custom resources.
+// Generate TypeScript code
+const generator = new Generator({
+  outputDir: './generated',
+  mode: 'full', // or 'models-only'
+  nestJsSwagger: true,
+  classValidator: true,
+});
 
-### Quick Start with CRDs
+await generator.generate(ir);
+```
 
-Generate TypeScript models from a CRD:
+## Request and Response Validation
 
-```bash
-# From a URL (e.g., ArgoCD AppProject CRD)
-npx klasik generate-crd \
-  --url https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/crds/appproject-crd.yaml \
-  --output ./generated
+Klasik supports automatic validation of both API requests and responses using class-validator. When enabled, requests and responses are validated against the decorators generated by the `--class-validator` plugin.
 
-# From multiple CRD URLs (merged into single output)
-npx klasik generate-crd \
-  -u https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/crds/application-crd.yaml \
-  -u https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/crds/appproject-crd.yaml \
-  --output ./generated
+### Configuration
 
-# From a local CRD file
-npx klasik generate-crd \
-  --url ./my-crd.yaml \
-  --output ./generated
+```typescript
+import { Configuration } from './generated/configuration';
+import { TasksApi, NewTask } from './generated';
+import axios from 'axios';
 
-# With status schemas
-npx klasik generate-crd \
-  --url ./my-crd.yaml \
-  --output ./generated \
-  --include-status
+const config = new Configuration({
+  basePath: 'https://api.example.com',
+  enableResponseTransformation: true,     // Required for response validation
+  enableResponseValidation: true,         // Enable response validation (default: false)
+  enableRequestValidation: true,          // Enable request validation (default: false)
+});
 
-# With NestJS and validation decorators
-npx klasik generate-crd \
-  --url ./my-crd.yaml \
-  --output ./src/generated \
-  --nestjs-swagger \
-  --class-validator
+const api = new TasksApi(config, axios.create());
 ```
 
-### CRD Features
+### Request Validation
 
-- ✅ **Automatic schema extraction** from `openAPIV3Schema`
-- ✅ **Multiple URL support** - Generate from multiple CRD sources in one command
-- ✅ **Version-based organization** - Each CRD version gets its own folder (e.g., `v1alpha1/`, `v1beta1/`)
-- ✅ **Multi-document YAML support** - Process multiple CRDs from a single file
-- ✅ **Nested type extraction** - Complex nested objects become separate TypeScript interfaces
-- ✅ **Full decorator support** - Works with `--nestjs-swagger`, `--class-validator`, `--esm`
-- ✅ **Spec and Status schemas** - Optional status model generation with `--include-status`
-- ✅ **Kubernetes metadata** - Standard ObjectMeta types included
+Request validation ensures request bodies are:
+1. Instances of the expected class
+2. Valid according to class-validator decorators
 
-### Generated CRD Structure
+```typescript
+import { NewTask } from './generated/models';
 
-For a CRD with multiple versions, klasik generates:
+// Create instance
+const newTask = new NewTask();
+newTask.title = 'My Task';
+newTask.description = 'Task description';
 
-```
-output/
-├── v1alpha1/
-│   ├── models/
-│   │   ├── app-project.ts              # Main resource
-│   │   ├── app-project-spec.ts         # Spec definition
-│   │   ├── app-project-status.ts       # Status (if --include-status)
-│   │   ├── object-meta.ts              # Kubernetes metadata
-│   │   └── [nested-types].ts           # Extracted nested types
-│   └── index.ts                        # Version exports
-├── v1beta1/
-│   └── ... (same structure)
-└── index.ts                            # All versions
+// This will validate before sending
+const response = await api.createTask(newTask);
 ```
 
-### Using Generated CRD Models
+Request validation will throw if:
+- Request body is not an instance: `RequestNotInstanceError`
+- Request body fails validation: `ValidationError`
 
-```typescript
-import { AppProject, AppProjectSpec } from './generated/v1alpha1';
-
-// Create a typed Kubernetes resource
-const project: AppProject = {
-  apiVersion: 'argoproj.io/v1alpha1',
-  kind: 'AppProject',
-  metadata: {
-    name: 'my-project',
-    namespace: 'argocd'
-  },
-  spec: {
-    description: 'My ArgoCD project',
-    destinations: [
-      { server: 'https://kubernetes.default.svc', namespace: '*' }
-    ],
-    sourceRepos: ['*']
-  }
-};
+### Response Validation
 
-// Full TypeScript intellisense and type checking!
-```
-
-### CRD Programmatic API
+Response validation ensures responses match the expected schema:
 
 ```typescript
-import { CRDGenerator } from 'klasik';
-
-const generator = new CRDGenerator();
-
-// Single URL
-await generator.generate({
-  urls: './crds/my-resource.yaml',
-  outputDir: './generated',
-  includeStatus: true,
-  nestJsSwagger: true,
-  classValidator: true
-});
-
-// Multiple URLs (merged into single output)
-await generator.generate({
-  urls: [
-    'https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/crds/application-crd.yaml',
-    'https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/crds/appproject-crd.yaml',
-    './local/my-crd.yaml'
-  ],
-  outputDir: './generated',
-  includeStatus: true,
-  nestJsSwagger: true
-});
+try {
+  const response = await api.getTasks();
+  // Response is validated
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.error('Validation failed:', error.validationErrors);
+  }
+}
 ```
 
-### Multi-CRD YAML Files
-
-Klasik automatically handles multi-document YAML files (CRDs separated by `---`):
-
-```yaml
----
-apiVersion: apiextensions.k8s.io/v1
-kind: CustomResourceDefinition
-metadata:
-  name: appprojects.argoproj.io
-spec:
-  # ... AppProject CRD
----
-apiVersion: apiextensions.k8s.io/v1
-kind: CustomResourceDefinition
-metadata:
-  name: applications.argoproj.io
-spec:
-  # ... Application CRD
-```
+### Custom Error Handling
 
-Output will be organized by resource kind:
+Use callbacks for custom error handling:
 
+```typescript
+const config = new Configuration({
+  basePath: 'https://api.example.com',
+  enableRequestValidation: true,
+  onRequestValidationError: (errors, modelClass, instance) => {
+    console.error(`Request validation failed for ${modelClass.name}:`);
+    errors.forEach(err => {
+      console.error(`  - ${err.property}: ${Object.values(err.constraints || {}).join(', ')}`);
+    });
+  },
+  enableResponseValidation: true,
+  onResponseValidationError: (errors, modelClass, instance) => {
+    console.error(`Response validation failed for ${modelClass.name}:`);
+    // Log to monitoring service
+    Sentry.captureException(new Error('API validation failed'));
+  }
+});
 ```
-output/
-├── AppProject/
-│   ├── v1alpha1/
-│   └── index.ts
-├── Application/
-│   ├── v1alpha1/
-│   └── index.ts
-└── index.ts
-```
-
-## JSON Schema Support
 
-Klasik can generate TypeScript models from JSON Schema files (like those from [SchemaStore.org](https://schemastore.org)). This is perfect for working with configuration files, data formats, and schema definitions.
+### Requirements
 
-### Quick Start with JSON Schema
+- Models must be generated with `--class-validator` flag
+- For response validation: `enableResponseTransformation` must be `true` (default)
+- `class-validator` package must be installed
 
-Generate TypeScript models from a JSON Schema:
+### Example with CLI
 
 ```bash
-# From SchemaStore (kustomization.json schema)
-npx klasik generate-jsonschema \
-  -u https://json.schemastore.org/kustomization.json \
-  -o ./generated/kustomization
-
-# From multiple schemas (merged into single output)
-npx klasik generate-jsonschema \
-  -u https://json.schemastore.org/kustomization.json \
-  -u https://json.schemastore.org/package.json \
-  -o ./generated/models
-
-# From a local file
-npx klasik generate-jsonschema \
-  -u ./my-schema.json \
-  -o ./generated
-
-# With NestJS and validation decorators
-npx klasik generate-jsonschema \
-  -u ./schema.json \
-  -o ./src/generated \
-  --nestjs-swagger \
+# Generate models with validation decorators
+klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./src/generated \
   --class-validator
-```
 
-### JSON Schema Features
+# Use in your code
+import { Configuration, TasksApi, NewTask } from './generated';
 
-- ✅ **All definitions generated** - Creates models for every definition in the schema
-- ✅ **Multiple URL support** - Merge models from multiple JSON Schema files
-- ✅ **Nested type extraction** - Complex nested objects become separate TypeScript interfaces
-- ✅ **Full decorator support** - Works with `--nestjs-swagger`, `--class-validator`, `--esm`
-- ✅ **Standards compliant** - Supports JSON Schema Draft 4 and Draft 7
-- ✅ **patternProperties handling** - Automatically converts to OpenAPI-compatible schemas
+const config = new Configuration({
+  basePath: 'https://api.example.com',
+  enableRequestValidation: true,
+  enableResponseValidation: true
+});
 
-### Generated Structure
+const api = new TasksApi(config);
 
-For a JSON Schema file with definitions:
+// Request will be validated
+const newTask = new NewTask();
+newTask.title = 'My Task';
+const created = await api.createTask(newTask);
 
+// Response will be validated
+const tasks = await api.listTasks();
 ```
-output/
-├── models/
-│   ├── kustomization.ts
-│   ├── config-map-args.ts
-│   ├── helm-chart.ts
-│   └── ... (all definitions)
-└── index.ts
-```
-
-**Naming convention:**
-- `ConfigMapArgs` → `config-map-args.ts`
-- `HelmChart` → `helm-chart.ts`
-- `Kustomization` → `kustomization.ts`
 
-### Using Generated JSON Schema Models
+For more details, see the [Validation Guide](./docs/validation.md).
 
-```typescript
-import { Kustomization, ConfigMapArgs } from './generated/kustomization';
-
-// Create a typed kustomization file
-const kustomization: Kustomization = {
-  apiVersion: 'kustomize.config.k8s.io/v1beta1',
-  kind: 'Kustomization',
-  resources: [
-    './deployment.yaml',
-    './service.yaml'
-  ],
-  configMapGenerator: [
-    {
-      name: 'my-config',
-      literals: ['key=value']
-    }
-  ]
-};
-
-// Full TypeScript intellisense and type checking!
-```
-
-### JSON Schema Programmatic API
+## CLI Commands
 
-```typescript
-import { JSONSchemaGenerator } from 'klasik';
+### `klasik generate`
 
-const generator = new JSONSchemaGenerator();
+Generate TypeScript client from OpenAPI specification.
 
-// Single URL
-await generator.generate({
-  urls: './schemas/my-schema.json',
-  outputDir: './generated',
-  nestJsSwagger: true,
-  classValidator: true
-});
+**Usage:**
 
-// Multiple URLs
-await generator.generate({
-  urls: [
-    'https://json.schemastore.org/kustomization.json',
-    './local-schema.json'
-  ],
-  outputDir: './generated',
-  keepSpec: true // Keep intermediate OpenAPI specs
-});
+```bash
+klasik generate [options]
 ```
 
-**JSONSchemaGeneratorOptions:**
-- `urls: string | string[]` - URL(s) or file path(s) to JSON Schema files (required)
-- `outputDir: string` - Output directory (required)
-- `headers?: Record<string, string>` - Custom HTTP headers
-- `timeout?: number` - Request timeout in milliseconds (default: 30000)
-- `fixEsmImports?: boolean` - Add .js extensions for ESM (default: false)
-- `nestJsSwagger?: boolean` - Include NestJS decorators (default: false)
-- `classValidator?: boolean` - Include validation decorators (default: false)
-- `skipJsExtensions?: boolean` - Skip .js extensions (default: false)
-- `templateDir?: string` - Custom template directory
-- `keepSpec?: boolean` - Keep intermediate OpenAPI specs (default: false)
-
-## CLI Commands
-
-### `generate`
-
-Generate a TypeScript client from an OpenAPI spec (remote URL or local file).
-
 **Options:**
-- `-u, --url <url>` - URL or file path to the OpenAPI spec (required)
-  - Supports: `https://...`, `http://...`, `file://...`, `/absolute/path`, `./relative/path`
-- `-o, --output <dir>` - Output directory for generated client code (required)
-- `-m, --mode <mode>` - Generation mode: `full` (models + APIs + config) or `models-only` (default: `full`)
-  - `full`: Generates complete axios client with APIs, models, and configuration
-  - `models-only`: Generates only model classes with class-transformer decorators (no API client code)
-- `-H, --header <header...>` - Custom headers for HTTP requests (format: "Key: Value")
-  - Can be used multiple times for multiple headers
-  - Perfect for authorization: `--header "Authorization: Bearer token"`
-- `-r, --resolve-refs` - Resolve and download external `$ref` references
-- `--esm` - Add `.js` extensions to imports for ESM compatibility (Node.js modules)
-- `--nestjs-swagger` - Include NestJS Swagger `@ApiProperty` decorators in generated models
-  - Automatically adds `@nestjs/swagger` to generated package.json
-  - Ideal for NestJS applications with Swagger/OpenAPI documentation
-  - Works with both `full` and `models-only` generation modes
-- `--class-validator` - Include class-validator decorators for runtime validation (requires openapi-class-transformer v2.0+)
-  - Automatically adds `class-validator` and `class-transformer` to generated package.json
-  - Enables runtime validation with decorators like `@IsString`, `@IsEmail`, `@Min`, `@Max`
-  - Forward-compatible flag - full decorator generation coming in future version
-- `-t, --template <dir>` - Custom template directory (klasik includes enhanced TSDoc templates by default)
-- `-k, --keep-spec` - Keep the downloaded spec file after generation
-- `--timeout <ms>` - Request timeout in milliseconds for HTTP requests (default: 30000)
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-u, --url <url>` | OpenAPI spec URL or file path (required) | - |
+| `-o, --output <dir>` | Output directory (required) | - |
+| `-m, --mode <mode>` | Generation mode: `full` or `models-only` | `full` |
+| `--resolve-refs` | Resolve external $ref files | `false` |
+| `--esm` | Add .js extensions for ESM compatibility | `false` |
+| `--skip-js-extensions` | Skip .js extensions (for bundlers) | `false` |
+| `--nestjs-swagger` | Add @ApiProperty decorators | `false` |
+| `--class-validator` | Add class-validator decorators | `false` |
+| `--header <header>` | Custom header (repeatable) | - |
+| `--timeout <ms>` | Request timeout | `30000` |
+| `--template <dir>` | Custom template directory | - |
+| `--keep-spec` | Keep downloaded spec file(s) | `false` |
+| `--export-style <style>` | Export style: `namespace`, `direct`, `both`, `none` | `namespace` |
 
 **Examples:**
 
 ```bash
-# From remote URL with authorization
-klasik generate \
-  --url https://api.example.com/openapi.json \
-  --output ./client \
-  --header "Authorization: Bearer token123" \
-  --timeout 60000
-
-# With external reference resolution
-klasik generate \
-  --url https://api.example.com/openapi.json \
-  --output ./client \
-  --header "Authorization: Bearer token123" \
-  --resolve-refs
+# Basic generation
+klasik generate --url ./openapi.yaml --output ./generated
 
-# NestJS integration with Swagger decorators
+# Full client with API methods (default mode)
 klasik generate \
-  --url https://api.example.com/openapi.json \
-  --output ./src/generated \
-  --mode models-only \
-  --nestjs-swagger
+  --url https://petstore.swagger.io/v2/swagger.json \
+  --output ./src/api
 
-# With runtime validation decorators
+# Models only (no API client)
 klasik generate \
   --url https://api.example.com/openapi.json \
-  --output ./src/generated \
-  --mode models-only \
-  --class-validator
+  --output ./src/models \
+  --mode models-only
 
-# Full NestJS setup: Swagger docs + validation
+# With NestJS and validation support
 klasik generate \
-  --url https://api.example.com/openapi.json \
-  --output ./src/generated \
-  --mode models-only \
+  --url https://api.example.com/spec.json \
+  --output ./src/api \
   --nestjs-swagger \
   --class-validator
 
-# Multiple headers
+# With external refs and authentication
 klasik generate \
-  --url https://api.example.com/openapi.json \
-  --output ./client \
-  --header "Authorization: Bearer token" \
-  --header "X-API-Version: v1"
+  --url https://api.example.com/spec.json \
+  --output ./generated \
+  --resolve-refs \
+  --header "Authorization: Bearer ${TOKEN}"
 
-# From local file
+# ESM compatibility
 klasik generate \
-  --url ./my-spec.json \
-  --output ./client
+  --url ./openapi.yaml \
+  --output ./generated \
+  --esm
 
-# From file:// URL
+# Custom templates
 klasik generate \
-  --url file:///Users/me/specs/api.json \
-  --output ./client
+  --url ./openapi.yaml \
+  --output ./generated \
+  --template ./my-templates
 ```
 
-### `download`
+### `klasik download`
+
+Download OpenAPI spec without generating code.
 
-Download an OpenAPI spec from a remote URL without generating code.
+**Usage:**
+
+```bash
+klasik download [options]
+```
 
 **Options:**
-- `-u, --url <url>` - Remote URL to download the OpenAPI spec from (required)
-- `-o, --output <file>` - Output file path for the downloaded spec (required)
-- `-H, --header <header...>` - Custom headers for the request
-- `-r, --resolve-refs` - Resolve and download external `$ref` references
-- `--timeout <ms>` - Request timeout in milliseconds (default: 30000)
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-u, --url <url>` | Remote spec URL (required) | - |
+| `-o, --output <file>` | Output file path (required) | - |
+| `--header <header>` | Custom header (repeatable) | - |
+| `--resolve-refs` | Resolve external $ref files | `false` |
+| `--timeout <ms>` | Request timeout | `30000` |
 
 **Examples:**
 
 ```bash
-# Download spec only
+# Download spec
+klasik download \
+  --url https://api.example.com/openapi.json \
+  --output ./specs/api-spec.json
+
+# With authentication
 klasik download \
   --url https://api.example.com/openapi.json \
   --output ./specs/api-spec.json \
-  --header "Authorization: Bearer token123"
+  --header "Authorization: Bearer ${TOKEN}"
 
-# Download spec with all external references
+# Download with all external references
 klasik download \
   --url https://api.example.com/openapi.json \
   --output ./specs/api-spec.json \
-  --header "Authorization: Bearer token123" \
   --resolve-refs
 ```
 
-### `generate-crd`
-
-Generate TypeScript models from Kubernetes CustomResourceDefinition (CRD) YAML files.
+### `klasik generate-crd`
 
-**Options:**
-- `-u, --url <url...>` - URL(s) or file path(s) to CRD YAML files (required)
-  - Can be specified multiple times: `-u url1 -u url2 -u url3`
-  - All CRDs from all URLs are merged into a single output directory
-  - Supports: `https://...`, `http://...`, `file://...`, `/absolute/path`, `./relative/path`
-- `-o, --output <dir>` - Output directory for generated models (required)
-- `--include-status` - Generate status schemas in addition to spec schemas (default: false)
-  - By default, only spec models are generated
-  - Enable this to also generate status models for reading resource status
-- `--nestjs-swagger` - Include NestJS Swagger `@ApiProperty` decorators
-- `--class-validator` - Include class-validator decorators
-- `--esm` - Add `.js` extensions to imports for ESM compatibility
-- `-H, --header <header...>` - Custom headers for HTTP requests (format: "Key: Value")
-- `-t, --template <dir>` - Custom template directory
-- `-k, --keep-spec` - Keep the generated OpenAPI spec files (for debugging)
-- `--crd-kind-case <format>` - Format for CRD kind names in folder names (default: pascal)
-  - `pascal`: `AppProject` (default)
-  - `snake`: `app_project`
-  - `kebab`: `app-project`
-- `--timeout <ms>` - Request timeout in milliseconds (default: 30000)
+Generate TypeScript models from Kubernetes CustomResourceDefinitions.
 
-**Examples:**
+**Usage:**
 
 ```bash
-# Generate from ArgoCD AppProject CRD
-klasik generate-crd \
-  --url https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/crds/appproject-crd.yaml \
-  --output ./generated/crds
+klasik generate-crd [options]
+```
 
-# Generate from multiple CRD URLs (merged into single output)
-klasik generate-crd \
-  -u https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/crds/application-crd.yaml \
-  -u https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/crds/appproject-crd.yaml \
-  --output ./generated/argocd
+**Options:**
 
-# Mix remote and local CRDs
-klasik generate-crd \
-  -u https://example.com/crd1.yaml \
-  -u ./crds/crd2.yaml \
-  -u ./crds/crd3.yaml \
-  --output ./src/generated
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-u, --url <url>` | CRD URL or file path (repeatable) | - |
+| `-o, --output <dir>` | Output directory (required) | - |
+| `--include-status` | Generate status schemas | `false` |
+| `--crd-kind-case <format>` | Folder naming: `pascal`, `snake`, `kebab` | `pascal` |
+| `--nestjs-swagger` | Add @ApiProperty decorators | `false` |
+| `--class-validator` | Add class-validator decorators | `false` |
+| `--esm` | Add .js extensions for ESM | `false` |
+| `--header <header>` | Custom header (repeatable) | - |
+| `--resolve-refs` | Resolve external $ref files | `false` |
+| `--template <dir>` | Custom template directory | - |
+| `--keep-spec` | Keep downloaded spec file(s) | `false` |
+| `--timeout <ms>` | Request timeout | `30000` |
+
+**Examples:**
 
-# Generate with status models
+```bash
+# Single CRD
 klasik generate-crd \
   --url ./my-crd.yaml \
-  --output ./generated \
-  --include-status
+  --output ./src/types
 
-# NestJS integration with validation
+# Multiple CRDs (automatic deduplication)
 klasik generate-crd \
-  --url ./crds/ \
-  --output ./src/generated/k8s \
+  --url https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/crds/application-crd.yaml \
+  --url https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/crds/appproject-crd.yaml \
+  --output ./src/generated \
+  --crd-kind-case kebab \
   --nestjs-swagger \
   --class-validator
 
-# From local file with authentication (if downloading references)
-klasik generate-crd \
-  --url ./local-crd.yaml \
-  --output ./generated \
-  --header "Authorization: Bearer token"
-
-# Multi-CRD file
-klasik generate-crd \
-  --url ./all-crds.yaml \
-  --output ./generated \
-  --include-status \
-  --nestjs-swagger
-
-# Generate with snake_case folder names
+# With status schemas
 klasik generate-crd \
-  --url https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/crds/appproject-crd.yaml \
-  --output ./generated \
-  --crd-kind-case snake
+  --url ./operator-crd.yaml \
+  --output ./src/types \
+  --include-status
 
-# Generate with kebab-case folder names
+# With authentication
 klasik generate-crd \
-  --url https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/crds/appproject-crd.yaml \
-  --output ./generated \
-  --crd-kind-case kebab
+  --url https://private-repo.com/crd.yaml \
+  --output ./src/types \
+  --header "Authorization: Bearer ${TOKEN}"
 ```
 
-**Output Structure:**
+### `klasik generate-jsonschema`
 
-For a single CRD:
-```
-output/
-├── v1alpha1/
-│   └── models/
-│       ├── my-resource.ts
-│       ├── my-resource-spec.ts
-│       ├── my-resource-status.ts  (if --include-status)
-│       └── ...
-└── index.ts
-```
+Generate TypeScript models from JSON Schema files.
 
-For multiple CRDs with `--crd-kind-case pascal` (default):
-```
-output/
-├── AppProject/
-│   ├── v1alpha1/
-│   └── index.ts
-├── Application/
-│   ├── v1alpha1/
-│   └── index.ts
-└── index.ts
-```
+**Usage:**
 
-With `--crd-kind-case snake`:
-```
-output/
-├── app_project/
-│   ├── v1alpha1/
-│   └── index.ts
-├── application/
-│   ├── v1alpha1/
-│   └── index.ts
-└── index.ts
-```
-
-With `--crd-kind-case kebab`:
-```
-output/
-├── app-project/
-│   ├── v1alpha1/
-│   └── index.ts
-├── application/
-│   ├── v1alpha1/
-│   └── index.ts
-└── index.ts
+```bash
+klasik generate-jsonschema [options]
 ```
 
-### `generate-jsonschema`
-
-Generate TypeScript models from JSON Schema files.
-
 **Options:**
-- `-u, --url <url...>` - URL(s) or file path(s) to JSON Schema files (required)
-  - Can be specified multiple times: `-u url1 -u url2 -u url3`
-  - All schemas from all URLs are merged into a single output directory
-  - Supports: `https://...`, `http://...`, `file://...`, `/absolute/path`, `./relative/path`
-- `-o, --output <dir>` - Output directory for generated models (required)
-- `--nestjs-swagger` - Include NestJS Swagger `@ApiProperty` decorators
-- `--class-validator` - Include class-validator decorators
-- `--esm` - Add `.js` extensions to imports for ESM compatibility
-- `-H, --header <header...>` - Custom headers for HTTP requests (format: "Key: Value")
-- `-t, --template <dir>` - Custom template directory
-- `-k, --keep-spec` - Keep the generated OpenAPI spec files (for debugging)
-- `--timeout <ms>` - Request timeout in milliseconds (default: 30000)
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-u, --url <url>` | JSON Schema URL or file path (repeatable) | - |
+| `-o, --output <dir>` | Output directory (required) | - |
+| `--nestjs-swagger` | Add @ApiProperty decorators | `false` |
+| `--class-validator` | Add class-validator decorators | `false` |
+| `--esm` | Add .js extensions for ESM | `false` |
+| `--header <header>` | Custom header (repeatable) | - |
+| `--resolve-refs` | Resolve external $ref files | `false` |
+| `--template <dir>` | Custom template directory | - |
+| `--keep-spec` | Keep intermediate OpenAPI specs | `false` |
+| `--timeout <ms>` | Request timeout | `30000` |
 
 **Examples:**
 
 ```bash
-# Generate from SchemaStore
-klasik generate-jsonschema \
-  --url https://json.schemastore.org/kustomization.json \
-  --output ./generated/kustomization
-
-# Generate from multiple JSON Schema files (merged into single output)
+# From SchemaStore
 klasik generate-jsonschema \
-  -u https://json.schemastore.org/kustomization.json \
-  -u https://json.schemastore.org/package.json \
-  --output ./generated/schemas
+  --url https://json.schemastore.org/package.json \
+  --output ./src/types
 
-# Mix remote and local schemas
+# Multiple schemas
 klasik generate-jsonschema \
-  -u https://json.schemastore.org/kustomization.json \
-  -u ./schemas/my-schema.json \
-  -u ./schemas/another-schema.json \
+  --url https://json.schemastore.org/kustomization.json \
+  --url https://json.schemastore.org/package.json \
   --output ./src/generated
 
-# NestJS integration with validation
+# From local file
 klasik generate-jsonschema \
-  --url ./schemas/ \
-  --output ./src/generated/models \
+  --url ./schemas/user.json \
+  --output ./src/types \
   --nestjs-swagger \
   --class-validator
-
-# From local file with ESM support
-klasik generate-jsonschema \
-  --url ./local-schema.json \
-  --output ./generated \
-  --esm
-
-# Keep intermediate OpenAPI specs for debugging
-klasik generate-jsonschema \
-  --url https://json.schemastore.org/kustomization.json \
-  --output ./generated \
-  --keep-spec
-```
-
-**Output Structure:**
-
-```
-output/
-├── models/
-│   ├── type-a.ts
-│   ├── type-b.ts
-│   └── ... (all definitions from all schemas)
-└── index.ts
-```
-
-## Programmatic API
-
-### OpenAPIClientGenerator
-
-```typescript
-import { OpenAPIClientGenerator } from 'klasik';
-
-const generator = new OpenAPIClientGenerator();
-
-await generator.generate({
-  specUrl: 'https://api.example.com/openapi.json',
-  outputDir: './client',
-  mode: 'models-only',
-  headers: {
-    'Authorization': 'Bearer token123',
-    'X-Custom-Header': 'value'
-  },
-  resolveReferences: true, // Download external $ref files
-  nestJsSwagger: true, // Include @ApiProperty decorators
-  classValidator: true, // Include validation decorators
-  templateDir: './custom-templates', // Optional
-  keepSpec: true, // Keep downloaded spec file
-  timeout: 60000 // Request timeout in ms
-});
 ```
 
-### SpecDownloader
-
-```typescript
-import { SpecDownloader } from 'klasik';
-
-const downloader = new SpecDownloader();
+## Kubernetes CRD Support
 
-const specPath = await downloader.download({
-  url: 'https://api.example.com/openapi.json',
-  outputPath: './specs/api-spec.json',
-  headers: {
-    'Authorization': 'Bearer token123'
-  },
-  resolveReferences: true, // Download external $ref files
-  timeout: 30000
-});
+Klasik can generate TypeScript models directly from Kubernetes CustomResourceDefinitions (CRDs). Perfect for working with custom Kubernetes resources like ArgoCD Applications, Cert-Manager Certificates, or your own custom resources.
 
-console.log(`Spec downloaded to: ${specPath}`);
+### Features
 
-// Clean up temporary files
-downloader.cleanupTemp();
-```
+- ✅ **Automatic schema extraction** from `openAPIV3Schema`
+- ✅ **Multiple URL support** - Generate from multiple CRDs in one command
+- ✅ **Automatic deduplication** - Shared types (ObjectMeta, TypeMeta) generated once
+- ✅ **Multi-document YAML** - Process multiple CRDs from a single file
+- ✅ **Nested type extraction** - Complex objects become separate interfaces
+- ✅ **Full decorator support** - NestJS, class-validator, class-transformer
+- ✅ **Status schemas** - Optional with `--include-status`
+- ✅ **Version support** - Handles multiple CRD versions (v1alpha1, v1, etc.)
 
-### CRDGenerator
+### Automatic Deduplication
 
-Generate TypeScript models from Kubernetes CustomResourceDefinitions programmatically:
+When generating from multiple CRDs, Klasik automatically deduplicates shared types by name:
 
-```typescript
-import { CRDGenerator } from 'klasik';
-
-const generator = new CRDGenerator();
-
-await generator.generate({
-  url: 'https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/crds/appproject-crd.yaml',
-  outputDir: './generated/crds',
-  includeStatus: true, // Generate status models
-  nestJsSwagger: true, // Include @ApiProperty decorators
-  classValidator: true, // Include validation decorators
-  fixEsmImports: false, // Add .js extensions
-  headers: {
-    'Authorization': 'Bearer token123'
-  },
-  timeout: 60000
-});
+```bash
+klasik generate-crd \
+  --url application-crd.yaml \    # Defines ObjectMeta
+  --url appproject-crd.yaml \     # Also defines ObjectMeta
+  --output ./generated
 ```
 
-**CRDGeneratorOptions:**
-- `url: string` - URL or file path to CRD YAML (required)
-- `outputDir: string` - Output directory (required)
-- `includeStatus?: boolean` - Generate status schemas (default: false)
-- `headers?: Record<string, string>` - Custom HTTP headers
-- `timeout?: number` - Request timeout in milliseconds (default: 30000)
-- `fixEsmImports?: boolean` - Add .js extensions for ESM (default: false)
-- `nestJsSwagger?: boolean` - Include NestJS decorators (default: false)
-- `classValidator?: boolean` - Include validation decorators (default: false)
-- `skipJsExtensions?: boolean` - Skip .js extensions (default: false)
-- `templateDir?: string` - Custom template directory
-- `keepSpec?: boolean` - Keep intermediate OpenAPI specs (default: false)
-
-**Multi-CRD YAML:**
-
-The CRDGenerator automatically handles multi-document YAML files:
-
-```typescript
-// This YAML contains multiple CRDs separated by ---
-await generator.generate({
-  url: './all-crds.yaml', // Contains AppProject, Application, etc.
-  outputDir: './generated',
-  includeStatus: true
-});
-
-// Output will be organized by CRD kind
-// ./generated/AppProject/v1alpha1/...
-// ./generated/Application/v1alpha1/...
-```
+**Result:** Only ONE `object-meta.ts` file is generated. The last CRD's definition is used (controllable via URL order).
 
-## Generated Client Features
-
-The generated TypeScript client includes:
-
-- ✅ **Class-transformer decorators** - `@Expose()` and `@Type()` on all models
-- ✅ **Automatic response transformation** - API responses converted to class instances
-- ✅ **Runtime type metadata** - Static `attributeTypeMap` on all models
-- ✅ **Union type support** - `anyOf` schemas become TypeScript unions
-- ✅ **Rich TSDoc comments** - Comprehensive documentation from OpenAPI spec metadata
-- ✅ **Vendor extensions** - Preserved in JSDoc comments and metadata
-- ✅ **Error handling** - Configurable transformation error handlers
-- ✅ **Configuration options** - Enable/disable transformation, custom error handlers
-- ✅ **NestJS Swagger decorators** (optional) - `@ApiProperty` with type, description, example, required, and nullable when `--nestjs-swagger` is enabled
-- ✅ **class-validator decorators** (optional) - Runtime validation decorators when `--class-validator` is enabled (full support in v2.0+)
-
-### Enhanced TSDoc Documentation
-
-Klasik includes enhanced Mustache templates that generate rich TSDoc comments from your OpenAPI specification. The generated code includes:
-
-**For Models:**
-- Class-level documentation with description
-- Property descriptions from OpenAPI schema
-- Type information with `@type` tags
-- Validation constraints (`@minimum`, `@maximum`, `@minLength`, `@maxLength`, `@pattern`)
-- Format specifications (`@format`)
-- Example values (`@example`)
-- Required field markers (`@required`)
-- Deprecation warnings (`@deprecated`)
-
-**For API Endpoints:**
-- Method name and HTTP verb (`@method`)
-- Summary and detailed descriptions
-- Parameter documentation with types and requirements
-- Return type information
-- Error scenarios (`@throws`)
-- Deprecation notices
-
-Example generated model with rich TSDoc:
+### Generated Structure
 
-```typescript
-/**
- * User
- *
- * Represents a user in the system
- *
- * @export
- * @class User
- */
-export class User {
-    /**
-     * id - Unique identifier for the user
-     *
-     * @type {string}
-     * @memberof User
-     * @required
-     * @format uuid
-     * @example "550e8400-e29b-41d4-a716-446655440000"
-     */
-    @Expose()
-    'id': string;
-
-    /**
-     * email - User's email address
-     *
-     * @type {string}
-     * @memberof User
-     * @required
-     * @format email
-     * @pattern ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
-     */
-    @Expose()
-    'email': string;
-}
 ```
-
-Example generated API method:
-
-```typescript
-/**
- * getUserById - Get user by ID
- *
- * Retrieves a single user by their unique identifier
- *
- * @method GET
- * @summary Get user by ID
- * @param {string} userId - The user's unique identifier (required)
- * @param {RawAxiosRequestConfig} [options] Override http request option.
- * @throws {RequiredError} When required parameters are missing
- * @returns {Promise<AxiosResponse<User>>}
- */
-async getUserById(userId: string, options?: RawAxiosRequestConfig): Promise<AxiosResponse<User>>
+src/generated/
+└── models/
+    ├── application.ts              # Main Application CRD
+    ├── application-spec.ts         # Nested spec type
+    ├── application-status.ts       # Status (with --include-status)
+    ├── app-project.ts              # Main AppProject CRD
+    ├── object-meta.ts              # SHARED (deduplicated)
+    ├── type-meta.ts                # SHARED (deduplicated)
+    ├── package.json
+    ├── tsconfig.json
+    └── index.ts                    # Barrel exports
 ```
 
-These templates automatically extract metadata from your OpenAPI spec and format it as proper TSDoc comments, making your generated client code well-documented and IDE-friendly with IntelliSense support.
-
-**Note:** Klasik's templates automatically handle special characters in descriptions by using proper escaping, ensuring your TSDoc comments are always valid even when OpenAPI descriptions contain characters like `*`, `/`, `@`, etc.
-
-### Using the Generated Client
+### Using Generated CRD Models
 
 ```typescript
-import { DefaultApi, Configuration } from './generated-client';
-import { plainToInstance } from 'class-transformer';
-
-// Create API client
-const config = new Configuration({
-    basePath: 'https://api.example.com',
-    enableResponseTransformation: true, // Default
-    onTransformationError: (error, modelClass, data) => {
-        console.error('Transformation failed:', error);
-    }
-});
-
-const api = new DefaultApi(config);
-
-// Get user - response is automatically transformed to User class instance
-const response = await api.getUserById({ id: '123' });
-const user = response.data; // user is instanceof User ✅
+import { Application } from './generated/models';
+
+const app = new Application();
+app.apiVersion = 'argoproj.io/v1alpha1';
+app.kind = 'Application';
+app.metadata = {
+  name: 'my-app',
+  namespace: 'default'
+};
+app.spec = {
+  project: 'default',
+  source: {
+    repoURL: 'https://github.com/example/repo',
+    path: '.',
+    targetRevision: 'HEAD'
+  },
+  destination: {
+    server: 'https://kubernetes.default.svc',
+    namespace: 'default'
+  }
+};
 
-console.log(user.name); // Fully typed!
+// Full TypeScript intellisense and type checking!
 ```
 
-## External Reference Resolution
-
-Klasik can automatically resolve and download external `$ref` references in your OpenAPI specs. This is useful when your spec splits schemas across multiple files.
-
-### How It Works
-
-When you enable `--resolve-refs` (CLI) or `resolveReferences: true` (programmatic), klasik will:
-
-1. **Parse the main spec** for external `$ref` references
-2. **Download all referenced files** preserving directory structure
-3. **Recursively resolve nested references** in downloaded files
-4. **Use the same authentication** for all downloads
-
-### Example OpenAPI Spec with External References
+## JSON Schema Support
 
-```json
-{
-  "openapi": "3.0.0",
-  "paths": {
-    "/users": {
-      "get": {
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "./schemas/users-orgs.yaml#/components/schemas/Org"
-                }
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}
-```
+Klasik can generate TypeScript models from JSON Schema files (like those from [SchemaStore.org](https://schemastore.org)). Perfect for configuration files, data formats, and schema definitions.
 
-With `--resolve-refs`, klasik will automatically download `./schemas/users-orgs.yaml` and any files it references.
+### Features
 
-### Output Structure
+- ✅ **All definitions generated** - Creates models for every definition
+- ✅ **Multiple URL support** - Merge models from multiple schemas
+- ✅ **Standards compliant** - Supports JSON Schema Draft 4 and Draft 7
+- ✅ **Nested type extraction** - Complex objects become separate interfaces
+- ✅ **Full decorator support** - NestJS, class-validator, class-transformer
+- ✅ **Automatic naming** - Schema title or filename becomes class name
 
-Referenced files are downloaded preserving the directory structure:
+### Generated Structure
 
 ```
 output/
-├── openapi-spec.json       # Main spec
-└── schemas/
-    ├── users-orgs.yaml     # Referenced schema
-    └── common/
-        └── types.yaml      # Nested reference
-```
-
-### Supported Reference Types
-
-- **Relative paths**: `./schemas/user.yaml`, `../common/types.yaml`
-  - When the main spec is from a remote URL, relative paths are resolved against the spec's URL
-  - Example: spec at `https://raw.githubusercontent.com/org/repo/main/api/openapi.yaml` with ref `./schemas/user.yaml` resolves to `https://raw.githubusercontent.com/org/repo/main/api/schemas/user.yaml`
-- **Remote URLs**: `https://api.example.com/schemas/user.yaml`
-- **Mixed**: Main spec from HTTPS, references can be relative or absolute
-
-### CLI Example
-
-```bash
-# Download spec with all external references
-npx klasik generate \
-  --url https://api.example.com/openapi.json \
-  --output ./client \
-  --header "Authorization: Bearer token" \
-  --resolve-refs
+├── models/
+│   ├── package.ts
+│   ├── person.ts
+│   ├── repository.ts
+│   └── index.ts
+├── package.json
+└── tsconfig.json
 ```
 
-### Programmatic Example
+### Using Generated JSON Schema Models
 
 ```typescript
-import { OpenAPIClientGenerator } from 'klasik';
-
-await new OpenAPIClientGenerator().generate({
-  specUrl: 'https://api.example.com/openapi.json',
-  outputDir: './client',
-  headers: { 'Authorization': 'Bearer token' },
-  resolveReferences: true,
-  keepSpec: true // Keep all downloaded files
-});
+import { Package } from './generated/models';
+
+const pkg: Package = {
+  name: 'my-package',
+  version: '1.0.0',
+  description: 'My awesome package',
+  author: {
+    name: 'John Doe',
+    email: 'john@example.com'
+  }
+};
+
+// Full TypeScript intellisense and type checking!
 ```
 
 ## NestJS Integration
 
-### Using with NestJS Applications
-
-Klasik-generated models integrate seamlessly with NestJS applications. Use `--mode models-only` with decorator flags for best results.
+Klasik integrates seamlessly with NestJS, generating models with `@ApiProperty` decorators for automatic Swagger/OpenAPI documentation and `class-validator` decorators for runtime validation.
 
-#### Swagger Documentation Support
+### Setup
 
-Generate models with `@ApiProperty` decorators for automatic Swagger documentation:
+Generate models with NestJS support:
 
 ```bash
-npx klasik generate \
+klasik generate \
   --url https://api.example.com/openapi.json \
-  --output ./src/generated/dto \
+  --output ./src/generated \
   --mode models-only \
-  --nestjs-swagger
-```
-
-This generates DTOs like:
-
-```typescript
-import { Expose } from 'class-transformer';
-import { ApiProperty } from '@nestjs/swagger';
-
-export class UserDto {
-    @ApiProperty({
-        type: String,
-        description: 'Unique identifier',
-        required: true,
-        example: '123e4567-e89b-41d3-a456-426614174000',
-    })
-    @Expose()
-    id: string;
-
-    @ApiProperty({
-        type: String,
-        description: 'User email address',
-        required: true,
-        format: 'email',
-    })
-    @Expose()
-    email: string;
-}
+  --nestjs-swagger \
+  --class-validator
 ```
 
-Use in your NestJS controllers:
+### Using in NestJS Controllers
 
 ```typescript
-import { Controller, Get, Post, Body } from '@nestjs/common';
-import { ApiTags, ApiResponse } from '@nestjs/swagger';
-import { UserDto } from './generated/dto';
+import { Controller, Post, Body } from '@nestjs/common';
+import { ApiTags, ApiOperation } from '@nestjs/swagger';
+import { CreateUserDto } from './generated/models';
 
 @ApiTags('users')
 @Controller('users')
 export class UsersController {
-  @Get()
-  @ApiResponse({ type: [UserDto], status: 200 })
-  async findAll(): Promise<UserDto[]> {
-    // Your implementation
-  }
-
   @Post()
-  @ApiResponse({ type: UserDto, status: 201 })
-  async create(@Body() createUserDto: UserDto): Promise<UserDto> {
-    // Your implementation
+  @ApiOperation({ summary: 'Create user' })
+  async create(@Body() createUserDto: CreateUserDto) {
+    // Automatic validation via class-validator
+    // Automatic Swagger docs via @ApiProperty
+    return this.usersService.create(createUserDto);
   }
 }
 ```
 
-Your Swagger UI automatically displays complete documentation from the `@ApiProperty` decorators.
-
-#### Runtime Validation Support
-
-Add the `--class-validator` flag for runtime validation decorators:
-
-```bash
-npx klasik generate \
-  --url https://api.example.com/openapi.json \
-  --output ./src/generated/dto \
-  --mode models-only \
-  --nestjs-swagger \
-  --class-validator
-```
-
-**Note**: Full decorator generation requires openapi-class-transformer v2.0+. For now, the dependencies are added to package.json, and you can manually add validation decorators:
+### Generated Model Example
 
 ```typescript
-import { Expose } from 'class-transformer';
 import { ApiProperty } from '@nestjs/swagger';
-import { IsString, IsEmail } from 'class-validator';
-
-export class UserDto {
-    @ApiProperty({ type: String, required: true })
-    @IsString()
-    @Expose()
-    id: string;
-
-    @ApiProperty({ type: String, required: true, format: 'email' })
-    @IsEmail()
-    @Expose()
-    email: string;
-}
-```
+import { IsString, IsEmail, MinLength, IsOptional } from 'class-validator';
+import { Expose } from 'class-transformer';
 
-Use with NestJS ValidationPipe:
+export class CreateUserDto {
+  @Expose()
+  @ApiProperty({
+    type: String,
+    description: 'User email address',
+    required: true,
+    format: 'email'
+  })
+  @IsEmail()
+  email: string;
+
+  @Expose()
+  @ApiProperty({
+    type: String,
+    description: 'User password',
+    required: true,
+    minLength: 8
+  })
+  @IsString()
+  @MinLength(8)
+  password: string;
 
-```typescript
-import { ValidationPipe } from '@nestjs/common';
-
-// In main.ts
-app.useGlobalPipes(new ValidationPipe({
-  transform: true,
-  whitelist: true,
-}));
-
-// In controller
-@Post()
-async create(@Body() dto: UserDto): Promise<UserDto> {
-  // dto is already validated and transformed to UserDto instance!
+  @Expose()
+  @ApiProperty({
+    type: String,
+    description: 'User display name',
+    required: false
+  })
+  @IsString()
+  @IsOptional()
+  name?: string;
 }
 ```
 
-#### Required Dependencies for NestJS
+## Advanced Topics
+
+### External Reference Resolution
 
-When using `--nestjs-swagger` or `--class-validator`, ensure your project has these peer dependencies:
+When your OpenAPI spec uses external `$ref`, Klasik can automatically download and inline them:
 
 ```bash
-npm install @nestjs/swagger swagger-ui-express
-npm install class-validator class-transformer
-npm install reflect-metadata
+klasik generate \
+  --url ./api-spec.yaml \
+  --output ./generated \
+  --resolve-refs
 ```
 
-Update your `tsconfig.json`:
+**What it does:**
+1. Discovers all external `$ref` recursively
+2. Downloads referenced files (with auth if needed)
+3. Inlines them into the main spec
+4. Generates complete TypeScript types
 
-```json
-{
-  "compilerOptions": {
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true
-  }
-}
+**Supported formats:**
+- ✅ Relative paths: `./schemas/User.yaml`
+- ✅ Absolute paths: `/path/to/schema.yaml`
+- ✅ Remote URLs: `https://api.example.com/schemas/User.yaml`
+- ✅ With fragments: `./User.yaml#/definitions/User`
+- ✅ Nested refs (ref within ref)
+- ✅ Circular reference detection
+
+**Example spec with external refs:**
+
+```yaml
+# main-spec.yaml
+components:
+  schemas:
+    User:
+      $ref: './schemas/user.yaml'  # Local file
+    Post:
+      $ref: 'https://api.example.com/schemas/post.yaml'  # Remote URL
+    Comment:
+      $ref: './schemas/comment.yaml#/Comment'  # With fragment
+```
+
+**With authentication:**
+```bash
+klasik generate \
+  --url https://private-api.com/spec.yaml \
+  --resolve-refs \
+  --header "Authorization: Bearer ${TOKEN}"
 ```
 
-#### Best Practices
+### Authentication Headers
 
-1. **Use models-only mode**: Generate only DTOs, keep your NestJS business logic separate
-2. **Separate directories**: Generate into `src/generated/dto` or similar
-3. **Extend generated classes**: For complex validation, extend generated DTOs
-4. **Version control**: Commit generated files or regenerate in CI/CD
+Access private API specs with custom headers:
 
-```typescript
-// Custom DTO extending generated model
-import { UserDto } from '../generated/dto';
-import { IsStrongPassword } from 'class-validator';
+```bash
+# Bearer token
+klasik generate \
+  --url https://internal-api.company.com/spec.json \
+  --header "Authorization: Bearer ${API_TOKEN}" \
+  --output ./generated
 
-export class CreateUserDto extends UserDto {
-  @IsStrongPassword()
-  password: string;
-}
-```
+# API key
+klasik generate \
+  --url https://api.example.com/spec.json \
+  --header "X-API-Key: ${API_KEY}" \
+  --output ./generated
 
-## Best Practices for Existing Projects
+# Multiple headers
+klasik generate \
+  --url https://api.example.com/spec.json \
+  --header "Authorization: Bearer ${TOKEN}" \
+  --header "X-Custom-Header: value" \
+  --output ./generated
+```
 
-When integrating klasik into an existing TypeScript project, follow these best practices to avoid conflicts:
+### ESM Support
 
-### Generate into a Subdirectory
+For Node.js ESM projects, use the `--esm` flag to add `.js` extensions to imports:
 
 ```bash
-# Generate models into src/generated to avoid overwriting project files
-npx klasik generate \
-  --url https://api.example.com/openapi.yaml \
-  --output ./src/generated \
-  --mode models-only \
-  --resolve-refs
+klasik generate \
+  --url ./openapi.yaml \
+  --output ./generated \
+  --esm
 ```
 
-### Clean Up Generated Config Files
+**Generated imports:**
 
-klasik generates `package.json` and `tsconfig.json` files. Remove them after generation:
+```typescript
+// With --esm
+import { User } from './user.js';
+import { Post } from './post.js';
 
-```json
-// package.json
-{
-  "scripts": {
-    "generate-client": "npx klasik generate --url $API_URL --output ./src/generated --mode models-only --resolve-refs && npm run cleanup-generated",
-    "cleanup-generated": "rm -f ./src/generated/package.json ./src/generated/tsconfig*.json ./src/generated/.openapi-generator*"
-  }
-}
+// Without --esm
+import { User } from './user';
+import { Post } from './post';
 ```
 
-### TypeScript Configuration for class-transformer
+**For bundlers (webpack, vite, esbuild):**
 
-Add these settings to your `tsconfig.json` for compatibility:
+Use `--skip-js-extensions` to omit extensions:
 
-```json
-{
-  "compilerOptions": {
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true,
-    "skipLibCheck": true  // Skip type checking in node_modules (recommended for class-transformer)
-  }
-}
+```bash
+klasik generate \
+  --url ./openapi.yaml \
+  --output ./generated \
+  --esm \
+  --skip-js-extensions
 ```
 
-### Models-Only Mode
+### Custom Templates
 
-Use `--mode models-only` when you:
-- Only need data models with class-transformer decorators
-- Want to use your own API client (axios, fetch, etc.)
-- Are integrating into an existing project with its own HTTP layer
-- Want to avoid package.json/tsconfig.json conflicts
+Klasik uses Mustache templates for code generation. You can provide custom templates:
 
 ```bash
-npx klasik generate \
-  --url https://api.example.com/openapi.yaml \
-  --output ./src/generated \
-  --mode models-only  # ✅ Generates only models, no API client
+klasik generate \
+  --url ./openapi.yaml \
+  --output ./generated \
+  --template ./my-templates
 ```
 
-### Full Mode
+**Template structure:**
 
-Use `--mode full` (default) when you:
-- Want a complete ready-to-use axios client
-- Are starting a new project from scratch
-- Want automatic response transformation with class-transformer
-
-```bash
-npx klasik generate \
-  --url https://api.example.com/openapi.yaml \
-  --output ./api-client \
-  --mode full  # Generates complete client with APIs
+```
+my-templates/
+├── model.mustache           # Model class template
+├── api-class.mustache       # API class template (full mode)
+├── configuration.mustache   # Configuration class template
+└── index.mustache          # Barrel export template
 ```
 
-### ESM (ECMAScript Modules) Support
+### Best Practices
 
-If your project uses ECMAScript Modules (`"type": "module"` in package.json), use the `--esm` flag to automatically add `.js` extensions to all relative imports:
+#### 1. Use Version Pinning
 
-```bash
-# Generate ESM-compatible code
-npx klasik generate \
-  --url https://api.example.com/openapi.yaml \
-  --output ./src/generated \
-  --mode models-only \
-  --esm  # ✅ Adds .js extensions to imports
-```
+For production projects, pin to specific spec versions:
 
-**What `--esm` does:**
-- Adds `.js` extensions to all relative imports: `from './user'` → `from './user.js'`
-- Adds `.js` extensions to all relative exports: `export * from './api'` → `export * from './api.js'`
-- Handles directory imports: `from './models'` → `from './models/index.js'`
-- Only affects relative imports (doesn't touch external packages like `axios`, `class-transformer`)
+```bash
+# ✅ Good: Specific commit hash
+klasik generate-crd \
+  --url https://raw.githubusercontent.com/argoproj/argo-cd/v2.8.0/manifests/crds/application-crd.yaml \
+  --output ./src/types
 
-**Before `--esm`:**
-```typescript
-import { User } from './models/user';
-import { Cluster } from '../models/cluster';
-export * from './api/orgs-api';
+# ❌ Bad: Using master/main branch
+klasik generate-crd \
+  --url https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/crds/application-crd.yaml \
+  --output ./src/types
 ```
 
-**After `--esm`:**
-```typescript
-import { User } from './models/user.js';
-import { Cluster } from '../models/cluster.js';
-export * from './api/orgs-api.js';
-```
+#### 2. Keep Generated Code Separate
 
-**When to use `--esm`:**
-- Your package.json has `"type": "module"`
-- You're using Node.js native ESM
-- You're targeting modern JavaScript environments
-- You want to eliminate post-processing scripts
+Store generated code in a dedicated directory:
 
-**package.json setup for ESM:**
-```json
-{
-  "type": "module",
-  "scripts": {
-    "generate-client": "npx klasik generate --url $API_URL --output src/generated --mode models-only --esm"
-  }
-}
+```
+src/
+├── api/
+│   └── generated/       # Generated code here
+│       ├── models/
+│       ├── apis/
+│       └── index.ts
+├── services/            # Your business logic
+└── controllers/         # Your controllers
 ```
 
-## Advanced Configuration
+Add to `.gitignore`:
 
-### Custom Error Handling
-
-```typescript
-const config = new Configuration({
-    basePath: 'https://api.example.com',
-    onTransformationError: (error, modelClass, data) => {
-        // Log to custom logger
-        logger.error('Failed to transform response', {
-            error: error.message,
-            modelClass: modelClass.name,
-            rawData: data
-        });
-
-        // Send to error tracking
-        Sentry.captureException(error);
-    }
-});
+```gitignore
+src/api/generated/
 ```
 
-### Disable Transformation
+Regenerate in CI/CD:
 
-```typescript
-const config = new Configuration({
-    basePath: 'https://api.example.com',
-    enableResponseTransformation: false // Get plain objects
-});
+```yaml
+# .github/workflows/ci.yml
+- name: Generate API Client
+  run: |
+    npx klasik generate \
+      --url https://api.example.com/openapi.json \
+      --output ./src/api/generated \
+      --nestjs-swagger \
+      --class-validator
 ```
 
-## Requirements
+#### 3. Validate After Generation
+
+Always compile generated code to catch issues early:
 
-- Node.js >= 16
-- TypeScript >= 5.0 (for experimentalDecorators support)
+```bash
+klasik generate --url ./spec.yaml --output ./generated
+cd ./generated
+npm install
+npm run build
+```
 
-### TypeScript Configuration
+#### 4. Use Consistent Options
 
-Your `tsconfig.json` must include:
+Create a script or Makefile for consistent generation:
 
 ```json
+// package.json
 {
-  "compilerOptions": {
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true
+  "scripts": {
+    "generate": "klasik generate --url https://api.example.com/openapi.json --output ./src/generated --nestjs-swagger --class-validator",
+    "generate:crds": "klasik generate-crd --url https://example.com/crd.yaml --output ./src/k8s --include-status"
   }
 }
 ```
@@ -1330,6 +826,10 @@ Your `tsconfig.json` must include:
 ## Development
 
 ```bash
+# Clone the repository
+git clone https://github.com/yourusername/klasik-2.git
+cd klasik-2
+
 # Install dependencies
 npm install
 
@@ -1339,20 +839,25 @@ npm run build
 # Run tests
 npm test
 
-# Watch mode
-npm run dev
+# Run CLI locally
+node dist/cli/index.js generate --url ./test-spec.yaml --output ./test-output
 ```
 
+For more details, see [CONTRIBUTING.md](CONTRIBUTING.md) and [ARCHITECTURE.md](ARCHITECTURE.md).
+
 ## License
 
 MIT
 
-## Related Projects
+## Credits
 
-- [openapi-class-transformer](https://github.com/example/openapi-class-transformer) - The underlying generator used by this package
-- [class-transformer](https://github.com/typestack/class-transformer) - Transformation library
-- [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) - OpenAPI code generator
+Built with:
+- [ts-morph](https://github.com/dsherret/ts-morph) - TypeScript Compiler API wrapper
+- [class-transformer](https://github.com/typestack/class-transformer) - Object transformation
+- [class-validator](https://github.com/typestack/class-validator) - Runtime validation
+- [mustache](https://github.com/janl/mustache.js) - Template engine
+- [commander](https://github.com/tj/commander.js) - CLI framework
 
-## Contributing
+---
 
-Contributions are welcome! Please open an issue or submit a pull request.
+**Note:** Klasik is a complete rebuild with AST-based code generation, replacing the string manipulation approach from v1. See [ARCHITECTURE.md](ARCHITECTURE.md) for technical details.