@portel/photon-core 1.3.0 → 1.4.0

package/dist/mcp-client.js

@@ -186,6 +186,219 @@ export class MCPToolError extends MCPError {
         this.name = 'MCPToolError';
     }
 }
+/**
+ * Error thrown when MCP is not configured correctly
+ * Provides detailed, actionable guidance for users
+ */
+export class MCPConfigurationError extends MCPError {
+    configPath;
+    missingMCPs;
+    constructor(missingMCPs) {
+        const configPath = `~/.photon/mcp-servers.json`;
+        const message = MCPConfigurationError.formatMessage(missingMCPs, configPath);
+        super(missingMCPs[0]?.name || 'unknown', message);
+        this.name = 'MCPConfigurationError';
+        this.configPath = configPath;
+        this.missingMCPs = missingMCPs;
+    }
+    /**
+     * Format detailed error message with configuration instructions
+     */
+    static formatMessage(missingMCPs, configPath) {
+        const lines = [
+            '',
+            '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━',
+            '❌ MCP Configuration Required',
+            '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━',
+            '',
+        ];
+        // List missing MCPs
+        lines.push(`The following MCP server${missingMCPs.length > 1 ? 's are' : ' is'} required but not configured:`);
+        lines.push('');
+        for (const mcp of missingMCPs) {
+            lines.push(`  • ${mcp.name}`);
+            if (mcp.source) {
+                lines.push(`    Source: ${mcp.source} (${mcp.sourceType})`);
+            }
+            if (mcp.declaredIn) {
+                lines.push(`    Declared in: ${mcp.declaredIn}`);
+            }
+            if (mcp.originalError) {
+                lines.push(`    Error: ${mcp.originalError}`);
+            }
+            lines.push('');
+        }
+        // Configuration instructions
+        lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        lines.push('🔧 How to Fix');
+        lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        lines.push('');
+        lines.push(`Add the following to ${configPath}:`);
+        lines.push('');
+        // Generate example config
+        const exampleConfig = MCPConfigurationError.generateExampleConfig(missingMCPs);
+        lines.push(exampleConfig);
+        lines.push('');
+        // Step-by-step instructions
+        lines.push('Steps:');
+        lines.push(`  1. Create or edit ${configPath}`);
+        lines.push('  2. Add the configuration above');
+        lines.push('  3. Replace placeholder values with your actual configuration');
+        lines.push('  4. Restart the Photon');
+        lines.push('');
+        // Per-source-type guidance
+        const uniqueTypes = new Set(missingMCPs.map(m => m.sourceType));
+        if (uniqueTypes.size > 0) {
+            lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+            lines.push('📖 Configuration Guide');
+            lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+            lines.push('');
+            for (const type of uniqueTypes) {
+                lines.push(...MCPConfigurationError.getSourceTypeGuide(type));
+                lines.push('');
+            }
+        }
+        lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        return lines.join('\n');
+    }
+    /**
+     * Generate example JSON config for missing MCPs
+     */
+    static generateExampleConfig(missingMCPs) {
+        const servers = {};
+        for (const mcp of missingMCPs) {
+            servers[mcp.name] = MCPConfigurationError.getExampleServerConfig(mcp);
+        }
+        const config = { mcpServers: servers };
+        return JSON.stringify(config, null, 2)
+            .split('\n')
+            .map(line => '  ' + line)
+            .join('\n');
+    }
+    /**
+     * Get example server config based on source type
+     */
+    static getExampleServerConfig(mcp) {
+        switch (mcp.sourceType) {
+            case 'npm':
+                return {
+                    command: 'npx',
+                    args: ['-y', mcp.source],
+                    env: {
+                        '// Add required environment variables here': '',
+                    },
+                };
+            case 'github': {
+                // Parse github source: owner/repo or owner/repo#branch
+                const [repo, branch] = mcp.source.split('#');
+                const args = ['-y', `github:${repo}`];
+                if (branch) {
+                    args[1] = `github:${repo}#${branch}`;
+                }
+                return {
+                    command: 'npx',
+                    args,
+                    env: {
+                        '// Add required environment variables here': '',
+                    },
+                };
+            }
+            case 'url':
+                if (mcp.source.startsWith('ws://') || mcp.source.startsWith('wss://')) {
+                    return {
+                        url: mcp.source,
+                        transport: 'websocket',
+                    };
+                }
+                return {
+                    url: mcp.source,
+                    transport: 'sse',
+                };
+            case 'local':
+                return {
+                    command: mcp.source,
+                    args: [],
+                    cwd: '// Optional: working directory',
+                };
+            default:
+                return {
+                    '// Configure this MCP server': '',
+                    command: 'npx',
+                    args: ['-y', '<package-name>'],
+                };
+        }
+    }
+    /**
+     * Get source-type specific guidance
+     */
+    static getSourceTypeGuide(type) {
+        switch (type) {
+            case 'npm':
+                return [
+                    '📦 NPM Packages:',
+                    '   MCP servers from npm are run via npx.',
+                    '   Example: @modelcontextprotocol/server-github',
+                    '',
+                    '   {',
+                    '     "command": "npx",',
+                    '     "args": ["-y", "@modelcontextprotocol/server-github"],',
+                    '     "env": {',
+                    '       "GITHUB_TOKEN": "ghp_your_token_here"',
+                    '     }',
+                    '   }',
+                ];
+            case 'github':
+                return [
+                    '🐙 GitHub Repositories:',
+                    '   MCP servers from GitHub repos are cloned and run.',
+                    '   Format: owner/repo or owner/repo#branch',
+                    '',
+                    '   {',
+                    '     "command": "npx",',
+                    '     "args": ["-y", "github:anthropics/mcp-server-github"],',
+                    '     "env": {',
+                    '       "GITHUB_TOKEN": "ghp_your_token_here"',
+                    '     }',
+                    '   }',
+                ];
+            case 'url':
+                return [
+                    '🌐 Remote URLs:',
+                    '   MCP servers running on remote hosts.',
+                    '',
+                    '   HTTP/SSE:',
+                    '   {',
+                    '     "url": "https://mcp.example.com/api",',
+                    '     "transport": "sse",',
+                    '     "headers": { "Authorization": "Bearer token" }',
+                    '   }',
+                    '',
+                    '   WebSocket:',
+                    '   {',
+                    '     "url": "wss://mcp.example.com/ws",',
+                    '     "transport": "websocket"',
+                    '   }',
+                ];
+            case 'local':
+                return [
+                    '💻 Local Commands:',
+                    '   MCP servers running as local processes.',
+                    '',
+                    '   {',
+                    '     "command": "/path/to/mcp-server",',
+                    '     "args": ["--port", "3000"],',
+                    '     "cwd": "/working/directory",',
+                    '     "env": { "CONFIG": "value" }',
+                    '   }',
+                ];
+            default:
+                return [
+                    '⚙️ Custom Configuration:',
+                    '   Configure the MCP server based on its documentation.',
+                ];
+        }
+    }
+}
 /**
  * Create a proxy-based MCP client that allows direct method calls
  *

package/dist/mcp-client.js.map

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

package/dist/photon-config.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Photon Runtime Configuration
+ *
+ * Manages ~/.photon/mcp-servers.json for MCP server configuration.
+ * Compatible with Claude Desktop's mcpServers format.
+ */
+import type { MCPConfig, MCPServerConfig } from './mcp-sdk-transport.js';
+/**
+ * Default config directory
+ */
+export declare const PHOTON_CONFIG_DIR: string;
+/**
+ * Default MCP servers config file
+ */
+export declare const MCP_SERVERS_CONFIG_FILE: string;
+/**
+ * Photon MCP servers configuration file format
+ * Compatible with Claude Desktop's mcpServers format
+ */
+export interface PhotonMCPConfig {
+    mcpServers: Record<string, MCPServerConfig>;
+}
+/**
+ * Load MCP servers configuration from ~/.photon/mcp-servers.json
+ *
+ * @param configPath Optional custom config path (defaults to ~/.photon/mcp-servers.json)
+ * @returns The MCP configuration, or empty config if file doesn't exist
+ */
+export declare function loadPhotonMCPConfig(configPath?: string): Promise<PhotonMCPConfig>;
+/**
+ * Save MCP servers configuration to ~/.photon/mcp-servers.json
+ *
+ * @param config The configuration to save
+ * @param configPath Optional custom config path
+ */
+export declare function savePhotonMCPConfig(config: PhotonMCPConfig, configPath?: string): Promise<void>;
+/**
+ * Check if an MCP server is configured
+ *
+ * @param mcpName The MCP server name to check
+ * @param config Optional pre-loaded config (loads from file if not provided)
+ */
+export declare function isMCPConfigured(mcpName: string, config?: PhotonMCPConfig): Promise<boolean>;
+/**
+ * Get configuration for a specific MCP server
+ *
+ * @param mcpName The MCP server name
+ * @param config Optional pre-loaded config
+ * @returns The server config or undefined if not found
+ */
+export declare function getMCPServerConfig(mcpName: string, config?: PhotonMCPConfig): Promise<MCPServerConfig | undefined>;
+/**
+ * Add or update an MCP server configuration
+ *
+ * @param mcpName The MCP server name
+ * @param serverConfig The server configuration
+ * @param configPath Optional custom config path
+ */
+export declare function setMCPServerConfig(mcpName: string, serverConfig: MCPServerConfig, configPath?: string): Promise<void>;
+/**
+ * Remove an MCP server configuration
+ *
+ * @param mcpName The MCP server name to remove
+ * @param configPath Optional custom config path
+ */
+export declare function removeMCPServerConfig(mcpName: string, configPath?: string): Promise<void>;
+/**
+ * List all configured MCP servers
+ *
+ * @param configPath Optional custom config path
+ * @returns Array of MCP server names
+ */
+export declare function listMCPServers(configPath?: string): Promise<string[]>;
+/**
+ * Convert PhotonMCPConfig to MCPConfig (for SDK transport)
+ */
+export declare function toMCPConfig(config: PhotonMCPConfig): MCPConfig;
+/**
+ * Merge environment variables into MCP server config
+ * Supports ${VAR_NAME} syntax for env var references
+ *
+ * @param serverConfig The server config to process
+ * @returns Config with env vars resolved
+ */
+export declare function resolveEnvVars(serverConfig: MCPServerConfig): MCPServerConfig;
+//# sourceMappingURL=photon-config.d.ts.map

