dreamcontext 0.5.0

package/skill-packs/engineering/firebase-cloud-functions/references/gen_comparison.md

@@ -0,0 +1,45 @@
+# 1st Gen vs 2nd Gen Comparison
+
+**2nd gen is mandatory for all new functions.** 1st gen is legacy only.
+
+## Comparison Table
+
+| Feature | 1st Gen | 2nd Gen (Cloud Run) |
+|---|---|---|
+| Infrastructure | Legacy Firebase Runtime | Cloud Run + Eventarc (90+ event sources) |
+| HTTP Timeout | 9 minutes | **60 minutes** |
+| Event Timeout | 540s | 540s (scheduled/task queue: 1800s) |
+| Max Instance Size | 8 GiB RAM / 2 vCPU | **32 GiB RAM / 4 vCPU** (16 GiB recommended) |
+| Concurrency per instance | 1 request | **1–1000** (default 80) |
+| Min Instances | Available | Available + **CPU scaling** |
+| Service Account | App Engine default | Compute Engine default (more secure) |
+| Trigger Support | Limited Firebase events | **All Eventarc** + Pub/Sub + custom |
+| Image Registry | Container/Artifact Registry | **Artifact Registry only** |
+| Traffic Splitting | No | Yes (revision rollback) |
+| Retry Window | 7 days | **24 hours** |
+
+## Supported Runtimes (March 2026)
+
+- **Node.js**: 22 (recommended), 20, 18 (deprecated)
+- **Python**: 3.11+ (`firebase-functions` Python SDK)
+- **TypeScript**: Native (ESM/CommonJS)
+
+## Import Pattern
+
+```js
+// 2nd gen (CORRECT)
+const { onRequest, onCall } = require("firebase-functions/v2/https");
+const { onDocumentCreated, onDocumentUpdated } = require("firebase-functions/v2/firestore");
+
+// 1st gen (LEGACY — do not use in new code)
+const functions = require("firebase-functions");
+```
+
+## Migration Rule
+
+If agent encounters 1st gen code:
+1. Replace `functions.https.onRequest` → `onRequest` from `firebase-functions/v2/https`
+2. Replace `functions.firestore.document().onUpdate` → `onDocumentUpdated` from `firebase-functions/v2/firestore`
+3. Replace `.runWith({ failurePolicy: true })` → `{ retry: true }` in options
+4. Replace `functions.config()` → `defineSecret()` / `defineString()`
+5. Add `concurrency` and `minInstances` to options

package/skill-packs/engineering/firebase-cloud-functions/references/idempotency.md

