@vinkius-core/mcp-fusion-openapi-gen 1.0.0

package/README.md

@@ -0,0 +1,211 @@
+# @vinkius-core/mcp-fusion-openapi-gen
+
+> OpenAPI 3.x → **MCP Fusion** Server Generator
+
+[![npm version](https://img.shields.io/npm/v/@vinkius-core/mcp-fusion-openapi-gen.svg?style=flat-square&color=0ea5e9)](https://www.npmjs.com/package/@vinkius-core/mcp-fusion-openapi-gen)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue.svg?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-green.svg?style=flat-square)](../../LICENSE)
+
+Parse any OpenAPI 3.x spec and generate a **complete, ready-to-run MCP Server** powered by **MCP Fusion** — with Presenters, Tools, ToolRegistry, and server bootstrap. All features configurable via YAML.
+
+---
+
+## What It Generates
+
+Given an OpenAPI spec (YAML/JSON), the generator produces:
+
+```
+output/
+├── models/                # M — Zod schemas (data boundary)
+│   ├── pet.schema.ts
+│   └── store.schema.ts
+├── views/                 # V — createPresenter() (perception layer)
+│   ├── pet.presenter.ts
+│   └── store.presenter.ts
+├── agents/                # A — Agent layer — defineTool()
+│   ├── pet.tool.ts
+│   └── store.tool.ts
+├── server.ts              # MCP Server bootstrap
+└── index.ts               # ToolRegistry + registerAll barrel
+```
+
+Every file follows the **[MVA Convention](/mva-convention)** — the standard directory structure for **MCP Fusion** projects.
+
+## Installation
+
+```bash
+npm install @vinkius-core/mcp-fusion-openapi-gen
+```
+
+## Quick Start
+
+### 1. Generate from OpenAPI spec
+
+```bash
+npx openapi-gen --input ./petstore.yaml --output ./generated
+```
+
+### 2. Run the generated server
+
+```bash
+API_BASE_URL=https://api.example.com npx tsx ./generated/server.ts
+```
+
+That's it — you have a fully functional MCP Server.
+
+## Configuration
+
+Create an `openapi-gen.yaml` file in your project root for full control:
+
+```yaml
+# openapi-gen.yaml
+input: ./specs/petstore.yaml
+output: ./generated
+
+features:
+  tags: true              # Add tags to tools
+  annotations: true       # Infer readOnly, destructive, idempotent from HTTP method
+  presenters: true        # Generate Presenter files with response schemas
+  descriptions: true      # Include summaries/descriptions on actions
+  toonDescription: false  # Enable TOON-optimized descriptions
+  serverFile: true        # Generate server.ts bootstrap
+  deprecated: comment     # 'include' | 'skip' | 'comment'
+
+naming:
+  style: snake_case       # 'snake_case' | 'camelCase'
+  deduplication: true     # Auto-suffix duplicates (_2, _3, ...)
+
+server:
+  name: petstore-mcp
+  version: 1.0.0
+  transport: stdio          # 'stdio' | 'sse'
+  toolExposition: flat      # 'flat' | 'grouped' — how the LLM sees your tools
+  actionSeparator: '_'      # Flat mode delimiter: pet_get_by_id
+
+context:
+  import: '../types.js#AppCtx'  # Custom context type
+
+# Tag filtering
+includeTags:
+  - pet
+  - store
+excludeTags:
+  - internal
+```
+
+Auto-detected when present, or pass explicitly:
+
+```bash
+npx openapi-gen --config ./openapi-gen.yaml
+```
+
+## CLI Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--input <path>` | Path to OpenAPI YAML/JSON spec | From config |
+| `--output <dir>` | Output directory | `./generated` |
+| `--config <path>` | Path to config file | Auto-detect `openapi-gen.yaml` |
+| `--base-url <expr>` | Base URL expression for fetch calls | `ctx.baseUrl` |
+| `--server-name <name>` | MCP Server name | `openapi-mcp-server` |
+| `--context <import>` | Custom context type import | Default `ApiContext` |
+
+CLI flags override config file values.
+
+## Generated Code Features
+
+### Annotations (from HTTP Method)
+
+```typescript
+// GET → readOnly: true
+// DELETE → destructive: true
+// PUT → idempotent: true
+```
+
+### Coerced Path/Query Parameters
+
+```typescript
+// Path and query params use z.coerce for safe string-to-type conversion
+petId: z.coerce.number().int().describe('ID of pet to return')
+```
+
+### Presenter Binding
+
+```typescript
+// Each action with a response schema binds to a Presenter
+get_pet_by_id: {
+    returns: PetPresenter,
+    // ...
+}
+```
+
+### Tag Filtering
+
+Only generate tools for the tags you need:
+
+```yaml
+includeTags: [pet]         # Only pet tools
+excludeTags: [internal]    # Everything except internal
+```
+
+### Custom Context
+
+Inject your own typed context into all tools:
+
+```yaml
+context:
+  import: '../types.js#AppCtx'
+```
+
+Generates:
+
+```typescript
+import type { AppCtx } from '../types.js';
+const petTools = defineTool<AppCtx>('pet', { ... });
+```
+
+## Programmatic API
+
+```typescript
+import { parseOpenAPI, mapEndpoints, emitFiles, mergeConfig } from '@vinkius-core/mcp-fusion-openapi-gen';
+
+const spec = parseOpenAPI(yamlString);
+const mapped = mapEndpoints(spec);
+const config = mergeConfig({ features: { tags: true }, includeTags: ['pet'] });
+const files = emitFiles(mapped, config);
+
+for (const file of files) {
+    writeFileSync(`./out/${file.path}`, file.content);
+}
+```
+
+## Pipeline
+
+```
+OpenAPI 3.x Spec (YAML/JSON)
+        │
+        ▼
+  ┌─────────────┐
+  │ OpenApiParser │  → ApiSpec IR (groups, actions, params, responses)
+  └─────────────┘
+        │
+        ▼
+  ┌───────────────┐
+  │ EndpointMapper │  → Named actions (snake_case), dedup, annotations
+  └───────────────┘
+        │
+        ▼
+  ┌────────────┐
+  │ CodeEmitter │  → TypeScript files (Presenters, Tools, Registry, Server)
+  └────────────┘
+```
+
+## Requirements
+
+- Node.js ≥ 18
+- `@vinkius-core/mcp-fusion` ^2.0.0 (peer dependency)
+- `zod` ^3.25.1 || ^4.0.0 (peer dependency)
+
+## License
+
+Apache-2.0

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * CLI Entry Point — openapi-gen
+ *
+ * Usage:
+ *   openapi-gen generate -i <spec> -o <outDir> [--config <config.yaml>] [--base-url <url>]
+ *
+ * @module
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { parseOpenAPI } from './parser/OpenApiParser.js';
+import { mapEndpoints } from './mapper/EndpointMapper.js';
+import { emitFiles } from './emitter/CodeEmitter.js';
+import { loadConfig, applyCliOverrides } from './config/ConfigLoader.js';
+function parseArgs(argv) {
+    const args = argv.slice(2);
+    const command = args[0] ?? '';
+    const result = {};
+    for (let i = 1; i < args.length; i++) {
+        const arg = args[i];
+        switch (arg) {
+            case '-i':
+            case '--input':
+                result['input'] = args[++i];
+                break;
+            case '-o':
+            case '--output':
+                result['output'] = args[++i];
+                break;
+            case '--base-url':
+                result['baseUrl'] = args[++i];
+                break;
+            case '--context':
+                result['context'] = args[++i];
+                break;
+            case '-c':
+            case '--config':
+                result['config'] = args[++i];
+                break;
+            case '--server-name':
+                result['serverName'] = args[++i];
+                break;
+        }
+    }
+    return {
+        command,
+        ...(result['input'] !== undefined ? { input: result['input'] } : {}),
+        ...(result['output'] !== undefined ? { output: result['output'] } : {}),
+        ...(result['baseUrl'] !== undefined ? { baseUrl: result['baseUrl'] } : {}),
+        ...(result['context'] !== undefined ? { context: result['context'] } : {}),
+        ...(result['config'] !== undefined ? { config: result['config'] } : {}),
+        ...(result['serverName'] !== undefined ? { serverName: result['serverName'] } : {}),
+    };
+}
+// ── Commands ─────────────────────────────────────────────
+function runGenerate(rawArgs) {
+    // Load config (YAML file → defaults → CLI overrides)
+    const baseConfig = loadConfig(rawArgs.config);
+    const overrides = {
+        ...(rawArgs.input !== undefined ? { input: rawArgs.input } : {}),
+        ...(rawArgs.output !== undefined ? { output: rawArgs.output } : {}),
+        ...(rawArgs.baseUrl !== undefined ? { baseUrl: rawArgs.baseUrl } : {}),
+        ...(rawArgs.context !== undefined ? { contextImport: rawArgs.context } : {}),
+        ...(rawArgs.serverName !== undefined ? { serverName: rawArgs.serverName } : {}),
+    };
+    const config = applyCliOverrides(baseConfig, overrides);
+    // Resolve input
+    const inputPath = config.input ?? rawArgs.input;
+    if (!inputPath) {
+        console.error('Error: --input (-i) is required (or set `input` in config file).');
+        console.error('Usage: openapi-gen generate -i <spec.yaml> -o <outDir>');
+        process.exit(1);
+    }
+    const specPath = resolve(inputPath);
+    let specContent;
+    try {
+        specContent = readFileSync(specPath, 'utf-8');
+    }
+    catch {
+        console.error(`Error: Cannot read file "${specPath}".`);
+        process.exit(1);
+    }
+    console.log(`📂 Parsing: ${specPath}`);
+    // Parse + Map
+    const spec = parseOpenAPI(specContent);
+    const mapped = mapEndpoints(spec);
+    console.log(`✅ Parsed: ${spec.title} v${spec.version}`);
+    console.log(`📋 Groups: ${mapped.groups.length}`);
+    const totalActions = mapped.groups.reduce((sum, g) => sum + g.actions.length, 0);
+    console.log(`🔧 Actions: ${totalActions}`);
+    // Show active features
+    console.log(`\n⚙️  Features:`);
+    console.log(`   Tags: ${config.features.tags ? '✅' : '❌'}`);
+    console.log(`   Annotations: ${config.features.annotations ? '✅' : '❌'}`);
+    console.log(`   Presenters: ${config.features.presenters ? '✅' : '❌'}`);
+    console.log(`   Descriptions: ${config.features.descriptions ? '✅' : '❌'}`);
+    console.log(`   Server file: ${config.features.serverFile ? '✅' : '❌'}`);
+    console.log(`   toonDescription: ${config.features.toonDescription ? '✅' : '❌'}`);
+    // Emit
+    const files = emitFiles(mapped, config);
+    // Write output
+    const outDir = resolve(config.output ?? './generated');
+    mkdirSync(outDir, { recursive: true });
+    for (const file of files) {
+        const filePath = join(outDir, file.path);
+        writeFileSync(filePath, file.content, 'utf-8');
+        console.log(`  📄 ${file.path}`);
+    }
+    console.log(`\n🎉 Generated ${files.length} files in ${outDir}`);
+    if (config.features.serverFile) {
+        console.log(`\n🚀 Run your MCP server:`);
+        console.log(`   API_BASE_URL=https://api.example.com npx tsx ${outDir}/server.ts`);
+    }
+}
+function printHelp() {
+    console.log(`
+openapi-gen — OpenAPI → MCP Fusion Server Generator
+
+USAGE:
+  openapi-gen generate -i <spec> -o <outDir> [options]
+
+COMMANDS:
+  generate    Parse OpenAPI spec and generate a complete MCP Server
+
+OPTIONS:
+  -i, --input <file>         OpenAPI spec file (YAML or JSON)
+  -o, --output <dir>         Output directory (default: ./generated)
+  -c, --config <file>        Config file (default: auto-detect openapi-gen.yaml)
+  --base-url <url>           Base URL expression for fetch calls
+  --context <path#Type>      Custom context type import
+  --server-name <name>       MCP Server name
+  --help                     Show this help message
+
+CONFIG FILE (openapi-gen.yaml):
+  input: ./petstore.yaml
+  output: ./src/generated
+  features:
+    tags: true
+    annotations: true
+    presenters: true
+    descriptions: true
+    deprecated: comment       # skip | comment | include
+    toonDescription: false
+    serverFile: true
+  context:
+    import: '../types.js#AppCtx'
+  server:
+    name: my-api-server
+    version: 1.0.0
+    transport: stdio
+  includeTags: []
+  excludeTags: []
+
+EXAMPLES:
+  openapi-gen generate -i petstore.yaml -o ./src/mcp
+  openapi-gen generate -i api.json -o ./mcp --config project.yaml
+  openapi-gen generate -i spec.yaml -o ./tools --server-name "my-tools"
+`);
+}
+// ── Main ─────────────────────────────────────────────────
+const cliArgs = parseArgs(process.argv);
+switch (cliArgs.command) {
+    case 'generate':
+        runGenerate(cliArgs);
+        break;
+    case '--help':
+    case 'help':
+    case '':
+        printHelp();
+        break;
+    default:
+        console.error(`Unknown command: "${cliArgs.command}". Use --help for usage.`);
+        process.exit(1);
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/config/ConfigLoader.d.ts

@@ -0,0 +1,29 @@
+import { type GeneratorConfig } from './GeneratorConfig.js';
+/**
+ * Load configuration from a YAML/JSON file.
+ *
+ * Priority:
+ *   1. Explicit `configPath` argument
+ *   2. Auto-detect `openapi-gen.yaml` in `cwd`
+ *   3. Fall back to all defaults
+ *
+ * @param configPath - Explicit path to config file (optional)
+ * @param cwd - Working directory for auto-detection (default: process.cwd())
+ * @returns Fully merged GeneratorConfig
+ */
+export declare function loadConfig(configPath?: string, cwd?: string): GeneratorConfig;
+/**
+ * Merge a loaded config with CLI argument overrides.
+ *
+ * CLI args take precedence over file values.
+ */
+export declare function applyCliOverrides(config: GeneratorConfig, cli: CliOverrides): GeneratorConfig;
+/** CLI arguments that can override config file values */
+export interface CliOverrides {
+    readonly input?: string;
+    readonly output?: string;
+    readonly baseUrl?: string;
+    readonly contextImport?: string;
+    readonly serverName?: string;
+}
+//# sourceMappingURL=ConfigLoader.d.ts.map

package/dist/config/ConfigLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConfigLoader.d.ts","sourceRoot":"","sources":["../../src/config/ConfigLoader.ts"],"names":[],"mappings":"AAWA,OAAO,EAAe,KAAK,eAAe,EAAsB,MAAM,sBAAsB,CAAC;AAY7F;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,eAAe,CAsB7E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,EAAE,YAAY,GAAG,eAAe,CAe7F;AAED,yDAAyD;AACzD,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAChC"}

package/dist/config/ConfigLoader.js

@@ -0,0 +1,81 @@
+/**
+ * ConfigLoader — YAML Configuration File Reader
+ *
+ * Loads `openapi-gen.yaml` from cwd or a specified path, validates
+ * the structure, and merges with defaults. CLI args override file values.
+ *
+ * @module
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { mergeConfig } from './GeneratorConfig.js';
+// ── Filename Conventions ─────────────────────────────────
+const CONFIG_FILENAMES = [
+    'openapi-gen.yaml',
+    'openapi-gen.yml',
+    'openapi-gen.json',
+];
+// ── Public API ───────────────────────────────────────────
+/**
+ * Load configuration from a YAML/JSON file.
+ *
+ * Priority:
+ *   1. Explicit `configPath` argument
+ *   2. Auto-detect `openapi-gen.yaml` in `cwd`
+ *   3. Fall back to all defaults
+ *
+ * @param configPath - Explicit path to config file (optional)
+ * @param cwd - Working directory for auto-detection (default: process.cwd())
+ * @returns Fully merged GeneratorConfig
+ */
+export function loadConfig(configPath, cwd) {
+    const workDir = cwd ?? process.cwd();
+    // 1. Explicit path
+    if (configPath) {
+        const absPath = resolve(workDir, configPath);
+        if (!existsSync(absPath)) {
+            throw new Error(`Config file not found: "${absPath}"`);
+        }
+        return parseConfigFile(absPath);
+    }
+    // 2. Auto-detect
+    for (const filename of CONFIG_FILENAMES) {
+        const candidate = join(workDir, filename);
+        if (existsSync(candidate)) {
+            return parseConfigFile(candidate);
+        }
+    }
+    // 3. All defaults
+    return mergeConfig({});
+}
+/**
+ * Merge a loaded config with CLI argument overrides.
+ *
+ * CLI args take precedence over file values.
+ */
+export function applyCliOverrides(config, cli) {
+    return {
+        ...config,
+        ...(cli.input !== undefined ? { input: cli.input } : {}),
+        ...(cli.output !== undefined ? { output: cli.output } : {}),
+        ...(cli.baseUrl !== undefined ? { baseUrl: cli.baseUrl } : {}),
+        context: {
+            ...config.context,
+            ...(cli.contextImport !== undefined ? { import: cli.contextImport } : {}),
+        },
+        server: {
+            ...config.server,
+            ...(cli.serverName !== undefined ? { name: cli.serverName } : {}),
+        },
+    };
+}
+// ── Internal ─────────────────────────────────────────────
+function parseConfigFile(filePath) {
+    const content = readFileSync(filePath, 'utf-8');
+    const raw = filePath.endsWith('.json')
+        ? JSON.parse(content)
+        : parseYaml(content);
+    return mergeConfig(raw);
+}
+//# sourceMappingURL=ConfigLoader.js.map

package/dist/config/ConfigLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConfigLoader.js","sourceRoot":"","sources":["../../src/config/ConfigLoader.ts"],"names":[],"mappings":"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"}

package/dist/config/GeneratorConfig.d.ts

@@ -0,0 +1,110 @@
+/**
+ * GeneratorConfig — Full Configuration for the OpenAPI-to-MCP Generator
+ *
+ * Controls every aspect of code generation: which MCP Fusion features
+ * are enabled, naming conventions, tag filtering, server scaffolding,
+ * and context injection.
+ *
+ * Can be loaded from a YAML file (`openapi-gen.yaml`) or passed programmatically.
+ *
+ * @module
+ */
+/**
+ * Controls which MCP Fusion features appear in generated code.
+ * All fields default to `true` for maximum fidelity.
+ */
+export interface FeatureFlags {
+    /** Apply OpenAPI tags as MCP tool tags via `.tags()` */
+    readonly tags: boolean;
+    /** Infer `readOnly` / `destructive` / `idempotent` from HTTP methods */
+    readonly annotations: boolean;
+    /** Generate Presenter files with `createPresenter()` + Zod response schemas */
+    readonly presenters: boolean;
+    /** Chain `.describe()` on every Zod field that has an OpenAPI description */
+    readonly descriptions: boolean;
+    /** Handle deprecated operations: 'skip' = omit, 'comment' = add @deprecated JSDoc */
+    readonly deprecated: 'skip' | 'comment' | 'include';
+    /** Enable `toonDescription: true` on generated `defineTool()` calls */
+    readonly toonDescription: boolean;
+    /** Generate a complete MCP Server file (`server.ts`) with `attachToServer()` */
+    readonly serverFile: boolean;
+}
+/** Controls how action names are derived from operationId / path */
+export interface NamingConfig {
+    /** Action naming style */
+    readonly style: 'snake_case' | 'camelCase';
+    /** Append _2, _3 for collision resolution */
+    readonly deduplication: boolean;
+}
+/** Controls the context type used in generated tools */
+export interface ContextConfig {
+    /** Import path with type name, e.g. `'../src/types.js#MyAppContext'` */
+    readonly import?: string;
+}
+/** Controls the generated MCP Server file */
+export interface ServerConfig {
+    /** Server name shown to MCP clients */
+    readonly name: string;
+    /** Server version */
+    readonly version: string;
+    /** Transport type for the generated server */
+    readonly transport: 'stdio' | 'sse';
+    /**
+     * Exposition strategy for projecting tools onto the MCP wire format.
+     * - `'flat'`    — Each action becomes an independent MCP tool (default)
+     * - `'grouped'` — All actions in a builder merge into a single MCP tool
+     */
+    readonly toolExposition: 'flat' | 'grouped';
+    /**
+     * Separator for flat mode action naming: `{toolName}{separator}{actionKey}`.
+     * @default '_'
+     * @example 'pet_get_by_id', 'pet.get_by_id', 'pet-get_by_id'
+     */
+    readonly actionSeparator: string;
+}
+/**
+ * Complete generator configuration.
+ *
+ * Can be loaded from `openapi-gen.yaml` or passed to `emitFiles()`.
+ * All fields have sensible defaults — see {@link DEFAULT_CONFIG}.
+ */
+export interface GeneratorConfig {
+    /** Path to OpenAPI spec file (YAML or JSON) */
+    readonly input?: string;
+    /** Output directory for generated files */
+    readonly output?: string;
+    /** Base URL expression for fetch calls (default: `'ctx.baseUrl'`) */
+    readonly baseUrl?: string;
+    /** Feature toggles */
+    readonly features: FeatureFlags;
+    /** Naming conventions */
+    readonly naming: NamingConfig;
+    /** Context type injection */
+    readonly context: ContextConfig;
+    /** Server generation settings */
+    readonly server: ServerConfig;
+    /** Only generate tools for these tags (empty = all) */
+    readonly includeTags: readonly string[];
+    /** Exclude these tags from generation */
+    readonly excludeTags: readonly string[];
+}
+/** Default configuration — all features enabled */
+export declare const DEFAULT_CONFIG: GeneratorConfig;
+/**
+ * Deep-merge a partial config with defaults.
+ * Partial values override defaults at each level.
+ */
+export declare function mergeConfig(partial: PartialConfig): GeneratorConfig;
+/** Partial config shape for merging */
+export interface PartialConfig {
+    readonly input?: string;
+    readonly output?: string;
+    readonly baseUrl?: string;
+    readonly features?: Partial<FeatureFlags>;
+    readonly naming?: Partial<NamingConfig>;
+    readonly context?: Partial<ContextConfig>;
+    readonly server?: Partial<ServerConfig>;
+    readonly includeTags?: readonly string[];
+    readonly excludeTags?: readonly string[];
+}
+//# sourceMappingURL=GeneratorConfig.d.ts.map

package/dist/config/GeneratorConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GeneratorConfig.d.ts","sourceRoot":"","sources":["../../src/config/GeneratorConfig.ts"],"names":[],"mappings":"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"}