klasik 1.0.22 → 1.0.23

package/.claude/settings.local.json

@@ -12,7 +12,9 @@
       "WebFetch(domain:zod.dev)",
       "Bash(node test-disc-union.js:*)",
       "Bash(node test-disc-code.js:*)",
-      "Bash(node test-new-validators.js:*)"
+      "Bash(node test-new-validators.js:*)",
+      "Bash(node dist/cli.js generate-crd:*)",
+      "Bash(node test-programmatic-api.js:*)"
     ]
   }
 }

package/README.md

@@ -5,6 +5,7 @@ Download OpenAPI specifications from remote URLs and generate TypeScript clients
 ## Features
 
 - 📥 **Download OpenAPI specs** from remote URLs or local files
+- ☸️ **Kubernetes CRD support** - Generate TypeScript models from CustomResourceDefinitions
 - 📁 **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
@@ -13,7 +14,7 @@ Download OpenAPI specifications from remote URLs and generate TypeScript clients
 - 🔄 **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 (11 tests passing)
+- 🧪 **Well-tested** - Comprehensive test coverage
 - 📦 **Easy to use** - Simple CLI and programmatic API
 
 ## Installation
@@ -86,6 +87,143 @@ await generator.generate({
 });
 ```
 
+## Kubernetes CRD Support
+
+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.
+
+### Quick Start with CRDs
+
+Generate TypeScript models from a CRD:
+
+```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
+
+# From a local CRD file
+npx klasik generate-crd \
+  --url ./my-crd.yaml \
+  --output ./generated
+
+# With status schemas
+npx klasik generate-crd \
+  --url ./my-crd.yaml \
+  --output ./generated \
+  --include-status
+
+# With NestJS and validation decorators
+npx klasik generate-crd \
+  --url ./my-crd.yaml \
+  --output ./src/generated \
+  --nestjs-swagger \
+  --class-validator
+```
+
+### CRD Features
+
+- ✅ **Automatic schema extraction** from `openAPIV3Schema`
+- ✅ **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
+
+### Generated CRD Structure
+
+For a CRD with multiple versions, klasik generates:
+
+```
+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
+```
+
+### Using Generated CRD Models
+
+```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: ['*']
+  }
+};
+
+// Full TypeScript intellisense and type checking!
+```
+
+### CRD Programmatic API
+
+```typescript
+import { CRDGenerator } from 'klasik';
+
+const generator = new CRDGenerator();
+
+await generator.generate({
+  url: './crds/my-resource.yaml',
+  outputDir: './generated',
+  includeStatus: true,
+  nestJsSwagger: true,
+  classValidator: true
+});
+```
+
+### 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
+```
+
+Output will be organized by resource kind:
+
+```
+output/
+├── AppProject/
+│   ├── v1alpha1/
+│   └── index.ts
+├── Application/
+│   ├── v1alpha1/
+│   └── index.ts
+└── index.ts
+```
+
 ## CLI Commands
 
 ### `generate`
@@ -201,6 +339,86 @@ klasik download \
   --resolve-refs
 ```
 
+### `generate-crd`
+
+Generate TypeScript models from Kubernetes CustomResourceDefinition (CRD) YAML files.
+
+**Options:**
+- `-u, --url <url>` - URL or file path to CRD YAML (required)
+  - 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)
+- `--timeout <ms>` - Request timeout in milliseconds (default: 30000)
+
+**Examples:**
+
+```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
+
+# Generate with status models
+klasik generate-crd \
+  --url ./my-crd.yaml \
+  --output ./generated \
+  --include-status
+
+# NestJS integration with validation
+klasik generate-crd \
+  --url ./crds/ \
+  --output ./src/generated/k8s \
+  --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
+```
+
+**Output Structure:**
+
+For a single CRD:
+```
+output/
+├── v1alpha1/
+│   └── models/
+│       ├── my-resource.ts
+│       ├── my-resource-spec.ts
+│       ├── my-resource-status.ts  (if --include-status)
+│       └── ...
+└── index.ts
+```
+
+For multiple CRDs:
+```
+output/
+├── AppProject/
+│   ├── v1alpha1/
+│   └── index.ts
+├── Application/
+│   ├── v1alpha1/
+│   └── index.ts
+└── index.ts
+```
+
 ## Programmatic API
 
 ### K8sClientGenerator
@@ -250,6 +468,59 @@ console.log(`Spec downloaded to: ${specPath}`);
 downloader.cleanupTemp();
 ```
 