@@ -0,0 +1,145 @@
+# Idempotency & Infinite Loop Prevention
+
+**THE most critical reference in this skill.** Firestore trigger loops and non-idempotent retries cause billing explosions ($1000s+), quota exhaustion, and data corruption.
+
+## 1. At-Least-Once Delivery
+
+Firebase event triggers (Firestore, Pub/Sub, Storage, etc.) do NOT guarantee exactly-once delivery. The same event CAN fire multiple times (retry, duplicate delivery).
+
+**Idempotency = same input → same output, no extra side effects on repeat calls.**
+
+If a function is NOT idempotent + retry is enabled → duplicated writes, double charges, duplicate emails, infinite loops.
+
+## 2. Infinite Loop — The #1 Danger
+
+**Root cause**: Firestore `onUpdate`/`onWrite` trigger writes to the SAME document → triggers itself → infinite loop.
+
+### NEVER DO THIS
+```js
+// DANGEROUS — infinite loop!
+exports.badFunction = onDocumentUpdated("users/{userId}", (event) => {
+  return event.data.after.ref.update({ lastUpdated: new Date() });
+  // ↑ This update triggers onDocumentUpdated again → loop forever
+});
+```
+
+Real-world cost: A developer in 2024 got an **$8,000 bill** from a timestamp update loop.
+
+## 3. Three-Layer Guard System (ALL REQUIRED for retry-enabled functions)
+
+### Layer 1: Event Age Check (drops stale retries)
+```js
+const eventAgeMs = Date.now() - Date.parse(event.time);
+if (eventAgeMs > 10000) { // 10 seconds
+  console.log("Stale event dropped");
+  return;
+}
+```
+
+### Layer 2: Before/After Comparison (prevents self-trigger loops)
+```js
+exports.safeCounter = onDocumentUpdated("users/{userId}", (event) => {
+  const before = event.data.before.data();
+  const after = event.data.after.data();
+
+  // Only run if the field we care about actually changed
+  if (before.name === after.name) {
+    console.log("No relevant change → loop prevented");
+    return;
+  }
+
+  return event.data.after.ref.set({
+    name_change_count: (after.name_change_count || 0) + 1
+  }, { merge: true });
+});
+```
+
+### Layer 3: Idempotency Key + Transaction (guarantees exactly-once processing)
+```js
+exports.processOrder = onDocumentCreated(
+  { document: "orders/{orderId}", retry: true },
+  async (event) => {
+    const eventId = event.id;
+    const processedRef = db.collection("processedEvents").doc(eventId);
+
+    await db.runTransaction(async (t) => {
+      const snap = await t.get(processedRef);
+      if (snap.exists) return; // Already processed → idempotent skip
+
+      // Do the work
+      await event.data.ref.update({ status: "processed" });
+      t.set(processedRef, { done: true, processedAt: FieldValue.serverTimestamp() });
+    });
+  }
+);
+```
+
+### Python Example (same guards)
+```python
+@on_document_updated(document="users/{userId}")
+def safe_counter(event):
+    before = event.data.before.to_dict()
+    after = event.data.after.to_dict()
+
+    if before.get("name") == after.get("name"):
+        return  # No change → prevent loop
+
+    event.data.after.reference.update({
+        "name_change_count": after.get("name_change_count", 0) + 1
+    })
+```
+
+## 4. Alternative Loop Prevention Patterns
+
+### Processed Flag / Timestamp
+```js
+const after = event.data.after.data();
+const before = event.data.before.data();
+if (after.processedAt && after.processedAt > before.processedAt) return;
+await docRef.update({ processedAt: FieldValue.serverTimestamp() });
+```
+
+### Separate Collection
+Write trigger output to a different collection instead of the same document:
+- Trigger on `users/{userId}` → write to `userEvents/{eventId}`
+- Or use subcollection: `users/{userId}/processed/{eventId}`
+
+## 5. External API Idempotency
+
+For external services (Stripe, SendGrid, etc.), use `event.id` as the idempotency key:
+
+```js
+const stripe = require("stripe")(stripeKey.value());
+await stripe.charges.create({
+  amount: 1000,
+  currency: "usd",
+  source: token,
+}, {
+  idempotencyKey: event.id  // Stripe deduplicates based on this
+});
+```
+
+## 6. Retry Configuration
+
+### 2nd Gen (recommended)
+```js
+{ retry: true }  // 24-hour retry window
+```
+
+### 1st Gen (legacy)
+```js
+.runWith({ failurePolicy: true })  // 7-day retry window
+```
+
+**RULE**: NEVER enable retry without all three guard layers. Retry + loop = 24 hours (or 7 days in 1st gen) of continuous invocations.
+
+## 7. Decision Matrix
+
+| Scenario | Required Guards |
+|---|---|
+| Firestore `onUpdate`/`onWrite` + no retry | Layer 2 (before/after) minimum |
+| Firestore `onUpdate`/`onWrite` + retry | ALL THREE layers |
+| Firestore `onCreate` + retry | Layer 1 (age) + Layer 3 (idempotency key) |
+| HTTP / Callable | Standard HTTP idempotency (request dedup) |
+| Pub/Sub + retry | Layer 1 + Layer 3 |
+| External API call | Layer 3 + API-level idempotency key |

package/skill-packs/engineering/firebase-cloud-functions/references/local_testing.md

