Fix npm package manifest to resolve installation failures

[Copilot]

Users reported installation failures for both npm install -g @clduab11/gemini-flow and gemini extensions install https://github.com/clduab11/gemini-flow. The errors indicated missing configuration files and ES module issues, though the actual code was correct (using .cjs extension properly).

Changes

package.json

• Added explicit files field listing all publishable directories and files
• Ensures critical files (gemini-extension.json, postinstall.cjs, extension-loader.js) are always included in npm package
• Prevents npm version inconsistencies in package resolution

INSTALLATION_TROUBLESHOOTING.md (new)

• Documents three installation methods: npm global, Gemini CLI extension, local development
• Provides solutions for common errors (ES module conflicts, permission issues, cache problems)
• Includes environment requirements and verification commands

README.md

• Added all three installation methods with clear examples
• Linked to troubleshooting guide

Context

The reported errors referenced postinstall.js but the codebase correctly uses postinstall.cjs. The issues likely stemmed from npm cache or environment-specific behavior. Without an explicit files field, npm's default inclusion logic can vary across versions, potentially omitting critical files like gemini-extension.json from the published package.

Verification

# Package now includes all critical files
tar -tzf clduab11-gemini-flow-*.tgz | grep -E "(gemini-extension|postinstall|extension-loader)"
# package/gemini-extension.json
# package/scripts/postinstall.cjs
# package/extensions/gemini-cli/extension-loader.js

# Extension loader resolves manifest correctly
node -e "import('./extensions/gemini-cli/extension-loader.js').then(m => {
  const ext = new m.GeminiFlowExtension();
  console.log(ext.loadManifest()); // Works in global install location
})"

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Bug]: gemini extensions install and npm install -g fail for gemini-flow</issue_title>
<issue_description>### Version

0.11.3

Environment

Node.js

What happened?

When attempting to install gemini-flow using either gemini extensions install https://github.com/clduab11/gemini-flow or npm install -g @clduab11/gemini-flow,
the installation fails.

Steps to Reproduce:

1. Using gemini extensions install:
   1 gemini extensions install https://github.com/clduab11/gemini-flow

2. Using npm install -g:
   1 npm install -g @clduab11/gemini-flow

Expected Behavior:

Actual Behavior:

1. gemini extensions install fails with the following error:
   1 Configuration file not found at C:\Users\dasbl\AppData\Local\Temp\gemini-extension<random_string>\gemini-extension.json
   This is despite the fact that https://raw.githubusercontent.com/clduab11/gemini-flow/main/gemini-extension.json is accessible.

2. npm install -g fails with the following error:

1 ReferenceError: require is not defined in ES module scope, you can use import instead
2 This file is being treated as an ES module because it has a '.js' file extension and
'C:\Users\dasbl\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.
3 at file:///C:/Users/dasbl/AppData/Roaming/npm/node_modules/@clduab11/gemini-flow/scripts/postinstall.js:8:22

Expected behavior

The gemini-flow extension should install successfully.

Steps to reproduce

1. Using gemini extensions install:
   gemini extensions install https://github.com/clduab11/gemini-flow

2. Using npm install -g:
   npm install -g @clduab11/gemini-flow

Relevant log output

1. `gemini extensions install` fails with the following error:
Configuration file not found at C:\Users\dasbl\AppData\Local\Temp\gemini-extension<random_string>\gemini-extension.json
      This is despite the fact that https://raw.githubusercontent.com/clduab11/gemini-flow/main/gemini-extension.json is accessible.

   2. `npm install -g` fails with the following error:

 ReferenceError: require is not defined in ES module scope, you can use import instead
This file is being treated as an ES module because it has a '.js' file extension and
     'C:\Users\dasbl\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.
at file:///C:/Users/dasbl/AppData/Roaming/npm/node_modules/@clduab11/gemini-flow/scripts/postinstall.js:8:22

Additional context

No response</issue_description>

<agent_instructions>@github-copilot, please analyze and auto-fix this issue.

Issue Title: gemini extensions install and npm install -g fail for gemini-flow
Version: 0.11.3
Environment: Node.js

Problem summary:
Both gemini extensions install https://github.com/clduab11/gemini-flow and npm install -g @clduab11/gemini-flow fail to install successfully.

Error details:

• gemini extensions install fails with:
  Configuration file not found at C:\Users\dasbl\AppData\Local\Temp\gemini-extension\gemini-extension.json
  (but https://raw.githubusercontent.com/clduab11/gemini-flow/main/gemini-extension.json is accessible)
• npm install -g fails with:
  ReferenceError: require is not defined in ES module scope, you can use import instead
  (file is treated as ES module due to .js extension and "type": "module" in package.json; suggest renaming to .cjs or refactoring imports)

  at file:///C:/Users/dasbl/AppData/Roaming/npm/node_modules/@clduab11/gemini-flow/scripts/postinstall.js:8:22
  

Expected behavior:
gemini-flow extension and npm package should install successfully.

Steps to Reproduce:

1. gemini extensions install https://github.com/clduab11/gemini-flow
2. npm install -g @clduab11/gemini-flow

Relevant log output:
See error messages above.

Action requested:
Auto-analyze/code fix for:

• file/module type incompatibilities
• config file resolution
• install success for both methods

1</agent_instructions>

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

• Fixes [Bug]: gemini extensions install and npm install -g fail for gemini-flow #96

---

💡 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.

[ryan-gray-db]

Additional Finding: Missing CLI Dependencies

While testing v1.3.3 after a fresh npm install -g @clduab11/gemini-flow, I encountered another issue not covered by this PR.

Problem

After installation, running gemini-flow --help fails with:

Failed to load fallback CLI: Cannot find package 'commander' imported from /path/to/gemini-flow/dist/cli/simple-index.js

Root Cause

The CLI requires commander, chalk, and ora packages, but these are not listed in package.json dependencies. They must be manually installed:

cd ~/.n/lib/node_modules/@clduab11/gemini-flow && npm install commander chalk ora

After this, gemini-flow --help works correctly.

Suggested Fix

Add these to dependencies in package.json:

"dependencies": {
  "commander": "^12.0.0",
  "chalk": "^5.3.0",
  "ora": "^8.0.0",
  // ... existing deps
}

This is separate from the file inclusion fixes in this PR but affects the same installation flow.