Build binary

[aswinashok44]

Summary

Build a distributable binary of Gemini CLI using Node SEA.

Details

The approach is to inject sea-launch.cjs and assets (bundled gemin.mjs, node-pty, macOS sandbox profiles and default policies) into the node binary, when the standalone binary is run, the assets are extracted to a temporary folder and gemini.mjs is run. This happens only on the first run of each version, second run onwards the previously extracted files are run, for security the files read from temporary location are compared with its hash from the bundled assets in the binary.

The build script signs the binary using the certificate made available via the CI environment variables, The signing is done inside out (pty.node first, then the injected node binary) so that the OS trusts the extracted dependency binaries.

The changes to integrations tests and non build binary feature related files are to improve the overall stability of integration-tests when run on the binary, especially for windows.

Related Issues

#3804

How to Validate

npm run build:binary

will build the binary for the platform you are running on, there is an included github workflow that builds and tests the binary for windows, linux and mac (both arm and x64) by running the integration tests and stores the binary as github action asset to download and test locally

TODO

• Update windows binary metadata (currently is looks like node.js binary, icon description and other fields need to be updated)
• Auto updater needs to be updated to update to latest version when running binary
• Maybe better error messages when binary start fails for better UX, pointing to docs/instructions to recover from a bad state

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[gemini-code-assist]

Summary of Changes

Hello @aswinashok44, 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 introduces the capability to build a standalone, distributable binary for the Gemini CLI. This significantly simplifies deployment and execution by packaging the application and its dependencies into a single executable. The changes encompass the build process, secure handling of embedded assets, and platform-specific signing, alongside improvements to hook execution and testing infrastructure to support this new distribution method.

Highlights

• Distributable Binary Build: Implemented a new build:binary script to create a single executable application (SEA) for the Gemini CLI using Node.js SEA, bundling all necessary assets and dependencies into a standalone binary.
• Secure Asset Management: The binary now injects gemini.mjs, node-pty, macOS sandbox profiles, and default policies. On first run, these assets are extracted to a temporary folder, and their integrity is verified against bundled hashes to ensure security.
• Binary Signing Process: The build script includes a robust signing process for the generated binary, first signing native modules like pty.node and then the main executable, ensuring trust by the operating system, especially on macOS and Windows.
• Improved Hook Execution Robustness: Enhanced the HookRunner to better handle process timeouts on Windows by using taskkill for more reliable termination and added PowerShell-specific exit code propagation for command hooks.
• Windows Compatibility Enhancements: Added PowerShell Compress-Archive as a fallback for the zip command in skill packaging and included specific shell settings for Windows in integration tests to improve reliability.
• Integration Test Updates: Modified integration tests to support running against the newly built binary and introduced a new test suite specifically for the sea-launch mechanism.

Changelog

• .gitignore
  • Added a new line at the end of the file.
• esbuild.config.js
  • Configured process.env.GEMINI_SANDBOX_IMAGE_DEFAULT using pkg.config?.sandboxImageUri for esbuild.
• integration-tests/hooks-agent-flow.test.ts
  • Escaped the messageCountFile path using JSON.stringify within the beforeModelScript to prevent quoting issues.
• integration-tests/hooks-system.test.ts
  • Added process.exit(0) to the hookScript to ensure proper termination.
  • Increased the timeout for command execution in hook tests from 5 seconds to 30 seconds.
• integration-tests/run_shell_command.test.ts
  • Added Measure-Object -Line as the line count command for PowerShell.
  • Conditionally disabled interactive shell for Windows in 'yolo mode' integration tests.
• package-lock.json
  • Updated dependency tree, including new entries for array-flatten, path-to-regexp, utils-merge.
  • Added nested cookie, debug, and statuses dependencies under express and finalhandler.
• package.json
  • Added a new build:binary script to trigger the binary build process.
  • Updated test and test:ci scripts to include test:sea-launch.
  • Added a new test:sea-launch script to run tests for the SEA launch mechanism.
• packages/cli/src/config/sandboxConfig.ts
  • Prioritized process.env.GEMINI_SANDBOX_IMAGE_DEFAULT when determining the sandbox image, falling back to packageJson?.config?.sandboxImageUri.
• packages/core/src/hooks/hookRunner.ts
  • Imported execSync from node:child_process.
  • Added logic to propagate PowerShell exit codes by appending an exit code check to commands.
  • Implemented platform-specific process killing for timeouts on Windows using taskkill.
• packages/core/src/skills/builtin/skill-creator/scripts/package_skill.cjs
  • Introduced a fallback to PowerShell's Compress-Archive for creating zip files on Windows if the zip command is not found.
• packages/test-utils/src/test-rig.ts
  • Modified getGeminiCommand to support running integration tests against a pre-built binary specified by INTEGRATION_TEST_GEMINI_BINARY_PATH.
• scripts/build_binary.js
  • Added a new script to orchestrate the entire binary build process, including cleaning, bundling, staging native modules, generating SEA configuration, injecting the blob, and signing the final executable.
• scripts/entitlements.plist
  • Added a new entitlements file for macOS binary signing, allowing JIT compilation, unsigned executable memory, disabled library validation, and environment variable access.
• sea/sea-launch.cjs
  • Added a new CommonJS module responsible for the Single Executable Application (SEA) launch process, including argument sanitization, asset extraction to a temporary directory, integrity verification, and launching the main gemini.mjs.
• sea/sea-launch.test.js
  • Added a new test file with unit tests for the sea-launch.cjs module, covering argument sanitization, safe name generation, integrity verification, and runtime preparation.

Ignored Files

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/test-build-binary.yml

Activity

• No human activity (comments, reviews) has been provided for this pull request yet.

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 the capability to build a distributable binary using Node.js SEA. The implementation is robust, considering cross-platform compatibility, security aspects like code signing and asset integrity verification, and CI stability. However, two high-severity vulnerabilities were identified: a command injection flaw in the skill packaging script on Windows, and a bypass of the binary's integrity check via an environment variable. Addressing these issues is crucial to significantly improve the security posture of the distributed binary and associated developer tools.

[aswinashok44]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces the ability to build a distributable binary of the Gemini CLI using Node.js Single Executable Applications (SEA). While the SEA launcher implementation incorporates security best practices, a high-severity TOCTOU vulnerability was identified in the runtime extraction logic, potentially allowing a local attacker to execute arbitrary code. Furthermore, a critical security vulnerability was found in the new build script concerning the potential leakage of a code-signing password in CI logs. Overall, the changes are comprehensive and enhance distributability, with other parts like build scripts and integration tests generally following security best practices.

[aswinashok44]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a significant new capability: building a distributable binary of the Gemini CLI using Node.js Single Executable Applications (SEA). The changes are comprehensive, touching build scripts, test infrastructure, and runtime code. The implementation is well-thought-out, incorporating important security features like asset integrity checking and platform-specific handling for code signing and native modules. The PR also includes several valuable stability improvements for tests, particularly on Windows. My review identified a critical issue in the hook timeout handling logic on Windows, where the application could hang indefinitely. Apart from this, the changes appear robust and well-executed.