@dasasian/firebase-structured-logger 0.1.0

package/skills/logs/SKILL.md

@@ -0,0 +1,185 @@
+# /logs — Logging Validation Skill
+
+Validate frontend and backend logging implementation for a given file.
+
+---
+
+## Phase 0 — Detect File Type
+
+Identify whether the target file is frontend or backend:
+
+**Frontend:** path starts with `src/`, imports from `firebase-structured-logger/client`, uses `logError/logWarn/logInfo/logDebug` or `bc.*`
+**Backend:** path starts with `functions/src/`, imports from `firebase-structured-logger/functions`, uses `initRequestLogger/getLogger/logError/logWarn/logInfo/logDebug`
+
+---
+
+## Phase 1 — Delegate to Explore Agent
+
+**Never analyze directly — always delegate to preserve main conversation context.**
+
+Build a task for the Explore agent:
+
+```
+Read these files:
+1. src/main.tsx (or app entry point) — find initLogger<AppLabels>() call, identify AppLabels type name
+2. The AppLabels type definition file — read all label field names
+3. [TARGET_FILE] — the file to analyze
+
+File type: [FRONTEND|BACKEND]
+
+Report back:
+- AppLabels type name and all its fields
+- For BACKEND: also note which AppLabels fields appear in request.data or function params
+- Full contents of the target file with line numbers
+```
+
+---
+
+## Phase 2 — Analyze
+
+Using the Explore agent's output, check the target file against the rules below.
+
+---
+
+### Frontend Rules
+
+**Imports**
+- Must use `logError/logWarn/logInfo/logDebug` from the project's logger utility (e.g. `src/utils/logger.ts`)
+- Must use `bc` from `firebase-structured-logger/client` for breadcrumbs
+- Never use `console.error()` directly — always use the logger
+
+**Error paths**
+- Every `catch` block must call `logError`
+- `logError` accepts `unknown` — never cast with `as Error`
+- Do not pass `errorType` explicitly unless overriding the auto-derived value from `error.name`
+
+**Breadcrumbs**
+
+Breadcrumbs reconstruct what the user was doing before an error — a session timeline, not just a wrapper around service calls. They belong primarily in components and screens, not service files.
+
+UX-layer breadcrumbs to check for (flag if missing):
+- Screen/route changes → `bc.nav('ScreenName')`
+- Modal open/close → `bc.action('open_item_modal', { itemId })`
+- Tab switches → `bc.action('switch_tab', { tab })`
+- Explicit user decisions → `bc.action('merge_chosen')`, `bc.action('discard_changes')`
+- Scan/camera events → `bc.action('barcode_scanned', { barcode })`
+
+Service-layer breadcrumbs (secondary — useful but not sufficient on their own):
+- Before a Firestore/API call → `bc.action('save_item', { itemId })`
+- On error → `bc.error('save_failed', { itemId })`
+
+**A component file with no UX-layer breadcrumbs is almost certainly missing them. A service file with only service-layer breadcrumbs may be fine.**
+
+API:
+- `bc.action(name: string, data?)` — user-initiated operations and decisions
+- `bc.state(name: string, data?)` — significant state changes
+- `bc.nav(screen: string)` — screen/route changes
+- `bc.error(type: string, data?)` — when an error occurs
+
+**Label completeness**
+- For each function, check which `AppLabels` fields are in scope as variables
+- Flag any that are not passed to the log call
+
+**Rate limiting**
+- Never log inside loops
+- Never log on every keystroke or render
+
+**PII**
+- No email, name, address in labels or context
+- `userId` is OK; full user objects are not
+
+---
+
+### Backend Rules
+
+**Imports**
+- Must import from `firebase-structured-logger/functions`
+- Use `logError/logWarn/logInfo/logDebug` — never `console.log/console.error` directly
+
+**`initRequestLogger` — mandatory at function entry**
+- Every `onCall` handler must call `initRequestLogger<AppLabels>(request, { functionName, labels })` as the first line
+- Auto-seeds `userId` and `functionName` — do not pass these manually in labels
+- Any `AppLabels` fields present in `request.data` or function params should be passed in `labels`
+- Flag missing `initRequestLogger` as a critical violation
+
+**Error paths**
+- Every `catch` block must call `logError`
+- `logError` accepts `unknown` — never cast with `as Error`
+- Do not pass `errorType` explicitly unless overriding the auto-derived value from `error.name`
+
+**Label completeness**
+- For each log call, check which `AppLabels` fields are in scope
+- Fields already seeded via `initRequestLogger` labels do not need repeating
+- Flag any in-scope fields not seeded at entry or passed on the log call
+
+**PII**
+- Same rules as frontend
+
+---
+
+## Output Format
+
+Report in three sections:
+
+### Violations
+```
+Line <N>: <description>
+```
+
+### Missing Logging
+```
+Line <N>: <what should be logged and why>
+```
+
+### Label Completeness
+```
+Function <name>: missing labels [<label1>, <label2>] — these entities are in scope
+```
+
+If no issues found in a section, write "None."
+
+---
+
+## Phase 3 — Fix
+
+When asked to fix violations found in Phase 2, use the FSL API Reference below. Do not read `firebase-structured-logger` source files — the reference is authoritative.
+
+---
+
+## FSL API Reference
+
+### Frontend
+Import from project logger utility (e.g. `src/utils/logger.ts`):
+```ts
+logError(raw: unknown, labels?: Partial<AppLabels>, context?: Record<string, unknown>, attachments?: Record<string, Blob | File | string>): Promise<void>
+logWarn(message: string, labels?: Partial<AppLabels>, context?: Record<string, unknown>, attachments?: Record<string, Blob | File | string>): Promise<void>
+logInfo(message: string, labels?: Partial<AppLabels>, context?: Record<string, unknown>, attachments?: Record<string, Blob | File | string>): Promise<void>
+logDebug(message: string, labels?: Partial<AppLabels>, context?: Record<string, unknown>, attachments?: Record<string, Blob | File | string>): Promise<void>
+```
+
+Import `bc` from `firebase-structured-logger/client`:
+```ts
+bc.action(name: string, data?: Record<string, unknown>): void  // before operations
+bc.state(name: string, data?: Record<string, unknown>): void   // on state changes
+bc.nav(screen: string): void                                   // on navigation
+bc.error(type: string, data?: Record<string, unknown>): void   // on errors
+```
+
+### Backend
+Import from `firebase-structured-logger/functions`:
+```ts
+// Call first in every onCall handler — auto-seeds userId and functionName
+initRequestLogger<AppLabels>(request, { functionName: 'myFunc', labels: { organizationId: request.data.organizationId } })
+
+logError(raw: unknown, labels?: Record<string, string | undefined>, context?: Record<string, unknown>, attachments?: Record<string, string | Buffer>): void
+logWarn(message: string, labels?: Record<string, string | undefined>, context?: Record<string, unknown>, attachments?: Record<string, string | Buffer>): void
+logInfo(message: string, labels?: Record<string, string | undefined>, context?: Record<string, unknown>, attachments?: Record<string, string | Buffer>): void
+logDebug(message: string, labels?: Record<string, string | undefined>, context?: Record<string, unknown>, attachments?: Record<string, string | Buffer>): void
+```
+
+### Key behaviours
+- `logError` auto-derives `errorType` from `error.name` — only pass explicitly to override (e.g. `{ errorType: 'DatabaseError' }`)
+- `logError` accepts `unknown` — never cast with `as Error`
+- `initRequestLogger` auto-seeds `userId` (from `request.auth.uid`) and `functionName` — do not pass these in labels
+- Every log entry includes `labels.logId` (ULID) — if `attachments` are passed, they are uploaded to GCS at `logAttachments/{logId}/{name}` fire-and-forget; upload failure never blocks the log entry
+- When catching an error, check if there are attachments in scope (images, file snapshots, captured data) that would help reproduce or diagnose it — if so, pass them via `attachments`