@@ -0,0 +1,218 @@
+# Cloud Functions Local Testing – Emulator Suite Deep Dive
+
+Test everything locally before deploying. Zero risk, zero cost.
+
+## 1. Setup (One-time)
+
+```bash
+npm install -g firebase-tools@latest
+firebase login
+firebase init emulators
+```
+
+Requirements:
+- `firebase-admin` >= 8.0.0
+- `firebase-functions` >= 3.0.0 (v2 syntax for 2nd gen)
+- Java 11+ (Firestore emulator requires JVM)
+
+### firebase.json emulator config
+```json
+{
+  "emulators": {
+    "functions": { "port": 5001 },
+    "firestore": { "port": 8080 },
+    "auth": { "port": 9099 },
+    "storage": { "port": 9199 },
+    "pubsub": { "port": 8085 },
+    "eventarc": { "port": 9299 },
+    "ui": { "port": 4000 }
+  }
+}
+```
+
+## 2. Running the Emulator
+
+```bash
+# All emulators (recommended)
+firebase emulators:start
+
+# Specific emulators
+firebase emulators:start --only functions,firestore,auth
+
+# Run tests then auto-shutdown
+firebase emulators:exec "npm test" --only functions,firestore
+
+# Debug mode (VS Code / Chrome DevTools breakpoints)
+firebase emulators:start --inspect-functions
+# → Open chrome://inspect to attach debugger
+```
+
+### Demo Project (safest — never touches production)
+```bash
+firebase use --add demo-myproject   # demo- prefix is mandatory
+```
+
+## 3. Supported Function Types in Emulator
+
+| Type | How to Test |
+|---|---|
+| HTTPS / Callable | `http://localhost:5001/<project>/<region>/<name>` |
+| Firestore triggers | Write via Admin SDK or Emulator UI → trigger fires |
+| Auth triggers | Create user via Admin SDK or Emulator UI |
+| Storage triggers | Upload file via Emulator UI |
+| Pub/Sub | Publish message via Admin SDK |
+| Eventarc (2nd gen) | `firebase emulators:start --only functions,eventarc` |
+| Alerts | Send synthetic alert from Emulator UI (Alerts tab) |
+| Scheduled | NO native emulator support → test via manual HTTP trigger |
+| Task Queue | Dispatch works, but rate limiting differs from production |
+
+### 2nd Gen + Eventarc Setup
+```bash
+firebase emulators:start --only functions,eventarc
+# EVENTARC_EMULATOR=localhost:9299 is set automatically
+# Admin SDK captures events automatically
+```
+
+## 4. Connecting Client Apps to Emulator
+
+### Web (Firebase v10+ Modular)
+```js
+import { getFunctions, connectFunctionsEmulator } from "firebase/functions";
+const functions = getFunctions();
+connectFunctionsEmulator(functions, "127.0.0.1", 5001);
+```
+
+### Android (Kotlin)
+```kotlin
+Firebase.functions.useEmulator("10.0.2.2", 5001)
+```
+
+### iOS (Swift)
+```swift
+Functions.functions().useEmulator(withHost: "localhost", port: 5001)
+```
+
+HTTPS functions: call `http://localhost:5001/...` directly.
+
+## 5. Environment & Secrets in Emulator
+
+### .env.local (highest priority, emulator-only)
+```
+# .env.local (gitignored, only used in emulator)
+API_KEY=local-test-key
+AUDIENCE=Local Humans
+```
+
+### Secrets
+- Create `.secret.local` to override production secrets locally.
+- Without `.secret.local`, emulator pulls from Secret Manager via ADC (Application Default Credentials).
+- `.secret.local` takes priority.
+
+### Legacy Runtime Config
+```bash
+firebase functions:config:get > .runtimeconfig.json
+# Emulator reads this file automatically
+```
+
+## 6. Emulator UI (localhost:4000)
+
+The most powerful debugging tool:
+- **Logs** → real-time `console.log` / `console.error` output
+- **Functions** → list of active triggers with execution details
+- **Firestore / Auth / Storage** → modify data directly, triggers fire automatically
+- **Alerts** → send synthetic alert events
+- **Execution Details** → input/output payloads, runtime duration, error stacks
+
+## 7. Debugging
+
+### Terminal + Emulator UI
+Both show logs simultaneously. `console.error` appears in red.
+
+### VS Code Debugger
+```bash
+firebase emulators:start --inspect-functions
+```
+Then attach VS Code debugger or use `chrome://inspect`.
+
+### Breakpoints
+With `--inspect-functions`, set breakpoints in VS Code. Step through trigger execution line by line.
+
+## 8. Local vs Production Differences
+
+| Aspect | Local Emulator | Production (Cloud Run) | Test Strategy |
+|---|---|---|---|
+| Retries | NOT supported | 24-hour window (2nd gen) | Manually trigger same event 3-5x |
+| Concurrency | Unlimited (local CPU) | 1–1000 per instance | Cannot test locally |
+| Cold Start | None (always warm) | 500ms–5s possible | Test after real deploy |
+| Timeout | `timeoutSeconds` honored | Same | Same code works |
+| Memory/CPU | Unlimited (local machine) | 32 GiB / 4 vCPU max | Local test is valid |
+| OS | Your machine (macOS/Windows) | Linux container | Bundle Linux binaries if needed |
+| IAM | ADC (your credentials) | Service account | Test IAM in production |
+| Networking | localhost only | Internet + VPC | Mock external APIs locally |
+
+## 9. Idempotency & Loop Testing Protocol
+
+Since retries don't work in the emulator, test idempotency manually:
+
+1. **Trigger the same event 5 times** (via Emulator UI or Admin SDK script)
+2. Verify `before/after` guard prevents re-processing
+3. Verify `eventAgeMs` check would drop stale events (simulate with old timestamps)
+4. Check `processedEvents` collection in emulator Firestore — should have exactly 1 entry per event
+5. Verify no infinite loop: watch Emulator UI logs for recursive trigger patterns
+
+```js
+// Test script: trigger same Firestore write 5 times
+const admin = require("firebase-admin");
+admin.initializeApp({ projectId: "demo-test" });
+const db = admin.firestore();
+db.settings({ host: "localhost:8080", ssl: false });
+
+for (let i = 0; i < 5; i++) {
+  await db.doc("users/test-user").set({ name: "Test", iteration: i });
+}
+// Check: function should process only relevant changes, not loop
+```
+
+## 10. Advanced Testing Patterns
+
+### Unit Tests (Firebase Test SDK)
+```bash
+npm install --save-dev @firebase/rules-unit-testing
+```
+Use with Mocha or Jest for isolated function testing.
+
+### Integration Tests with Auto-Shutdown
+```bash
+firebase emulators:exec "npm test" --only functions,firestore
+# Starts emulators → runs tests → shuts down automatically
+```
+
+### Data Seeding
+- Import/export Firestore data via Emulator UI
+- Or seed programmatically with Admin SDK in test setup
+
+### CI/CD Pipeline
+```bash
+# In CI (GitHub Actions, etc.)
+firebase emulators:exec "npm test" --only functions,firestore
+```
+Java 11+ must be available in CI environment.
+
+## 11. Agent Testing Checklist
+
+Before considering any function "tested":
+
+1. `firebase emulators:start --only functions,firestore,eventarc` running?
+2. Client SDK has `connectFunctionsEmulator` / `useEmulator` call?
+3. 2nd gen functions: Eventarc emulator included?
+4. `.env.local` + `.secret.local` configured for local secrets?
+5. Idempotency test: same event triggered 3+ times, no duplicates?
+6. Loop guard test: `before/after` comparison verified in logs?
+7. Emulator UI logs checked for unexpected re-triggers?
+8. Production differences documented (retry, scaling, OS)?
+9. `emulators:exec` used for CI/automated test runs?
+
+### Prohibitions
+- Deploying to production without local emulator testing
+- Relying on production retries instead of testing idempotency locally
+- Depending on local-only native commands (ImageMagick, etc.) without bundling for Linux

