Document ES module postinstall fix and add file extension guidelines

[Copilot]

Users reported npm install -g failing with ReferenceError: require is not defined in ES module scope when installing the package. The fix was already implemented (postinstall script uses .cjs extension), but lacked documentation to prevent regression.

Changes

Documentation

• Added file extension guidelines to scripts/README.md:
  • .mjs for ES modules (import/export)
  • .cjs for CommonJS (require/module.exports)
  • Avoid .js with "type": "module" to prevent ambiguity
• Clarified postinstall.cjs prevents the ES module error

Context

Package.json has "type": "module", making all .js files ES modules by default. The postinstall script requires CommonJS for require() statements, hence the .cjs extension.

// scripts/postinstall.cjs - Works correctly
const fs = require('fs');
const path = require('path');

// scripts/postinstall.js - Would fail with current package.json
// ReferenceError: require is not defined in ES module scope

All scripts now follow the convention: 5 .mjs files, 1 .cjs file, zero ambiguous .js files.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>npm install -g @clduab11/gemini-flow fails with "ReferenceError: require is not defined in ES module scope"</issue_title>
<issue_description>Hello,

I am unable to install @clduab11/gemini-flow globally using npm. The installation fails with a
ReferenceError.

Steps to Reproduce:

Run the following command in the terminal:

1 npm install -g @clduab11/gemini-flow

Expected Behavior:

The package should install successfully without any errors.

Actual Behavior:

The installation fails with the following error:

1 npm error code 1
2 npm error path C:\Users\mebel\AppData\Roaming\npm\node_modules\@clduab11\gemini-flow
3 npm error command failed
4 npm error command C:\WINDOWS\system32\cmd.exe /d /s /c node scripts/postinstall.js || true
5 npm error
  file:///C:/Users/mebel/AppData/Roaming/npm/node_modules/@clduab11/gemini-flow/scripts/postinstal
  l.js:8
6 npm error const { execSync } = require('child_process');
7 npm error                      ^
8 npm error
9 npm error ReferenceError: require is not defined in ES module scope, you can use import instead

10 npm error This file is being treated as an ES module because it has a '.js' file extension and
'C:\Users\mebel\AppData\Roaming\npm\node_modules@clduab11\gemini-flow\package.json' contains
"type": "module". To treat it as a CommonJS script, rename it to use the '.cjs' file extension.
11 npm error at
file:///C:/Users/mebel/AppData/Roaming/npm/node_modules/@clduab11/gemini-flow/scripts/postinstal
l.js:8:22
12 npm error at ModuleJob.run (node:internal/modules/esm/module_job:370:25)
13 npm error at async onImport.tracePromise.proto (node:internal/modules/esm/loader:665:26)
14 npm error at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:99:5)
15 npm error
16 npm error Node.js v24.4.0

Environment:

• OS: Windows (win32)
• Node.js version: v24.4.0
• npm version: 11.6.1

This seems to be a bug in the postinstall.js script which is using CommonJS require in an ES module
context.

Thank you for your help.</issue_description>

<agent_instructions>The user is receiving a ReferenceError when running npm install -g for @clduab11/gemini-flow: 'require is not defined in ES module scope'. This happens in scripts/postinstall.js, because package.json sets "type": "module", enforcing ES module rules, but the postinstall file uses CommonJS-style require. The task is to refactor this script for ES module compatibility (e.g., using import syntax or renaming as .cjs). Environment: Node.js v24+, npm 11.6+, Windows 10.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes npm install -g @clduab11/gemini-flow fails with "ReferenceError: require is not defined in ES module scope" #64

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull Request Overview

This PR documents the ES module/CommonJS handling in the project to prevent regressions. The postinstall script was already using the correct .cjs extension to avoid ES module scope errors, but this wasn't documented, creating risk of future mistakes.

Key changes:

• Added file extension guidelines explaining when to use .mjs, .cjs, and why to avoid .js
• Documented that postinstall.cjs prevents the "require is not defined" error in ES module scope

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[clduab11]

@gemini-code-assist, review and analyze all changes including resolved comments in this PR.

[gemini-code-assist]

Code Review

This pull request introduces a new extension management system for the Gemini CLI, which is a significant and valuable addition. It also includes documentation updates regarding ES module conventions, which helps prevent future regressions. My review focuses on the new extension manager feature. I've identified several critical security vulnerabilities, including potential for command injection and path traversal, which must be addressed. I've also noted some other areas for improvement regarding usability and error handling. Please see my detailed comments for suggestions on how to resolve these issues.