firebase-tools: Instructions file for Gemini CLI

GEMINI.md

This file provides guidance to Gemini CLI or other coding agents when working with code in this repository. It focuses on key conventions and best practices. For a comprehensive guide on the development setup and contribution process, see CONTRIBUTING.md.

Essential Commands

# Build the project
npm run build

# Link the package - once this is run, you can manually test changes in your terminal
npm link

npm test                         # Full test suite with linting and compilation
npm run mocha:fast               # Quick unit tests only
npx mocha {testfile}             # Quick unit test for a specific file

# Linting and formatting
npm run lint                     # Check all code
npm run lint:changed-files       # Lint changed files only (much faster)
npm run format                   # Auto-fix formatting issues

Best Practices

Code Quality & Utilities

• Survey prior art & harmonize utilities: When implementing logic that is or could be shared across callers (e.g., retries, backoff, string parsing, path containment, domain transformations):
  • Reuse or extend existing utilities: Check imported modules, the immediate subsystem, and src/utils.ts first; reuse or extend existing helpers rather than writing bespoke inline logic.
  • Extract and unify shared helpers: When logic is duplicated across modules or warrants a new common utility, place it in the appropriate shared module and unify existing custom implementations immediately rather than leaving parallel implementations.
• Use the central logger (src/logger.ts); never use console.log() for user-facing output.
• Throw FirebaseError (src/error.ts) for expected, user-facing errors. If the error is due to a violation of a precondition (e.g. something that is null but should never be), specify a non-zero exit code ({ exit: 1 }). Error messages should clearly explain what failed and why; when actionable, provide concrete remediation guidance using documented CLI flags, commands, or configuration options (e.g., the expected format, a --force flag, or a discovery command like firebase <entity>:list—never undocumented or legacy internal fields).
• Extract magic numbers and static constants: Define static IDs, default timeouts, millisecond offsets, and repeated strings as top-level constants (UPPER_SNAKE_CASE) instead of inlining magic values inside functions. Mark static configuration arrays and lookup tables as readonly or as const.
• Write high-signal comments that explain why, not what: Reserve comments and JSDoc for non-obvious rationale (protocol quirks, OS/platform edge cases, intentional trade-offs). Do not narrate self-evident code, attach multi-paragraph docblocks to small helpers, or repeat the same architectural explanation across multiple functions and tests—redundant commentary drifts out of sync and obscures control flow.
• API calls must use apiv2.ts for authenticated requests.
• Reduce nesting as much as possible: Code should avoid unnecessarily deep nesting or long periods of nesting. Use early returns, continue, and break statements in functions and loops to handle edge cases early and keep main logic flat. Consider helper functions to encapsulate complex branching.