bundling

[mattKorwel]

TLDR

• This pr moves us to shipping our public binary in bundled form.
• This pr revamps our CI process into a more cohesive and streamlined approach

Bundling

The primary benefits of bundling for a command-line tool revolve around performance, reliability, and a better end-user experience (Expand for more info)

Why It's a Good Change for a CLI (Pros)

1. 🚀 Faster Startup Performance:
This is the most significant advantage for a CLI. When you run a Node.js application, the require() or import statements trigger a complex module resolution process that involves searching the file system for node_modules directories. This can result in hundreds or even thousands of file system I/O operations, which slows down the initial startup time.

• Unbundled: gemini -> require('libA') -> require('libB') -> ... (many file lookups)
• Bundled: gemini (one file is loaded into memory)

By consolidating all the necessary code into a single file, you reduce the startup to a single file read, making the CLI feel significantly more responsive to the user.

2. 📦 Faster and More Reliable Installation:
Users installing your CLI will have a much better experience.

• Fewer Files: npm install has to download and write far fewer files to the user's disk. This is faster and reduces the chance of installation errors due to network hiccups or file system issues.
• Smaller Footprint: Bundlers perform "tree-shaking," which means they analyze your code and exclude any unused functions or modules from your dependencies. This results in a smaller, optimized final artifact compared to shipping the entire node_modules directory.

3. 🛡️ Increased Reliability and Consistency:
A bundled application is self-contained and predictable.

• Dependency Isolation: The bundle includes the exact versions of the dependencies that you tested against. This completely eliminates a whole class of "works on my machine" bugs where a user might have a different, incompatible version of a sub-dependency in their environment that could break your tool.
• Immunity to node_modules Issues: Your CLI will no longer be affected by the user's local node_modules structure, global packages, or potential conflicts between different projects. It just runs.

4. 🚚 Simplified Distribution:
Having a single executable file makes distribution and packaging much simpler if you ever decide to, for example, package the CLI with a standalone Node.js binary (using a tool like pkg) or include it in a Docker image.

---

The Downsides of Bundling (Cons)

While the benefits are substantial for a CLI, there are trade-offs to consider, mostly affecting the development and debugging workflow.

1. 🐛 Debugging Complexity:
The code that runs is not the code you wrote. It's been transpiled, minified, and combined.

• Obfuscated Stack Traces: An error in the bundled file will point to a line number in a massive, often unreadable, file.
• Mitigation: Source Maps (.js.map files). A bundler can generate source maps that map the bundled code back to your original source files. When you use these with developer tools, stack traces become readable again. You can choose to publish these for public debugging or keep them private for your team.

2. 🩹 Difficult for End-Users to Patch:
If a user discovers a bug in one of your dependencies, they can't easily use a tool like patch-package to fix it themselves, because the dependency code is baked into the bundle. For a CLI, this is generally an acceptable trade-off for the reliability it provides.

3. 🏗️ Added Build-Step Complexity:
Your development process now requires a build step. You can't just run the source code directly; you must first build the bundle. This adds a layer of complexity to your local development, testing, and CI/CD pipeline.

Summary: Pros vs. Cons

Aspect	✅ Pros of Bundling	❌ Cons of Bundling
Performance	Drastically faster startup time and quicker installation.	Minor build time overhead during development.
Reliability	Isolates dependencies, preventing conflicts and ensuring consistency.	Users cannot easily patch sub-dependencies.
Size	Smaller total size on disk due to tree-shaking.	The single file itself can be large.
Debugging	Simpler to distribute and analyze a single artifact.	Difficult to debug without source maps.
Development	Clear separation between source and distributable code.	Requires a build step, adding complexity.

Conclusion:

For a library that other developers will include in their projects, bundling is often a bad idea because it leads to code duplication and conflicts.

However, for a standalone application like the Gemini CLI, the benefits of performance and reliability for the end-user are paramount. The faster startup time and insulation from environmental issues create a much more professional and robust tool. The downsides are primarily developer-facing and can be effectively managed with source maps and a solid build process. Your PR is making a very good trade-off.

