@alcyone-labs/arg-parser 2.1.0 → 2.1.1

package/dist/core/ArgParser.d.ts

@@ -0,0 +1,380 @@
+import type { GenerateMcpToolsOptions, IMcpToolStructure } from "../mcp/mcp-integration";
+import { ArgParserBase, type IArgParserParams } from "./ArgParserBase";
+import type { IFlag, IHandlerContext, OutputSchemaConfig } from "./types";
+/**
+ * Configuration for a single MCP transport
+ */
+export type McpTransportConfig = {
+    type: "stdio" | "sse" | "streamable-http";
+    port?: number;
+    host?: string;
+    path?: string;
+    sessionIdGenerator?: () => string;
+};
+/**
+ * Configuration options for MCP sub-command
+ */
+export type McpSubCommandOptions = {
+    /** Preset transport configurations to use when no CLI flags are provided */
+    defaultTransports?: McpTransportConfig[];
+    /** Single preset transport configuration (alternative to defaultTransports) */
+    defaultTransport?: McpTransportConfig;
+};
+/**
+ * Extended server information for DXT package generation and MCP server metadata
+ * This type includes logo support for MCP servers and DXT packages
+ */
+export type DxtServerInfo = {
+    name: string;
+    version: string;
+    description?: string;
+    /** Author information for DXT manifest */
+    author?: {
+        name: string;
+        email?: string;
+        url?: string;
+    };
+    /** Repository information for DXT manifest */
+    repository?: {
+        type: string;
+        url: string;
+    };
+    /** License identifier for DXT manifest */
+    license?: string;
+    /** Homepage URL for DXT manifest */
+    homepage?: string;
+    /** Documentation URL for DXT manifest */
+    documentation?: string;
+    /** Support/issues URL for DXT manifest */
+    support?: string;
+    /** Keywords for DXT manifest */
+    keywords?: string[];
+    /**
+     * Logo/icon for DXT manifest and MCP server - can be a local file path or URL
+     * This is where logo support is provided for MCP-enabled ArgParser instances
+     */
+    logo?: string;
+};
+/**
+ * MCP server configuration options for withMcp() method
+ * This centralizes MCP server metadata that was previously scattered across addMcpSubCommand calls
+ */
+export type McpServerOptions = {
+    /** MCP server metadata */
+    serverInfo?: DxtServerInfo;
+    /** Default transport configurations for the MCP server */
+    defaultTransports?: McpTransportConfig[];
+    /** Single default transport configuration (alternative to defaultTransports) */
+    defaultTransport?: McpTransportConfig;
+    /** Tool generation options for the MCP server */
+    toolOptions?: GenerateMcpToolsOptions;
+};
+/**
+ * Combined options for withMcp() method
+ */
+export type WithMcpOptions<THandlerReturn = any> = IArgParserParams<THandlerReturn> & {
+    /** MCP-specific server configuration */
+    mcp?: McpServerOptions;
+};
+/**
+ * Type alias for clarity - ArgParser options with MCP capabilities
+ * This provides a clearer name for WithMcpOptions
+ */
+export type ArgParserWithMcpOptions<THandlerReturn = any> = WithMcpOptions<THandlerReturn>;
+/**
+ * Configuration for an individual MCP tool (deprecated - use ToolConfig instead)
+ * @deprecated Use ToolConfig and addTool() instead. Will be removed in v2.0.
+ */
+export type McpToolConfig = {
+    /** Tool name (must be unique within the server) */
+    name: string;
+    /** Tool description */
+    description?: string;
+    /** Input schema for the tool (Zod schema) */
+    inputSchema?: any;
+    /** Output schema for the tool (Zod schema) */
+    outputSchema?: any;
+    /** Handler function for the tool */
+    handler: (args: any) => Promise<any> | any;
+};
+/**
+ * Configuration for a unified tool that works in both CLI and MCP modes
+ */
+export type ToolConfig = {
+    /** Tool name (CLI subcommand name & MCP tool name) */
+    name: string;
+    /** Tool description */
+    description?: string;
+    /** Flags for this tool (auto-converted to MCP schema) */
+    flags: readonly IFlag[];
+    /** Handler function for the tool */
+    handler: (ctx: IHandlerContext) => Promise<any> | any;
+    /** Output schema for this tool (predefined pattern, Zod schema, or schema definition object) */
+    outputSchema?: OutputSchemaConfig;
+};
+/**
+ * ArgParser with Model Context Protocol (MCP) integration capabilities.
+ *
+ * This class adds MCP server functionality on top of the standard ArgParser,
+ * allowing CLI tools to be easily exposed as MCP tools with minimal boilerplate.
+ *
+ * @example
+ * ```typescript
+ * const parser = new ArgParser({
+ *   appName: "My CLI",
+ *   appCommandName: "my-cli",
+ *   handler: async (ctx) => ({ result: "success" })
+ * })
+ *   .addFlags([...])
+ *   .addMcpSubCommand("serve", {
+ *     name: "my-cli-mcp-server",
+ *     version: "1.0.0"
+ *   });
+ * ```
+ */
+export declare class ArgParser<THandlerReturn = any> extends ArgParserBase<THandlerReturn> {
+    #private;
+    /** Stored MCP server configuration from withMcp() */
+    private _mcpServerConfig?;
+    /** Registered MCP tools (deprecated) */
+    private _mcpTools;
+    /** Registered unified tools */
+    private _tools;
+    /** Output schema management */
+    private _defaultOutputSchema?;
+    private _outputSchemaMap;
+    private _autoGenerateOutputSchema?;
+    /** MCP version for output schema compatibility */
+    private _mcpProtocolVersion;
+    /**
+     * Get the stored MCP server configuration
+     * @returns MCP server configuration if set via withMcp(), undefined otherwise
+     */
+    getMcpServerConfig(): McpServerOptions | undefined;
+    /**
+     * Set a default output schema for all MCP tools generated from this parser
+     * @param schema - Predefined pattern name, Zod schema, or schema definition object
+     * @returns This ArgParser instance for chaining
+     */
+    setDefaultOutputSchema(schema: OutputSchemaConfig): this;
+    /**
+     * Set an output schema for a specific tool/command
+     * @param toolName - Name of the tool/command
+     * @param schema - Predefined pattern name, Zod schema, or schema definition object
+     * @returns This ArgParser instance for chaining
+     */
+    setOutputSchema(toolName: string, schema: OutputSchemaConfig): this;
+    /**
+     * Enable automatic output schema generation for MCP tools
+     * @param pattern - True for default pattern, or specific pattern name
+     * @returns This ArgParser instance for chaining
+     */
+    enableAutoOutputSchema(pattern?: boolean | keyof typeof import("./types").OutputSchemaPatterns): this;
+    /**
+     * Set the MCP protocol version for compatibility checks
+     * @param version - MCP protocol version (e.g., "2025-06-18")
+     * @returns This ArgParser instance for chaining
+     */
+    setMcpProtocolVersion(version: string): this;
+    /**
+     * Check if the current MCP protocol version supports output schemas
+     * Output schemas were introduced in MCP version 2025-06-18
+     * @returns true if output schemas are supported
+     */
+    private supportsOutputSchemas;
+    /**
+     * Add a unified tool that works in both CLI and MCP modes
+     * In CLI mode, the tool becomes a subcommand with its own flags
+     * In MCP mode, the tool becomes an MCP tool with auto-generated schema
+     *
+     * @param toolConfig Configuration for the tool
+     * @returns This ArgParser instance for chaining
+     */
+    addTool(toolConfig: ToolConfig): this;
+    /**
+     * Add an MCP tool to this parser (deprecated)
+     * @deprecated Use addTool() instead. This method will be removed in v2.0.
+     * @param toolConfig Configuration for the MCP tool
+     * @returns This ArgParser instance for chaining
+     */
+    addMcpTool(toolConfig: McpToolConfig): this;
+    /**
+     * Get all registered unified tools
+     * @returns Map of tool names to tool configurations
+     */
+    getTools(): Map<string, ToolConfig>;
+    /**
+     * Get all registered MCP tools (deprecated)
+     * @deprecated Use getTools() instead
+     * @returns Map of tool names to tool configurations
+     */
+    getMcpTools(): Map<string, McpToolConfig>;
+    /**
+     * Get information about all available tools (unified, legacy MCP, and CLI-generated)
+     * @param options Optional configuration for MCP tool generation
+     * @returns Object with tool counts and names for debugging
+     */
+    getToolInfo(options?: GenerateMcpToolsOptions): {
+        unifiedTools: string[];
+        legacyMcpTools: string[];
+        cliTools: string[];
+        totalTools: number;
+        duplicates: string[];
+    };
+    /**
+     * Get information about all available MCP tools (legacy method)
+     * @deprecated Use getToolInfo() instead
+     * @param options Optional configuration for MCP tool generation
+     * @returns Object with tool counts and names for debugging
+     */
+    getMcpToolInfo(options?: GenerateMcpToolsOptions): {
+        manualTools: string[];
+        cliTools: string[];
+        totalTools: number;
+        duplicates: string[];
+    };
+    /**
+     * Validate that all tools are properly registered and routable
+     * @returns Validation results
+     */
+    validateToolRouting(): {
+        isValid: boolean;
+        issues: string[];
+        cliSubcommands: string[];
+        mcpTools: string[];
+    };
+    /**
+     * Test tool routing by simulating a tool call
+     * This is useful for debugging and ensuring tools are properly registered
+     * @param toolName Name of the tool to test
+     * @param args Arguments to pass to the tool
+     * @returns Promise with the tool execution result or error
+     */
+    testMcpToolRouting(toolName: string, args?: any): Promise<{
+        success: boolean;
+        result?: any;
+        error?: string;
+        executionTime?: number;
+    }>;
+    /**
+     * Generate MCP tools from this ArgParser instance
+     * @param options Optional configuration for MCP tool generation
+     * @returns Array of MCP tool structures ready for server registration
+     */
+    toMcpTools(options?: GenerateMcpToolsOptions): IMcpToolStructure[];
+    /**
+     * Create an MCP server with tools generated from this ArgParser
+     * @param serverInfo Server configuration
+     * @param toolOptions Optional MCP tool generation options
+     * @returns Configured MCP server instance
+     */
+    createMcpServer(serverInfo?: DxtServerInfo, toolOptions?: GenerateMcpToolsOptions): Promise<any>;
+    /**
+     * Set up change notifications for the MCP server
+     * @param _server The MCP server instance (unused for now, but reserved for future client connection tracking)
+     */
+    private setupMcpChangeNotifications;
+    /**
+     * Start an MCP server using stdio transport
+     * @param serverInfo Server configuration
+     * @param toolOptions Optional MCP tool generation options
+     * @returns Promise that resolves when server is connected
+     */
+    startMcpServer(serverInfo: {
+        name: string;
+        version: string;
+        description?: string;
+    }, toolOptions?: GenerateMcpToolsOptions): Promise<void>;
+    /**
+     * Start an MCP server with multiple transport types simultaneously
+     * @param serverInfo Server configuration
+     * @param transports Array of transport configurations
+     * @param toolOptions Optional MCP tool generation options
+     * @returns Promise that resolves when all servers are started
+     */
+    startMcpServerWithMultipleTransports(serverInfo: {
+        name: string;
+        version: string;
+        description?: string;
+    }, transports: Array<{
+        type: "stdio" | "sse" | "streamable-http";
+        port?: number;
+        host?: string;
+        path?: string;
+        sessionIdGenerator?: () => string;
+    }>, toolOptions?: GenerateMcpToolsOptions): Promise<void>;
+    /**
+     * Start an MCP server with a specific transport type
+     * @param serverInfo Server configuration
+     * @param transportType Type of transport to use
+     * @param transportOptions Transport-specific options
+     * @param toolOptions Optional MCP tool generation options
+     * @returns Promise that resolves when server is connected
+     */
+    startMcpServerWithTransport(serverInfo: {
+        name: string;
+        version: string;
+        description?: string;
+    }, transportType: "stdio" | "sse" | "streamable-http", transportOptions?: {
+        port?: number;
+        host?: string;
+        path?: string;
+        sessionIdGenerator?: () => string;
+    }, toolOptions?: GenerateMcpToolsOptions): Promise<void>;
+    parse(processArgs: string[], options?: any): Promise<any>;
+    /**
+     * CLI-friendly parse method that automatically handles ParseResult objects
+     * When autoExit is false, this method will call process.exit() based on ParseResult
+     * This ensures backward compatibility for CLI applications
+     */
+    parseForCli(processArgs: string[], options?: any): any;
+    /**
+     * Alias for parse() method for backward compatibility
+     * Since parse() is already async, this just calls parse()
+     *
+     * @deprecated Use parse() instead. This method will be removed in a future version.
+     */
+    parseAsync(processArgs: string[], options?: any): Promise<any>;
+    /**
+     * Add an MCP sub-command that starts an MCP server exposing this parser's functionality
+     * @param subCommandName Name of the sub-command (default: "mcp-server")
+     * @param serverInfo Server configuration (supports extended DXT fields)
+     * @param options Optional configuration including preset transports and tool options
+     * @returns This ArgParserWithMcp instance for chaining
+     * @deprecated Use withMcp() to configure server metadata and --s-mcp-serve system flag instead. This method will be removed in v2.0.
+     */
+    addMcpSubCommand(subCommandName: string | undefined, serverInfo: DxtServerInfo, options?: McpSubCommandOptions & {
+        toolOptions?: GenerateMcpToolsOptions;
+    }): this;
+    /**
+     * Add an MCP sub-command that starts an MCP server exposing this parser's functionality
+     * @param subCommandName Name of the sub-command (default: "mcp-server")
+     * @param serverInfo Server configuration (supports extended DXT fields)
+     * @param toolOptions Optional MCP tool generation options (backward compatibility)
+     * @returns This ArgParserWithMcp instance for chaining
+     * @deprecated Use withMcp() to configure server metadata and --s-mcp-serve system flag instead. This method will be removed in v2.0.
+     */
+    addMcpSubCommand(subCommandName: string | undefined, serverInfo: DxtServerInfo, toolOptions?: GenerateMcpToolsOptions): this;
+    /**
+     * Factory method to create an ArgParser instance with MCP capabilities
+     * This provides a clean API for users who want MCP functionality from the start
+     * Automatically sets handleErrors: false for MCP compatibility
+     *
+     * @param options Combined ArgParser and MCP server configuration options
+     * @param initialFlags Optional array of initial flags to add
+     * @returns ArgParser instance with MCP capabilities and stored server metadata
+     */
+    static withMcp<T = any>(options?: WithMcpOptions<T>, initialFlags?: readonly IFlag[]): ArgParser<T>;
+    /**
+     * Create an ArgParser instance optimized for CLI usage
+     * This sets autoExit: true by default for traditional CLI behavior
+     */
+    static forCli<T = any>(options?: ConstructorParameters<typeof ArgParserBase>[0], initialFlags?: ConstructorParameters<typeof ArgParserBase>[1]): ArgParser<T>;
+    /**
+     * Create an ArgParser instance optimized for library usage
+     * This sets autoExit: false by default for programmatic control
+     */
+    static forLibrary<T = any>(options?: ConstructorParameters<typeof ArgParserBase>[0], initialFlags?: ConstructorParameters<typeof ArgParserBase>[1]): ArgParser<T>;
+    static fromArgParser<T = any>(parser: ArgParserBase<T>): ArgParser<T>;
+}
+//# sourceMappingURL=ArgParser.d.ts.map

