@wxp212/gemini-cli 0.28.3-2

package/bundle/docs/ide-integration/index.md

@@ -0,0 +1,202 @@
+# IDE integration
+
+Gemini CLI can integrate with your IDE to provide a more seamless and
+context-aware experience. This integration allows the CLI to understand your
+workspace better and enables powerful features like native in-editor diffing.
+
+Currently, the supported IDEs are [Antigravity](https://antigravity.google),
+[Visual Studio Code](https://code.visualstudio.com/), and other editors that
+support VS Code extensions. To build support for other editors, see the
+[IDE Companion Extension Spec](./ide-companion-spec.md).
+
+## Features
+
+- **Workspace context:** The CLI automatically gains awareness of your workspace
+  to provide more relevant and accurate responses. This context includes:
+  - The **10 most recently accessed files** in your workspace.
+  - Your active cursor position.
+  - Any text you have selected (up to a 16KB limit; longer selections will be
+    truncated).
+
+- **Native diffing:** When Gemini suggests code modifications, you can view the
+  changes directly within your IDE's native diff viewer. This allows you to
+  review, edit, and accept or reject the suggested changes seamlessly.
+
+- **VS Code commands:** You can access Gemini CLI features directly from the VS
+  Code Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`):
+  - `Gemini CLI: Run`: Starts a new Gemini CLI session in the integrated
+    terminal.
+  - `Gemini CLI: Accept Diff`: Accepts the changes in the active diff editor.
+  - `Gemini CLI: Close Diff Editor`: Rejects the changes and closes the active
+    diff editor.
+  - `Gemini CLI: View Third-Party Notices`: Displays the third-party notices for
+    the extension.
+
+## Installation and setup
+
+There are three ways to set up the IDE integration:
+
+### 1. Automatic nudge (recommended)
+
+When you run Gemini CLI inside a supported editor, it will automatically detect
+your environment and prompt you to connect. Answering "Yes" will automatically
+run the necessary setup, which includes installing the companion extension and
+enabling the connection.
+
+### 2. Manual installation from CLI
+
+If you previously dismissed the prompt or want to install the extension
+manually, you can run the following command inside Gemini CLI:
+
+```
+/ide install
+```
+
+This will find the correct extension for your IDE and install it.
+
+### 3. Manual installation from a marketplace
+
+You can also install the extension directly from a marketplace.
+
+- **For Visual Studio Code:** Install from the
+  [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=google.gemini-cli-vscode-ide-companion).
+- **For VS Code forks:** To support forks of VS Code, the extension is also
+  published on the
+  [Open VSX Registry](https://open-vsx.org/extension/google/gemini-cli-vscode-ide-companion).
+  Follow your editor's instructions for installing extensions from this
+  registry.
+
+> NOTE: The "Gemini CLI Companion" extension may appear towards the bottom of
+> search results. If you don't see it immediately, try scrolling down or sorting
+> by "Newly Published".
+>
+> After manually installing the extension, you must run `/ide enable` in the CLI
+> to activate the integration.
+
+## Usage
+
+### Enabling and disabling
+
+You can control the IDE integration from within the CLI:
+
+- To enable the connection to the IDE, run:
+  ```
+  /ide enable
+  ```
+- To disable the connection, run:
+  ```
+  /ide disable
+  ```
+
+When enabled, Gemini CLI will automatically attempt to connect to the IDE
+companion extension.
+
+### Checking the status
+
+To check the connection status and see the context the CLI has received from the
+IDE, run:
+
+```
+/ide status
+```
+
+If connected, this command will show the IDE it's connected to and a list of
+recently opened files it is aware of.
+
+> [!NOTE] The file list is limited to 10 recently accessed files within your
+> workspace and only includes local files on disk.)
+
+### Working with diffs
+
+When you ask Gemini to modify a file, it can open a diff view directly in your
+editor.
+
+**To accept a diff**, you can perform any of the following actions:
+
+- Click the **checkmark icon** in the diff editor's title bar.
+- Save the file (e.g., with `Cmd+S` or `Ctrl+S`).
+- Open the Command Palette and run **Gemini CLI: Accept Diff**.
+- Respond with `yes` in the CLI when prompted.
+
+**To reject a diff**, you can:
+
+- Click the **'x' icon** in the diff editor's title bar.
+- Close the diff editor tab.
+- Open the Command Palette and run **Gemini CLI: Close Diff Editor**.
+- Respond with `no` in the CLI when prompted.
+
+You can also **modify the suggested changes** directly in the diff view before
+accepting them.
+
+If you select ‘Allow for this session’ in the CLI, changes will no longer show
+up in the IDE as they will be auto-accepted.
+
+## Using with sandboxing
+
+If you are using Gemini CLI within a sandbox, please be aware of the following:
+
+- **On macOS:** The IDE integration requires network access to communicate with
+  the IDE companion extension. You must use a Seatbelt profile that allows
+  network access.
+- **In a Docker container:** If you run Gemini CLI inside a Docker (or Podman)
+  container, the IDE integration can still connect to the VS Code extension
+  running on your host machine. The CLI is configured to automatically find the
+  IDE server on `host.docker.internal`. No special configuration is usually
+  required, but you may need to ensure your Docker networking setup allows
+  connections from the container to the host.
+
+## Troubleshooting
+
+If you encounter issues with IDE integration, here are some common error
+messages and how to resolve them.
+
+### Connection errors
+
+- **Message:**
+  `🔴 Disconnected: Failed to connect to IDE companion extension in [IDE Name]. Please ensure the extension is running. To install the extension, run /ide install.`
+  - **Cause:** Gemini CLI could not find the necessary environment variables
+    (`GEMINI_CLI_IDE_WORKSPACE_PATH` or `GEMINI_CLI_IDE_SERVER_PORT`) to connect
+    to the IDE. This usually means the IDE companion extension is not running or
+    did not initialize correctly.
+  - **Solution:**
+    1.  Make sure you have installed the **Gemini CLI Companion** extension in
+        your IDE and that it is enabled.
+    2.  Open a new terminal window in your IDE to ensure it picks up the correct
+        environment.
+
+- **Message:**
+  `🔴 Disconnected: IDE connection error. The connection was lost unexpectedly. Please try reconnecting by running /ide enable`
+  - **Cause:** The connection to the IDE companion was lost.
+  - **Solution:** Run `/ide enable` to try and reconnect. If the issue
+    continues, open a new terminal window or restart your IDE.
+
+### Configuration errors
+
+- **Message:**
+  `🔴 Disconnected: Directory mismatch. Gemini CLI is running in a different location than the open workspace in [IDE Name]. Please run the CLI from one of the following directories: [List of directories]`
+  - **Cause:** The CLI's current working directory is outside the workspace you
+    have open in your IDE.
+  - **Solution:** `cd` into the same directory that is open in your IDE and
+    restart the CLI.
+
+- **Message:**
+  `🔴 Disconnected: To use this feature, please open a workspace folder in [IDE Name] and try again.`
+  - **Cause:** You have no workspace open in your IDE.
+  - **Solution:** Open a workspace in your IDE and restart the CLI.
+
+### General errors
+
+- **Message:**
+  `IDE integration is not supported in your current environment. To use this feature, run Gemini CLI in one of these supported IDEs: [List of IDEs]`
+  - **Cause:** You are running Gemini CLI in a terminal or environment that is
+    not a supported IDE.
+  - **Solution:** Run Gemini CLI from the integrated terminal of a supported
+    IDE, like Antigravity or VS Code.
+
+- **Message:**
+  `No installer is available for IDE. Please install the Gemini CLI Companion extension manually from the marketplace.`
+  - **Cause:** You ran `/ide install`, but the CLI does not have an automated
+    installer for your specific IDE.
+  - **Solution:** Open your IDE's extension marketplace, search for "Gemini CLI
+    Companion", and
+    [install it manually](#3-manual-installation-from-a-marketplace).

package/bundle/docs/index.md

@@ -0,0 +1,123 @@
+# Gemini CLI documentation
+
+Gemini CLI is an open-source AI agent that brings the power of Gemini directly
+into your terminal. It is designed to be a terminal-first, extensible, and
+powerful tool for developers, engineers, SREs, and beyond.
+
+Gemini CLI integrates with your local environment. It can read and edit files,
+execute shell commands, and search the web, all while maintaining your project
+context.
+
+## Get started
+
+Begin your journey with Gemini CLI by setting up your environment and learning
+the basics.
+
+- **[Quickstart](./get-started/index.md):** A streamlined guide to get you
+  chatting in minutes.
+- **[Installation](./get-started/installation.md):** Instructions for macOS,
+  Linux, and Windows.
+- **[Authentication](./get-started/authentication.md):** Set up access using
+  Google OAuth, API keys, or Vertex AI.
+- **[Examples](./get-started/examples.md):** View common usage scenarios to
+  inspire your own workflows.
+
+## Use Gemini CLI
+
+Master the core capabilities that let Gemini CLI interact with your system
+safely and effectively.
+
+- **[Using the CLI](./cli/index.md):** Learn the basics of the command-line
+  interface.
+- **[File management](./tools/file-system.md):** Grant the model the ability to
+  read code and apply changes directly to your files.
+- **[Shell commands](./tools/shell.md):** Allow the model to run builds, tests,
+  and git commands.
+- **[Memory management](./tools/memory.md):** Teach Gemini CLI facts about your
+  project and preferences that persist across sessions.
+- **[Project context](./cli/gemini-md.md):** Use `GEMINI.md` files to provide
+  persistent context for your projects.
+- **[Web search and fetch](./tools/web-search.md):** Enable the model to fetch
+  real-time information from the internet.
+- **[Session management](./cli/session-management.md):** Save, resume, and
+  organize your chat sessions.
+
+## Configuration
+
+Customize Gemini CLI to match your workflow and preferences.
+
+- **[Settings](./cli/settings.md):** Control response creativity, output
+  verbosity, and more.
+- **[Model selection](./cli/model.md):** Choose the best Gemini model for your
+  specific task.
+- **[Ignore files](./cli/gemini-ignore.md):** Use `.geminiignore` to keep
+  sensitive files out of the model's context.
+- **[Trusted folders](./cli/trusted-folders.md):** Define security boundaries
+  for file access and execution.
+- **[Token caching](./cli/token-caching.md):** Optimize performance and cost by
+  caching context.
+- **[Themes](./cli/themes.md):** Personalize the visual appearance of the CLI.
+
+## Advanced features
+
+Explore powerful features for complex workflows and enterprise environments.
+
+- **[Headless mode](./cli/headless.md):** Run Gemini CLI in scripts or CI/CD
+  pipelines for automated reasoning.
+- **[Sandboxing](./cli/sandbox.md):** Execute untrusted code or tools in a
+  secure, isolated container.
+- **[Checkpointing](./cli/checkpointing.md):** Save and restore workspace state
+  to recover from experimental changes.
+- **[Custom commands](./cli/custom-commands.md):** Create shortcuts for
+  frequently used prompts.
+- **[System prompt override](./cli/system-prompt.md):** Customize the core
+  instructions given to the model.
+- **[Telemetry](./cli/telemetry.md):** Understand how usage data is collected
+  and managed.
+- **[Enterprise](./cli/enterprise.md):** Manage configurations and policies for
+  large teams.
+
+## Extensions
+
+Extend Gemini CLI's capabilities with new tools and behaviors using extensions.
+
+- **[Introduction](./extensions/index.md):** Learn about the extension system
+  and how to manage extensions.
+- **[Writing extensions](./extensions/writing-extensions.md):** Learn how to
+  create your first extension.
+- **[Extensions reference](./extensions/reference.md):** Deeply understand the
+  extension format, commands, and configuration.
+- **[Best practices](./extensions/best-practices.md):** Learn strategies for
+  building great extensions.
+- **[Extensions releasing](./extensions/releasing.md):** Learn how to share your
+  extensions with the world.
+
+## Ecosystem and extensibility
+
+Connect Gemini CLI to external services and other development tools.
+
+- **[MCP servers](./tools/mcp-server.md):** Connect to external services using
+  the Model Context Protocol.
+- **[IDE integration](./ide-integration/index.md):** Use Gemini CLI alongside VS
+  Code.
+- **[Hooks](./hooks/index.md):** (Preview) Write scripts that run on specific
+  CLI events.
+- **[Agent skills](./cli/skills.md):** (Preview) Add specialized expertise and
+  workflows.
+- **[Sub-agents](./core/subagents.md):** (Preview) Delegate tasks to specialized
+  agents.
+
+## Development and reference
+
+Deep dive into the architecture and contribute to the project.
+
+- **[Architecture](./architecture.md):** Understand the technical design of
+  Gemini CLI.
+- **[Command reference](./cli/commands.md):** A complete list of available
+  commands.
+- **[Local development](./local-development.md):** Set up your environment to
+  contribute to Gemini CLI.
+- **[Contributing](../CONTRIBUTING.md):** Learn how to submit pull requests and
+  report issues.
+- **[FAQ](./faq.md):** Answers to common questions.
+- **[Troubleshooting](./troubleshooting.md):** Solutions for common issues.

package/bundle/docs/integration-tests.md

@@ -0,0 +1,211 @@
+# Integration tests
+
+This document provides information about the integration testing framework used
+in this project.
+
+## Overview
+
+The integration tests are designed to validate the end-to-end functionality of
+the Gemini CLI. They execute the built binary in a controlled environment and
+verify that it behaves as expected when interacting with the file system.
+
+These tests are located in the `integration-tests` directory and are run using a
+custom test runner.
+
+## Building the tests
+
+Prior to running any integration tests, you need to create a release bundle that
+you want to actually test:
+
+```bash
+npm run bundle
+```
+
+You must re-run this command after making any changes to the CLI source code,
+but not after making changes to tests.
+
+## Running the tests
+
+The integration tests are not run as part of the default `npm run test` command.
+They must be run explicitly using the `npm run test:integration:all` script.
+
+The integration tests can also be run using the following shortcut:
+
+```bash
+npm run test:e2e
+```
+
+## Running a specific set of tests
+
+To run a subset of test files, you can use
+`npm run <integration test command> <file_name1> ....` where &lt;integration
+test command&gt; is either `test:e2e` or `test:integration*` and `<file_name>`
+is any of the `.test.js` files in the `integration-tests/` directory. For
+example, the following command runs `list_directory.test.js` and
+`write_file.test.js`:
+
+```bash
+npm run test:e2e list_directory write_file
+```
+
+### Running a single test by name
+
+To run a single test by its name, use the `--test-name-pattern` flag:
+
+```bash
+npm run test:e2e -- --test-name-pattern "reads a file"
+```
+
+### Regenerating model responses
+
+Some integration tests use faked out model responses, which may need to be
+regenerated from time to time as the implementations change.
+
+To regenerate these golden files, set the REGENERATE_MODEL_GOLDENS environment
+variable to "true" when running the tests, for example:
+
+**WARNING**: If running locally you should review these updated responses for
+any information about yourself or your system that gemini may have included in
+these responses.
+
+```bash
+REGENERATE_MODEL_GOLDENS="true" npm run test:e2e
+```
+
+**WARNING**: Make sure you run **await rig.cleanup()** at the end of your test,
+else the golden files will not be updated.
+
+### Deflaking a test
+
+Before adding a **new** integration test, you should test it at least 5 times
+with the deflake script or workflow to make sure that it is not flaky.
+
+### Deflake script
+
+```bash
+npm run deflake -- --runs=5 --command="npm run test:e2e -- -- --test-name-pattern '<your-new-test-name>'"
+```
+
+#### Deflake workflow
+
+```bash
+gh workflow run deflake.yml --ref <your-branch> -f test_name_pattern="<your-test-name-pattern>"
+```
+
+### Running all tests
+
+To run the entire suite of integration tests, use the following command:
+
+```bash
+npm run test:integration:all
+```
+
+### Sandbox matrix
+
+The `all` command will run tests for `no sandboxing`, `docker` and `podman`.
+Each individual type can be run using the following commands:
+
+```bash
+npm run test:integration:sandbox:none
+```
+
+```bash
+npm run test:integration:sandbox:docker
+```
+
+```bash
+npm run test:integration:sandbox:podman
+```
+
+## Diagnostics
+
+The integration test runner provides several options for diagnostics to help
+track down test failures.
+
+### Keeping test output
+
+You can preserve the temporary files created during a test run for inspection.
+This is useful for debugging issues with file system operations.
+
+To keep the test output set the `KEEP_OUTPUT` environment variable to `true`.
+
+```bash
+KEEP_OUTPUT=true npm run test:integration:sandbox:none
+```
+
+When output is kept, the test runner will print the path to the unique directory
+for the test run.
+
+### Verbose output
+
+For more detailed debugging, set the `VERBOSE` environment variable to `true`.
+
+```bash
+VERBOSE=true npm run test:integration:sandbox:none
+```
+
+When using `VERBOSE=true` and `KEEP_OUTPUT=true` in the same command, the output
+is streamed to the console and also saved to a log file within the test's
+temporary directory.
+
+The verbose output is formatted to clearly identify the source of the logs:
+
+```
+--- TEST: <log dir>:<test-name> ---
+... output from the gemini command ...
+--- END TEST: <log dir>:<test-name> ---
+```
+
+## Linting and formatting
+
+To ensure code quality and consistency, the integration test files are linted as
+part of the main build process. You can also manually run the linter and
+auto-fixer.
+
+### Running the linter
+
+To check for linting errors, run the following command:
+
+```bash
+npm run lint
+```
+
+You can include the `:fix` flag in the command to automatically fix any fixable
+linting errors:
+
+```bash
+npm run lint:fix
+```
+
+## Directory structure
+
+The integration tests create a unique directory for each test run inside the
+`.integration-tests` directory. Within this directory, a subdirectory is created
+for each test file, and within that, a subdirectory is created for each
+individual test case.
+
+This structure makes it easy to locate the artifacts for a specific test run,
+file, or case.
+
+```
+.integration-tests/
+└── <run-id>/
+    └── <test-file-name>.test.js/
+        └── <test-case-name>/
+            ├── output.log
+            └── ...other test artifacts...
+```
+
+## Continuous integration
+
+To ensure the integration tests are always run, a GitHub Actions workflow is
+defined in `.github/workflows/chained_e2e.yml`. This workflow automatically runs
+the integrations tests for pull requests against the `main` branch, or when a
+pull request is added to a merge queue.
+
+The workflow runs the tests in different sandboxing environments to ensure
+Gemini CLI is tested across each:
+
+- `sandbox:none`: Runs the tests without any sandboxing.
+- `sandbox:docker`: Runs the tests in a Docker container.
+- `sandbox:podman`: Runs the tests in a Podman container.

package/bundle/docs/issue-and-pr-automation.md

@@ -0,0 +1,134 @@
+# Automation and triage processes
+
+This document provides a detailed overview of the automated processes we use to
+manage and triage issues and pull requests. Our goal is to provide prompt
+feedback and ensure that contributions are reviewed and integrated efficiently.
+Understanding this automation will help you as a contributor know what to expect
+and how to best interact with our repository bots.
+
+## Guiding principle: Issues and pull requests
+
+First and foremost, almost every Pull Request (PR) should be linked to a
+corresponding Issue. The issue describes the "what" and the "why" (the bug or
+feature), while the PR is the "how" (the implementation). This separation helps
+us track work, prioritize features, and maintain clear historical context. Our
+automation is built around this principle.
+
+> **Note:** Issues tagged as "🔒Maintainers only" are reserved for project
+> maintainers. We will not accept pull requests related to these issues.
+
+---
+
+## Detailed automation workflows
+
+Here is a breakdown of the specific automation workflows that run in our
+repository.
+
+### 1. When you open an issue: `Automated Issue Triage`
+
+This is the first bot you will interact with when you create an issue. Its job
+is to perform an initial analysis and apply the correct labels.
+
+- **Workflow File**: `.github/workflows/gemini-automated-issue-triage.yml`
+- **When it runs**: Immediately after an issue is created or reopened.
+- **What it does**:
+  - It uses a Gemini model to analyze the issue's title and body against a
+    detailed set of guidelines.
+  - **Applies one `area/*` label**: Categorizes the issue into a functional area
+    of the project (e.g., `area/ux`, `area/models`, `area/platform`).
+  - **Applies one `kind/*` label**: Identifies the type of issue (e.g.,
+    `kind/bug`, `kind/enhancement`, `kind/question`).
+  - **Applies one `priority/*` label**: Assigns a priority from P0 (critical) to
+    P3 (low) based on the described impact.
+  - **May apply `status/need-information`**: If the issue lacks critical details
+    (like logs or reproduction steps), it will be flagged for more information.
+  - **May apply `status/need-retesting`**: If the issue references a CLI version
+    that is more than six versions old, it will be flagged for retesting on a
+    current version.
+- **What you should do**:
+  - Fill out the issue template as completely as possible. The more detail you
+    provide, the more accurate the triage will be.
+  - If the `status/need-information` label is added, please provide the
+    requested details in a comment.
+
+### 2. When you open a pull request: `Continuous Integration (CI)`
+
+This workflow ensures that all changes meet our quality standards before they
+can be merged.
+
+- **Workflow File**: `.github/workflows/ci.yml`
+- **When it runs**: On every push to a pull request.
+- **What it does**:
+  - **Lint**: Checks that your code adheres to our project's formatting and
+    style rules.
+  - **Test**: Runs our full suite of automated tests across macOS, Windows, and
+    Linux, and on multiple Node.js versions. This is the most time-consuming
+    part of the CI process.
+  - **Post Coverage Comment**: After all tests have successfully passed, a bot
+    will post a comment on your PR. This comment provides a summary of how well
+    your changes are covered by tests.
+- **What you should do**:
+  - Ensure all CI checks pass. A green checkmark ✅ will appear next to your
+    commit when everything is successful.
+  - If a check fails (a red "X" ❌), click the "Details" link next to the failed
+    check to view the logs, identify the problem, and push a fix.
+
+### 3. Ongoing triage for pull requests: `PR Auditing and Label Sync`
+
+This workflow runs periodically to ensure all open PRs are correctly linked to
+issues and have consistent labels.
+
+- **Workflow File**: `.github/workflows/gemini-scheduled-pr-triage.yml`
+- **When it runs**: Every 15 minutes on all open pull requests.
+- **What it does**:
+  - **Checks for a linked issue**: The bot scans your PR description for a
+    keyword that links it to an issue (e.g., `Fixes #123`, `Closes #456`).
+  - **Adds `status/need-issue`**: If no linked issue is found, the bot will add
+    the `status/need-issue` label to your PR. This is a clear signal that an
+    issue needs to be created and linked.
+  - **Synchronizes labels**: If an issue _is_ linked, the bot ensures the PR's
+    labels perfectly match the issue's labels. It will add any missing labels
+    and remove any that don't belong, and it will remove the `status/need-issue`
+    label if it was present.
+- **What you should do**:
+  - **Always link your PR to an issue.** This is the most important step. Add a
+    line like `Resolves #<issue-number>` to your PR description.
+  - This will ensure your PR is correctly categorized and moves through the
+    review process smoothly.
+
+### 4. Ongoing triage for issues: `Scheduled Issue Triage`
+
+This is a fallback workflow to ensure that no issue gets missed by the triage
+process.
+
+- **Workflow File**: `.github/workflows/gemini-scheduled-issue-triage.yml`
+- **When it runs**: Every hour on all open issues.
+- **What it does**:
+  - It actively seeks out issues that either have no labels at all or still have
+    the `status/need-triage` label.
+  - It then triggers the same powerful Gemini-based analysis as the initial
+    triage bot to apply the correct labels.
+- **What you should do**:
+  - You typically don't need to do anything. This workflow is a safety net to
+    ensure every issue is eventually categorized, even if the initial triage
+    fails.
+
+### 5. Release automation
+
+This workflow handles the process of packaging and publishing new versions of
+the Gemini CLI.
+
+- **Workflow File**: `.github/workflows/release-manual.yml`
+- **When it runs**: On a daily schedule for "nightly" releases, and manually for
+  official patch/minor releases.
+- **What it does**:
+  - Automatically builds the project, bumps the version numbers, and publishes
+    the packages to npm.
+  - Creates a corresponding release on GitHub with generated release notes.
+- **What you should do**:
+  - As a contributor, you don't need to do anything for this process. You can be
+    confident that once your PR is merged into the `main` branch, your changes
+    will be included in the very next nightly release.
+
+We hope this detailed overview is helpful. If you have any questions about our
+automation or processes, please don't hesitate to ask!