CI

Artifacts

1. On each push to a pr or main, we will bundle our code and push it to github's npm package registry: https://github.com/google-gemini/gemini-cli/pkgs/npm/gemini-cli
2. On each push to a pr or main we will build the sandbox docker image and push it to githubs container registry: https://github.com/google-gemini/gemini-cli/pkgs/container/gemini-cli%2Fsandbox

Both of those artifacts are then used in all remaining tests. Specifically end 2 end tests no longer build the code or the sandbox image (with in context of github actions, this should all still work locally).

Merge queue Skipper

While i was hopeful that this would have a net positive impact on us, it hasn't materialized. It is currently adding a significant overhead in code complexity and maintenance. This PR removes it in the spirit of simplification. If we want to approach it again later we can, totally open to feedback here.

Environments

All the ci operations work against our prod environment. No changes will be made or packages pushed to prod. This is intended to help reduce noise, customer facing confusion, and churn on pakcage versions (which are onetime use on npmjs). We will follow this change with the ability to 'promote' a specific tested bundled package from dev to prod and ideally this would be our primmary deployment mechanism. All patches, releases etc will go do dev, we will validate and we can delete and reuse package numbers if needed. Then when we are comfortable those will be promoted to Prod. This will be a follow on change.

Release Channels

As of version 0.11 stable, and 0.12-preview the code is still non bundled. 0.13-nightly is bundled.

[gemini-code-assist]

Summary of Changes

Hello @mattKorwel, 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 refines the project's development and release processes, primarily by overhauling npm package management and CLI bundling. It introduces automated scripts for developers to seamlessly configure their local npm registries, enabling easy access to pre-release versions hosted on GitHub Packages. Concurrently, the changes simplify the release preparation workflow by adjusting how the CLI package is handled and published, moving towards a model where a pre-bundled CLI is consumed as a dependency. Additionally, the update includes minor but important improvements to the CLI's command loading capabilities and accessibility features, alongside a default setting adjustment for an experimental feature.

Highlights

• Registry Configuration: New scripts (npm run use-dev, npm run use-prod) and updated documentation (CONTRIBUTING.md) are introduced to manage npm registry settings, facilitating the use of GitHub Packages for pre-release versions and easy switching between development and production registries.
• Publishing Workflow Streamlining: The GitHub Action for publishing releases and the prepare-github-release.js script have been updated, removing workspace-specific publishing and bundle copying logic, indicating a shift towards a more streamlined or changed bundling/publishing strategy for the CLI.
• CLI Dependency Update: The project now explicitly depends on @google-gemini/gemini-cli (a nightly build from GitHub Packages), suggesting a move towards consuming a pre-bundled CLI rather than building it directly within the repository for release.
• Command Loader Enhancements: The non-interactive CLI's slash command handling has been improved by integrating additional command loaders (McpPromptLoader), enhancing its extensibility and the types of commands it can support.
• Accessibility Improvements: Accessibility has been enhanced in the Todo list components by adding aria-label and aria-role attributes to various UI elements.
• Codebase Investigator Default Setting: The default setting for the experimental enableCodebaseInvestigator feature has been changed from true to false in both the settings schema and core configuration.

Ignored Files

• Ignored by pattern: .github/workflows/** (3)
  • .github/workflows/ci.yml
  • .github/workflows/e2e.yml
  • .github/workflows/release-patch-1-create-pr.yml

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 significant changes to the project's bundling and publishing strategy, shifting to GitHub Packages for pre-release versions under the new @google-gemini scope. New scripts have been added to manage npm registry configuration for developers. My review found a critical issue in the new configure-registry.js script that could lead to the loss of a user's global .npmrc configuration. I've provided a detailed comment and a suggested fix to make the process safer by using a backup-and-restore mechanism. The other changes, including updates to CI/CD, documentation, and tests, appear consistent with the overall goal of this PR.