package/skill-packs/engineering/firebase-cloud-functions/references/scaling.md

@@ -0,0 +1,128 @@
+# Scaling, Concurrency & Cold Start
+
+## Concurrency (2nd Gen's Biggest Advantage)
+
+A single 2nd gen instance can handle **1–1000 concurrent requests** (default: 80).
+
+```js
+exports.myFunc = onRequest({
+  concurrency: 500,      // 500 simultaneous requests per instance
+  minInstances: 5,       // 5 warm instances always ready
+  maxInstances: 100,     // cap to prevent runaway scaling
+  memory: "1GiB",
+  cpu: 2,
+}, (req, res) => { ... });
+```
+
+### Recommended Concurrency Values
+
+| Function Type | Concurrency | Rationale |
+|---|---|---|
+| HTTP / Callable | >= 200 | High throughput, shared instance state |
+| Firestore background trigger | >= 80 | Moderate parallelism |
+| CPU-intensive (image processing) | 1–10 | Avoid resource contention |
+| External API calls (rate-limited) | 10–50 | Respect downstream limits |
+
+## Cold Start Prevention
+
+Cold start = new instance spin-up. Can add 500ms–5s latency.
+
+### minInstances (primary solution)
+```js
+{ minInstances: 1 }  // At least 1 warm instance → cold start eliminated for most traffic
+```
+- `minInstances: 1` reduces cold starts by ~90%.
+- `minInstances: 5` for high-traffic production functions.
+- Cost: warm instances bill for idle time. Trade-off: latency vs cost.
+
+### Global Variable Caching
+```js
+// Initialize ONCE, reuse across invocations on same instance
+const admin = require("firebase-admin");
+admin.initializeApp();
+const db = admin.firestore();
+
+// Heavy clients: cache at module level
+let aiClient;
+function getAiClient() {
+  if (!aiClient) aiClient = new SomeAiClient();
+  return aiClient;
+}
+```
+
+### onInit() for Heavy Initialization (2nd gen)
+```js
+const { onInit } = require("firebase-functions/v2/core");
+
+onInit(() => {
+  // Runs once per instance, before any request
+  // Use for GenAI client init, connection pools, etc.
+});
+```
+
+## Background Activity — FORBIDDEN
+
+NEVER start background work after sending a response:
+
+```js
+// WRONG — background activity breaks instance reuse
+exports.bad = onRequest((req, res) => {
+  res.send("OK");
+  setTimeout(() => doSomething(), 5000); // ← NEVER DO THIS
+});
+
+// CORRECT — finish all work before responding
+exports.good = onRequest(async (req, res) => {
+  await doSomething();
+  res.send("OK");
+});
+```
+
+## Runtime Options (Full Template)
+
+```js
+const { setGlobalOptions } = require("firebase-functions/v2");
+
+setGlobalOptions({
+  region: "us-central1",
+  memory: "512MiB",
+  cpu: 1,
+  concurrency: 200,
+  minInstances: 1,
+  maxInstances: 50,
+});
+```
+
+Per-function override:
+```js
+exports.heavyFunc = onRequest({
+  timeoutSeconds: 300,
+  memory: "4GiB",
+  cpu: 4,
+  concurrency: 10,
+  minInstances: 2,
+  maxInstances: 20,
+  serviceAccount: "my-sa@project.iam.gserviceaccount.com"
+}, handler);
+```
+
+## CPU Scaling Option
+
+```js
+// Use 1st gen CPU behavior (scales with memory)
+setGlobalOptions({ cpu: "gcf_gen1" });
+```
+
+## Quotas & Limits (March 2026)
+
+| Limit | 2nd Gen |
+|---|---|
+| Max memory | 32 GiB |
+| Max vCPU | 4 |
+| HTTP timeout | 60 minutes |
+| Event timeout | 540s (scheduled: 1800s) |
+| Concurrency per instance | 1000 |
+| Function count | ~1000 (minus Cloud Run services) |
+| Max deployment size | 100 MiB (compressed) |
+
+Quota exceeded = HTTP 500 + function stops. Always set `maxInstances` to cap costs.

