fix(core): resolve DEP0040 punycode deprecation via patch-package

[ATHARVA262005]

Summary

This PR resolves the [DEP0040] DeprecationWarning caused by the punycode module in Node.js 21+. It redirects the whatwg-url dependency to use the userland punycode package via a surgical patch, ensuring compatibility without breaking IDN logic.

Details

The fix involves:

• Adding punycode (userland) as a dependency.
• Applying a patch to whatwg-url using patch-package to replace the built-in require("punycode") with require("punycode/") (trailing slash ensures userland package usage).
• This eliminates the deprecation warning on newer Node versions (21-25) while maintaining functionality.

Related Issues

Closes #12289

How to Validate

1. Trace Deprecation Test: Run node --trace-deprecation to confirm the warning often seen with whatwg-url is gone.
2. Verification: valid on Node v22.12.0 (Windows).
3. Upstream Tests: Pre-existing upstream test failures were audited and confirmed to be unrelated to this change.

Pre-Merge Checklist

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

[gemini-code-assist]

Summary of Changes

Hello @ATHARVA262005, 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 a solution to a Node.js deprecation warning encountered in newer Node.js versions by strategically patching a dependency. It ensures the continued functionality of URL parsing while eliminating the warning, thereby improving compatibility and maintaining the integrity of internationalized domain name (IDN) logic.

Highlights

• Deprecation Warning Resolution: Addresses the DEP0040 DeprecationWarning for the punycode module in Node.js 21+ environments, ensuring compatibility with newer Node.js versions.
• Userland punycode Adoption: Ensures the whatwg-url dependency uses the userland punycode package instead of the deprecated built-in Node.js module.
• patch-package Integration: Implements the necessary dependency redirection via a surgical patch applied using patch-package, which has been added as a new development dependency.
• Automated Patch Application: A postinstall script has been added to package.json to automatically apply the whatwg-url patch during package installation.

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 PR addresses a deprecation warning in Node.js 21+ caused by the punycode module within the whatwg-url dependency. It introduces patch-package to apply a patch that redirects the dependency to use the userland punycode package. The changes include adding punycode and patch-package as dependencies, modifying the package-lock.json and package.json files, and adding a patch file. The review focuses on the addition of patch-package and the correctness of the patch application.

[gemini-code-assist]

Adding patch-package as a postinstall script is a good way to ensure that patches are applied after dependencies are installed. However, if the intention is to only apply this patch in development environments, it might be better to conditionally apply it based on the NODE_ENV environment variable to avoid unnecessary overhead in production environments.

If it should always be applied, then this is fine.

[ATHARVA262005]

The postinstall script must run in all environments (including production) because whatwg-url is a runtime dependency used by @google-cloud/storage. If we skip patching in production, the [DEP0040] warning will persist in our production logs, which is exactly what we are trying to fix.

[gemini-code-assist]

The patch changes the require statement to point to the userland punycode package. While this resolves the deprecation warning, it's crucial to ensure that the userland package provides the exact same API and behavior as the deprecated built-in module to avoid unexpected issues. It would be helpful to add a comment in the patch file itself explaining why the trailing slash is necessary and that the userland package is API-compatible.

-const punycode = require("punycode");
+const punycode = require("punycode/"); // Trailing slash ensures userland package usage

[ATHARVA262005]

I've added the comment as requested. Regarding compatibility: the punycode userland package (v2.3.1) is the official polyfill for the deprecated Node.js core module and maintains strict API compatibility for the methods used here (ucs2.decode and toASCII). The trailing slash is the standard Node.js mechanism to force loading from node_modules."

[gemini-cli]

Hi there! Thank you for your contribution to Gemini CLI. We really appreciate the time and effort you've put into this pull request.

To keep our backlog manageable and ensure we're focusing on current priorities, we are closing pull requests that haven't seen maintainer activity for 30 days. Currently, the team is prioritizing work associated with 🔒 maintainer only or help wanted issues.

If you believe this change is still critical, please feel free to comment with updated details. Otherwise, we encourage contributors to focus on open issues labeled as help wanted. Thank you for your understanding!

[ATHARVA262005]

Updated Details for Reopening: This change is critical as it resolves the primary source of [DEP0040] warnings impacting all users on Node.js 21-25.

I have just finished:

Rebasing the branch onto the latest nightly to ensure zero conflicts with the 5 most recent commits.

Verification on Node v22.12.0 confirming the warning is eliminated via the whatwg-url patch.

Guideline Audit: Verified strict compliance with CONTRIBUTING.md.

@Adib234 – As I was assigned to this yesterday, I’ve completed the final "surgical" fix. Could you please reopen this PR for final review?