package/dist/core/ArgParser.d.ts.map

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

package/dist/core/ArgParserBase.d.ts

@@ -0,0 +1,206 @@
+import { McpChangeType, McpNotificationsManager } from "../mcp/mcp-notifications.js";
+import { McpPromptConfig, McpPromptsManager } from "../mcp/mcp-prompts.js";
+import { McpResourceConfig, McpResourcesManager } from "../mcp/mcp-resources.js";
+import type { IFlag, IHandlerContext, ISubCommand, ParseResult, ProcessedFlag, TParsedArgs } from "./types";
+export declare class ArgParserError extends Error {
+    cmdChain: string[];
+    commandChain: string[];
+    constructor(message: string, cmdChain?: string[]);
+}
+export interface IArgParserParams<THandlerReturn = any> {
+    /**
+     * This is the display name of the app, used in help text
+     */
+    appName?: string;
+    subCommands?: ISubCommand[];
+    handler?: (ctx: IHandlerContext<any, any>) => THandlerReturn | Promise<THandlerReturn>;
+    /**
+     * Add an extra new line between each flag group,
+     * makes the text more readable but uses more space
+     *
+     * Default: true
+     */
+    extraNewLine?: boolean;
+    /**
+     * Wraps the line at width, if shorter, wrapping will be more
+     * aggressive. Wrapping is based on words.
+     *
+     * Default: 50
+     * Minimum: 30
+     */
+    wrapAtWidth?: number;
+    /**
+     * Controls the placing of right text on the screen.
+     * The higher the value, the more to the right the text will be.
+     *
+     * Default: 30
+     * Minimum: 20
+     */
+    blankSpaceWidth?: number;
+    /**
+     * Character to display next to the flag to express mandatory fields.
+     *
+     * Default: *
+     */
+    mandatoryCharacter?: string;
+    /**
+     * Throw an error if a flag is added more than once
+     * @default false
+     */
+    throwForDuplicateFlags?: boolean;
+    description?: string;
+    /**
+     * Automatically handle ArgParserErrors by printing a formatted message
+     * and exiting. Set to false to catch ArgParserError manually.
+     * @default true
+     */
+    handleErrors?: boolean;
+    /**
+     * Whether to automatically call process.exit() based on ParseResult.
+     * When true (default), maintains backward compatibility with CLI behavior.
+     * When false, returns ParseResult objects for programmatic use.
+     * @default true
+     */
+    autoExit?: boolean;
+    /**
+     * The command name to display in help suggestions (e.g., 'dabl').
+     * If not provided, it falls back to guessing from the script path.
+     */
+    appCommandName?: string;
+    /**
+     * If true, when this parser is added as a sub-command, it will inherit
+     * flags from its direct parent *unless* a flag with the same name
+     * already exists in this parser. Child flags take precedence.
+     * @default false
+     */
+    inheritParentFlags?: boolean;
+}
+export interface IParseOptions {
+    /**
+     * When true, skips help flag processing (doesn't exit or show help)
+     * @default false
+     */
+    skipHelpHandling?: boolean;
+    /**
+     * When true, skips the execution of any command handlers.
+     * @default false
+     */
+    skipHandlers?: boolean;
+    /**
+     * When true (default), automatically awaits async handlers before returning.
+     * When false, returns immediately with _asyncHandlerPromise for manual handling.
+     * @default true
+     */
+    deep?: boolean;
+}
+type TParsedArgsWithRouting<T = any> = T & {
+    $commandChain?: string[];
+    handlerToExecute?: {
+        handler: Function;
+        context: IHandlerContext;
+    };
+};
+export declare class ArgParserBase<THandlerReturn = any> {
+    #private;
+    constructor(options?: IArgParserParams<THandlerReturn>, initialFlags?: readonly IFlag[]);
+    get flags(): ProcessedFlag[];
+    get flagNames(): string[];
+    getAppName(): string | undefined;
+    getAppCommandName(): string | undefined;
+    getSubCommandName(): string;
+    getDescription(): string | undefined;
+    getAutoExit(): boolean;
+    /**
+     * Helper method to handle exit logic based on autoExit setting
+     * Returns a ParseResult instead of calling process.exit() when autoExit is false
+     */
+    private _handleExit;
+    getHandler(): ((ctx: IHandlerContext) => void) | undefined;
+    getSubCommands(): Map<string, ISubCommand>;
+    private _addToOutput;
+    addFlags(flags: readonly IFlag[]): this;
+    addFlag(flag: IFlag): this;
+    addSubCommand(subCommandConfig: ISubCommand): this;
+    /**
+     * Sets the handler function for this specific parser instance.
+     * This handler will be executed if this parser is the final one
+     * in the command chain and `executeHandlers` is enabled on the root parser.
+     *
+     * @param handler - The function to execute.
+     * @returns The ArgParser instance for chaining.
+     */
+    setHandler(handler: (ctx: IHandlerContext<any, any>) => THandlerReturn | Promise<THandlerReturn>): this;
+    printAll(filePath?: string): void;
+    parse(processArgs: string[], options?: IParseOptions): Promise<TParsedArgsWithRouting<any> | ParseResult>;
+    /**
+     * Alias for parse() method for backward compatibility
+     * Since parse() is already async, this just calls parse()
+     *
+     * @deprecated Use parse() instead. This method will be removed in a future version.
+     */
+    parseAsync(processArgs: string[], options?: IParseOptions): Promise<TParsedArgsWithRouting<any> | ParseResult>;
+    /**
+     * Recursive helper for parsing arguments and handling sub-commands.
+     * This method assumes the global help check has already been performed in `parse`.
+     */
+    private _parseRecursive;
+    helpText(): string;
+    getSubCommand(name: string): ISubCommand | undefined;
+    hasFlag(name: string): boolean;
+    getCommandChain(): string[];
+    getLastParseResult(): TParsedArgs<ProcessedFlag[]>;
+    /**
+     * Add an MCP resource to this parser
+     */
+    addMcpResource(config: McpResourceConfig): this;
+    /**
+     * Remove an MCP resource by name
+     */
+    removeMcpResource(name: string): this;
+    /**
+     * Get all registered MCP resources
+     */
+    getMcpResources(): McpResourceConfig[];
+    /**
+     * Add an MCP prompt to this parser
+     */
+    addMcpPrompt(config: McpPromptConfig): this;
+    /**
+     * Remove an MCP prompt by name
+     */
+    removeMcpPrompt(name: string): this;
+    /**
+     * Get all registered MCP prompts
+     */
+    getMcpPrompts(): McpPromptConfig[];
+    /**
+     * Add a change listener for MCP entities
+     */
+    onMcpChange(listener: (event: {
+        type: McpChangeType;
+        action: string;
+        entityName?: string;
+    }) => void): this;
+    /**
+     * Remove a change listener for MCP entities
+     */
+    offMcpChange(listener: (event: {
+        type: McpChangeType;
+        action: string;
+        entityName?: string;
+    }) => void): this;
+    /**
+     * Get the MCP notifications manager (for advanced usage)
+     */
+    getMcpNotificationsManager(): McpNotificationsManager;
+    /**
+     * Get the MCP resources manager (for advanced usage)
+     */
+    getMcpResourcesManager(): McpResourcesManager;
+    /**
+     * Get the MCP prompts manager (for advanced usage)
+     */
+    getMcpPromptsManager(): McpPromptsManager;
+}
+export {};
+//# sourceMappingURL=ArgParserBase.d.ts.map

