feat: Introduce core tool definitions, command action types, and a ne…

[Devnil434]

Summary

Adds a new /map built-in command that lets Gemini analyze the current workspace and generate a Mermaid.js architecture diagram directly in the terminal. The command uses a new backend tool (map_project_structure) to scan project files, detect entry points, and sample import relationships.

Details

• Introduces MapTool (map_project_structure) in packages/core/src/tools/map-tool.ts.
• Tool scans ts/js files using glob, respects .gitignore / .geminiignore, and reads package.json for dependencies and workspaces.
• Detects entry points (index|main|cli|bin) and extracts import samples to build a dependency overview.
• Returns structured JSON (scanDirectory, dependencies, workspaces, entryPoints, keyFileImports) for Gemini to synthesize into a Mermaid diagram.
• Adds /map command (autoExecute: true) that runs a guided prompt instructing Gemini to act as an Architecture Cartographer.
• Restricts tool usage to map_project_structure for safety.
• Registers tool in coreTools.ts and config.ts, and loads command via BuiltinCommandLoader.ts.
• Adds unit tests for both the tool and command.

Related Issues

Related to developer experience improvements for exploring repository architecture.

How to Validate

1. Build the CLI:

   npm install
   npm run build
   

Start the CLI:

gemini

Run:

/map

4. Expected result: Gemini scans the repo and prints a Mermaid architecture diagram summarizing dependencies and entry points.

Pre-Merge Checklist

• Added/updated tests
• Updated docs (if needed)
• Noted breaking changes (none)

closes #21080

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the CLI's capabilities by introducing a new command that enables Gemini to automatically generate architectural diagrams of a project. It achieves this by integrating a powerful new backend tool for project structure analysis and by extending the core system to allow dynamic control over the model's persona and tool access during specific interactions. This feature aims to improve developer experience by providing quick, visual insights into codebase organization.

Highlights

• New /map Command: Introduced a new built-in /map command that allows Gemini to analyze the current workspace and generate a Mermaid.js architecture diagram directly in the terminal. This command automatically executes a guided prompt.
• New map_project_structure Tool: Added a new backend tool, map_project_structure, responsible for scanning project files (TypeScript/JavaScript), detecting entry points, sampling import relationships, and reading package.json for dependencies and workspaces. It respects .gitignore and .geminiignore.
• Dynamic Prompt and Tool Configuration: Implemented the ability to dynamically extend the system prompt and restrict the set of available tools for a given turn. This allows commands like /map to guide the model with a specific persona ('Architecture Cartographer') and limit its tool usage for safety and focus.
• Core Infrastructure Updates: Modified core client and command processing logic to support passing dynamic system prompt extensions and tool restrictions through the submit_prompt action, ensuring these configurations are applied and reset correctly per turn.

Changelog

• packages/cli/src/services/BuiltinCommandLoader.ts
  • Imported mapCommand.
  • Registered mapCommand as a built-in command.
• packages/cli/src/ui/commands/mapCommand.test.ts
  • Added unit tests for mapCommand, verifying its definition and the submit_prompt action's configuration.
• packages/cli/src/ui/commands/mapCommand.ts
  • Added the new /map slash command definition.
  • Configured the /map command to trigger a submit_prompt action with a specific system prompt extension and restricted tool usage to map_project_structure.
• packages/cli/src/ui/components/SettingsDialog.test.tsx
  • Adjusted test logic, likely for branch merge compatibility.
• packages/cli/src/ui/hooks/slashCommandProcessor.ts
  • Updated useSlashCommandProcessor to pass systemPromptExtension and tools from submit_prompt results.
• packages/cli/src/ui/hooks/useGeminiStream.ts
  • Modified prepareQueryForGemini and sendMessageStream to accept and propagate systemPromptExtension and tools options.
  • Implemented logic to reset systemPromptExtension and tools after a turn when they were dynamically applied.
• packages/cli/src/ui/types.ts
  • Extended the SubmitPromptResult interface to include optional systemPromptExtension and tools properties.
• packages/cli/ts_errors.txt
  • Added a file listing TypeScript errors, indicating initial compilation issues during development.
• packages/core/src/commands/types.ts
  • Extended the SubmitPromptActionReturn interface to include optional systemPromptExtension and tools properties.
• packages/core/src/config/config.ts
  • Imported MapTool.
  • Registered MapTool within the configuration.
• packages/core/src/core/client.ts
  • Defined SendMessageStreamOptions interface for dynamic prompt and tool configurations.
  • Modified setTools to allow specifying a list of allowedTools.
  • Updated updateSystemInstruction to accept an optional extension for dynamic system prompt modification.
  • Adjusted sendMessageStream and related methods to accept and utilize SendMessageStreamOptions.
  • Added logic to reset dynamic system instructions and tools after a turn.
• packages/core/src/tools/definitions/base-declarations.ts
  • Defined the MAP_TOOL_NAME constant as 'map_project_structure'.
• packages/core/src/tools/definitions/coreTools.ts
  • Imported MAP_TOOL_NAME.
  • Added MAP_DEFINITION to the core tool definitions.
• packages/core/src/tools/definitions/model-family-sets/default-legacy.ts
  • Added the map_project_structure tool definition, including its description and dir_path parameter schema.
• packages/core/src/tools/definitions/model-family-sets/gemini-3.ts
  • Added the map_project_structure tool definition, including its description and dir_path parameter schema.
• packages/core/src/tools/definitions/types.ts
  • Updated CoreToolSet interface to include map_project_structure.
