From 8d3fec08e59b100da036b685d20b080203ba3a4c Mon Sep 17 00:00:00 2001 From: moon jooho Date: Fri, 4 Jul 2025 09:13:02 +0900 Subject: Add and improve JSDoc comments for core tool methods (#3128) --- packages/core/src/tools/glob.ts | 6 +++++- packages/core/src/tools/mcp-client.ts | 17 +++++++++++++++++ packages/core/src/tools/shell.ts | 16 ++++++++++++++++ packages/core/src/tools/web-search.ts | 9 +++++++-- packages/core/src/tools/write-file.ts | 7 +++++++ 5 files changed, 52 insertions(+), 3 deletions(-) (limited to 'packages/core/src') diff --git a/packages/core/src/tools/glob.ts b/packages/core/src/tools/glob.ts index 0dd2f411..22dacc83 100644 --- a/packages/core/src/tools/glob.ts +++ b/packages/core/src/tools/glob.ts @@ -122,7 +122,11 @@ export class GlobTool extends BaseTool { } /** - * Checks if a path is within the root directory. + * Checks if a given path is within the root directory bounds. + * This security check prevents accessing files outside the designated root directory. + * + * @param pathToCheck The absolute path to validate + * @returns True if the path is within the root directory, false otherwise */ private isWithinRoot(pathToCheck: string): boolean { const absolutePathToCheck = path.resolve(pathToCheck); diff --git a/packages/core/src/tools/mcp-client.ts b/packages/core/src/tools/mcp-client.ts index 52196b80..359ce30a 100644 --- a/packages/core/src/tools/mcp-client.ts +++ b/packages/core/src/tools/mcp-client.ts @@ -162,6 +162,16 @@ export async function discoverMcpTools( } } +/** + * Connects to an MCP server and discovers available tools, registering them with the tool registry. + * This function handles the complete lifecycle of connecting to a server, discovering tools, + * and cleaning up resources if no tools are found. + * + * @param mcpServerName The name identifier for this MCP server + * @param mcpServerConfig Configuration object containing connection details + * @param toolRegistry The registry to register discovered tools with + * @returns Promise that resolves when discovery is complete + */ async function connectAndDiscover( mcpServerName: string, mcpServerConfig: MCPServerConfig, @@ -375,6 +385,13 @@ async function connectAndDiscover( } } +/** + * Sanitizes a JSON schema object to ensure compatibility with Vertex AI. + * This function recursively processes the schema to remove problematic properties + * that can cause issues with the Gemini API. + * + * @param schema The JSON schema object to sanitize (modified in-place) + */ export function sanitizeParameters(schema?: Schema) { if (!schema) { return; diff --git a/packages/core/src/tools/shell.ts b/packages/core/src/tools/shell.ts index bbb998d5..f0a30a9c 100644 --- a/packages/core/src/tools/shell.ts +++ b/packages/core/src/tools/shell.ts @@ -89,6 +89,15 @@ Process Group PGID: Process group started or \`(none)\``, return description; } + /** + * Extracts the root command from a given shell command string. + * This is used to identify the base command for permission checks. + * + * @param command The shell command string to parse + * @returns The root command name, or undefined if it cannot be determined + * @example getCommandRoot("ls -la /tmp") returns "ls" + * @example getCommandRoot("git status && npm test") returns "git" + */ getCommandRoot(command: string): string | undefined { return command .trim() // remove leading and trailing whitespace @@ -98,6 +107,13 @@ Process Group PGID: Process group started or \`(none)\``, .pop(); // take last part and return command root (or undefined if previous line was empty) } + /** + * Determines whether a given shell command is allowed to execute based on + * the tool's configuration including allowlists and blocklists. + * + * @param command The shell command string to validate + * @returns True if the command is allowed to execute, false otherwise + */ isCommandAllowed(command: string): boolean { // 0. Disallow command substitution if (command.includes('$(') || command.includes('`')) { diff --git a/packages/core/src/tools/web-search.ts b/packages/core/src/tools/web-search.ts index c4dcc54a..5ee8e85c 100644 --- a/packages/core/src/tools/web-search.ts +++ b/packages/core/src/tools/web-search.ts @@ -81,7 +81,12 @@ export class WebSearchTool extends BaseTool< ); } - validateParams(params: WebSearchToolParams): string | null { + /** + * Validates the parameters for the WebSearchTool. + * @param params The parameters to validate + * @returns An error message string if validation fails, null if valid + */ + validateToolParams(params: WebSearchToolParams): string | null { if ( this.schema.parameters && !SchemaValidator.validate( @@ -105,7 +110,7 @@ export class WebSearchTool extends BaseTool< params: WebSearchToolParams, signal: AbortSignal, ): Promise { - const validationError = this.validateParams(params); + const validationError = this.validateToolParams(params); if (validationError) { return { llmContent: `Error: Invalid parameters provided. Reason: ${validationError}`, diff --git a/packages/core/src/tools/write-file.ts b/packages/core/src/tools/write-file.ts index 2d5e85be..c343cab8 100644 --- a/packages/core/src/tools/write-file.ts +++ b/packages/core/src/tools/write-file.ts @@ -96,6 +96,13 @@ export class WriteFileTool this.client = this.config.getGeminiClient(); } + /** + * Checks if a given path is within the root directory bounds. + * This security check prevents writing files outside the designated root directory. + * + * @param pathToCheck The absolute path to validate + * @returns True if the path is within the root directory, false otherwise + */ private isWithinRoot(pathToCheck: string): boolean { const normalizedPath = path.normalize(pathToCheck); const normalizedRoot = path.normalize(this.config.getTargetDir()); -- cgit v1.2.3