package/skills/query-logs/SKILL.md

@@ -0,0 +1,93 @@
+# /query-logs — Cloud Logging Query Skill
+
+Query structured logs written by firebase-structured-logger using the firebase-mcp-server.
+
+## Setup
+
+The `firebase_functions_logs` MCP tool reads from:
+- **Production**: Google Cloud Logging (default)
+- **Development**: Local JSONL file when `DEV_LOG_FILE` env var is set in the MCP server
+
+## Queryable Labels
+
+All entries written by firebase-structured-logger include these labels:
+
+| Label | Description |
+|-------|-------------|
+| `appId` | Application identifier (e.g. `acme`, `store`) |
+| `userId` | Firebase Auth UID |
+| `screen` | Current screen name |
+| `releaseId` | Git short hash or explicit release ID |
+| `platform` | `ios`, `android`, `macos`, `windows`, `web` |
+| `browser` | `chrome`, `firefox`, `safari`, `edge` |
+| `errorType` | Error class name (e.g. `TypeError`, `NetworkError`) |
+| `errorCategory` | `crash` for unhandled errors |
+| `functionName` | Cloud Function name (server-side logs only) |
+| `logId` | ULID — unique per log entry, used to locate attachments in GCS |
+| `hasAttachments` | `'true'` when attachments were uploaded alongside this entry |
+
+App-specific labels are defined in each app's `AppLabels` type.
+
+## Common Queries
+
+### All errors for a user
+```
+labels.userId="<uid>" severity=ERROR
+```
+
+### Errors on a specific screen
+```
+labels.screen="<screen>" severity=ERROR
+```
+
+### Unhandled crashes
+```
+labels.errorCategory="crash"
+```
+
+### Logs from a specific release
+```
+labels.releaseId="<hash>"
+```
+
+### Recent errors (last hour)
+```
+severity=ERROR timestamp>="<ISO8601>"
+```
+
+## Retrieving Attachments
+
+When a log entry has `labels.hasAttachments = "true"`, files were uploaded to GCS alongside it.
+
+**Step 1 — Find entries with attachments:**
+```
+labels.hasAttachments="true"
+```
+
+**Step 2 — List attachments for an entry:**
+
+Use `firebase_storage_ls` with the path `logAttachments/{logId}/` to see what files are present.
+
+**Step 3 — Download and analyze:**
+
+Use `firebase_storage_read` with path `logAttachments/{logId}/{filename}` — this downloads the file to `/tmp` and returns a `tempPath`. Then use the `Read` tool on `tempPath` to analyze the content.
+
+**Example flow:**
+```
+1. Query logs → find entry with logId "01KJBK2QBC5GJGMYZ5GT1Q5TQ6"
+2. firebase_storage_ls  path: "logAttachments/01KJBK2QBC5GJGMYZ5GT1Q5TQ6/"
+3. firebase_storage_read  path: "logAttachments/01KJBK2QBC5GJGMYZ5GT1Q5TQ6/photo.jpg"
+4. Read tool on tempPath → analyze image in context of the error
+```
+
+Only check GCS when `hasAttachments = "true"` — entries without it have no files.
+
+---
+
+## Development (Local JSONL)
+
+When running with Firebase Emulator, logs are written to the path configured in `initLogger({ devLogFile })`.
+
+Set `DEV_LOG_FILE=/path/to/logs.jsonl` in the MCP server environment to enable local log reading.
+
+Each JSONL line is a JSON object matching Cloud Logging structure for query compatibility.