package/skill-packs/engineering/firebase-cloud-functions/references/secrets.md

@@ -0,0 +1,70 @@
+# Secrets & Environment Configuration
+
+## functions.config() is DEPRECATED
+
+`functions.config()` is deprecated and will be **removed March 2027**. Agent MUST NOT use it.
+
+## Correct Approach: Parameterized Config + Secret Manager
+
+### Secrets (API keys, credentials)
+
+```js
+const { defineSecret } = require("firebase-functions/params");
+const apiKey = defineSecret("API_KEY");
+const stripeKey = defineSecret("STRIPE_SECRET_KEY");
+
+exports.myFunc = onRequest(
+  { secrets: [apiKey, stripeKey] },  // Declare which secrets this function needs
+  (req, res) => {
+    const key = apiKey.value();      // Access at runtime
+    const stripe = require("stripe")(stripeKey.value());
+  }
+);
+```
+
+### CLI Commands
+
+```bash
+firebase functions:secrets:set API_KEY          # Set a secret
+firebase functions:secrets:access API_KEY       # Read current value
+firebase functions:secrets:destroy API_KEY      # Delete
+firebase functions:secrets:prune                # Remove unused secrets
+```
+
+### Environment Variables (non-sensitive config)
+
+```js
+const { defineString, defineInt } = require("firebase-functions/params");
+
+const region = defineString("REGION", { default: "us-central1" });
+const maxRetries = defineInt("MAX_RETRIES", { default: 3 });
+```
+
+### .env Files (development only)
+
+```
+# .env (all environments)
+REGION=us-central1
+
+# .env.local (emulator only — gitignored)
+API_KEY=test-key-123
+```
+
+**NEVER commit `.env` files with real secrets to version control.**
+
+## Secret Access Scope
+
+- Secrets are only available to functions that declare them in `secrets: [...]`.
+- Undeclared access → runtime error (value is empty).
+- Security rules do NOT apply to secrets — they are Cloud-level access control.
+
+## Service Account
+
+2nd gen uses **Compute Engine default service account** (more restrictive than 1st gen's App Engine default).
+
+Override per function:
+```js
+{
+  serviceAccount: "custom-sa@project.iam.gserviceaccount.com"
+}
+```