@dreki-gg/pi-firestore

Firestore debugging tools for pi — query collections, inspect documents, and map data relationships.

Setup

1. Install

pi install npm:@dreki-gg/pi-firestore

2. Create a service account

1. Go to the Firebase Console → Project Settings → Service Accounts
2. Click Generate new private key
3. Save the JSON file in your project (e.g. ./service-account.json)
4. Add it to .gitignore — never commit credentials

3. Configure your project

Create .pi/firestore.json in your project root.

Single-environment config is still supported:

{
  "projectId": "my-firebase-project",
  "serviceAccountKeyPath": "./service-account.json"
}

For multiple Firebase/Firestore environments, use environments and pick a default:

{
  "defaultEnvironment": "development",
  "environments": {
    "development": {
      "projectId": "my-firebase-project-dev",
      "serviceAccountKeyPath": "./service-account.dev.json",
      "defaultCollection": "users"
    },
    "staging": {
      "projectId": "my-firebase-project-staging",
      "serviceAccountKeyPath": "./service-account.staging.json"
    }
  },
  "maxSampleSize": 10,
  "scanPaths": ["src"],
  "scanExclude": ["node_modules", "dist", ".git"]
}

Field	Type	Description	Default
defaultEnvironment	string	Environment used when a tool call does not specify environment.	First configured environment
environments	Record<string, EnvironmentConfig>	Named Firebase/Firestore environments. Each environment has its own project and service account.	—
projectId	string	Required in single-environment config. GCP/Firebase project ID. Falls back to .firebaserc default project only in single-environment config.	—
serviceAccountKeyPath	string	Required in single-environment config. Path to service account JSON (relative to project root).	—
defaultCollection	string	Default collection for queries. In multi-environment config this belongs inside each environment.	(none)
maxSampleSize	number	Documents per collection to sample for relation analysis. Shared by all environments.	10
scanPaths	string[]	Directories to scan for codebase relation analysis. Shared by all environments.	["."]
scanExclude	string[]	Patterns to exclude from codebase scan. Shared by all environments.	["node_modules", "dist", ".git"]

Tip: If you have a .firebaserc file, the projectId is read from its projects.default automatically for the legacy single-environment config.

Usage

Natural language

Just ask pi to inspect your Firestore data:

> List all collections in Firestore
> Show me the users collection
> How many orders have status "pending"?
> Get the document at users/abc123
> What's the relationship between the users and orders collections?

Tools

firestore_list_collections

List top-level collections or subcollections of a document.

Parameter	Type	Description
environment	string?	Configured environment name (e.g. development, staging). Defaults to defaultEnvironment.
path	string?	Document path to list subcollections (e.g. users/abc123). Omit for top-level.

firestore_query

Query documents with filters, ordering, and pagination.

Parameter	Type	Description
environment	string?	Configured environment name. Defaults to defaultEnvironment.
collection	string	Required. Collection path (e.g. users or users/abc/orders)
where	array?	Filter conditions: [{field, op, value}]
orderBy	object?	Sort: {field, direction} (asc/desc)
limit	number?	Max results (1–100, default 25)
startAfter	string?	Document ID cursor for pagination

Supported operators: ==, !=, <, <=, >, >=, in, not-in, array-contains, array-contains-any

firestore_get_document

Get a single document by full path, including subcollection list.

Parameter	Type	Description
environment	string?	Configured environment name. Defaults to defaultEnvironment.
path	string	Required. Full document path (e.g. users/abc123)

firestore_count

Count documents in a collection with optional filters.

Parameter	Type	Description
environment	string?	Configured environment name. Defaults to defaultEnvironment.
collection	string	Required. Collection path
where	array?	Filter conditions (same format as query)

firestore_relation_map

Build a relation map between collections by scanning your codebase and analyzing document fields.

Parameter	Type	Description
environment	string?	Configured environment name. Defaults to defaultEnvironment.
collections	string[]?	Specific collections to analyze. Omit for all.

How it works:

1. Codebase scan: Searches your source files for Firestore collection/doc references (e.g. collection('users'), doc('orders/xyz'))
2. Field analysis: Samples documents from each collection and detects reference-like fields (e.g. userId → users, path-like values)
3. Confidence levels: 🟢 high (field name matches collection), 🟡 medium (co-referenced in code), 🔴 low (value-based match)

Command: /firestore

Check your configuration and connection status:

/firestore

Check a specific environment:

/firestore staging

Shows: config status, available environments, selected environment, project ID, service account status, Firestore client status, top-level collections.

Query Examples

# List all collections in the default environment
→ firestore_list_collections

# List all collections in staging
→ firestore_list_collections environment:"staging"

# Get orders for a specific user
→ firestore_query collection:"orders" where:[{field:"userId", op:"==", value:"abc123"}]

# Count active users
→ firestore_count collection:"users" where:[{field:"status", op:"==", value:"active"}]

# Get a specific document and its subcollections
→ firestore_get_document path:"users/abc123"

# Map all relationships
→ firestore_relation_map

# Map specific collections
→ firestore_relation_map collections:["users", "orders", "products"]

How It Works

1. The extension loads .pi/firestore.json and initializes Firebase Admin SDK for the default environment on session start
2. When a tool call specifies environment, the extension initializes and reuses a separate Firebase app for that environment
3. Results are formatted as markdown with truncation to fit LLM context windows
4. The relation map combines static code analysis with live data analysis for comprehensive relationship detection

License

MIT