{"_id":"@dreki-gg/pi-firestore","name":"@dreki-gg/pi-firestore","dist-tags":{"latest":"0.3.1"},"versions":{"0.3.1":{"name":"@dreki-gg/pi-firestore","version":"0.3.1","description":"Firestore debugging tools for pi — query collections, inspect documents, and map data relationships","keywords":["pi-package","pi","firestore","firebase","debugging"],"author":{"name":"Juan Albarran","email":"jalbarrandev@gmail.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/dreki-gg/pi-extensions.git","directory":"packages/firestore"},"type":"module","scripts":{"typecheck":"tsc --noEmit","test":"bun test","lint":"oxlint extensions test","format":"oxfmt --write extensions test","format:check":"oxfmt --check extensions test"},"pi":{"extensions":["./extensions/firestore"]},"dependencies":{"effect":"^3.21.2","firebase-admin":"^13.4.0"},"devDependencies":{"@types/node":"24","bun-types":"^1.3.14","oxfmt":"^0.43.0","oxlint":"^1.58.0","typescript":"^6.0.0"},"peerDependencies":{"@earendil-works/pi-coding-agent":"*","typebox":"*"},"overrides":{"uuid":"^11.1.0","node-domexception":"npm:@user-agent/domexception@^0.2.7"},"peerDependenciesMeta":{"@earendil-works/pi-coding-agent":{"optional":true},"typebox":{"optional":true}},"gitHead":"c48ed25bbb6c9b5441dd1fa2184e5b59313f02f0","_id":"@dreki-gg/pi-firestore@0.3.1","bugs":{"url":"https://github.com/dreki-gg/pi-extensions/issues"},"homepage":"https://github.com/dreki-gg/pi-extensions#readme","_nodeVersion":"24.12.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-ahe0s4gWWHm/T+pHvmvyATT9+7hVahdaBvvhS0d0Ji15jmWYzIj5u7fdj4VBn2gMjjTBjRmWlVFzujmG+YvxIQ==","shasum":"4682162d662b1331a1dd5e214c7c2af203f59ad9","tarball":"https://registry.npmjs.org/@dreki-gg/pi-firestore/-/pi-firestore-0.3.1.tgz","fileCount":20,"unpackedSize":80400,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBX+ldL3r9NGNLOo8W1eL965VaQSsrunDO+GHlFQY6AoAiBmMbgYlPgSILYGufZ1AGUMWFZX9Mkx6TDhj2lzkqviaA=="}]},"_npmUser":{"name":"jalbarrang","email":"jalbarrandev@gmail.com"},"directories":{},"maintainers":[{"name":"jalbarrang","email":"jalbarrandev@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-firestore_0.3.1_1780120966650_0.14566739411468865"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-30T06:02:46.492Z","0.3.1":"2026-05-30T06:02:46.826Z","modified":"2026-05-30T06:02:47.018Z"},"maintainers":[{"name":"jalbarrang","email":"jalbarrandev@gmail.com"}],"description":"Firestore debugging tools for pi — query collections, inspect documents, and map data relationships","homepage":"https://github.com/dreki-gg/pi-extensions#readme","keywords":["pi-package","pi","firestore","firebase","debugging"],"repository":{"type":"git","url":"git+https://github.com/dreki-gg/pi-extensions.git","directory":"packages/firestore"},"author":{"name":"Juan Albarran","email":"jalbarrandev@gmail.com"},"bugs":{"url":"https://github.com/dreki-gg/pi-extensions/issues"},"license":"MIT","readme":"# @dreki-gg/pi-firestore\n\nFirestore debugging tools for [pi](https://github.com/earendil-works/pi) — query collections, inspect documents, and map data relationships.\n\n## Setup\n\n### 1. Install\n\n```bash\npi install npm:@dreki-gg/pi-firestore\n```\n\n### 2. Create a service account\n\n1. Go to the [Firebase Console](https://console.firebase.google.com/) → Project Settings → Service Accounts\n2. Click **Generate new private key**\n3. Save the JSON file in your project (e.g. `./service-account.json`)\n4. **Add it to `.gitignore`** — never commit credentials\n\n### 3. Configure your project\n\nCreate `.pi/firestore.json` in your project root.\n\nSingle-environment config is still supported:\n\n```json\n{\n  \"projectId\": \"my-firebase-project\",\n  \"serviceAccountKeyPath\": \"./service-account.json\"\n}\n```\n\nFor multiple Firebase/Firestore environments, use `environments` and pick a default:\n\n```json\n{\n  \"defaultEnvironment\": \"development\",\n  \"environments\": {\n    \"development\": {\n      \"projectId\": \"my-firebase-project-dev\",\n      \"serviceAccountKeyPath\": \"./service-account.dev.json\",\n      \"defaultCollection\": \"users\"\n    },\n    \"staging\": {\n      \"projectId\": \"my-firebase-project-staging\",\n      \"serviceAccountKeyPath\": \"./service-account.staging.json\"\n    }\n  },\n  \"maxSampleSize\": 10,\n  \"scanPaths\": [\"src\"],\n  \"scanExclude\": [\"node_modules\", \"dist\", \".git\"]\n}\n```\n\n| Field | Type | Description | Default |\n|-------|------|-------------|---------|\n| `defaultEnvironment` | `string` | Environment used when a tool call does not specify `environment`. | First configured environment |\n| `environments` | `Record<string, EnvironmentConfig>` | Named Firebase/Firestore environments. Each environment has its own project and service account. | — |\n| `projectId` | `string` | **Required in single-environment config.** GCP/Firebase project ID. Falls back to `.firebaserc` default project only in single-environment config. | — |\n| `serviceAccountKeyPath` | `string` | **Required in single-environment config.** Path to service account JSON (relative to project root). | — |\n| `defaultCollection` | `string` | Default collection for queries. In multi-environment config this belongs inside each environment. | _(none)_ |\n| `maxSampleSize` | `number` | Documents per collection to sample for relation analysis. Shared by all environments. | `10` |\n| `scanPaths` | `string[]` | Directories to scan for codebase relation analysis. Shared by all environments. | `[\".\"]` |\n| `scanExclude` | `string[]` | Patterns to exclude from codebase scan. Shared by all environments. | `[\"node_modules\", \"dist\", \".git\"]` |\n\n> **Tip:** If you have a `.firebaserc` file, the `projectId` is read from its `projects.default` automatically for the legacy single-environment config.\n\n## Usage\n\n### Natural language\n\nJust ask pi to inspect your Firestore data:\n\n```\n> List all collections in Firestore\n> Show me the users collection\n> How many orders have status \"pending\"?\n> Get the document at users/abc123\n> What's the relationship between the users and orders collections?\n```\n\n### Tools\n\n#### `firestore_list_collections`\n\nList top-level collections or subcollections of a document.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `environment` | `string?` | Configured environment name (e.g. `development`, `staging`). Defaults to `defaultEnvironment`. |\n| `path` | `string?` | Document path to list subcollections (e.g. `users/abc123`). Omit for top-level. |\n\n#### `firestore_query`\n\nQuery documents with filters, ordering, and pagination.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `environment` | `string?` | Configured environment name. Defaults to `defaultEnvironment`. |\n| `collection` | `string` | **Required.** Collection path (e.g. `users` or `users/abc/orders`) |\n| `where` | `array?` | Filter conditions: `[{field, op, value}]` |\n| `orderBy` | `object?` | Sort: `{field, direction}` (asc/desc) |\n| `limit` | `number?` | Max results (1–100, default 25) |\n| `startAfter` | `string?` | Document ID cursor for pagination |\n\n**Supported operators:** `==`, `!=`, `<`, `<=`, `>`, `>=`, `in`, `not-in`, `array-contains`, `array-contains-any`\n\n#### `firestore_get_document`\n\nGet a single document by full path, including subcollection list.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `environment` | `string?` | Configured environment name. Defaults to `defaultEnvironment`. |\n| `path` | `string` | **Required.** Full document path (e.g. `users/abc123`) |\n\n#### `firestore_count`\n\nCount documents in a collection with optional filters.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `environment` | `string?` | Configured environment name. Defaults to `defaultEnvironment`. |\n| `collection` | `string` | **Required.** Collection path |\n| `where` | `array?` | Filter conditions (same format as query) |\n\n#### `firestore_relation_map`\n\nBuild a relation map between collections by scanning your codebase and analyzing document fields.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `environment` | `string?` | Configured environment name. Defaults to `defaultEnvironment`. |\n| `collections` | `string[]?` | Specific collections to analyze. Omit for all. |\n\n**How it works:**\n1. **Codebase scan:** Searches your source files for Firestore collection/doc references (e.g. `collection('users')`, `doc('orders/xyz')`)\n2. **Field analysis:** Samples documents from each collection and detects reference-like fields (e.g. `userId` → `users`, path-like values)\n3. **Confidence levels:** 🟢 high (field name matches collection), 🟡 medium (co-referenced in code), 🔴 low (value-based match)\n\n### Command: `/firestore`\n\nCheck your configuration and connection status:\n\n```\n/firestore\n```\n\nCheck a specific environment:\n\n```\n/firestore staging\n```\n\nShows: config status, available environments, selected environment, project ID, service account status, Firestore client status, top-level collections.\n\n## Query Examples\n\n```\n# List all collections in the default environment\n→ firestore_list_collections\n\n# List all collections in staging\n→ firestore_list_collections environment:\"staging\"\n\n# Get orders for a specific user\n→ firestore_query collection:\"orders\" where:[{field:\"userId\", op:\"==\", value:\"abc123\"}]\n\n# Count active users\n→ firestore_count collection:\"users\" where:[{field:\"status\", op:\"==\", value:\"active\"}]\n\n# Get a specific document and its subcollections\n→ firestore_get_document path:\"users/abc123\"\n\n# Map all relationships\n→ firestore_relation_map\n\n# Map specific collections\n→ firestore_relation_map collections:[\"users\", \"orders\", \"products\"]\n```\n\n## How It Works\n\n1. The extension loads `.pi/firestore.json` and initializes Firebase Admin SDK for the default environment on session start\n2. When a tool call specifies `environment`, the extension initializes and reuses a separate Firebase app for that environment\n3. Results are formatted as markdown with truncation to fit LLM context windows\n4. The relation map combines static code analysis with live data analysis for comprehensive relationship detection\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-6d41bdf1991337b97c1be11b2c965b8a"}