package/dist/photon-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"photon-config.d.ts","sourceRoot":"","sources":["../src/photon-config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzE;;GAEG;AACH,eAAO,MAAM,iBAAiB,QAAqC,CAAC;AAEpE;;GAEG;AACH,eAAO,MAAM,uBAAuB,QAAmD,CAAC;AAExF;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAC7C;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAsBvF;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,eAAe,EACvB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAGtC;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,eAAe,EAC7B,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAIf;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAIf;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAG3E;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAI9D;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,eAAe,GAAG,eAAe,CAuB7E"}

package/dist/photon-config.js

@@ -0,0 +1,156 @@
+/**
+ * Photon Runtime Configuration
+ *
+ * Manages ~/.photon/mcp-servers.json for MCP server configuration.
+ * Compatible with Claude Desktop's mcpServers format.
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+/**
+ * Default config directory
+ */
+export const PHOTON_CONFIG_DIR = path.join(os.homedir(), '.photon');
+/**
+ * Default MCP servers config file
+ */
+export const MCP_SERVERS_CONFIG_FILE = path.join(PHOTON_CONFIG_DIR, 'mcp-servers.json');
+/**
+ * Load MCP servers configuration from ~/.photon/mcp-servers.json
+ *
+ * @param configPath Optional custom config path (defaults to ~/.photon/mcp-servers.json)
+ * @returns The MCP configuration, or empty config if file doesn't exist
+ */
+export async function loadPhotonMCPConfig(configPath) {
+    const filePath = configPath || MCP_SERVERS_CONFIG_FILE;
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const config = JSON.parse(content);
+        // Validate structure
+        if (!config.mcpServers || typeof config.mcpServers !== 'object') {
+            console.error(`Invalid config format in ${filePath}: missing mcpServers`);
+            return { mcpServers: {} };
+        }
+        return config;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            // File doesn't exist - return empty config
+            return { mcpServers: {} };
+        }
+        console.error(`Failed to load config from ${filePath}: ${error.message}`);
+        return { mcpServers: {} };
+    }
+}
+/**
+ * Save MCP servers configuration to ~/.photon/mcp-servers.json
+ *
+ * @param config The configuration to save
+ * @param configPath Optional custom config path
+ */
+export async function savePhotonMCPConfig(config, configPath) {
+    const filePath = configPath || MCP_SERVERS_CONFIG_FILE;
+    const dir = path.dirname(filePath);
+    // Ensure directory exists
+    await fs.mkdir(dir, { recursive: true });
+    // Write config with pretty formatting
+    await fs.writeFile(filePath, JSON.stringify(config, null, 2), 'utf-8');
+}
+/**
+ * Check if an MCP server is configured
+ *
+ * @param mcpName The MCP server name to check
+ * @param config Optional pre-loaded config (loads from file if not provided)
+ */
+export async function isMCPConfigured(mcpName, config) {
+    const cfg = config || await loadPhotonMCPConfig();
+    return mcpName in cfg.mcpServers;
+}
+/**
+ * Get configuration for a specific MCP server
+ *
+ * @param mcpName The MCP server name
+ * @param config Optional pre-loaded config
+ * @returns The server config or undefined if not found
+ */
+export async function getMCPServerConfig(mcpName, config) {
+    const cfg = config || await loadPhotonMCPConfig();
+    return cfg.mcpServers[mcpName];
+}
+/**
+ * Add or update an MCP server configuration
+ *
+ * @param mcpName The MCP server name
+ * @param serverConfig The server configuration
+ * @param configPath Optional custom config path
+ */
+export async function setMCPServerConfig(mcpName, serverConfig, configPath) {
+    const config = await loadPhotonMCPConfig(configPath);
+    config.mcpServers[mcpName] = serverConfig;
+    await savePhotonMCPConfig(config, configPath);
+}
+/**
+ * Remove an MCP server configuration
+ *
+ * @param mcpName The MCP server name to remove
+ * @param configPath Optional custom config path
+ */
+export async function removeMCPServerConfig(mcpName, configPath) {
+    const config = await loadPhotonMCPConfig(configPath);
+    delete config.mcpServers[mcpName];
+    await savePhotonMCPConfig(config, configPath);
+}
+/**
+ * List all configured MCP servers
+ *
+ * @param configPath Optional custom config path
+ * @returns Array of MCP server names
+ */
+export async function listMCPServers(configPath) {
+    const config = await loadPhotonMCPConfig(configPath);
+    return Object.keys(config.mcpServers);
+}
+/**
+ * Convert PhotonMCPConfig to MCPConfig (for SDK transport)
+ */
+export function toMCPConfig(config) {
+    return {
+        mcpServers: config.mcpServers,
+    };
+}
+/**
+ * Merge environment variables into MCP server config
+ * Supports ${VAR_NAME} syntax for env var references
+ *
+ * @param serverConfig The server config to process
+ * @returns Config with env vars resolved
+ */
+export function resolveEnvVars(serverConfig) {
+    const resolved = { ...serverConfig };
+    // Process env object if present
+    if (resolved.env) {
+        const processedEnv = {};
+        for (const [key, value] of Object.entries(resolved.env)) {
+            processedEnv[key] = resolveEnvValue(value);
+        }
+        resolved.env = processedEnv;
+    }
+    // Process args if present
+    if (resolved.args) {
+        resolved.args = resolved.args.map(resolveEnvValue);
+    }
+    // Process url if present
+    if (resolved.url) {
+        resolved.url = resolveEnvValue(resolved.url);
+    }
+    return resolved;
+}
+/**
+ * Resolve ${VAR_NAME} references in a string value
+ */
+function resolveEnvValue(value) {
+    return value.replace(/\$\{([^}]+)\}/g, (_, varName) => {
+        return process.env[varName] || '';
+    });
+}
+//# sourceMappingURL=photon-config.js.map

