@alexma03/utcp-cli 1.1.0

package/dist/index.d.cts

@@ -0,0 +1,319 @@
+import { z } from 'zod';
+import { CallTemplate, Serializer, CommunicationProtocol, IUtcpClient, RegisterManualResult } from '@alexma03/utcp-sdk';
+
+/**
+ * REQUIRED
+ * Configuration for a single command step in a CLI execution flow.
+ *
+ * Attributes:
+ *     command: The command string to execute. Can contain UTCP_ARG_argname_UTCP_END
+ *         placeholders that will be replaced with values from tool_args. Can also
+ *         reference previous command outputs using $CMD_0_OUTPUT, $CMD_1_OUTPUT, etc.
+ *     append_to_final_output: Whether this command's output should be included
+ *         in the final result. If not specified, defaults to False for all
+ *         commands except the last one.
+ *
+ * Examples:
+ *     Basic command step:
+ *     ```json
+ *     {
+ *       "command": "git status",
+ *       "append_to_final_output": true
+ *     }
+ *     ```
+ *
+ *     Command with argument placeholders and output reference:
+ *     ```json
+ *     {
+ *       "command": "echo \"Cloning to: UTCP_ARG_target_dir_UTCP_END, previous status: $CMD_0_OUTPUT\"",
+ *       "append_to_final_output": true
+ *     }
+ *     ```
+ */
+interface CommandStep {
+    /**
+     * Command string to execute, may contain UTCP_ARG_argname_UTCP_END placeholders
+     */
+    command: string;
+    /**
+     * Whether to include this command's output in final result. Defaults to False for all except last command
+     */
+    append_to_final_output?: boolean | null;
+}
+/**
+ * Zod schema for CommandStep.
+ */
+declare const CommandStepSchema: z.ZodType<CommandStep>;
+/**
+ * REQUIRED
+ * Call template configuration for Command Line Interface (CLI) tools.
+ *
+ * This class defines the configuration for executing command-line tools and
+ * programs as UTCP tool providers. Commands are executed in a single subprocess
+ * to maintain state (like directory changes) between commands.
+ *
+ * **Cross-Platform Script Generation:**
+ * - **Windows**: Commands are converted to a PowerShell script
+ * - **Unix/Linux/macOS**: Commands are converted to a Bash script
+ *
+ * **Command Syntax Requirements:**
+ * - Windows: Use PowerShell syntax (e.g., `Get-ChildItem`, `Set-Location`)
+ * - Unix: Use Bash/shell syntax (e.g., `ls`, `cd`)
+ *
+ * **Referencing Previous Command Output:**
+ * You can reference the output of previous commands using variables:
+ * - **PowerShell**: `$CMD_0_OUTPUT`, `$CMD_1_OUTPUT`, etc.
+ * - **Bash**: `$CMD_0_OUTPUT`, `$CMD_1_OUTPUT`, etc.
+ *
+ * Example: `echo "Previous result: $CMD_0_OUTPUT"`
+ *
+ * Attributes:
+ *     call_template_type: The type of the call template. Must be "cli".
+ *     commands: A list of CommandStep objects defining the commands to execute
+ *         in order. Each command can contain UTCP_ARG_argname_UTCP_END placeholders
+ *         that will be replaced with values from tool_args during execution.
+ *     env_vars: A dictionary of environment variables to set for the command's
+ *         execution context. Values can be static strings or placeholders for
+ *         variables from the UTCP client's variable substitutor.
+ *     working_dir: The working directory from which to run the commands. If not
+ *         provided, it defaults to the current process's working directory.
+ *     auth: Authentication details. Not applicable to the CLI protocol, so it
+ *         is always None.
+ *
+ * Examples:
+ *     Cross-platform directory operations:
+ *     ```json
+ *     {
+ *       "name": "cross_platform_dir_tool",
+ *       "call_template_type": "cli",
+ *       "commands": [
+ *         {
+ *           "command": "cd UTCP_ARG_target_dir_UTCP_END",
+ *           "append_to_final_output": false
+ *         },
+ *         {
+ *           "command": "ls -la",
+ *           "append_to_final_output": true
+ *         }
+ *       ]
+ *     }
+ *     ```
+ *
+ *     Referencing previous command output:
+ *     ```json
+ *     {
+ *       "name": "reference_previous_output_tool",
+ *       "call_template_type": "cli",
+ *       "commands": [
+ *         {
+ *           "command": "git status --porcelain",
+ *           "append_to_final_output": false
+ *         },
+ *         {
+ *           "command": "echo \"Found changes: $CMD_0_OUTPUT\"",
+ *           "append_to_final_output": true
+ *         }
+ *       ]
+ *     }
+ *     ```
+ *
+ *     Command with environment variables and placeholders:
+ *     ```json
+ *     {
+ *       "name": "python_multi_step_tool",
+ *       "call_template_type": "cli",
+ *       "commands": [
+ *         {
+ *           "command": "python setup.py install",
+ *           "append_to_final_output": false
+ *         },
+ *         {
+ *           "command": "python script.py --input UTCP_ARG_input_file_UTCP_END --result \"$CMD_0_OUTPUT\""
+ *         }
+ *       ],
+ *       "env_vars": {
+ *         "PYTHONPATH": "/custom/path",
+ *         "API_KEY": "${API_KEY_VAR}"
+ *       }
+ *     }
+ *     ```
+ *
+ * Security Considerations:
+ *     - Commands are executed in a subprocess. Ensure that the commands
+ *       specified are from a trusted source.
+ *     - Avoid passing unsanitized user input directly into the command string.
+ *       Use tool argument validation where possible.
+ *     - All placeholders are replaced with string values from tool_args.
+ *     - Commands should use the appropriate syntax for the target platform
+ *       (PowerShell on Windows, Bash on Unix).
+ *     - Previous command outputs are available as variables but should be
+ *       used carefully to avoid command injection.
+ */
+interface CliCallTemplate extends CallTemplate {
+    call_template_type: 'cli';
+    commands: CommandStep[];
+    env_vars?: Record<string, string> | null;
+    working_dir?: string | null;
+    auth?: undefined;
+    allowed_communication_protocols?: string[];
+}
+/**
+ * Zod schema for CLI Call Template.
+ */
+declare const CliCallTemplateSchema: z.ZodType<CliCallTemplate>;
+/**
+ * REQUIRED
+ * Serializer for converting between `CliCallTemplate` and dictionary representations.
+ *
+ * This class handles the serialization and deserialization of `CliCallTemplate`
+ * objects, ensuring that they can be correctly represented as dictionaries and
+ * reconstructed from them, with validation.
+ */
+declare class CliCallTemplateSerializer extends Serializer<CliCallTemplate> {
+    /**
+     * REQUIRED
+     * Converts a `CliCallTemplate` instance to its dictionary representation.
+     *
+     * @param obj The `CliCallTemplate` instance to serialize.
+     * @returns A dictionary representing the `CliCallTemplate`.
+     */
+    toDict(obj: CliCallTemplate): Record<string, unknown>;
+    /**
+     * REQUIRED
+     * Validates a dictionary and constructs a `CliCallTemplate` instance.
+     *
+     * @param obj The dictionary to validate and deserialize.
+     * @returns A `CliCallTemplate` instance.
+     * @throws Error if the dictionary is not a valid representation of a `CliCallTemplate`.
+     */
+    validateDict(obj: Record<string, unknown>): CliCallTemplate;
+}
+
+/**
+ * Command Line Interface (CLI) communication protocol for the UTCP client.
+ *
+ * This module provides an implementation of the `CommunicationProtocol` interface
+ * that enables the UTCP client to interact with command-line tools. It supports
+ * discovering tools by executing a command and parsing its output for a UTCP
+ * manual, as well as calling those tools with arguments.
+ *
+ * Key Features:
+ *     - Asynchronous execution of shell commands.
+ *     - Tool discovery by running a command that outputs a UTCP manual.
+ *     - Flexible argument formatting for different CLI conventions.
+ *     - Support for environment variables and custom working directories.
+ *     - Cross-platform command parsing for Windows and Unix-like systems.
+ *
+ * Security Considerations:
+ *     Executing arbitrary command-line tools can be dangerous. This protocol
+ *     should only be used with trusted tools.
+ */
+
+/**
+ * REQUIRED
+ * Communication protocol for interacting with CLI-based tool providers.
+ *
+ * This class implements the `CommunicationProtocol` interface to handle
+ * communication with command-line tools. It discovers tools by executing a
+ * command specified in a `CliCallTemplate` and parsing the output for a UTCP
+ * manual. It also executes tool calls by running the corresponding command
+ * with the provided arguments.
+ */
+declare class CliCommunicationProtocol implements CommunicationProtocol {
+    /**
+     * Log informational messages.
+     */
+    private _log_info;
+    /**
+     * Log error messages.
+     */
+    private _log_error;
+    /**
+     * Prepare environment variables for command execution.
+     *
+     * @param provider The CLI provider
+     * @returns Environment variables dictionary
+     */
+    private _prepare_environment;
+    private _executeShellScript;
+    /**
+     * Substitute UTCP_ARG placeholders in command string with tool arguments.
+     *
+     * @param command Command string containing UTCP_ARG_argname_UTCP_END placeholders
+     * @param toolArgs Dictionary of argument names and values
+     * @returns Command string with placeholders replaced by actual values
+     */
+    private _substitute_utcp_args;
+    /**
+     * Build a combined shell script from multiple commands.
+     *
+     * @param commands List of CommandStep objects to combine
+     * @param toolArgs Tool arguments for placeholder substitution
+     * @returns Shell script string that executes all commands in sequence
+     */
+    private _build_combined_shell_script;
+    /**
+     * REQUIRED
+     * Registers a CLI-based manual and discovers its tools.
+     *
+     * This method executes the command specified in the `CliCallTemplate`'s
+     * commands. It then attempts to parse the command's output (stdout) as a
+     * UTCP manual in JSON format.
+     *
+     * @param caller The UTCP client instance that is calling this method.
+     * @param manualCallTemplate The `CliCallTemplate` containing the details for
+     *     tool discovery, such as the command to run.
+     * @returns A `RegisterManualResult` object indicating whether the registration
+     *     was successful and containing the discovered tools.
+     * @throws Error if the `manualCallTemplate` is not an instance of
+     *     `CliCallTemplate` or if commands are not set.
+     */
+    registerManual(caller: IUtcpClient, manualCallTemplate: CallTemplate): Promise<RegisterManualResult>;
+    /**
+     * REQUIRED
+     * Deregisters a CLI manual.
+     *
+     * For the CLI protocol, this is a no-op as there are no persistent
+     * connections to terminate.
+     *
+     * @param caller The UTCP client instance that is calling this method.
+     * @param manualCallTemplate The call template of the manual to deregister.
+     */
+    deregisterManual(caller: IUtcpClient, manualCallTemplate: CallTemplate): Promise<void>;
+    /**
+     * REQUIRED
+     * Calls a CLI tool by executing its command.
+     *
+     * This method constructs and executes the command specified in the
+     * `CliCallTemplate`. It formats the provided `tool_args` as command-line
+     * arguments and runs the command in a subprocess.
+     *
+     * @param caller The UTCP client instance that is calling this method.
+     * @param toolName The name of the tool to call.
+     * @param toolArgs A dictionary of arguments for the tool call.
+     * @param toolCallTemplate The `CliCallTemplate` for the tool.
+     * @returns The result of the command execution. If the command exits with a code
+     *     of 0, it returns the content of stdout. If the exit code is non-zero,
+     *     it returns the content of stderr.
+     * @throws Error if `toolCallTemplate` is not an instance of
+     *     `CliCallTemplate` or if commands are not set.
+     */
+    callTool(caller: IUtcpClient, toolName: string, toolArgs: Record<string, any>, toolCallTemplate: CallTemplate): Promise<any>;
+    /**
+     * REQUIRED
+     * Streaming calls are not supported for the CLI protocol.
+     *
+     * @throws Error Always, as this functionality is not supported.
+     */
+    callToolStreaming(caller: IUtcpClient, toolName: string, toolArgs: Record<string, any>, toolCallTemplate: CallTemplate): AsyncGenerator<any, void, unknown>;
+    close(): Promise<void>;
+}
+
+/**
+ * Registers the CLI protocol's CallTemplate serializer
+ * and its CommunicationProtocol implementation.
+ * This function should be called once when the CLI plugin is loaded.
+ */
+declare function register(override?: boolean): void;
+
+export { type CliCallTemplate, CliCallTemplateSchema, CliCallTemplateSerializer, CliCommunicationProtocol, type CommandStep, CommandStepSchema, register };