+### CRDGenerator
+
+Generate TypeScript models from Kubernetes CustomResourceDefinitions programmatically:
+
+```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
+});
+```
+
+**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/...
+```
+
 ## Generated Client Features
 
 The generated TypeScript client includes:

package/dist/cli.js

@@ -134,4 +134,53 @@ program
         process.exit(1);
     }
 });
+program
+    .command('generate-crd')
+    .description('Generate TypeScript models from Kubernetes CRD YAML files')
+    .requiredOption('-u, --url <url>', 'URL or file path to CRD YAML')
+    .requiredOption('-o, --output <dir>', 'Output directory for generated models')
+    .option('--include-status', 'Generate status schemas in addition to spec schemas', false)
+    .option('--nestjs-swagger', 'Include NestJS Swagger @ApiProperty decorators in generated models', false)
+    .option('--class-validator', 'Include class-validator decorators in generated models', false)
+    .option('--esm', 'Add .js extensions to imports for ESM compatibility', false)
+    .option('-H, --header <header...>', 'Custom headers for the request (format: "Key: Value")')
+    .option('--timeout <ms>', 'Request timeout in milliseconds', '30000')
+    .option('-t, --template <dir>', 'Custom template directory')
+    .option('-k, --keep-spec', 'Keep the generated OpenAPI spec files', false)
+    .action(async (options) => {
+    try {
+        // Parse headers if provided
+        const headers = {};
+        if (options.header) {
+            for (const header of options.header) {
+                const [key, ...valueParts] = header.split(':');
+                const value = valueParts.join(':').trim();
+                if (key && value) {
+                    headers[key.trim()] = value;
+                }
+            }
+        }
+        // Resolve output directory to absolute path
+        const outputDir = path.resolve(options.output);
+        const { CRDGenerator } = await Promise.resolve().then(() => __importStar(require('./crd/crd-generator')));
+        const generator = new CRDGenerator();
+        await generator.generate({
+            url: options.url,
+            outputDir,
+            includeStatus: options.includeStatus,
+            headers: Object.keys(headers).length > 0 ? headers : undefined,
+            timeout: parseInt(options.timeout, 10),
+            fixEsmImports: options.esm,
+            nestJsSwagger: options.nestjsSwagger,
+            classValidator: options.classValidator,
+            templateDir: options.template,
+            keepSpec: options.keepSpec,
+        });
+        process.exit(0);
+    }
+    catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
 program.parse();

package/dist/crd/crd-generator.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Options for CRD client generation
+ */
+export interface CRDGeneratorOptions {
+    /**
+     * URL or file path to CRD YAML file(s)
+     */
+    url: string;
+    /**
+     * Output directory for generated models
+     */
+    outputDir: string;
+    /**
+     * Whether to include status schemas in generation
+     * @default false
+     */
+    includeStatus?: boolean;
+    /**
+     * Custom headers for downloading CRDs from URLs
+     */
+    headers?: Record<string, string>;
+    /**
+     * Request timeout for downloading specs in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Whether to fix ESM imports by adding .js extensions
+     * @default false
+     */
+    fixEsmImports?: boolean;
+    /**
+     * Include NestJS Swagger @ApiProperty decorators
+     * @default false
+     */
+    nestJsSwagger?: boolean;
+    /**
+     * Include class-validator decorators
+     * @default false
+     */
+    classValidator?: boolean;
+    /**
+     * Skip adding .js extensions to imports/exports
+     * @default false
+     */
+    skipJsExtensions?: boolean;
+    /**
+     * Custom template directory
+     */
+    templateDir?: string;
+    /**
+     * Whether to keep the intermediate OpenAPI specs
+     * @default false
+     */
+    keepSpec?: boolean;
+}
+/**
+ * Main orchestrator for generating TypeScript models from Kubernetes CRDs
+ */
+export declare class CRDGenerator {
+    private parser;
+    private converter;
+    private k8sGenerator;
+    constructor();
+    /**
+     * Main generation workflow
+     * @param options Generation options
+     */
+    generate(options: CRDGeneratorOptions): Promise<void>;
+    /**
+     * Process a single CRD
+     * @param crd Parsed CRD
+     * @param outputDir Output directory for this CRD
+     * @param options Generation options
+     * @returns Array of version directory names
+     */
+    private processCRD;
+    /**
+     * Generate index file for a CRD (when multiple CRDs in one file)
+     * @param crdDir CRD directory
+     * @param versions Array of version names
+     */
+    private generateCRDIndex;
+    /**
+     * Generate main index file (when multiple CRDs in one file)
+     * @param outputDir Output directory
+     * @param crdNames Array of CRD kind names
+     */
+    private generateMainIndex;
+    /**
+     * Generate version index file (for single CRD)
+     * @param outputDir Output directory
+     * @param versions Array of version names
+     */
+    private generateVersionIndex;
+    /**
+     * Load CRD file from URL or local path
+     * @param url URL or file path
+     * @param headers Optional HTTP headers
+     * @param timeout Optional timeout in milliseconds
+     * @returns CRD file content as string
+     */
+    private loadCRDFile;
+    /**
+     * Check if the URL is a local file path
+     */
+    private isLocalFile;
+    /**
+     * Load CRD from local file
+     */
+    private loadLocalCRDFile;
+}