package/dist/core/ArgParserBase.d.ts.map

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

package/dist/core/FlagManager.d.ts

@@ -0,0 +1,16 @@
+import type { IFlag, ProcessedFlag } from "./types";
+export declare class FlagManager {
+    #private;
+    constructor(options?: {
+        throwForDuplicateFlags?: boolean;
+    }, initialFlags?: readonly IFlag[]);
+    static _safeFlag(flag: IFlag): ProcessedFlag;
+    addFlag(flag: IFlag): this;
+    _setProcessedFlagForInheritance(processedFlag: ProcessedFlag): this;
+    addFlags(flags: readonly IFlag[]): this;
+    hasFlag(name: string): boolean;
+    getFlag(name: string): ProcessedFlag | undefined;
+    get flags(): ProcessedFlag[];
+    get flagNames(): string[];
+}
+//# sourceMappingURL=FlagManager.d.ts.map

package/dist/core/FlagManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FlagManager.d.ts","sourceRoot":"","sources":["../../src/core/FlagManager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEpD,qBAAa,WAAW;;gBAKpB,OAAO,GAAE;QAAE,sBAAsB,CAAC,EAAE,OAAO,CAAA;KAAO,EAClD,YAAY,GAAE,SAAS,KAAK,EAAO;IAMrC,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,GAAG,aAAa;IAwC5C,OAAO,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI;IAoB1B,+BAA+B,CAAC,aAAa,EAAE,aAAa,GAAG,IAAI;IAQnE,QAAQ,CAAC,KAAK,EAAE,SAAS,KAAK,EAAE,GAAG,IAAI;IAOvC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI9B,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAIhD,IAAI,KAAK,IAAI,aAAa,EAAE,CAE3B;IAED,IAAI,SAAS,IAAI,MAAM,EAAE,CAExB;CACF"}