package/dist/index.d.ts

@@ -0,0 +1,319 @@
+import { z } from 'zod';
+import { CallTemplate, Serializer, CommunicationProtocol, IUtcpClient, RegisterManualResult } from '@alexma03/utcp-sdk';
+
+/**
+ * REQUIRED
+ * Configuration for a single command step in a CLI execution flow.
+ *
+ * Attributes:
+ *     command: The command string to execute. Can contain UTCP_ARG_argname_UTCP_END
+ *         placeholders that will be replaced with values from tool_args. Can also
+ *         reference previous command outputs using $CMD_0_OUTPUT, $CMD_1_OUTPUT, etc.
+ *     append_to_final_output: Whether this command's output should be included
+ *         in the final result. If not specified, defaults to False for all
+ *         commands except the last one.
+ *
+ * Examples:
+ *     Basic command step:
+ *     ```json
+ *     {
+ *       "command": "git status",
+ *       "append_to_final_output": true
+ *     }
+ *     ```
+ *
+ *     Command with argument placeholders and output reference:
+ *     ```json
+ *     {
+ *       "command": "echo \"Cloning to: UTCP_ARG_target_dir_UTCP_END, previous status: $CMD_0_OUTPUT\"",
+ *       "append_to_final_output": true
+ *     }
+ *     ```
+ */
+interface CommandStep {
+    /**
+     * Command string to execute, may contain UTCP_ARG_argname_UTCP_END placeholders
+     */
+    command: string;
+    /**
+     * Whether to include this command's output in final result. Defaults to False for all except last command
+     */
+    append_to_final_output?: boolean | null;
+}
+/**
+ * Zod schema for CommandStep.
+ */
+declare const CommandStepSchema: z.ZodType<CommandStep>;
+/**
+ * REQUIRED
+ * Call template configuration for Command Line Interface (CLI) tools.
+ *
+ * This class defines the configuration for executing command-line tools and
+ * programs as UTCP tool providers. Commands are executed in a single subprocess
+ * to maintain state (like directory changes) between commands.
+ *
+ * **Cross-Platform Script Generation:**
+ * - **Windows**: Commands are converted to a PowerShell script
+ * - **Unix/Linux/macOS**: Commands are converted to a Bash script
+ *
+ * **Command Syntax Requirements:**
+ * - Windows: Use PowerShell syntax (e.g., `Get-ChildItem`, `Set-Location`)
+ * - Unix: Use Bash/shell syntax (e.g., `ls`, `cd`)
+ *
+ * **Referencing Previous Command Output:**
+ * You can reference the output of previous commands using variables:
+ * - **PowerShell**: `$CMD_0_OUTPUT`, `$CMD_1_OUTPUT`, etc.
+ * - **Bash**: `$CMD_0_OUTPUT`, `$CMD_1_OUTPUT`, etc.
+ *
+ * Example: `echo "Previous result: $CMD_0_OUTPUT"`
+ *
+ * Attributes:
+ *     call_template_type: The type of the call template. Must be "cli".
+ *     commands: A list of CommandStep objects defining the commands to execute
+ *         in order. Each command can contain UTCP_ARG_argname_UTCP_END placeholders
+ *         that will be replaced with values from tool_args during execution.
+ *     env_vars: A dictionary of environment variables to set for the command's
+ *         execution context. Values can be static strings or placeholders for
+ *         variables from the UTCP client's variable substitutor.
+ *     working_dir: The working directory from which to run the commands. If not
+ *         provided, it defaults to the current process's working directory.
+ *     auth: Authentication details. Not applicable to the CLI protocol, so it
+ *         is always None.
+ *
+ * Examples:
+ *     Cross-platform directory operations:
+ *     ```json
+ *     {
+ *       "name": "cross_platform_dir_tool",
+ *       "call_template_type": "cli",
+ *       "commands": [
+ *         {
+ *           "command": "cd UTCP_ARG_target_dir_UTCP_END",
+ *           "append_to_final_output": false
+ *         },
+ *         {
+ *           "command": "ls -la",
+ *           "append_to_final_output": true
+ *         }
+ *       ]
+ *     }
+ *     ```
+ *
+ *     Referencing previous command output:
+ *     ```json
+ *     {
+ *       "name": "reference_previous_output_tool",
+ *       "call_template_type": "cli",
+ *       "commands": [
+ *         {
+ *           "command": "git status --porcelain",
+ *           "append_to_final_output": false
+ *         },
+ *         {
+ *           "command": "echo \"Found changes: $CMD_0_OUTPUT\"",
+ *           "append_to_final_output": true
+ *         }
+ *       ]
+ *     }
+ *     ```
+ *
+ *     Command with environment variables and placeholders:
+ *     ```json
+ *     {
+ *       "name": "python_multi_step_tool",
+ *       "call_template_type": "cli",
+ *       "commands": [
+ *         {
+ *           "command": "python setup.py install",
+ *           "append_to_final_output": false
+ *         },
+ *         {
+ *           "command": "python script.py --input UTCP_ARG_input_file_UTCP_END --result \"$CMD_0_OUTPUT\""
+ *         }
+ *       ],
+ *       "env_vars": {
+ *         "PYTHONPATH": "/custom/path",
+ *         "API_KEY": "${API_KEY_VAR}"
+ *       }
+ *     }
+ *     ```
+ *
+ * Security Considerations:
+ *     - Commands are executed in a subprocess. Ensure that the commands
+ *       specified are from a trusted source.
+ *     - Avoid passing unsanitized user input directly into the command string.
+ *       Use tool argument validation where possible.
+ *     - All placeholders are replaced with string values from tool_args.
+ *     - Commands should use the appropriate syntax for the target platform
+ *       (PowerShell on Windows, Bash on Unix).
+ *     - Previous command outputs are available as variables but should be
+ *       used carefully to avoid command injection.
+ */
+interface CliCallTemplate extends CallTemplate {
+    call_template_type: 'cli';
+    commands: CommandStep[];
+    env_vars?: Record<string, string> | null;
+    working_dir?: string | null;
+    auth?: undefined;
+    allowed_communication_protocols?: string[];
+}
+/**
+ * Zod schema for CLI Call Template.
+ */
+declare const CliCallTemplateSchema: z.ZodType<CliCallTemplate>;
+/**
+ * REQUIRED
+ * Serializer for converting between `CliCallTemplate` and dictionary representations.
+ *
+ * This class handles the serialization and deserialization of `CliCallTemplate`
+ * objects, ensuring that they can be correctly represented as dictionaries and
+ * reconstructed from them, with validation.
+ */
+declare class CliCallTemplateSerializer extends Serializer<CliCallTemplate> {
+    /**
+     * REQUIRED
+     * Converts a `CliCallTemplate` instance to its dictionary representation.
+     *
+     * @param obj The `CliCallTemplate` instance to serialize.
+     * @returns A dictionary representing the `CliCallTemplate`.
+     */
+    toDict(obj: CliCallTemplate): Record<string, unknown>;
+    /**
+     * REQUIRED
+     * Validates a dictionary and constructs a `CliCallTemplate` instance.
+     *
+     * @param obj The dictionary to validate and deserialize.
+     * @returns A `CliCallTemplate` instance.
+     * @throws Error if the dictionary is not a valid representation of a `CliCallTemplate`.
+     */
+    validateDict(obj: Record<string, unknown>): CliCallTemplate;
+}
+
+/**
+ * Command Line Interface (CLI) communication protocol for the UTCP client.
+ *
+ * This module provides an implementation of the `CommunicationProtocol` interface
+ * that enables the UTCP client to interact with command-line tools. It supports
+ * discovering tools by executing a command and parsing its output for a UTCP
+ * manual, as well as calling those tools with arguments.
+ *
+ * Key Features:
+ *     - Asynchronous execution of shell commands.
+ *     - Tool discovery by running a command that outputs a UTCP manual.
+ *     - Flexible argument formatting for different CLI conventions.
+ *     - Support for environment variables and custom working directories.
+ *     - Cross-platform command parsing for Windows and Unix-like systems.
+ *
+ * Security Considerations:
+ *     Executing arbitrary command-line tools can be dangerous. This protocol
+ *     should only be used with trusted tools.
+ */
+
+/**
+ * REQUIRED
+ * Communication protocol for interacting with CLI-based tool providers.
+ *
+ * This class implements the `CommunicationProtocol` interface to handle
+ * communication with command-line tools. It discovers tools by executing a
+ * command specified in a `CliCallTemplate` and parsing the output for a UTCP
+ * manual. It also executes tool calls by running the corresponding command
+ * with the provided arguments.
+ */
+declare class CliCommunicationProtocol implements CommunicationProtocol {
+    /**
+     * Log informational messages.
+     */
+    private _log_info;
+    /**
+     * Log error messages.
+     */
+    private _log_error;
+    /**
+     * Prepare environment variables for command execution.
+     *
+     * @param provider The CLI provider
+     * @returns Environment variables dictionary
+     */
+    private _prepare_environment;
+    private _executeShellScript;
+    /**
+     * Substitute UTCP_ARG placeholders in command string with tool arguments.
+     *
+     * @param command Command string containing UTCP_ARG_argname_UTCP_END placeholders
+     * @param toolArgs Dictionary of argument names and values
+     * @returns Command string with placeholders replaced by actual values
+     */
+    private _substitute_utcp_args;
+    /**
+     * Build a combined shell script from multiple commands.
+     *
+     * @param commands List of CommandStep objects to combine
+     * @param toolArgs Tool arguments for placeholder substitution
+     * @returns Shell script string that executes all commands in sequence
+     */
+    private _build_combined_shell_script;
+    /**
+     * REQUIRED
+     * Registers a CLI-based manual and discovers its tools.
+     *
+     * This method executes the command specified in the `CliCallTemplate`'s
+     * commands. It then attempts to parse the command's output (stdout) as a
+     * UTCP manual in JSON format.
+     *
+     * @param caller The UTCP client instance that is calling this method.
+     * @param manualCallTemplate The `CliCallTemplate` containing the details for
+     *     tool discovery, such as the command to run.
+     * @returns A `RegisterManualResult` object indicating whether the registration
+     *     was successful and containing the discovered tools.
+     * @throws Error if the `manualCallTemplate` is not an instance of
+     *     `CliCallTemplate` or if commands are not set.
+     */
+    registerManual(caller: IUtcpClient, manualCallTemplate: CallTemplate): Promise<RegisterManualResult>;
+    /**
+     * REQUIRED
+     * Deregisters a CLI manual.
+     *
+     * For the CLI protocol, this is a no-op as there are no persistent
+     * connections to terminate.
+     *
+     * @param caller The UTCP client instance that is calling this method.
+     * @param manualCallTemplate The call template of the manual to deregister.
+     */
+    deregisterManual(caller: IUtcpClient, manualCallTemplate: CallTemplate): Promise<void>;
+    /**
+     * REQUIRED
+     * Calls a CLI tool by executing its command.
+     *
+     * This method constructs and executes the command specified in the
+     * `CliCallTemplate`. It formats the provided `tool_args` as command-line
+     * arguments and runs the command in a subprocess.
+     *
+     * @param caller The UTCP client instance that is calling this method.
+     * @param toolName The name of the tool to call.
+     * @param toolArgs A dictionary of arguments for the tool call.
+     * @param toolCallTemplate The `CliCallTemplate` for the tool.
+     * @returns The result of the command execution. If the command exits with a code
+     *     of 0, it returns the content of stdout. If the exit code is non-zero,
+     *     it returns the content of stderr.
+     * @throws Error if `toolCallTemplate` is not an instance of
+     *     `CliCallTemplate` or if commands are not set.
+     */
+    callTool(caller: IUtcpClient, toolName: string, toolArgs: Record<string, any>, toolCallTemplate: CallTemplate): Promise<any>;
+    /**
+     * REQUIRED
+     * Streaming calls are not supported for the CLI protocol.
+     *
+     * @throws Error Always, as this functionality is not supported.
+     */
+    callToolStreaming(caller: IUtcpClient, toolName: string, toolArgs: Record<string, any>, toolCallTemplate: CallTemplate): AsyncGenerator<any, void, unknown>;
+    close(): Promise<void>;
+}
+
+/**
+ * Registers the CLI protocol's CallTemplate serializer
+ * and its CommunicationProtocol implementation.
+ * This function should be called once when the CLI plugin is loaded.
+ */
+declare function register(override?: boolean): void;
+
+export { type CliCallTemplate, CliCallTemplateSchema, CliCallTemplateSerializer, CliCommunicationProtocol, type CommandStep, CommandStepSchema, register };