• packages/core/src/tools/map-tool.test.ts
  • Added unit tests for MapTool, verifying its instantiation, properties, and parameter validation.
• packages/core/src/tools/map-tool.ts
  • Added the new MapTool class and MapToolInvocation for project structure mapping.
  • Implemented logic to scan directories, read package.json, detect entry points, and sample imports using glob.
  • Ensured file exclusions (.gitignore, .geminiignore) are respected during scanning.
  • Provided structured JSON output containing dependencies, workspaces, entry points, and key file imports.
• packages/core/src/tools/tool-names.ts
  • Exported MAP_TOOL_NAME.

Activity

• The author, Devnil434, has introduced a new feature to generate architecture diagrams.
• Unit tests have been added for both the new mapCommand and the MapTool.
• The pull request description indicates that documentation has been updated (if needed) and no breaking changes were introduced.
• A ts_errors.txt file was added, suggesting that some TypeScript compilation issues were encountered and likely addressed during development.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a new /map command and a corresponding map_project_structure tool to generate architecture diagrams. The implementation involves changes across the CLI and core packages to support per-turn system prompt extensions and tool restrictions. My review focuses on the new tool's implementation in packages/core/src/tools/map-tool.ts, where I've identified a critical issue that could lead to a runtime crash and a high-severity issue related to unsafe type assertions when parsing package.json.

[Devnil434]

/gemini review

[Devnil434]

@gemini-cli-robot already fixed accoding to yolur review suggestion.

[gemini-code-assist]

Code Review

This pull request introduces a new /map command and its backend tool map_project_structure to generate project architecture diagrams. While the feature is useful, the security audit identified two high-severity vulnerabilities: the infrastructure for restricting tools and extending system prompts for slash commands is flawed, potentially leading to privilege escalation in multi-turn conversations, and the MapTool implementation lacks proper symlink validation, which could allow reading sensitive files outside the workspace. Furthermore, the PR contains several code quality issues, including unresolved merge conflict markers, an accidentally committed TypeScript error log file, and an incorrect error type used by the new map tool. All identified issues must be addressed before merging.

[Devnil434]

@gemini-code-assist already fixed as per your suggestion.

[gemini-code-assist]

Thank you for letting me know. I appreciate you addressing the suggestions. I will take these updates into account during the next review cycle.

[Devnil434]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a new /map command to generate a Mermaid.js architecture diagram of the project, which is a great developer experience improvement. The implementation is well-structured, adding a new map_project_structure tool in the core package and the corresponding command in the CLI. The changes to plumb through systemPromptExtension and tools from slash commands to the GeminiClient are handled correctly, including the crucial logic to reset this state after the turn. I have one suggestion to improve the robustness of import parsing in the new tool to provide more accurate diagrams. Overall, this is a solid feature addition.

[Devnil434]

@gemini-code-assist is it ok completely

[gemini-code-assist]

Hi @Devnil434, thanks for checking in! I've performed a fresh review of the pull request, taking into account the recent changes.

The overall implementation of the /map command and map_project_structure tool is well-structured and addresses the core functionality. However, I've identified a couple of points that could be improved:

• Incomplete Import Sampling in MapTool (Medium Severity)

  • File: packages/core/src/tools/map-tool.ts
  • Lines: 104-104
  • Explanation: The MapToolInvocation currently samples imports from only the first 10 identified entry points (entryPoints.slice(0, 10)). While this is an efficiency measure, it might lead to an incomplete architectural map, especially in large projects with many entry points where critical dependencies might be defined in files beyond the initial 10. The model's prompt asks it to "collect all entry points constraints, components and data flows... going directory by directory if needed," but the tool itself limits the initial data provided. This could hinder the model's ability to form a "deep holistic understanding."
  • Suggestion: Consider increasing the number of sampled entry points or implementing a more sophisticated sampling strategy if performance allows, or clarify in the tool's description that it provides a sample of imports rather than a comprehensive list from all entry points. For now, I'd suggest increasing the limit slightly to provide more data to the model.

• Presence of ts_errors.txt (Low Severity)

  • File: packages/cli/ts_errors.txt
  • Lines: 1-9
  • Explanation: The ts_errors.txt file appears to contain temporary TypeScript compilation errors. This file should not be part of the final commit as it's not functional code and can clutter the repository.
  • Suggestion: Please remove this file before merging.

• Long Prompt String in mapCommand.ts (Low Severity)

  • File: packages/cli/src/ui/commands/mapCommand.ts
  • Lines: 25-26
  • Explanation: The content.text string for the /map command is very long. While it provides detailed instructions, it can be hard to read and maintain as a single string literal.
  • Suggestion: For improved readability and maintainability, consider breaking this long string into multiple lines or using a template literal if further complexity is expected.

Addressing these points would further improve the quality of the pull request. Let me know if you have any questions!

[gemini-cli]

Hi there! Thank you for your interest in contributing to Gemini CLI.

To ensure we maintain high code quality and focus on our prioritized roadmap, we have updated our contribution policy (see Discussion #17383).

We only guarantee review and consideration of pull requests for issues that are explicitly labeled as 'help wanted'. All other community pull requests are subject to closure after 14 days if they do not align with our current focus areas. For this reason, we strongly recommend that contributors only submit pull requests against issues explicitly labeled as 'help-wanted'.

This pull request is being closed as it has been open for 14 days without a 'help wanted' designation. We encourage you to find and contribute to existing 'help wanted' issues in our backlog! Thank you for your understanding and for being part of our community!