package/dist/photon-config.js.map

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

package/dist/schema-extractor.d.ts

@@ -7,7 +7,7 @@
  *
  * Now uses TypeScript's compiler API for robust type parsing
  */
-import { ExtractedSchema, ConstructorParam, TemplateInfo, StaticInfo, MCPDependency } from './types.js';
+import { ExtractedSchema, ConstructorParam, TemplateInfo, StaticInfo, MCPDependency, PhotonDependency, ResolvedInjection, PhotonAssets } from './types.js';
 export interface ExtractedMetadata {
     tools: ExtractedSchema[];
     templates: TemplateInfo[];
@@ -53,6 +53,11 @@ export declare class SchemaExtractor {
      * Returns null if the union should use standard anyOf processing
      */
     private extractEnumFromUnion;
+    /**
+     * Check if a type is a primitive (string, number, boolean)
+     * Primitives are injected from environment variables
+     */
+    private isPrimitiveType;
     /**
      * Extract constructor parameters for config injection
      */
@@ -91,6 +96,11 @@ export declare class SchemaExtractor {
      * Check if JSDoc contains @Static tag
      */
     private hasStaticTag;
+    /**
+     * Check if JSDoc contains @stateful tag
+     * Indicates this method is a stateful workflow that supports checkpoint/resume
+     */
+    private hasStatefulTag;
     /**
      * Extract URI pattern from @Static tag
      * Example: @Static github://repos/{owner}/{repo}/readme
@@ -139,5 +149,93 @@ export declare class SchemaExtractor {
      * Classify MCP source type based on format
      */
     private classifyMCPSource;
+    /**
+     * Extract Photon dependencies from source code
+     * Parses @photon tags in file-level or class-level JSDoc comments
+     *
+     * Format: @photon <name> <source>
+     *
+     * Source formats:
+     * - Marketplace: rss-feed (simple name from marketplace)
+     * - GitHub: portel-dev/photons/rss-feed
+     * - npm package: npm:@portel/rss-feed-photon
+     * - Local path: ./my-photon.photon.ts
+     *
+     * Example:
+     * ```
+     * /**
+     *  * @photon rssFeed rss-feed
+     *  * @photon custom ./my-photon.photon.ts
+     *  *\/
+     * ```
+     */
+    extractPhotonDependencies(source: string): PhotonDependency[];
+    /**
+     * Classify Photon source type based on format
+     */
+    private classifyPhotonSource;
+    /**
+     * Resolve all injections for a Photon class
+     * Determines how each constructor parameter should be injected:
+     * - Primitives (string, number, boolean) → env var
+     * - Non-primitives matching @mcp → MCP client
+     * - Non-primitives matching @photon → Photon instance
+     *
+     * @param source The Photon source code
+     * @param mcpName The MCP name (for env var prefixing)
+     */
+    resolveInjections(source: string, mcpName: string): ResolvedInjection[];
+    /**
+     * Convert MCP name and parameter name to environment variable name
+     * Example: (filesystem, workdir) → FILESYSTEM_WORKDIR
+     */
+    private toEnvVarName;
+    /**
+     * Extract all assets from Photon source code
+     * Parses @ui, @prompt, @resource annotations from class-level JSDoc
+     *
+     * Format:
+     * - @ui <id> <path> - UI templates for MCP Apps
+     * - @prompt <id> <path> - Static MCP prompts
+     * - @resource <id> <path> - Static MCP resources
+     *
+     * Example:
+     * ```
+     * /**
+     *  * @ui preferences ./ui/preferences.html
+     *  * @prompt system ./prompts/system.md
+     *  * @resource config ./resources/config.json
+     *  *\/
+     * export default class MyPhoton extends PhotonMCP { ... }
+     * ```
+     */
+    extractAssets(source: string, assetFolder?: string): PhotonAssets;
+    /**
+     * Extract UI assets from @ui annotations
+     * Format: @ui <id> <path>
+     * Path must start with ./ or / to distinguish from method-level @ui references
+     */
+    private extractUIAssets;
+    /**
+     * Extract prompt assets from @prompt annotations
+     * Format: @prompt <id> <path>
+     * Path must start with ./ or / to be a valid declaration
+     */
+    private extractPromptAssets;
+    /**
+     * Extract resource assets from @resource annotations
+     * Format: @resource <id> <path>
+     * Path must start with ./ or / to be a valid declaration
+     */
+    private extractResourceAssets;
+    /**
+     * Extract method-level @ui annotations that link UI to tools
+     * Format: @ui <id> on a method's JSDoc
+     */
+    private extractMethodUILinks;
+    /**
+     * Get MIME type from file extension
+     */
+    private getMimeTypeFromPath;
 }
 //# sourceMappingURL=schema-extractor.d.ts.map

package/dist/schema-extractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-extractor.d.ts","sourceRoot":"","sources":["../src/schema-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,YAAY,EAAE,UAAU,EAA2B,aAAa,EAAE,MAAM,YAAY,CAAC;AAEjI,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,qBAAa,eAAe;IAC1B;;OAEG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAUnE;;OAEG;IACH,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB;IAgIvD;;OAEG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,EAAE;IAIpD;;OAEG;IACH,OAAO,CAAC,eAAe;IAqBvB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAS7B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAiC3B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAyGxB;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IA0F5B;;OAEG;IACH,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,EAAE;IAmD5D;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAuB3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAqB1B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IA4BxB;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;IA2G/B;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IA0FxB;;OAEG;IACH,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,OAAO,CAAC,YAAY;IAIpB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAKxB;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAsBrB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAKvB;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAkB9B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE;IAyBvD;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAqB1B"}
+{"version":3,"file":"schema-extractor.d.ts","sourceRoot":"","sources":["../src/schema-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,YAAY,EAAE,UAAU,EAA2B,aAAa,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,YAAY,EAAuC,MAAM,YAAY,CAAC;AAEzN,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,qBAAa,eAAe;IAC1B;;OAEG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAUnE;;OAEG;IACH,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB;IAkIvD;;OAEG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,EAAE;IAIpD;;OAEG;IACH,OAAO,CAAC,eAAe;IAqBvB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAS7B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAiC3B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAyGxB;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IA0F5B;;;OAGG;IACH,OAAO,CAAC,eAAe;IAKvB;;OAEG;IACH,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,EAAE;IAoD5D;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAuB3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAqB1B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IA4BxB;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;IA2G/B;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IA0FxB;;OAEG;IACH,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,OAAO,CAAC,YAAY;IAIpB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAItB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAKxB;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAsBrB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAKvB;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAkB9B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE;IAyBvD;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAsBzB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,EAAE;IAyB7D;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAuB5B;;;;;;;;;OASG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,iBAAiB,EAAE;IAgDvE;;;OAGG;IACH,OAAO,CAAC,YAAY;IAapB;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,YAAY;IAgBjE;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAkBvB;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAgB3B;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IAiB7B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAuC5B;;OAEG;IACH,OAAO,CAAC,mBAAmB;CAiC5B"}